1pki-server-upgrade(8) PKI Server Upgrade Tool pki-server-upgrade(8)
2
6 pki-server-upgrade - Tool for upgrading Certificate System server con‐
7 figuration.
8
11 pki-server-upgrade [OPTIONS]
12
15 There are two parts to upgrading Certificate System: upgrading the sys‐
16 tem configuration files used by both the client and the server pro‐
17 cesses and upgrading the server configuration files.
18 When upgrading Certificate System, the existing server configuration
20 files (e.g. server.xml, web.xml) may need to be upgraded because the
21 content may have changed from one version to another. The configuration
22 upgrade is executed automatically during RPM upgrade. However, in case
23 there is a problem, the process can also be run manually using pki-
24 server-upgrade.
25 The server upgrade process is done incrementally using upgrade
27 scriptlets. A server consists of the server instance itself and the
28 subsystems running in that instance. The upgrade process executes one
29 scriptlet at a time, running through each component (server instance
30 and subsystem) in parallel and completing before executing the next
31 scriptlet. If one component encounters an error, that component is
32 skipped in the subsequent upgrade scriptlets. The upgrade process and
33 scriptlet execution for each component is monitored in upgrade track‐
34 ers. A counter shows the latest index number for the most recently exe‐
35 cuted scriptlet; when all scriptlets have run, the component tracker
36 shows the updated version number.
37 The scriptlets are stored in the upgrade directory:
39 /usr/share/pki/server/upgrade/<version>/<index>-<name>
40 The version is the server version to be upgraded. The index is the
41 script execution order. The name is the scriptlet name.
42 During upgrade, the scriptlets will back up all changes to the file
44 system into the following folder:
45 /var/log/pki/server/upgrade/<version>/<index>
46 The version and index values indicate the scriptlet being executed. A
47 copy of the files and folders that are being modified or removed will
48 be stored in oldfiles. The names of the newly-added files and folders
49 will be stored in newfiles.
50 The instance upgrade process is tracked using this file:
52 /var/lib/pki/<instance>/conf/tomcat.conf
53 The subsystem upgrade process is tracked using this file:
54 /var/lib/pki/<instance>/<subsystem>/conf/CS.cfg
55 The file stores the current configuration version and the last success‐
56 ful scriptlet index.
57
60 General options
61 --silent
62 Upgrade in silent mode.
63 --status
65 Show upgrade status only without performing the upgrade.
66 --revert
68 Revert the last version.
69 -i, --instance <instance>
71 Upgrade a specific instance only.
72 -s, --subsystem <subsystem>
74 Upgrade a specific subsystem in an instance only.
75 -t, --instance-type <type>
77 Upgrade a specific instance type, by the major version number of
78 the Dogtag instance. For example, use 9 for Dogtag 9 instances
79 and 10 for Dogtag 10.
80 -X Show advanced options.
82 -v, --verbose
84 Run in verbose mode.
85 -h, --help
87 Show this help message.
88 Advanced options
91 The advanced options circumvent the normal component tracking process
92 by changing the scriptlet order or changing the tracker information.
93 WARNING: These options may render the system unusable.
95 --scriptlet-version <version>
98 Run scriptlets for a specific version only.
99 --scriptlet-index <index>
101 Run a specific scriptlet only.
102 --remove-tracker
104 Remove the tracker.
105 --reset-tracker
107 Reset the tracker to match the package version.
108 --set-tracker <version>
110 Set the tracker to a specific version.
111
114 Interactive mode
115 By default, pki-server-upgrade will run interactively to upgrade all
116 server instances and subsystems on the machine. It will ask for a con‐
117 firmation before executing each scriptlet.
118 % pki-server-upgrade
120 If there is an error, it will stop and show the error.
122 Silent mode
125 The upgrade process can also be done silently without user interaction:
126 % pki-server-upgrade --silent
128 If there is an error, the upgrade process will stop for that particular
130 instance/subsystem. Other instances/subsystems will continue to be
131 upgraded.
132 Checking upgrade status
135 It is possible to check the status of a running upgrade process.
136 % pki-server-upgrade --status
138 Troubleshooting
141 Check the scriptlet to see which operations are being executed. Once
142 the error is identified and corrected, the upgrade can be resumed by
143 re-running pki-server-upgrade.
144 If necessary, the upgrade can be run in verbose mode:
146 % pki-server-upgrade --verbose
148 It is possible to rerun a failed script by itself, specifying the
150 instance and subsystem, version, and scriptlet index:
151 % pki-server-upgrade --instance pki-tomcat --subsystem ca --scriptlet-
153 version 10.0.1 --scriptlet-index 1
154 Reverting an upgrade
157 If necessary, the upgrade can be reverted:
158 % pki-server-upgrade --revert
160 Files and folders that were created by the scriptlet will be removed.
162 Files and folders that were modified or removed by the scriptlet will
163 be restored.
164
167 /usr/sbin/pki-server-upgrade
168
171 Ade Lee <alee@redhat.com>, Ella Deon Lackey <dlackey@redhat.com>, and
172 Endi Dewata <edewata@redhat.com>. pki-server-upgrade was written by
173 the Dogtag project.
174
177 Copyright (c) 2013 Red Hat, Inc. This is licensed under the GNU General
178 Public License, version 2 (GPLv2). A copy of this license is available
179 at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
180version 1.0 Jul 22, 2013 pki-server-upgrade(8)