.nh
.TH pki-server-nuxwdog 8 "December 20, 2018" PKI "PKI Nuxwdog Management Commands"
.SH NAME
.PP
pki-server-nuxwdog - Command-line interface for enabling PKI server instances to start using \fBnuxwdog\fP\&.

.SH SYNOPSIS
.PP
\fBpki-server\fP [\fICLI-options\fP] \fBnuxwdog\fP
.br
\fBpki-server\fP [\fICLI-options\fP] \fBnuxwdog-enable\fP
.br
\fBpki-server\fP [\fICLI-options\fP] \fBnuxwdog-disable\fP

.SH DESCRIPTION
.PP
When a PKI server instance starts, it reads a plain text configuration file
(i.e. /etc/pki/\fIinstance_name\fP/password.conf) 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 PKI server instance unattended,
including on server reboots.

.PP
\fBnuxwdog\fP is a mechanism to start PKI server without storing passwords in file (i.e. password.conf);
but prompt the administrator for the relevant passwords.
These passwords will be cached securely in the kernel keyring.
If the CS instance crashes unexpectedly, \fBsystemd\fP will attempt to restart the instance using the cached passwords.

.PP
PKI server instances need to be reconfigured to use \fBnuxwdog\fP 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\fP section.

.PP
\fBpki-server nuxwdog\fP commands provide a mechanism to reconfigure instances
to either start or not start with \fBnuxwdog\fP\&.

.PP
\fBpki-server\fP [\fICLI-options\fP] \fBnuxwdog\fP
.br
    This command is to list available \fBnuxwdog\fP commands.

.PP
\fBpki-server\fP [\fICLI-options\fP] \fBnuxwdog-enable\fP
.br
    This command is to reconfigure ALL local PKI server instances to start using \fBnuxwdog\fP\&.
    To reconfigure a particular PKI server instance only, use \fBpki-server instance-nuxwdog-enable\fP\&.

.PP
\fBpki-server\fP [\fICLI-options\fP] \fBnuxwdog-disable\fP
.br
    This command is to reconfigure ALL local PKI server instances to start without using \fBnuxwdog\fP\&.
    To reconfigure a particular PKI server instance only, use \fBpki-server instance-nuxwdog-disable\fP\&.
    Once this operation is complete, instances will need to read a  \fBpassword.conf\fP file in order to start up.

.SH OPTIONS
.PP
The CLI options are described in \fBpki-server(8)\fP\&.

.SH OPERATIONS
.PP
Configuring a PKI server instance to start using \fBnuxwdog\fP requires changes
to instance configuration files such as \fBserver.xml\fP\&.
These changes are performed by \fBpki-server\fP\&.

.PP
Once a subsystem has been converted to using \fBnuxwdog\fP, the \fBpassword.conf\fP 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
\fBNote:\fP If a subsystem stores any of its system certificates in a cryptographic token other than the internal NSS database,
it will have entries in \fBpassword.conf\fP that look like \fBhardware-TOKEN_NAME=password\fP\&.
In this case, an additional parameter must be added to CS.cfg.

.PP
.RS

.nf
cms.tokenList=TOKEN_NAME

.fi
.RE

.PP
When this parameter is added, nuxwdog will prompt the password for
\fBhardware-TOKEN_NAME\fP in addition to the other passwords.

.PP
An instance that is started by \fBnuxwdog\fP is started by a different systemd unit file (\fBpki-tomcatd-nuxwdog\fP).
Therefore, to start/stop/restart an instance using the following:

.PP
.RS

.nf
$ systemctl <start/stop/restart> pki-tomcatd-nuxwdog@<instance_id>.service

.fi
.RE

.PP
If the PKI server instance is converted back to not using \fBnuxwdog\fP to start,
then the usual systemd unit scripts can be invoked:

.PP
.RS

.nf
$ systemctl <start/stop/restart> pki-tomcatd@<instance_id>.service

.fi
.RE

.SH SEE ALSO
.PP
\fBpki-server(8)\fP
.br
    PKI server management commands

.SH AUTHORS
.PP
Ade Lee &lt;alee@redhat.com&gt; and Dinesh Prasanth M K &lt;dmoluguw@redhat.com&gt;

.SH COPYRIGHT
.PP
Copyright (c) 2018 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.