diff options
| -rw-r--r-- | base/server/man/man8/pki-server-instance.8 | 104 | ||||
| -rw-r--r-- | base/server/man/man8/pki-server-migrate.8 | 46 | ||||
| -rw-r--r-- | base/server/man/man8/pki-server-nuxwdog.8 | 102 | ||||
| -rw-r--r-- | base/server/man/man8/pki-server-subsystem.8 | 95 | ||||
| -rw-r--r-- | base/server/man/man8/pki-server.8 | 82 | ||||
| -rw-r--r-- | specs/pki-core.spec | 5 |
6 files changed, 434 insertions, 0 deletions
diff --git a/base/server/man/man8/pki-server-instance.8 b/base/server/man/man8/pki-server-instance.8 new file mode 100644 index 000000000..18518f618 --- /dev/null +++ b/base/server/man/man8/pki-server-instance.8 @@ -0,0 +1,104 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server-instance 8 "July 15, 2015" "version 10.2" "PKI Instance Management Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server instance \- Command-Line Interface for managing Certificate System instances. + +.SH SYNOPSIS +.nf +\fBpki-server [CLI options] instance\fR +\fBpki-server [CLI options] instance-find\fR +\fBpki-server [CLI options] instance-show\fR <instance ID> +\fBpki-server [CLI options] instance-start\fR <instance ID> +\fBpki-server [CLI options] instance-stop\fR <instance ID> +\fBpki-server [CLI options] instance-migrate\fR --tomcat <version> <instance ID> +\fBpki-server [CLI options] instance-nuxwdog-enable\fR <instance ID> +\fBpki-server [CLI options] instance-nuxwdog-disable\fR <instance ID> +.fi + +.SH DESCRIPTION +.PP +The \fBpki-server instance\fR commands provide command-line interfaces to manage +Certificate Server (CS) instances. A Certificate Server instance consists of a +single Apache Tomcat instance that contains one or more CS subsystems. +.PP +Operations that are available include: listing and showing details about local +instances; starting and stopping instances; performing instance migrations; and +enabling or disabling password prompted instance startup using \fBnuxwdog\fR. +.PP +\fBpki-server [CLI options] instance\fR +.RS 4 +This command is to list available instance commands. +.RE +.PP +\fBpki-server [CLI options] instance-find\fR +.RS 4 +This command is to list local CS instances. +.RE +.PP +\fBpki-server [CLI options] instance-show\fR <instance ID> +.RS 4 +This command is to view a details about a particular instance. +.RE +.PP +\fBpki-server [CLI options] instance-start\fR <instance ID> +.RS 4 +This command is to start a CS instance. Note that currently this command +cannot be used to start \fBnuxwdog\fR-enabled instances. +.RE +.PP +\fBpki-server [CLI options] instance-stop\fR <instance ID> +.RS 4 +This command is to stop a CS instance. Note that currently this command +cannot be used to stop \fBnuxwdog\fR-enabled instances. +.RE +.PP +\fBpki-server [CLI options] instance-migrate\fR --tomcat <version> <instance_ID> +.RS 4 +There are differences in configuration between Apache Tomcat 7 and Apache Tomcat +8. This command reconfigures a CS instance to match the specified Tomcat version. +This command can be used to migrate initially created under Tomcat 7 when +Tomcat is upgraded.. See \fBpki-server migrate\fR(8) for further details. +.RE +.PP +\fBpki-server [CLI options] instance-nuxwdog-enable\fR <instance ID> +.RS 4 +This command is to convert a CS instance to start without access to a +password file, using the \fBnuxwdog\fR daemon. See \fBpki-server nuxwdog\fR(8) +for further details. +.RE +.PP +\fBpki-server [CLI options] instance-nuxwdog-disable\fR <instance ID> +.RS 4 +This command is to convert a CS instance to start with access to a +password file, rather than using the \fBnuxwdog\fR daemon. See \fBpki-server nuxwdog\fR(8) +for further details. +.RE + +.SH OPTIONS +The CLI options are described in \fBpki-server\fR(8). + +.SH OPERATIONS +To view available instance management commands, type \fBpki-server instance\fP. +To view each command's usage, type \fB pki-server instance-<command> \-\-help\fP. + +All pki-server commands must be executed as the system administrator. + +.SH AUTHORS +Ade Lee <alee@redhat.com> + +.SH COPYRIGHT +Copyright (c) 2015 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. diff --git a/base/server/man/man8/pki-server-migrate.8 b/base/server/man/man8/pki-server-migrate.8 new file mode 100644 index 000000000..d58d17399 --- /dev/null +++ b/base/server/man/man8/pki-server-migrate.8 @@ -0,0 +1,46 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server-migrate 8 "July 15, 2015" "version 10.2" "PKI Migration Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server migrate \- Command-Line Interface to run migration scripts on CS instances. + +.SH SYNOPSIS +.nf +\fBpki-server [CLI options] migrate --tomcat \fR[7|8] +.fi + +.SH DESCRIPTION +.PP +Apache Tomcat instances are configured differently in Tomcat 7 and 8. \fBpki-server migrate\fR +makes the necessary changes in the instance configuration files and symbolic links +so that the instance will work with the target Tomcat version. +.PP +This command will migrate all instances to the target Apache Tomcat version. To +migrate a specific instance only, use \fBpki-server instance-migrate\FR. +.PP + +.SH OPTIONS +The CLI options are described in \fBpki-server\fR(8). + +.SH OPERATIONS + +All \fBpki-server\fP commands must be executed as the system administrator. + +.SH AUTHORS +Ade Lee <alee@redhat.com> + +.SH COPYRIGHT +Copyright (c) 2015 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. diff --git a/base/server/man/man8/pki-server-nuxwdog.8 b/base/server/man/man8/pki-server-nuxwdog.8 new file mode 100644 index 000000000..01c4f34bc --- /dev/null +++ b/base/server/man/man8/pki-server-nuxwdog.8 @@ -0,0 +1,102 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server-nuxwdog 8 "July 15, 2015" "version 10.2" "PKI Nuxwdog Management Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server nuxwdog \- Command-Line Interface for enabling CS instances to start using \fBnuxwdog\fR. + +.SH SYNOPSIS +.nf +\fBpki-server [CLI options] nuxwdog\fR +\fBpki-server [CLI options] nuxwdog-enable\fR +\fBpki-server [CLI options] nuxwdog-disable\fR +.fi + +.SH DESCRIPTION +.PP +When a Certificate System (CS) instance starts, it reads a plain text configuration +file (\fB /etc/pki/<instance_name>/password.conf\fR) to obtain passwords needed to +initialize the server. This could include passwords needed to access server keys +in hardware or software cryptographic modules, or passwords to establish database +connections. +.PP +While this file is protected by file and SELinux permissions, it is even more secure +to remove this file entirely, and have the server prompt for these passwords on +startup. This means of course that it will not be possible to start the CS +instance unattended, including on server reboots. +.PP +\fBnuxwdog\fR is a daemon that will launch the CS instance and prompt the administrator +for the relevant passwords. These passwords will be cached securely in the kernel +keyring. If the CS instance crashes unexpectedly, \fBnuxwdog\fR will attempt to restart +the instance using the cached passwords. +.PP +CS instances need to be reconfigured to use \fBnuxwdog\fR to start. Not only are changes +required in instance configuration files, but instances need to use a different +systemd unit file to start. See details in the \fBOperations\fR section. + +\fBpki-server nuxwdog\fR commands provide a mechanism to reconfigure instances +to either start or not start with \fBnuxwdog\fR. +.PP +\fBpki-server [CLI options] nuxwdog\fR +.RS 4 +This command is to list available \fBnuxwdog\fR commands. +.RE +.PP +\fBpki-server [CLI options] nuxwdog-enable\fR +.RS 4 +This command is to reconfigure ALL local CS instances to start using \fBnuxwdog\fP. +To reconfigure a particular CS instance only, use \fBpki-server instance-nuxwdog-enable\fR. +.RE +.PP +\fBpki-server [CLI options] nuxwdog-disable\fR +.RS 4 +This command is to reconfigure ALL local CS instances to start without using +\fBnuxwdog\fP. To reconfigure a particular CS instance only, use +\fBpki-server instance-nuxwdog-disable\fR. Once this operation is complete, +instances will need to read a \fBpassword.conf\fR file in order to start up. +.RE + +.SH OPTIONS +The CLI options are described in \fBpki-server\fR(8). + +.SH OPERATIONS +Configuring a CS instance to start using \fBnuxwdog\fR requires changes to instance +configuration files such as \fBserver.xml\fP. These changes are performed by +\fBpki-server\fR. +.PP +Once a subsystem has been converted to using \fBnuxwdog\fR, the \fBpassword.conf\fR +file is no longer needed. It can be removed from the filesystem. Be sure, of course, +to note all passwords contained therein - some of which may be randomly generated +during the install. +.PP +An instance that is started by \fBnuxwdog\fR is started by a different systemd unit +file (\fBpki-tomcatd-nuxwdog\fR). Therefore, to start/stop/restart an instance using +the following: +.PP +\fBsystemctl start/stop/restart pki-tomcatd-nuxwdog@<instance_id>.service\fR +.PP +If the CS instance is converted back to not using \fBnuxwdog\fP to start, then the +usual systemd unit scripts can be invoked: +.PP +\fBsystemctl start/stop/restart pki-tomcatd@<instance_id>.service\fR +.PP + +All \fBpki-server\fP commands must be executed as the system administrator. + +.SH AUTHORS +Ade Lee <alee@redhat.com> + +.SH COPYRIGHT +Copyright (c) 2015 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. diff --git a/base/server/man/man8/pki-server-subsystem.8 b/base/server/man/man8/pki-server-subsystem.8 new file mode 100644 index 000000000..04d57f5ac --- /dev/null +++ b/base/server/man/man8/pki-server-subsystem.8 @@ -0,0 +1,95 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server-subsystem 8 "July 15, 2015" "version 10.2" "PKI Subsystem Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server subsystem \- Command-Line Interface for managing Certificate System subsystems. + +.SH SYNOPSIS +.nf +\fBpki-server [CLI options] subsystem\fR +\fBpki-server [CLI options] subsystem-find\fR -i <instance ID> +\fBpki-server [CLI options] subsystem-show\fR -i <instance ID> <subsystem ID> +\fBpki-server [CLI options] subsystem-enable\fR -i <instance ID> <subsystem ID> +\fBpki-server [CLI options] subsystem-disable\fR -i <instance ID> <subsystem ID> +.fi + +.SH DESCRIPTION +.PP +The \fBpki-server subsystem\fR commands provide command-line interfaces to manage +Certificate Server (CS) subsystems. A Certificate Server instance consists of a single +Apache Tomcat instance that contains one or more CS subsystems. Valid subsystem +identifiers are '\fBca\fR', '\fBkra\fR', '\fBtks\fR', '\fBocsp\fR' and '\fBtps\fR'. +No instance may have more than one of each type of subsystem. +.PP +\fBpki-server subsystem\fR commands perform operations on a specific subsystem within +a CS instance. Consequently, all \fBpki-server subsystem\fR commands require specification +of the instance ID to completely identify the target subsystem. +.PP +Operations that are available include: listing subsystems in an instance; +showing details about a subsystem; and enabling and disabling subsystems. +.PP +\fBpki-server [CLI options] subsystem\fR +.RS 4 +This command is to list available subsystem commands. +.RE +.PP +\fBpki-server [CLI options] subsystem-find\fR -i <instance ID> +.RS 4 +This command is to list subsystems within a specific instance. +.RE +.PP +\fBpki-server [CLI options] subsystem-show\fR -i <instance ID> <subsystem ID> +.RS 4 +This command is to view a details about a particular subsystem. +.RE +.PP +\fBpki-server [CLI options] subsystem-enable\fR -i <instance ID> <subsystem ID> +.RS 4 +This command is to enable a particular subsystem. Each subsystem consists of +a web application within the Apache Tomcat instance. Enabling a subsystem means +deploying the web application so that the application initializes and is +accessible via the HTTP and HTTPS ports for the Apache Tomcat instance. +.PP +\fBNote:\fR Each subsystem runs a set of self-tests on startup. If these self-tests +fail, the subsystem will be disabled by undeploying the web application. The +deployment status (enabled/disabled) of the subsystem can be determined from the +output of \fBpki-server subsystem-show\fR. Once the underlying problem is fixed, +the subsystem should be re-enabled using \fBpki-server subsystem-enable\fR. +.RE +.PP +\fBpki-server [CLI options] subsystem-disable\fR -i <instance ID> <subsystem ID> +.RS 4 +This command is to disable a subsystem by undeploying the web application +corresponding to the subsystem. The subsystem will no longer be accessible +through the web interfaces. This is useful when specific subsystems need to be +made inaccessible for maintenance as Apache Tomcat allows web applications to be +deployed/undeployed while the instance is still running (hot deployment). +.RE + +.SH OPTIONS +The CLI options are described in \fBpki-server\fR(8). + +.SH OPERATIONS +To view available subsystem management commands, type \fBpki-server subsystem\fP. +To view each command's usage, type \fB pki-server subsystem-<command> \-\-help\fP. + +All pki-server commands must be executed as the system administrator. + +.SH AUTHORS +Ade Lee <alee@redhat.com> + +.SH COPYRIGHT +Copyright (c) 2015 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. diff --git a/base/server/man/man8/pki-server.8 b/base/server/man/man8/pki-server.8 new file mode 100644 index 000000000..027143522 --- /dev/null +++ b/base/server/man/man8/pki-server.8 @@ -0,0 +1,82 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server 8 "July 15, 2015" "version 10.2" "PKI Administrative Command-Line Interface (CLI)" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server \- Command-Line Interface for performing administrative tasks on Certificate System subsystems. + +.SH SYNOPSIS +\fBpki-server\fR [CLI options] <command> [command arguments] + +.SH DESCRIPTION +.PP +The \fBpki-server\fR command provides a command-line interface allowing administrators +to perform various administrative operations on the Certificate System instances. +These services include starting/stopping instances, enabling/disabling subsystems, +performing certain migrations and enabling/disabling startup using \fBnuxwdog\fR. +.PP +Operations are performed using file system utilities, and can only be performed +by an administrative user on the local host. This utility does not connect to any +of the subsystem's WEB or REST interfaces. + +.SH CLI OPTIONS +.B --help +Prints additional help information. +.TP +.B -d +Displays debug information. +.TP +.B -v +Displays verbose information. + +.SH OPERATIONS +To view available commands and options, simply type \fBpki-server\fP. +.PP +Some commands have sub-commands. To view the sub-commands, type \fBpki-server <command>\fP. +To view each command's usage, type \fB pki-server <command> \-\-help\fP. + +.SH FILES +.I /usr/sbin/pki-server + +.SH SEE ALSO +.PP +\fBpki-server-instance\fR(1) +.RS 4 +Certificate Server instance management commands +.RE + +.PP +\fBpki-server-subsystem\fR(1) +.RS 4 +Certificate Server subsystem management commands +.RE + +.PP +\fBpki-server-migrate\fR(1) +.RS 4 +Certificate server migration script management commands +.RE + +.PP +\fBpki-server-nuxwdog\fR(1) +.RS 4 +Commands to enable/disable startup using \fBnuxwdog\fP. +.RE + +.SH AUTHORS +Ade Lee <alee@redhat.com>. + +.SH COPYRIGHT +Copyright (c) 2015 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. diff --git a/specs/pki-core.spec b/specs/pki-core.spec index 6ac51d85e..06fd9c7d3 100644 --- a/specs/pki-core.spec +++ b/specs/pki-core.spec @@ -906,6 +906,11 @@ systemctl daemon-reload %{_mandir}/man8/pki-server-upgrade.8.gz %{_mandir}/man8/pkidestroy.8.gz %{_mandir}/man8/pkispawn.8.gz +%{_mandir}/man8/pki-server.8.gz +%{_mandir}/man8/pki-server-instance.8.gz +%{_mandir}/man8/pki-server-subsystem.8.gz +%{_mandir}/man8/pki-server-nuxwdog.8.gz +%{_mandir}/man8/pki-server-migrate.8.gz %{_datadir}/pki/setup/ %{_datadir}/pki/server/ |