pki-server-upgrade - Tool for upgrading Certificate System server configuration.
There are two parts to upgrading Certificate System: upgrading the system
configuration files used by both the client and the server processes and
upgrading the server configuration files.
When upgrading Certificate System, the existing server configuration files (e.g.
) may need to be upgraded because the content
may have changed from one version to another. The configuration upgrade is
executed automatically during RPM upgrade. However, in case there is a
problem, the process can also be run manually using pki-server-upgrade
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.
The scriptlets are stored in the upgrade directory:
is the server version to be upgraded. The index
script execution order. The name
is the scriptlet name.
During upgrade, the scriptlets will back up all changes to the file system into
the following folder:
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
The instance upgrade process is tracked using this file:
The subsystem upgrade process is tracked using this file:
The file stores the current configuration version and the last successful
- Upgrade in silent mode.
- Show upgrade status only without performing the
- Revert the last version.
- -i, --instance <instance>
- Upgrade a specific instance only.
- -s, --subsystem <subsystem>
- Upgrade a specific subsystem in an instance only.
- -t, --instance-type <type>
- Upgrade a specific instance type, by the major version
number of the Dogtag instance. For example, use 9 for Dogtag 9 instances
and 10 for Dogtag 10.
- Show advanced options.
- -v, --verbose
- Run in verbose mode.
- -h, --help
- Show this help message.
The advanced options circumvent the normal component tracking process by
changing the scriptlet order or changing the tracker information.
These options may render the system unusable.
- --scriptlet-version <version>
- Run scriptlets for a specific version only.
- --scriptlet-index <index>
- Run a specific scriptlet only.
- Remove the tracker.
- Reset the tracker to match the package version.
- --set-tracker <version>
- Set the tracker to a specific version.
By default, pki-server-upgrade
will run interactively to upgrade all
server instances and subsystems on the machine. It will ask for a confirmation
before executing each scriptlet.
If there is an error, it will stop and show the error.
The upgrade process can also be done silently without user interaction:
% pki-server-upgrade --silent
If there is an error, the upgrade process will stop for that particular
instance/subsystem. Other instances/subsystems will continue to be upgraded.
It is possible to check the status of a running upgrade process.
% pki-server-upgrade --status
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
If necessary, the upgrade can be run in verbose mode:
% pki-server-upgrade --verbose
It is possible to rerun a failed script by itself, specifying the instance and
subsystem, version, and scriptlet index:
% pki-server-upgrade --instance pki-tomcat --subsystem ca --scriptlet-version
10.0.1 --scriptlet-index 1
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.
Ade Lee <email@example.com>, Ella Deon Lackey <firstname.lastname@example.org>,
and Endi Dewata <email@example.com>. pki-server-upgrade
written by the Dogtag project.
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