.nh
.TH pki-server-upgrade 8 "Jul 22, 2013" PKI "PKI Server Upgrade Tool"
.SH NAME
.PP
pki-server-upgrade - Tool for upgrading PKI server configuration.

.SH SYNOPSIS
.PP
\fBpki-server\fP [\fICLI-options\fP] \fBupgrade\fP [\fIOPTIONS\fP]

.SH DESCRIPTION
.PP
There are two parts to upgrading PKI server:
upgrading the system configuration files used by both the client and the server processes
and upgrading the server configuration files.

.PP
When upgrading PKI server, the existing server configuration files (e.g. \fBserver.xml\fP, \fBweb.xml\fP)
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 \fBpki-server upgrade\fP\&.

.PP
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.

.PP
The scriptlets are stored in the upgrade directory:

.PP
.RS

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

.fi
.RE

.PP
The \fBversion\fP is the server version to be upgraded. The \fBindex\fP is the script execution order.
The \fBname\fP is the scriptlet name.

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

.PP
.RS

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

.fi
.RE

.PP
The \fBversion\fP and \fBindex\fP values indicate the scriptlet being executed.
A copy of the files and folders that are being modified or removed will be stored in \fBoldfiles\fP\&.
The names of the newly-added files and folders will be stored in \fBnewfiles\fP\&.

.PP
The instance upgrade process is tracked using this file:

.PP
.RS

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

.fi
.RE

.PP
The subsystem upgrade process is tracked using this file:

.PP
.RS

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

.fi
.RE

.PP
The file stores the current configuration version and the last successful scriptlet index.

.SH OPTIONS
.SS General options
.PP
\fB--status\fP
.br
    Show upgrade status only \fBwithout\fP performing the upgrade.

.PP
\fB--revert\fP
.br
    Revert the last version.

.PP
\fB-i\fP, \fB--instance\fP \fIinstance\fP
.br
    Upgrade a specific instance only.

.PP
\fB-X\fP
.br
    Show advanced options.

.PP
\fB-v\fP, \fB--verbose\fP
.br
    Run in verbose mode.

.PP
\fB-h\fP, \fB--help\fP
.br
    Show this help message.

.SS Advanced options
.PP
The advanced options circumvent the normal upgrade process by changing the tracker information.

.PP
\fBWARNING:\fP These options may render the system unusable.

.PP
\fB--remove-tracker\fP
.br
    Remove the tracker.

.PP
\fB--reset-tracker\fP
.br
    Reset the tracker to match the package version.

.PP
\fB--set-tracker\fP \fIversion\fP
.br
    Set the tracker to a specific version.

.SH OPERATIONS
.SS Upgrade process
.PP
To start the upgrade process:

.PP
.RS

.nf
$ pki-server upgrade

.fi
.RE

.SS Upgrade status
.PP
To check the upgrade status:

.PP
.RS

.nf
$ pki-server upgrade --status

.fi
.RE

.SS Troubleshooting
.PP
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 \fBpki-server upgrade\fP\&.

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

.PP
.RS

.nf
$ pki-server upgrade --verbose

.fi
.RE

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

.PP
.RS

.nf
$ pki-server upgrade --instance pki-tomcat

.fi
.RE

.SS Reverting an upgrade
.PP
If necessary, the upgrade can be reverted:

.PP
.RS

.nf
$ pki-server upgrade --revert

.fi
.RE

.PP
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.

.SH AUTHORS
.PP
Ade Lee &lt;alee@redhat.com&gt;, Ella Deon Lackey &lt;dlackey@redhat.com&gt;, and Endi S. Dewata &lt;edewata@redhat.com&gt;\&.

.SH COPYRIGHT
.PP
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.