1pki-server-upgrade(8) PKI Server Upgrade Tool pki-server-upgrade(8)
2
6 pki-server-upgrade - Tool for upgrading PKI server configuration.
7
10 pki-server [CLI-options] upgrade [OPTIONS]
11
14 There are two parts to upgrading PKI server: upgrading the system con‐
15 figuration files used by both the client and the server processes and
16 upgrading the server configuration files.
17 When upgrading PKI server, the existing server configuration files
20 (e.g. server.xml, web.xml) may need to be upgraded because the content
21 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
24 pki-server upgrade.
25 The server upgrade process is done incrementally using upgrade
28 scriptlets. A server consists of the server instance itself and the
29 subsystems running in that instance. The upgrade process executes one
30 scriptlet at a time, running through each component (server instance
31 and subsystem) in parallel and completing before executing the next
32 scriptlet. If one component encounters an error, that component is
33 skipped in the subsequent upgrade scriptlets. The upgrade process and
34 scriptlet execution for each component is monitored in upgrade track‐
35 ers. A counter shows the latest index number for the most recently
36 executed scriptlet; when all scriptlets have run, the component tracker
37 shows the updated version number.
38 The scriptlets are stored in the upgrade directory:
41 /usr/share/pki/server/upgrade/<version>/<index>-<name>
44 The version is the server version to be upgraded. The index is the
48 script execution order. The name is the scriptlet name.
49 During upgrade, the scriptlets will back up all changes to the file
52 system into the following folder:
53 /var/log/pki/server/upgrade/<version>/<index>
56 The version and index values indicate the scriptlet being executed. A
60 copy of the files and folders that are being modified or removed will
61 be stored in oldfiles. The names of the newly-added files and folders
62 will be stored in newfiles.
63 The instance upgrade process is tracked using this file:
66 /var/lib/pki/<instance>/conf/tomcat.conf
69 The subsystem upgrade process is tracked using this file:
73 /var/lib/pki/<instance>/<subsystem>/conf/CS.cfg
76 The file stores the current configuration version and the last success‐
80 ful scriptlet index.
81
84 General options
85 --silent
86 Upgrade in silent mode.
87 --status
90 Show upgrade status only without performing the upgrade.
91 --revert
94 Revert the last version.
95 -i, --instance instance
98 Upgrade a specific instance only.
99 -s, --subsystem subsystem
102 Upgrade a specific subsystem in an instance only.
103 -t, --instance-type type
106 Upgrade a specific instance type, by the major version number of
107 the Dogtag instance.
108 For example, use 9 for Dogtag 9 instances and 10 for Dogtag 10.
109 -X
112 Show advanced options.
113 -v, --verbose
116 Run in verbose mode.
117 -h, --help
120 Show this help message.
121 Advanced options
124 The advanced options circumvent the normal component tracking process
125 by changing the scriptlet order or changing the tracker information.
126 WARNING: These options may render the system unusable.
129 --scriptlet-version version
132 Run scriptlets for a specific version only.
133 --scriptlet-index index
136 Run a specific scriptlet only.
137 --remove-tracker
140 Remove the tracker.
141 --reset-tracker
144 Reset the tracker to match the package version.
145 --set-tracker version
148 Set the tracker to a specific version.
149
152 Interactive mode
153 By default, pki-server upgrade will run interactively to upgrade all
154 server instances and subsystems on the machine. It will ask for a con‐
155 firmation before executing each scriptlet.
156 $ pki-server upgrade
159 If there is an error, it will stop and show the error.
163 Silent mode
166 The upgrade process can also be done silently without user interaction:
167 $ pki-server upgrade --silent
170 If there is an error, the upgrade process will stop for that particular
174 instance/subsystem. Other instances/subsystems will continue to be
175 upgraded.
176 Checking upgrade status
179 It is possible to check the status of a running upgrade process.
180 $ pki-server upgrade --status
183 Troubleshooting
187 Check the scriptlet to see which operations are being executed. Once
188 the error is identified and corrected, the upgrade can be resumed by
189 re-running pki-server upgrade.
190 If necessary, the upgrade can be run in verbose mode:
193 $ pki-server upgrade --verbose
196 It is possible to rerun a failed script by itself, specifying the
200 instance and subsystem, version, and scriptlet index:
201 $ pki-server upgrade --instance pki-tomcat --subsystem ca --scriptlet-version 10.0.1 --scriptlet-index 1
204 Reverting an upgrade
208 If necessary, the upgrade can be reverted:
209 $ pki-server upgrade --revert
212 Files and folders that were created by the scriptlet will be removed.
216 Files and folders that were modified or removed by the scriptlet will
217 be restored.
218
221 Ade Lee lt;alee@redhat.comgt;, Ella Deon Lackey lt;dlackey@red‐
222 hat.comgt;, and Endi S. Dewata lt;edewata@redhat.comgt;.
223
226 Copyright (c) 2013 Red Hat, Inc. This is licensed under the GNU Gen‐
227 eral Public License, version 2 (GPLv2). A copy of this license is
228 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
229PKI Jul 22, 2013 pki-server-upgrade(8)