From bc99de26e30747560d9f33716aa9cb598925388e Mon Sep 17 00:00:00 2001
From: "Endi S. Dewata" <edewata@redhat.com>
Date: Wed, 10 Jul 2013 11:20:25 -0400
Subject: [PATCH] Added man pages for upgrade tools.

New man pages have been added for pki-upgrade and pki-server-upgrade.
The spec file and build scripts have been updated accordingly.

Ticket #582
---
 base/common/CMakeLists.txt                |  11 ++
 base/common/man/man8/pki-upgrade.8        | 153 ++++++++++++++++++++++++++++
 base/common/sbin/pki-upgrade              |  26 ++---
 base/java-tools/CMakeLists.txt            |  14 +--
 base/server/CMakeLists.txt                |  26 ++---
 base/server/man/man8/pki-server-upgrade.8 | 164 ++++++++++++++++++++++++++++++
 base/server/sbin/pki-server-upgrade       |  34 ++++---
 specs/pki-core.spec                       |  18 ++--
 8 files changed, 384 insertions(+), 62 deletions(-)
 create mode 100644 base/common/man/man8/pki-upgrade.8
 create mode 100644 base/server/man/man8/pki-server-upgrade.8

diff --git a/base/common/CMakeLists.txt b/base/common/CMakeLists.txt
index 3798503c06c9fa44df1354f4e0654e34964bd670..40d3048fc6b07cee8dc547e9b23e95da110167b3 100644
--- a/base/common/CMakeLists.txt
+++ b/base/common/CMakeLists.txt
@@ -114,5 +114,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 0000000000000000000000000000000000000000..069d0df2463c94ee29c814068752dc216b950332
--- /dev/null
+++ b/base/common/man/man8/pki-upgrade.8
@@ -0,0 +1,153 @@
+.\" 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 10, 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
+When upgrading Certificate System the existing system configuration files (e.g.
+/etc/pki/pki.conf) 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 upgrade process is done incrementally using upgrade scriptlets. The scriptlets
+are stored in the following location:
+.RS
+/usr/share/pki/upgrade/<version>/<index>-<name>
+.RE
+The \fBversion\fP indicates the system version to be upgraded. The \fBindex\fP
+indicates the script execution order. The \fBname\fP indicates the scriptlet name.
+
+During upgrade the scriptlets will backup all changes to the file system into
+the following folder:
+.RS
+/var/log/pki/upgrade/<version>/<index>
+.RE
+The \fBversion\fP and \fBindex\fP indicate the scriptlet being executed. Files
+and folders that are modified or removed will be stored in \fBoldfiles\fP. Files
+and folders that are newly created will be recorded in \fBnewfiles\fP.
+
+The 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.
+
+.SH OPTIONS
+
+.SS General options
+
+.TP
+.B --silent
+Upgrade in silent mode.
+.TP
+.B --status
+Show upgrade status only. Do not perform 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
+
+WARNING: 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 tracker.
+.TP
+.B --reset-tracker
+Reset tracker to match package version.
+.TP
+.B --set-tracker <version>
+Set tracker to a specific version.
+
+.SH OPERATIONS
+
+.SS Interactive mode
+
+By default pki-upgrade 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
+
+To check upgrade status execute the following command:
+
+.B % pki-upgrade --status
+
+.SS Troubleshooting
+
+If there is an error, rerun upgrade in verbose mode:
+
+.B % pki-upgrade --verbose
+
+Check the scriptlet to see what the operations being executed. Once the
+error is identified and corrected, the upgrade can be resumed by re-running
+pki-upgrade again.
+
+If necessary, the upgrade can be run in verbose mode:
+
+.B % pki-upgrade --verbose
+
+.SS Reverting upgrade
+
+If necessary, the upgrade can be reverted using the following command:
+
+.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> 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 48fb48b933e65bfad6655955fb74b49dd0e3e5bf..c2aa4e4e8aa19ea27bbc2fcc438c63c37d9c5a63 100755
--- a/base/common/sbin/pki-upgrade
+++ b/base/common/sbin/pki-upgrade
@@ -37,24 +37,25 @@ def interrupt_handler(signal, 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/java-tools/CMakeLists.txt b/base/java-tools/CMakeLists.txt
index 430985d710eaced527a1291814856a6ebdca3f00..d34290690469117321195ff7ec97231dd4f65a4e 100644
--- a/base/java-tools/CMakeLists.txt
+++ b/base/java-tools/CMakeLists.txt
@@ -1,14 +1,14 @@
 project(java-tools NONE)
 
 install(
-    FILES
-        man/man1/pki.1
+    DIRECTORY
+        man/
     DESTINATION
-        ${MAN_INSTALL_DIR}/man1
-    PERMISSIONS
-        OWNER_EXECUTE OWNER_WRITE OWNER_READ
-        GROUP_EXECUTE GROUP_READ
-        WORLD_EXECUTE WORLD_READ
+        ${MAN_INSTALL_DIR}
+    FILE_PERMISSIONS
+        OWNER_READ OWNER_WRITE
+        GROUP_READ
+        WORLD_READ
 )
 
 install(
diff --git a/base/server/CMakeLists.txt b/base/server/CMakeLists.txt
index 8beedbb67aae865522105633d305d5e6f9a85f3e..f157b4fed195cd450f398254f1b638e5ce670e71 100644
--- a/base/server/CMakeLists.txt
+++ b/base/server/CMakeLists.txt
@@ -22,26 +22,14 @@ set(APACHE_SUBSYSTEMS
 )
 
 install(
-    FILES
-        man/man5/pki_default.cfg.5
+    DIRECTORY
+        man/
     DESTINATION
-        ${MAN_INSTALL_DIR}/man5
-    PERMISSIONS
-        OWNER_EXECUTE OWNER_WRITE OWNER_READ
-        GROUP_EXECUTE GROUP_READ
-        WORLD_EXECUTE WORLD_READ
-)
-
-install(
-    FILES
-        man/man8/pkispawn.8
-        man/man8/pkidestroy.8
-    DESTINATION
-        ${MAN_INSTALL_DIR}/man8
-    PERMISSIONS
-        OWNER_EXECUTE OWNER_WRITE OWNER_READ
-        GROUP_EXECUTE GROUP_READ
-        WORLD_EXECUTE WORLD_READ
+        ${MAN_INSTALL_DIR}
+    FILE_PERMISSIONS
+        OWNER_READ OWNER_WRITE
+        GROUP_READ
+        WORLD_READ
 )
 
 # install Python libraries
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 0000000000000000000000000000000000000000..92796af98a1d90668271304a2b032ea6c61dbc07
--- /dev/null
+++ b/base/server/man/man8/pki-server-upgrade.8
@@ -0,0 +1,164 @@
+.\" 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 10, 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
+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 \fBpki-server-upgrade\fP.
+
+The upgrade process is done incrementally using upgrade scriptlets. The scriptlets
+are stored in the following location:
+.RS
+/usr/share/pki/server/upgrade/<version>/<index>-<name>
+.RE
+The \fBversion\fP indicates the system version to be upgraded. The \fBindex\fP
+indicates the script execution order. The \fBname\fP indicates the scriptlet name.
+
+During upgrade the scriptlets will backup 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 indicate the scriptlet being executed. Files
+and folders that are modified or removed will be stored in \fBoldfiles\fP. The
+newly created files and folders will be recorded in \fBnewfiles\fP.
+
+A server consists of the server instance itself and the subsystems running in
+that instance. 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.
+
+.SH OPTIONS
+
+.SS General options
+
+.TP
+.B --silent
+Upgrade in silent mode.
+.TP
+.B --status
+Show upgrade status only. Do not perform 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. Specify 9 for Dogtag 9 instances, 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
+
+WARNING: 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 tracker.
+.TP
+.B --reset-tracker
+Reset tracker to match package version.
+.TP
+.B --set-tracker <version>
+Set tracker to a specific version.
+
+.SH OPERATIONS
+
+.SS Interactive mode
+
+By default pki-server-upgrade will run interactively to upgrade all instances
+and all 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
+
+To check upgrade status execute the following command:
+
+.B % pki-server-upgrade --status
+
+.SS Troubleshooting
+
+Check the scriptlet to see what the operations being executed. Once the
+error is identified and corrected, the upgrade can be resumed by re-running
+pki-server-upgrade again.
+
+If necessary, the upgrade can be run in verbose mode:
+
+.B % pki-server-upgrade --verbose
+
+.SS Reverting upgrade
+
+If necessary, the upgrade can be reverted using the following command:
+
+.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> 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 59db87ba2634139ddf077a0d6eadad3a2f4e3bf7..6ad4a39c8301f1b65406f4467962122e5628166b 100755
--- a/base/server/sbin/pki-server-upgrade
+++ b/base/server/sbin/pki-server-upgrade
@@ -38,29 +38,30 @@ def interrupt_handler(signal, 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 '  -t, --instance-type <type>     Upgrade a specific instance type.'
+    print '                                 Specify 9 for Dogtag 9 instances, 10 for Dogtag 10.'
     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
-    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 fe0564563b7b08d153aacf20a74ecf515a4db425..0489ef0c73fef194e4d1353458649bd711b7ac70 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.4%{?dist}
+Release:          0.5%{?dist}
 Summary:          Certificate System - PKI Core Components
 URL:              http://pki.fedoraproject.org/
 License:          GPLv2
@@ -526,10 +526,6 @@ cd build
 cd build
 %{__make} install DESTDIR=%{buildroot} INSTALL="install -p"
 
-chmod 644 %{buildroot}%{_mandir}/man1/*
-chmod 644 %{buildroot}%{_mandir}/man5/*
-chmod 644 %{buildroot}%{_mandir}/man8/*
-
 # Fedora 18 and 17:  Substitute 'tomcat7jss.jar' for 'tomcatjss.jar'
 %if ! 0%{?rhel} && 0%{?fedora} <= 18
 	sed -i -e 's/grant codeBase "file:\/usr\/share\/java\/tomcatjss.jar" {/grant codeBase "file:\/usr\/share\/java\/tomcat7jss.jar" {/' %{buildroot}%{_datadir}/pki/server/conf/pki.policy
@@ -899,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,-)
@@ -932,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
@@ -973,8 +970,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:
 #
@@ -1088,6 +1087,9 @@ fi
 
 
 %changelog
+* Tue Jul 10 2013 Endi S. Dewata <edewata@redhat.com> 10.1.0-0.5
+- Added man pages for upgrade tools.
+
 * Tue Jul 9 2013 Ade Lee <alee@redhat.com> 10.1.0-0.4
 - Bugzilla Bug 973224 -  resteasy-base must be split into subpackages
   to simplify dependencies
-- 
1.8.1.4

