diff options
| -rw-r--r-- | base/common/CMakeLists.txt | 11 | ||||
| -rw-r--r-- | base/common/man/man8/pki-upgrade.8 | 165 | ||||
| -rwxr-xr-x | base/common/sbin/pki-upgrade | 26 | ||||
| -rw-r--r-- | base/server/man/man8/pki-server-upgrade.8 | 184 | ||||
| -rwxr-xr-x | base/server/sbin/pki-server-upgrade | 34 | ||||
| -rw-r--r-- | specs/pki-core.spec | 14 |
6 files changed, 402 insertions, 32 deletions
diff --git a/base/common/CMakeLists.txt b/base/common/CMakeLists.txt index e2b2a2f15..1c6ef9b54 100644 --- a/base/common/CMakeLists.txt +++ b/base/common/CMakeLists.txt @@ -76,5 +76,16 @@ install( ${SYSTEMD_ETC_INSTALL_DIR}/pki-tomcatd.target.wants ) +install( + DIRECTORY + man/ + DESTINATION + ${MAN_INSTALL_DIR} + FILE_PERMISSIONS + OWNER_READ OWNER_WRITE + GROUP_READ + WORLD_READ +) + add_subdirectory(src) add_subdirectory(test) diff --git a/base/common/man/man8/pki-upgrade.8 b/base/common/man/man8/pki-upgrade.8 new file mode 100644 index 000000000..dcddeb779 --- /dev/null +++ b/base/common/man/man8/pki-upgrade.8 @@ -0,0 +1,165 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-upgrade 8 "Jul 22, 2013" "version 1.0" "PKI Upgrade Tool" Endi S. Dewata +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-upgrade \- Tool for upgrading system-wide configuration for +Certificate System. + +.SH SYNOPSIS +\fBpki-upgrade\fR [OPTIONS] + +.SH 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 system configuration files (e.g. +\fB/etc/pki/pki.conf\fR) 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-upgrade\fP. + +The system upgrade process is done incrementally using upgrade scriptlets. The upgrade process +and scriptlet execution 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: +.RS +/usr/share/pki/upgrade/<version>/<index>-<name> +.RE +The \fBversion\fP is the system version to be upgraded. The \fBindex\fP +is the script execution order. The \fBname\fP is the scriptlet name. + +During upgrade, the scriptlets will back up all changes to the filesystem into the +following folder: +.RS +/var/log/pki/upgrade/<version>/<index> +.RE +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. + +The system upgrade process is tracked using this file: +.RS +/etc/pki/pki.version +.RE +The file stores the current configuration version and the last successful +scriptlet index. + +.SH OPTIONS + +.SS General options + +.TP +.B --silent +Upgrade in silent mode. +.TP +.B --status +Show upgrade status only \fBwithout\fP performing the upgrade. +.TP +.B --revert +Revert the last version. +.TP +.B -X +Show advanced options. +.TP +.B -v, --verbose +Run in verbose mode. +.TP +.B -h, --help +Show this help message. + +.SS Advanced options +The advanced options circumvent the normal component tracking process by changing the +scriptlet order or changing the tracker information. + +\fBWARNING:\fP These options may render the system unusable. + +.TP +.B --scriptlet-version <version> +Run scriptlets for a specific version only. +.TP +.B --scriptlet-index <index> +Run a specific scriptlet only. +.TP +.B --remove-tracker +Remove the tracker. +.TP +.B --reset-tracker +Reset the tracker to match the package version. +.TP +.B --set-tracker <version> +Set the tracker to a specific version. + +.SH OPERATIONS + +.SS Interactive mode + +By default, \fBpki-upgrade\fP will run interactively. It will ask for a confirmation +before executing each scriptlet. + +.B % pki-upgrade + +If there is an error, it will stop and show the error. + +.SS Silent mode + +The upgrade process can also be done silently without user interaction: + +.B % pki-upgrade --silent + +If there is an error, it will stop and show the error. + +.SS Checking upgrade status + +It is possible to check the status of a running upgrade process. + +.B % pki-upgrade --status + +.SS Troubleshooting + +If there is an error, rerun the upgrade in verbose mode: + +.B % pki-upgrade --verbose + +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-upgrade\fP. + +It is possible to rerun a failed script by itself, specifying the +instance and subsystem, version, and scriptlet index: + +.B % pki-upgrade --scriptlet-version 10.0.1 --scriptlet-index 1 + +.SS Reverting an upgrade + +If necessary, the upgrade can be reverted: + +.B % pki-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. + +.SH FILES +.I /usr/sbin/pki-upgrade + +.SH AUTHORS +Ade Lee <alee@redhat.com>, Ella Deon Lackey <dlackey@redhat.com>, and Endi Dewata <edewata@redhat.com>. +\fBpki-upgrade\fP was written by the Dogtag project. + +.SH 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. diff --git a/base/common/sbin/pki-upgrade b/base/common/sbin/pki-upgrade index f7216d0d0..a985f76f3 100755 --- a/base/common/sbin/pki-upgrade +++ b/base/common/sbin/pki-upgrade @@ -37,24 +37,25 @@ def interrupt_handler(event, frame): def usage(): print 'Usage: pki-upgrade [OPTIONS]' print - print ' --scriptlet-version <version> Run scriptlets for a specific version only.' - print ' --scriptlet-index <index> Run a specific scriptlet only.' - print - print ' --silent Upgrade in silent mode. Ignore any failures.' + print ' --silent Upgrade in silent mode.' print ' --status Show upgrade status only. Do not perform upgrade.' - print ' --revert Revert the last version' + print ' --revert Revert the last version.' print - print ' -X Show advanced usage.' + print ' -X Show advanced options.' print ' -v, --verbose Run in verbose mode.' print ' -h, --help Show this help message.' -def advancedUsage(): +def advancedOptions(): + print print 'WARNING: These options may render the system unusable.' - print 'Usage: pki-upgrade [OPTIONS]' - print ' --remove-tracker Remove tracker' - print ' --reset-tracker Reset tracker to match package version' - print ' --set-tracker <version> Set tracker to a specific version' + print + print ' --scriptlet-version <version> Run scriptlets for a specific version only.' + print ' --scriptlet-index <index> Run a specific scriptlet only.' + print + print ' --remove-tracker Remove tracker.' + print ' --reset-tracker Reset tracker to match package version.' + print ' --set-tracker <version> Set tracker to a specific version.' def main(argv): @@ -118,7 +119,8 @@ def main(argv): sys.exit() elif o == '-X': - advancedUsage() + usage() + advancedOptions() sys.exit() else: diff --git a/base/server/man/man8/pki-server-upgrade.8 b/base/server/man/man8/pki-server-upgrade.8 new file mode 100644 index 000000000..25e32743f --- /dev/null +++ b/base/server/man/man8/pki-server-upgrade.8 @@ -0,0 +1,184 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server-upgrade 8 "Jul 22, 2013" "version 1.0" "PKI Server Upgrade Tool" Endi S. Dewata +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server-upgrade \- Tool for upgrading Certificate System server configuration. + +.SH SYNOPSIS +\fBpki-server-upgrade\fR [OPTIONS] + +.SH 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. +\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. + +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: +.RS +/usr/share/pki/server/upgrade/<version>/<index>-<name> +.RE +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. + +During upgrade, the scriptlets will back up all changes to the file system into the +following folder: +.RS +/var/log/pki/server/upgrade/<version>/<index> +.RE +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. + +The instance upgrade process is tracked using this file: +.RS +/var/lib/pki/<instance>/conf/tomcat.conf +.RE +The subsystem upgrade process is tracked using this file: +.RS +/var/lib/pki/<instance>/<subsystem>/conf/CS.cfg +.RE +The file stores the current configuration version and the last successful +scriptlet index. + +.SH OPTIONS + +.SS General options + +.TP +.B --silent +Upgrade in silent mode. +.TP +.B --status +Show upgrade status only \fBwithout\fP performing the upgrade. +.TP +.B --revert +Revert the last version. +.TP +.B -i, --instance <instance> +Upgrade a specific instance only. +.TP +.B -s, --subsystem <subsystem> +Upgrade a specific subsystem in an instance only. +.TP +.B -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. +.TP +.B -X +Show advanced options. +.TP +.B -v, --verbose +Run in verbose mode. +.TP +.B -h, --help +Show this help message. + +.SS Advanced options +The advanced options circumvent the normal component tracking process by changing the +scriptlet order or changing the tracker information. + +\fBWARNING:\fP These options may render the system unusable. + +.TP +.B --scriptlet-version <version> +Run scriptlets for a specific version only. +.TP +.B --scriptlet-index <index> +Run a specific scriptlet only. +.TP +.B --remove-tracker +Remove the tracker. +.TP +.B --reset-tracker +Reset the tracker to match the package version. +.TP +.B --set-tracker <version> +Set the tracker to a specific version. + +.SH OPERATIONS + +.SS Interactive mode + +By default, \fBpki-server-upgrade\fP will run interactively to upgrade all +server instances and subsystems on the machine. It will ask for a confirmation +before +executing each scriptlet. + +.B % pki-server-upgrade + +If there is an error, it will stop and show the error. + +.SS Silent mode + +The upgrade process can also be done silently without user interaction: + +.B % 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. + +.SS Checking upgrade status + +It is possible to check the status of a running upgrade process. + +.B % pki-server-upgrade --status + +.SS 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 +\fBpki-server-upgrade\fP. + +If necessary, the upgrade can be run in verbose mode: + +.B % pki-server-upgrade --verbose + +It is possible to rerun a failed script by itself, specifying the +instance and subsystem, version, and scriptlet index: + +.B % pki-server-upgrade --instance pki-tomcat --subsystem ca --scriptlet-version 10.0.1 --scriptlet-index 1 + +.SS Reverting an upgrade + +If necessary, the upgrade can be reverted: + +.B % 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. + +.SH FILES +.I /usr/sbin/pki-server-upgrade + +.SH AUTHORS +Ade Lee <alee@redhat.com>, Ella Deon Lackey <dlackey@redhat.com>, and Endi Dewata <edewata@redhat.com>. +\fBpki-server-upgrade\fP was written by the Dogtag project. + +.SH 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. diff --git a/base/server/sbin/pki-server-upgrade b/base/server/sbin/pki-server-upgrade index dbe7aedb8..f9fd20951 100755 --- a/base/server/sbin/pki-server-upgrade +++ b/base/server/sbin/pki-server-upgrade @@ -38,29 +38,30 @@ def interrupt_handler(event, frame): def usage(): print 'Usage: pki-server-upgrade [OPTIONS]' print + print ' --silent Upgrade in silent mode.' + print ' --status Show upgrade status only. Do not perform upgrade.' + print ' --revert Revert the last version.' + print print ' -i, --instance <instance> Upgrade a specific instance only.' print ' -s, --subsystem <subsystem> Upgrade a specific subsystem in an instance only.' - print ' -t, --instance-type <type> Specify 9 for upgraded Dogtag 9 instances only,' - print ' 10 for Dogtag 10 instances only.' - print - print ' --scriptlet-version <version> Run scriptlets for a specific version only.' - print ' --scriptlet-index <index> Run a specific scriptlet only.' - print - print ' --silent Upgrade in silent mode. Ignore any failures.' - print ' --status Show upgrade status only. Do not perform upgrade.' - print ' --revert Revert the last version' + print ' -t, --instance-type <type> Upgrade a specific instance type.' + print ' Specify 9 for Dogtag 9 instances, 10 for Dogtag 10.' print - print ' -X Show advanced usage.' + print ' -X Show advanced options.' print ' -v, --verbose Run in verbose mode.' print ' -h, --help Show this help message.' -def advancedUsage(): +def advancedOptions(): + print print 'WARNING: These options may render the system unusable.' - print 'Usage: pki-upgrade [OPTIONS]' - print ' --remove-tracker Remove tracker' - print ' --reset-tracker Reset tracker to match package version' - print ' --set-tracker <version> Set tracker to a specific version' + print + print ' --scriptlet-version <version> Run scriptlets for a specific version only.' + print ' --scriptlet-index <index> Run a specific scriptlet only.' + print + print ' --remove-tracker Remove tracker.' + print ' --reset-tracker Reset tracker to match package version.' + print ' --set-tracker <version> Set tracker to a specific version.' def main(argv): @@ -138,7 +139,8 @@ def main(argv): sys.exit() elif o == '-X': - advancedUsage() + usage() + advancedOptions() sys.exit() else: diff --git a/specs/pki-core.spec b/specs/pki-core.spec index 3dede1eaa..555f492af 100644 --- a/specs/pki-core.spec +++ b/specs/pki-core.spec @@ -5,7 +5,7 @@ distutils.sysconfig import get_python_lib; print(get_python_lib(1))")} Name: pki-core Version: 10.1.0 -Release: 0.6%{?dist} +Release: 0.7%{?dist} Summary: Certificate System - PKI Core Components URL: http://pki.fedoraproject.org/ License: GPLv2 @@ -895,6 +895,7 @@ fi %{python_sitelib}/pki/*.pyo %dir %{_localstatedir}/log/pki %{_sbindir}/pki-upgrade +%{_mandir}/man8/pki-upgrade.8.gz %files -n pki-tools %defattr(-,root,root,-) @@ -928,7 +929,7 @@ fi %{_bindir}/TokenInfo %{_javadir}/pki/pki-tools.jar %{_datadir}/pki/java-tools/ -%{_mandir}/man1/* +%{_mandir}/man1/pki.1.gz %files -n pki-server @@ -968,8 +969,10 @@ fi %{_bindir}/pkisilent %{_datadir}/pki/silent/ %{_bindir}/pkicontrol -%{_mandir}/man5/* -%{_mandir}/man8/* +%{_mandir}/man5/pki_default.cfg.5.gz +%{_mandir}/man8/pki-server-upgrade.8.gz +%{_mandir}/man8/pkidestroy.8.gz +%{_mandir}/man8/pkispawn.8.gz # Details: # @@ -1083,6 +1086,9 @@ fi %changelog +* Mon Jul 22 2013 Endi S. Dewata <edewata@redhat.com> 10.1.0-0.7 +- Added man pages for upgrade tools. + * Wed Jul 17 2013 Endi S. Dewata <edewata@redhat.com> 10.1.0-0.6 - Cleaned up the code to install man pages. |