>From ad0d1f6be19a93fdb10e1cdc5b0392996c548bc8 Mon Sep 17 00:00:00 2001
From: Ade Lee <alee@redhat.com>
Date: Tue, 14 Jul 2015 15:06:03 -0400
Subject: [PATCH] Added man pages for pki-server

Trac ticket 1356
---
 base/server/man/man8/pki-server-instance.8  | 104 ++++++++++++++++++++++++++++
 base/server/man/man8/pki-server-migrate.8   |  46 ++++++++++++
 base/server/man/man8/pki-server-nuxwdog.8   | 102 +++++++++++++++++++++++++++
 base/server/man/man8/pki-server-subsystem.8 |  95 +++++++++++++++++++++++++
 base/server/man/man8/pki-server.8           |  82 ++++++++++++++++++++++
 5 files changed, 429 insertions(+)
 create mode 100644 base/server/man/man8/pki-server-instance.8
 create mode 100644 base/server/man/man8/pki-server-migrate.8
 create mode 100644 base/server/man/man8/pki-server-nuxwdog.8
 create mode 100644 base/server/man/man8/pki-server-subsystem.8
 create mode 100644 base/server/man/man8/pki-server.8

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 0000000000000000000000000000000000000000..e972eca7ee57e5bf1ace6f95b6712bdd85c42174
--- /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 instance\fR [CLI options]
+\fBpki-server instance-find\fR [CLI options]
+\fBpki-server instance-show\fR [CLI options] <instance ID>
+\fBpki-server instance-start\fR [CLI options] <instance ID>
+\fBpki-server instance-stop\fR [CLI options] <instance ID>
+\fBpki-server instance-migrate\fR [CLI options] --tomcat <version> <instance ID>
+\fBpki-server instance-nuxwdog-enable\fR [CLI options] <instance ID>
+\fBpki-server instance-nuxwdog-disable\fR [CLI options] <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 instance\fR [CLI options]
+.RS 4
+This command is to list available instance commands.
+.RE
+.PP
+\fBpki-server instance-find\fR [CLI options]
+.RS 4
+This command is to list local CS instances.
+.RE
+.PP
+\fBpki-server instance-show\fR [CLI options] <instance_ID>
+.RS 4
+This command is to view a details about a particular instance.
+.RE
+.PP
+\fBpki-server instance-start\fR [CLI options] <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 instance-stop\fR [CLI options] <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 instance-migrate\fR [CLI options] --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 instance-nuxwdog-enable\fR [CLI options] <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 instance-nuxwdog-disable\fR [CLI options] <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 server administrator.
+
+.SH AUTHORS
+Endi Dewata <edewata@redhat.com> and 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 0000000000000000000000000000000000000000..82933e65ba7b195151403d47a1ae5dc007e087c6
--- /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 migrate --tomcat \fR[7|8] [CLI options]
+.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 server administrator.
+
+.SH AUTHORS
+Endi Dewata <edewata@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 0000000000000000000000000000000000000000..d26046398e57add930e38d284dbd260d9c012fc2
--- /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 nuxwdog\fR [CLI options]
+\fBpki-server nuxwdog-enable\fR [CLI options]
+\fBpki-server nuxwdog-disable\fR [CLI options]
+.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 nuxwdog\fR [CLI options]
+.RS 4
+This command is to list available \fBnuxwdog\fR commands.
+.RE
+.PP
+\fBpki-server nuxwdog-enable\fR [CLI options]
+.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 nuxwdog-disable\fR [CLI options]
+.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 server 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 0000000000000000000000000000000000000000..79a7eba3f2546e1d324aa12cd681b5f85191b12e
--- /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 subsystem\fR [CLI options]
+\fBpki-server subsystem-find\fR -i <instance ID> [CLI options]
+\fBpki-server subsystem-show\fR [CLI options] -i <instance ID> <subsystem ID>
+\fBpki-server subsystem-enable\fR [CLI options] -i <instance ID> <subsystem ID>
+\fBpki-server subsystem-disable\fR [CLI options] -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 subsystem\fR [CLI options]
+.RS 4
+This command is to list available subsystem commands.
+.RE
+.PP
+\fBpki-server subsystem-find\fR -i <instance ID> [CLI options]
+.RS 4
+This command is to list subsystems within a specific instance.
+.RE
+.PP
+\fBpki-server subsystem-show\fR [CLI options] -i <instance ID> <subsystem ID>
+.RS 4
+This command is to view a details about a particular subsystem.
+.RE
+.PP
+\fBpki-server subsystem-enable\fR [CLI options] -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 subsystem-disable\fR [CLI options] -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 server administrator.
+
+.SH AUTHORS
+Endi Dewata <edewata@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 0000000000000000000000000000000000000000..0fb7822ecfd814a66f45349d75b06c96c3a96d43
--- /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> and Endi Dewata <edewata@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.
-- 
1.9.3

