1pki-server-upgrade(8)       PKI Server Upgrade Tool      pki-server-upgrade(8)
2
3
4

NAME

6       pki-server-upgrade - Tool for upgrading PKI server configuration.
7
8

SYNOPSIS

10       pki-server [CLI-options] upgrade [OPTIONS]
11
12

DESCRIPTION

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
18
19       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
26
27       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
39
40       The scriptlets are stored in the upgrade directory:
41
42
43              /usr/share/pki/server/upgrade/<version>/<index>-<name>
44
45
46
47       The version is the server version to be  upgraded.  The  index  is  the
48       script execution order.  The name is the scriptlet name.
49
50
51       During  upgrade,  the  scriptlets  will back up all changes to the file
52       system into the following folder:
53
54
55              /var/log/pki/server/upgrade/<version>/<index>
56
57
58
59       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
64
65       The instance upgrade process is tracked using this file:
66
67
68              /var/lib/pki/<instance>/conf/tomcat.conf
69
70
71
72       The subsystem upgrade process is tracked using this file:
73
74
75              /var/lib/pki/<instance>/<subsystem>/conf/CS.cfg
76
77
78
79       The file stores the current configuration version and the last success‐
80       ful scriptlet index.
81
82

OPTIONS

84   General options
85       --silent
86           Upgrade in silent mode.
87
88
89       --status
90           Show upgrade status only without performing the upgrade.
91
92
93       --revert
94           Revert the last version.
95
96
97       -i, --instance instance
98           Upgrade a specific instance only.
99
100
101       -s, --subsystem subsystem
102           Upgrade a specific subsystem in an instance only.
103
104
105       -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
110
111       -X
112           Show advanced options.
113
114
115       -v, --verbose
116           Run in verbose mode.
117
118
119       -h, --help
120           Show this help message.
121
122
123   Advanced options
124       The  advanced  options circumvent the normal component tracking process
125       by changing the scriptlet order or changing the tracker information.
126
127
128       WARNING: These options may render the system unusable.
129
130
131       --scriptlet-version version
132           Run scriptlets for a specific version only.
133
134
135       --scriptlet-index index
136           Run a specific scriptlet only.
137
138
139       --remove-tracker
140           Remove the tracker.
141
142
143       --reset-tracker
144           Reset the tracker to match the package version.
145
146
147       --set-tracker version
148           Set the tracker to a specific version.
149
150

OPERATIONS

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
157
158              $ pki-server upgrade
159
160
161
162       If there is an error, it will stop and show the error.
163
164
165   Silent mode
166       The upgrade process can also be done silently without user interaction:
167
168
169              $ pki-server upgrade --silent
170
171
172
173       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
177
178   Checking upgrade status
179       It is possible to check the status of a running upgrade process.
180
181
182              $ pki-server upgrade --status
183
184
185
186   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
191
192       If necessary, the upgrade can be run in verbose mode:
193
194
195              $ pki-server upgrade --verbose
196
197
198
199       It is possible to rerun a  failed  script  by  itself,  specifying  the
200       instance and subsystem, version, and scriptlet index:
201
202
203              $ pki-server upgrade --instance pki-tomcat --subsystem ca --scriptlet-version 10.0.1 --scriptlet-index 1
204
205
206
207   Reverting an upgrade
208       If necessary, the upgrade can be reverted:
209
210
211              $ pki-server upgrade --revert
212
213
214
215       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
219

AUTHORS

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
224
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.
229
230
231
232PKI                              Jul 22, 2013            pki-server-upgrade(8)
Impressum