pki-server-nuxwdog(8)

📦
version 11.2.0 · 4 versions
, in centos-stream 9, ubuntu jammy

🎀 NAME 🎀

hii bestie, welcome to pki-server-nuxwdog(8) — the whole page lives under the PKI Nuxwdog Management Commands umbrella, and it's literally the command-line interface for enabling PKI server instances to start using nuxwdog. slay. 💅

✨ SYNOPSIS ✨

pki-server [CLI-options] nuxwdog
pki-server [CLI-options] nuxwdog-enable
pki-server [CLI-options] nuxwdog-disable

🦋 DESCRIPTION 🦋

okay so picture this: when a PKI server instance starts up, it reads a plain text config file (i.e. /etc/pki/instance_name/password.conf) to grab the passwords it needs to initialize the server. ngl that could be passwords for accessing server keys in hardware or software crypto modules, or passwords to establish database connections. a whole vibe.

and like — yes, this file is protected by file and SELinux permissions, but it's even more secure to remove the file entirely and have the server prompt for those passwords on startup instead. the tradeoff? obviously it won't be possible to start the PKI server instance unattended, including on server reboots. 🙈

nuxwdog is the mechanism that lets you start a PKI server without storing passwords in a file (i.e. password.conf), and instead prompt the administrator for the relevant passwords. those passwords get cached securely in the kernel keyring. and if the CS instance crashes unexpectedly, systemd will attempt to restart the instance using the cached passwords. main character energy fr fr. 🔥

PKI server instances need to be reconfigured to use nuxwdog to start — and it's not just instance config file changes, the instances also need to use a different systemd unit file to start. the details live down in the Operations section, iykyk.

the pki-server nuxwdog commands are the mechanism to reconfigure instances to either start or not start with nuxwdog:

  • pki-server [CLI-options] nuxwdog — this one lists the available nuxwdog commands 👑
  • pki-server [CLI-options] nuxwdog-enable — this one reconfigures ALL local PKI server instances to start using nuxwdog.
    • to reconfigure a particular PKI server instance only, use pki-server instance-nuxwdog-enable.
  • pki-server [CLI-options] nuxwdog-disable — this one reconfigures ALL local PKI server instances to start without using nuxwdog.
    • to reconfigure a particular PKI server instance only, use pki-server instance-nuxwdog-disable.
    • once this operation is complete, instances will need to read a password.conf file in order to start up. 😭

💜 OPTIONS 💜

the CLI options are described in pki-server(8). that's it, that's the section — go read the main character's page. 🫶

🌸 OPERATIONS 🌸

configuring a PKI server instance to start using nuxwdog requires changes to instance configuration files such as server.xml. these changes are performed by pki-server. no cap.

once a subsystem has been converted to using nuxwdog, the password.conf file is no longer needed — it can be removed from the filesystem. but be sure, of course, to note all passwords contained therein first, because some of them may be randomly generated during the install. 💀 don't lose those.

⭐ note: if a subsystem stores any of its system certificates in a cryptographic token other than the internal NSS database, it will have entries in password.conf that look like hardware-TOKEN_NAME=password. in this case, an additional parameter must be added to CS.cfg.
cms.tokenList=TOKEN_NAME

when this parameter is added, nuxwdog will prompt the password for hardware-TOKEN_NAME in addition to the other passwords.

an instance that is started by nuxwdog is started by a different systemd unit file (pki-tomcatd-nuxwdog). therefore, to start/stop/restart an instance, use:

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

if the PKI server instance is converted back to not using nuxwdog to start, then the usual systemd unit scripts can be invoked:

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

🌈 SEE ALSO 🌈

🍓 AUTHORS 🍓

shoutout to Ade Lee (alee@redhat.com) and Dinesh Prasanth M K (dmoluguw@redhat.com) — icons only. 👑

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.

and that's the page!! 🫶 brought to you by the PKI crew, dated December 20, 2018 — pki-server-nuxwdog(8), signing off. mwah 💋✨

📦 where this page comes from