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

       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 confirmation 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 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.