pki-server-upgrade(8)

📦
version 11.7.1 · 3 versions
, in centos-stream 9, ubuntu jammy

🎀 pki-server-upgrade — the PKI Server Upgrade Tool, bestie edition

Hey girlypop, welcome to pki-server-upgrade, aka the tool for upgrading PKI server configuration. Yes, that's the manual page name up there, and yes, I'm gonna hold your hand through every single flag. Let's gooo 💅

✨ SYNOPSIS ✨

pki-server [CLI-options] upgrade [OPTIONS]

🌸 DESCRIPTION 🌸

Okay so, upgrading a PKI server is literally a two-part situation:

  • upgrading the system configuration files used by both the client and the server processes, and
  • upgrading the server configuration files.

When you upgrade PKI server, the existing server configuration files (like server.xml and web.xml) might need upgrading because their content may have changed from one version to another. The config upgrade is executed automatically during RPM upgrade — no cap. But borrow, if there's a problem, you can also run the process manually using pki-server upgrade. You've got options, queen 👑

The server upgrade process is done incrementally using upgrade scriptlets. A server consists of the server instance itself and the subsystems running in that instance. The upgrade process executes one scriptlet at a time, running through each component (server instance and subsystem) in parallel and completing before executing the next scriptlet. If one component encounters an error, that component is skipped in the subsequent upgrade scriptlets. The upgrade process and scriptlet execution for each component is monitored in upgrade trackers. A counter shows the latest index number for the most recently executed scriptlet; when all scriptlets have run, the component tracker shows the updated version number. Trackers are basically the group chat read receipts of the upgrade world 🫶

The scriptlets are stored in the upgrade directory:

/usr/share/pki/server/upgrade/<version>/<index>-<name>

Where version is the server version to be upgraded, index is the script execution order, and name is the scriptlet name. It's giving organized folder structure, honestly iconic ✨

During upgrade, the scriptlets will back up all changes to the file system into the following folder:

/var/log/pki/server/upgrade/<version>/<index>

The version and index values indicate the scriptlet being executed. A copy of the files and folders that are being modified or removed will be stored in oldfiles. The names of the newly-added files and folders will be stored in newfiles. Receipts! Saved! 🧾

The instance upgrade process is tracked using this file:

/var/lib/pki/<instance>/conf/tomcat.conf

The subsystem upgrade process is tracked using this file:

/var/lib/pki/<instance>/<subsystem>/conf/CS.cfg

That file stores the current configuration version and the last successful scriptlet index. Lowkey the most important file in this whole page, ngl 💖

💅 OPTIONS 💅

General options

  • --status — Show upgrade status only, without performing the upgrade. It's the "just checking in, not committing" of flags 👀
  • --revert — Revert the last version. Undo button, but make it enterprise.
  • -i, --instance instance — Upgrade a specific instance only. Pick your fave, no pressure on the others.
  • -X — Show advanced options. Open the secret menu, bestie 🔓
  • -v, --verbose — Run in verbose mode. All the tea, none of the filter ☕
  • -h, --help — Show this help message. Hi, hello, here's how it works 🫶

Advanced options

Bestie. Read this next part carefully, because these advanced options circumvent the normal upgrade process by changing the tracker information.

⚠️ WARNING: These options may render the system unusable. Like, actually. Not a drill. Proceed with main-character confidence at your own risk 💀
  • --remove-tracker — Remove the tracker. Gone. Deleted. No tracker, no memory.
  • --reset-tracker — Reset the tracker to match the package version. Fresh start energy ✨
  • --set-tracker version — Set the tracker to a specific version. You decide the truth, honestly.

🌈 OPERATIONS 🌈

Upgrade process

To start the upgrade process:

$ pki-server upgrade

That's it. That's the whole vibe. Slay.

Upgrade status

To check the upgrade status:

$ pki-server upgrade --status

Peek before you leap, queen 👑

Troubleshooting

Check the scriptlet to see which operations are being executed. Once the error is identified and corrected, the upgrade can be resumed by re-running pki-server upgrade. No need to start from scratch, we love a resume 😌

If necessary, the upgrade can be run in verbose mode:

$ pki-server upgrade --verbose

It is possible to rerun a failed upgrade for a specific instance:

$ pki-server upgrade --instance pki-tomcat

See? Targeted support. We love to see it 💜

Reverting an upgrade

If necessary, the upgrade can be reverted:

$ pki-server upgrade --revert

Files and folders that were created by the scriptlet will be removed. Files and folders that were modified or removed by the scriptlet will be restored. It's the Ctrl+Z we all deserve 🦋

👑 AUTHORS 👑

The absolute icons behind this: Ade Lee <alee@redhat.com>, Ella Deon Lackey <dlackey@redhat.com>, and Endi S. Dewata <edewata@redhat.com>. Legends, fr fr 🙌

Copyright (c) 2013 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. Legal stuff but make it cute ⚖️💖

And that's the whole page, bestie! Signing off from the PKI corner of the manual-verse, dated Jul 22, 2013, filed forever under pki-server-upgrade(8). Go forth and upgrade responsibly 🌟🎀

📦 where this page comes from