pki-server-upgrade(8)					      PKI Server Upgrade Tool					     pki-server-upgrade(8)

NAME

       pki-server-upgrade - Tool for upgrading Certificate System server configuration.

SYNOPSIS

       pki-server-upgrade [OPTIONS]

DESCRIPTION

       There  are  two parts to upgrading Certificate System: upgrading the system configuration files used by both the client and the server pro-
       cesses and upgrading the server configuration files.

       When upgrading Certificate System, the existing server configuration files (e.g.  server.xml, web.xml) 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  subsys-
       tems  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:
	      /usr/share/pki/server/upgrade/<version>/<index>-<name>
       The version is the server version to be upgraded. The index is the 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:
	      /var/log/pki/server/upgrade/<version>/<index>
       The version and index 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:
	      /var/lib/pki/<instance>/conf/tomcat.conf
       The subsystem upgrade process is tracked using this file:
	      /var/lib/pki/<instance>/<subsystem>/conf/CS.cfg
       The file stores the current configuration version and the last successful scriptlet index.

OPTIONS

   General options
       --silent
	      Upgrade in silent mode.

       --status
	      Show upgrade status only without performing the upgrade.

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

       -X     Show advanced options.

       -v, --verbose
	      Run in verbose mode.

       -h, --help
	      Show this help message.

   Advanced options
       The advanced options circumvent the normal component tracking process by changing the scriptlet order or changing the tracker information.

       WARNING: 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-tracker
	      Remove the tracker.

       --reset-tracker
	      Reset the tracker to match the package version.

       --set-tracker <version>
	      Set the tracker to a specific version.

OPERATIONS

   Interactive mode
       By default, pki-server-upgrade will run interactively to upgrade all server instances and subsystems on the machine. It will ask for a con-
       firmation before executing each scriptlet.

       % pki-server-upgrade

       If there is an error, it will stop and show the error.

   Silent mode
       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.

   Checking upgrade status
       It is possible to check the status of a running upgrade process.

       % pki-server-upgrade --status

   Troubleshooting
       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 pki-server-upgrade.

       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

   Reverting an upgrade
       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.

FILES

       /usr/sbin/pki-server-upgrade

AUTHORS

       Ade  Lee <alee@redhat.com>, Ella Deon Lackey <dlackey@redhat.com>, and Endi Dewata <edewata@redhat.com>.  pki-server-upgrade was written by
       the Dogtag project.

COPYRIGHT

       Copyright (c) 2013 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is avail-
       able at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.

version 1.0							   Jul 22, 2013 					     pki-server-upgrade(8)