This document describes everything there is to know regarding Upgrade-UX, an Open Source upgrade and patching framework designed to assist the UNIX system engineer in patching or upgrading systems in a consistent and repeatable way with evidence before and after the running upgrade-ux.

1. Introduction

Upgrade-UX is ai software framework to update or patch lots of Unix systems (Linux, HP-UX, AIX and Solaris).

In professional environments it is not allowed to just blindly update an UNIX system without testing this first out on a development system, pre-production and so on. The upgrade-ux product allows you to repeat this process in a consistent way and as many times as you like on any system. Upgrade-ux understands two states:

  • preview mode: will go through the whole process without actually doing the update

  • upgrade mode: will do it for real (the update)

The upgrade-ux uses configuration files which describes what a particular Unix Operating System requires to be upgraded in the way you want it (or designed it). Doing it this way allows you to exactly define how a system should look like after the upgrade or patching. Nothing else can be installed, removed or configured.

Furthermore, many checks can be build-in via adding simple scripts (see chapter "Adding your scripts"). We also keep of each run an unique log file, and furthermore, we keep evidence before and after patching in a special directory. Months later we can still inspect these logs and evidence directories to verify what happened or what has changed in the meantime.

1.1. Upgrade-UX project

The support and development of the Upgrade-UX project takes place on Github:

Upgrade-UX website

http://www.it3.be/projects/upgrade-ux.html

Github project

http://github.com/gdha/upgrade-ux/

In case you have questions, ideas or feedback about this document, you can contact the development team at: gratien.dhaese@gmail.com.

1.2. Design concepts

Based on experience from previous projects, a set of design principles were defined, and improved over time:

  • Focus on easy and repeatable tasks

  • Modular design, focused on system administrators

  • For Unix operating systems

  • Few external dependencies (ksh and standard Unix tools)

  • Easy to use and easy to extend

The goal is to make Upgrade-UX as least demanding as possible, it will require only the applications necessary to fulfill the job upgrade-ux is configured for.

1.3. Features and functionality

Upgrade-UX has a wide range of features:

  • Simple to use

  • Has a preview mode (to dry-run an upgrade without doing it) and an upgrade mode

  • Is customisable via local.conf configuration file

  • Is written in standard Korn Shell (which makes it highly portable)

  • Is UNIX Operating System independent as OS specific tasks reside in their own directory structures

  • Is easy extendable with your own scripts

  • The upgrade-ux command leaves a trace in its own log file

  • Running in preview or upgrade mode always creates evidence files

  • Has a man page

  • Has user documentation (you are reading it)

  • Can be used to install patch bundles of previous years with the YEAR variable

  • Does understand Serviceguard clusters

  • Can be programmed to bail out on settings you think are too serious to continue

  • Can trigger remote alarms, syslog, monitors,…

  • Can do a basis health check of your system - it is all up to you

  • Has excellent support by its author

2. Getting started

You can use upgrade-ux via installing the sources or the software depot (HP-UX, Linux,…)

2.1. Clone the sources via GitHub

The latest sources are available at GitHub and to clone the sources on your local Unix you could use

git clone git@github.com:gdha/upgrade-ux.git

To enter the directory use the command

cd upgrade-ux/opt/upgrade-ux

2.2. Installing the software depot on HP-UX

If the software depot was already been made available by the system administrator then you can use swinstall to do the job. The following is the output of the command swinstall -s SDserver:/var/opt/ignite/depots/GLOBAL/tools/11i UPGRADE-UX

2.3. Installing the RPM package on Linux (RHEL, SLES)

When the RPM is available you could install it via the command:

rpm -ivh upgrade-ux-1.0-1.el7.noarch.rpm

Or, in case you would liek to upgrade a version via yum you could do the following:

rpm -Uvh upgrade-ux-1.1-1.el7.noarch.rpm

2.4. Prerequisites

Be aware, that upgrade-ux is completely written in Korn Shell, therefore, you must have the ksh executable on your UNIX system. To be sure you could type which ksh. If it is not present please install it first (most likely on Linux where it is not a standard package in base OS).

3. Configuration

3.1. Upgrade-ux related configuration files

The configuration files that upgrade-ux uses are basically just shell scripts and should be treated as such.

The default location of the configuration files is /etc/opt/upgrade-ux/. However, if you are working with the sources (e.g. via git clone) then it is perfectly possible to use the relative paths, e.g.

ls $HOME/project/upgrade-ux/etc/opt/upgrade-ux/

The easiest way to explain which configuration files are possible is by showing the output of the upgrade-ux dump command:

3.1.1. Default configuration file default.conf

The default.conf contains lots of variables which should not be changed by the end-user. If you wish to modify one just redefine it in the local.conf file.

A good example of such variable is the YEAR. In the default.conf it is defined as:

# The default year to use with our patch bundle is *current year* [ $(date '+%Y') ] - to overrule define it manually
# in the local.conf file. E.g. when running upgrade-ux in 2015 but still installing patches from 2014 then define: YEAR=2014
YEAR=$(date '+%Y')

However, in some cases as mentioned above, if you are in the year 2015 and you still want to install patch bundles of 2014 then it is necessary to define the YEAR variable in the local.conf file, as YEAR=2014 (or whatever, the year might be).

3.1.2. Local configuration file local.conf

The local.conf should only contain variables which you want to overrule, as described in previous section (of the default.conf file). It is important to know that the local.conf file is the last configuration file read by upgrade-ux script and therefore, the variables defined in there are the last ones that will be used.

3.1.3. Exclude packages from the update process

The /etc/opt/upgrade/exclude.packages file contains a list of packages you wish to exclude from the update. This file is the same for HP-UX or Linux. A safe-guard is built-in to remove packages which are not found (installed) on current system. Use one line per package you wish to exclude. This file is not mandatory, so it does not have to exist for upgrade-ux to work properly (nothing will be excluded then).

3.1.4. Operating Specific configuration files

On each OS you have specific OS related configuration files, e.g.

HP-UX.conf
GNU/Linux.conf
SunOS.conf

These configuration files typically contain variables which have only a meaning within that specific OS, e.g. on HP-UX

SWINSTALL=/usr/sbin/swinstall

3.2. The INI files

The INI files are always OS specific and contain the definitions of which patch bundles should be installed or removed, and so on. The INI files are kept under the /etc/opt/upgrade-ux or $HOME/project/upgrade-ux/etc/opt/upgrade-ux/ directory and are typically called $OS-$OS_VERSION-$YEAR.ini

It follows also the different stages known within upgrade-ux and these are best explained with an example INI file (below you see the INI file for HP-UX 11.11 systems):

# HP-UX-11.11-2014.ini file
###########################
#
###################
# section preremove - which sd depots must be removed before we install the latest one (or even run update-ux)
###################
[preremove]
    command[0]      =       $SWREMOVE
    options[0]      =       "-x mount_all_filesystems=false  -x enforce_dependencies=false"
    bundle[0]       =       CFG2HTML
    version[0]      =       "C.06.*"         ; cfg2html
command[1]      =       $SWREMOVE
options[1]      =       "-x mount_all_filesystems=false  -x enforce_dependencies=false"
bundle[1]       =       NCS_UTILS
version[1]      =       "*"
####################
# section preinstall - anything to do before running the installation of patches, software or update-ux
####################
[preinstall]
#################
# section install - what shall we do during the installation phase
#################
# please list the software bundles which do not require a reboot first!!!
[install]
    # SecureShell
    command[0]      =       $SWINSTALL
    options[0]      =       "-x mount_all_filesystems=false"
    source[0]       =       "-s $SDSERVER:/var/opt/ignite/depots/GLOBAL/SSH/11.11"
    bundle[0]       =       T1471AA
    version[0]      =       A.06.20.004
# the centrifyDC is the same for all HP-UX 11i versions
command[1]      =       $SWINSTALL
options[1]      =       "-x mount_all_filesystems=false"
source[1]       =       "-s $SDSERVER:/var/opt/ignite/depots/GLOBAL/centrify/11.11/V5"
bundle[1]       =       "CentrifyDC"
version[1]      =       "5.1.1-831"
command[2]      =       $SWINSTALL
options[2]      =       "-x mount_all_filesystems=false"
source[2]       =       "-s $SDSERVER:/var/opt/ignite/depots/GLOBAL/centrify/11.31/V5"
bundle[2]       =       "Centrify_conf"
version[2]      =       "5.1.x"
command[3]      =       $SWINSTALL
options[3]      =       "-x mount_all_filesystems=false -x autoreboot=true"
source[3]       =       "-s $SDSERVER:/var/opt/ignite/depots/GLOBAL/jnjdrv11-11-may2014"
bundle[3]       =       "*"
version[3]      =       ""
#####################
# section postinstall
#####################
# Use this section for additional (internal) software bundles - we assume no reboots are required
[postinstall]
####################
# section postremove
####################
[postremove]
###################
# section configure
###################
# or define explicit commands (real cmds) with options or define script tag [string] which
# may be picked up by a script (under scripts/configure/default/)
[configure]
    command[0]      =       uncomment_cfg2html_in_crontab
    options[0]      =       ""
#################
# section cleanup
#################
[cleanup]
#####################
# section postexecute
#####################
[postexecute]
    command[0]      =       "/opt/cfg2html/bin/cfg2html"
    options[0]      =       "-2%Y%m%d"

3.2.1. The INI syntax

You can use as many comments as you like, but it should start with # or ; sign.

A stage or section is started with [section] header. The name within a section is known as a stage within upgrade-ux.

A section may be empty or may contain arrays (some of those may be left out and will be treated as empty strings). An array will always be treated as a string by the way. The content of arrays are wiped out when you enter a new stage (or section) by upgrade-ux.

The following arrays are known to upgrade-ux:

  • command[] - add the command to be executed (it can be a variable name, e.g. $SWINSTALL)

  • options[] - add here specific options required by command[]

  • source[] - should be the source location where the software bundle reside

  • bundle[] - the name of the software bundle

  • version[] - the specific version to be installed/removed (can contain * or may be empty as well)

If you do not need all arrays in a certain section then it is fine to leave these empty (or not mentioning these in the INI file)

Be careful although that you define the array index correctly in the INI file (see example above).

3.2.2. Section preremove

In the preremove section you typically define lines of software bundles that should be removed for one of other reason, e.g. when upgrading these would be problematic (in the way the software was designed - read badly). As said, if not needed leave this section empty.

3.2.3. Section preinstall

In the preinstall section we could define some commands that need to be run, but in most case we write small scripts to do specific tasks in this stage (or section) such as stopping some daemons, saving evidence of software inventory and so on. More about thiese scripts in Chapter 6 (The Upgrade-ux scripts).

3.2.4. Section install

In the install section you typically only define the software bundles that should be installed and in the right order. For example, for update the installation software (update-ux or yum) before the new updates. In this stage we do not have much special scripts.

3.2.5. Section postinstall

In the postinstall section we define the software pieces that were missing in the install section for some specific reason (if any). Furthermore, in this stage we capture lots of evidence again and compare these via special scripts. Again see Chapter 6 (The Upgrade-ux scripts).

3.2.6. Section postremove

In the postremove section you could remove software bundles taht were in the big update round of the install section, but should not stay on this particular platform for some reason. Again, you may leave it empty if not needed.

3.2.7. Section configure

In the configure section you could define scripts or commands to be executed by upgrade-ux to configure or add something in cron. See also the example shown above with uncomment_cfg2html_in_crontab, which is a toggle meant for a script called /opt/upgrade-ux/scripts/configure/default/10_configure_commands.sh that simply touches a file under $TMP_DIR

Another way to had this defined would have been:

command[0]="touch"
options[0]="$TMP_DIR/uncomment_cfg2html_in_crontab"

3.2.8. Section cleanup

In the cleanup section we could add commands to remove some old log files (of older software bundles), or you can also use it to report errors or any other message. The section is typically empty, but you could add some special scripts under /opt/upgrade-ux/scripts/cleanup/default/

3.2.9. Section postexecute

In the postexecute section you could define commands and options of things you want to execute, e.g.

command[0]      =       "/opt/cfg2html/bin/cfg2html"
options[0]      =       "-2%Y%m%d"

4. Workflows

The workflows (or commands) available can be listed with the -h option:

# /opt/upgrade-ux/bin/upgrade-ux -h
    ....
    List of commands:
     dump            dump configuration and system information
     mkdist          create a compressed tar archive distribution
     purgelogs       purge the LOG [/home/gdhaese1/projects/upgrade-ux/var/opt/upgrade-ux/log] directory
     test            a simple test workflow
     upgrade         upgrade the operating system

4.1. Dump workflow

The dump workflow was already discussed during the configuration chapter. The output of /opt/upgrade-ux/bin/upgrade-ux dump:

# /opt/upgrade-ux/bin/upgrade-ux dump
upgrade-ux 0.7 / 03-Jun-2014
Using log file: /var/opt/upgrade-ux/log/upgrade-ux-20140626-1656-hostname.log
Dumping out configuration and system information
System definition:
                                    ARCH = HP-UX-ia64
                                      OS = HP-UX
                        OS_MASTER_VENDOR =
                       OS_MASTER_VERSION =
                   OS_MASTER_VENDOR_ARCH =
                OS_MASTER_VENDOR_VERSION =
           OS_MASTER_VENDOR_VERSION_ARCH =
                               OS_VENDOR = hp
                              OS_VERSION = 11.31
                          OS_VENDOR_ARCH = hp/ia64
                       OS_VENDOR_VERSION = hp/11.31
                  OS_VENDOR_VERSION_ARCH = hp/11.31/ia64
Configuration tree:
                         HP-UX-ia64.conf : missing/empty
                              HP-UX.conf : OK
                                 hp.conf : missing/empty
                            hp/ia64.conf : missing/empty
                           hp/11.31.conf : missing/empty
                      hp/11.31/ia64.conf : missing/empty
                               site.conf : missing/empty
                              local.conf : OK

The first part displays the system definitions, such as OS, hardware type and OS version. The second part shows the configuration part and which files it could find (or you may define, create and/or use). They do not need to exist.

The following example shows the dump on a RHEL 7 system:

# /opt/upgrade-ux/bin/upgrade-ux dump
upgrade-ux 0.9 / Git
Using log file: /var/opt/upgrade-ux/log/upgrade-ux-20140626-1859-hostname.log
Dumping out configuration and system information
This is a 'Linux-x86_64' system, compatible with 'Linux-i386'.
System definition:
                                    ARCH = Linux-i386
                                      OS = GNU/Linux
                        OS_MASTER_VENDOR = fedora
                       OS_MASTER_VERSION = 7
                   OS_MASTER_VENDOR_ARCH = fedora/x86_64
                OS_MASTER_VENDOR_VERSION = fedora/7
           OS_MASTER_VENDOR_VERSION_ARCH = fedora/7/x86_64
                               OS_VENDOR = rhel
                              OS_VERSION = 7
                          OS_VENDOR_ARCH = rhel/x86_64
                       OS_VENDOR_VERSION = rhel/7
                  OS_VENDOR_VERSION_ARCH = rhel/7/x86_64
Configuration tree:
                         Linux-i386.conf : missing/empty
                          GNU/Linux.conf : OK
                             fedora.conf : missing/empty
                      fedora/x86_64.conf : missing/empty
                           fedora/7.conf : missing/empty
                    fedora/7/x86_64.conf : missing/empty
                               rhel.conf : missing/empty
                        rhel/x86_64.conf : missing/empty
                             rhel/7.conf : missing/empty
                      rhel/7/x86_64.conf : missing/empty
                               site.conf : missing/empty
                              local.conf : OK

These configuration files live under the /etc/opt/upgrade-ux or ./upgrade-ux/etc/opt/upgrade-ux (relative path) directory. At this moment we have the following configuration files present (however, it will grow over time):

    # ls -lR
    total 112
    drwxr-xr-x   2 gdhaese1   users         8192 Mar  6 13:39 GNU
    -rw-r--r--   1 gdhaese1   users         2919 Jun  3 15:07 HP-UX-11.11-2014.ini
    -rw-r--r--   1 gdhaese1   users         2918 Jun  3 15:07 HP-UX-11.23-2014.ini
    -rw-r--r--   1 gdhaese1   users         3687 Jun  3 15:06 HP-UX-11.31-2014.ini
    -rw-r--r--   1 gdhaese1   users         1068 May 12 10:52 HP-UX.conf
    -rw-r--r--   1 gdhaese1   users         4571 Jun 13 14:58 default.conf
    -rw-r--r--   1 gdhaese1   users          790 May 21 09:48 local.conf

    ./GNU:
    total 48
    -rw-r--r--   1 gdhaese1   users          102 Mar  6 13:39 Linux-fedora-20-2014.ini
    -rw-r--r--   1 gdhaese1   users          111 Mar  6 13:39 Linux-suse-11-2014.ini
    -rw-r--r--   1 gdhaese1   users           74 Mar  6 10:43 Linux.conf

4.2. Mkdist workflow

The mkdist workflow creates a compressed tar file of the current development tree, which only makes sense when you are using the git clone version of upgrade-ux. The compressed tar file is stored under /tmp file system and is called /tmp/upgrade-ux-0.9.tar.gz (the version can be different of course).

4.3. Purgelogs workflow

The purgelogs workflow just has a simple function and that is to purge log files which are older than 30 days. It will display the logs it has purged (only when you are using the option -v):

# opt/upgrade-ux/bin/upgrade-ux -v purgelogs

4.4. Test workflow

The test workflow is a very simplistic test (use option -v to see something):

# opt/upgrade-ux/bin/upgrade-ux -v test
upgrade-ux 0.9 / Git
Using log file: /home/gdhaese1/projects/upgrade-ux/var/opt/upgrade-ux/log/upgrade-ux-20140625-1354-hostname.log
no stale NFS mount points found

4.5. Upgrade workflow

The upgrade workflow is the real work horse here and in fact is the default workflow (meaning if no workflow is mentioned we will assume you mean upgrade).

The upgrade workflow has two modes:

  • preview mode: is going through the complete flow checking all software and simulating an update of the system. Is a perfect way to examine your system to see whether any underlying issues could prevent a successful upgrade. You can do the preview (option -p) any time and as much as you like. However, before doing the upgrade mode you are forced to go through a successful preview mode as well.

  • upgrade mode: is doing again all the checks, writing evidence and applying all the patch bundles or doing the upgrade. The system might reboot. After the reboot you can continue with retyping /opt/upgrade-ux/bin/upgrade-ux -v and it will continue from the point it was interrupted by the reboot as upgrade-ux keeps track of it stages.

5. Basic Usage

Before digging deeper in upgrade-ux lets explain the basic usage. The option help (-h) will produce the following:

# /opt/upgrade-ux/bin/upgrade-ux -h
Usage: upgrade-ux [-dDFsSpvV] [-c DIR ] COMMAND [-- ARGS...]

upgrade-ux comes with ABSOLUTELY NO WARRANTY; for details see
the GNU General Public License at: http://www.gnu.org/licenses/gpl.html

Available options:
 -c DIR       alternative config directory; instead of /etc/opt/upgrade-ux
 -d           debug mode; log debug messages
 -D           debugscript mode; log every function call
 -F           forcing preview or upgrade to continue when entering next stage is not allowed
 -s           simulation mode; show what scripts upgrade-ux would include
 -S           step-by-step mode; acknowledge each script individually
 -p           preview mode; run all install or other commands in preview
 -v           verbose mode; show more output
 -V           version information

List of commands:
 dump            dump configuration and system information
 mkdist          create a compressed tar archive distribution
 purgelogs       purge the LOG [/var/opt/upgrade-ux/log] directory
 test            a simple test workflow
 upgrade         upgrade the operating system

Keep in mind that upgrade-ux has an excellent man page too. See man 8 upgrade-ux

It is important to know that upgrade-ux is a quiet program and will not show any output if you do not request for it with the verbose option (-v). Another point of interest is its excellent logging facilities as under /var/opt/upgrade-ux/log directory upgrade-ux keep a log file of each run. The log files are composed as follow upgrade-ux-<YYYYMMDD>-<HHMM>-hostname.log

We already mentioned the evidence files which are kept under /var/opt/upgrade-ux/<YYYY-MM-DD>/ directory. The type of files you find under there are of course different according the OS, OS version and which software is installed. Furthermore, preview and upgrade mode may result in more or less evidence files.

Starting up the program should be done by referencing the full path /opt/upgrade-ux/bin/upgrade-ux as the directory is not part of the PATH variable, and we prefer to keep it this way to avoid accidents.

You probably understood by now that upgrade-ux must be started in preview mode first before we can run it in upgrade mode. However, we prefer that you always use the option -p (preview mode) to make it clear to yourself and other (when they need to dig into the log files for some reason) what you meant. Furthermore, in the log file there is always a trace of in which mode the program was running:

2014-06-10 15:22:45 Check if our PID (11950) is locked
2014-06-10 15:22:45 Found /tmp/upgrade-ux-LOCKDIR/upgrade-ux-PIDFILE file - we could be locked...
2014-06-10 15:22:45 lock is stale (6607) - will continue
2014-06-10 15:22:45 lock succeeded: 11950 - /tmp/upgrade-ux-LOCKDIR/upgrade-ux-PIDFILE
2014-06-10 15:22:47 upgrade-ux 0.7 / 03-Jun-2014
2014-06-10 15:22:47 Command line options: /opt/upgrade-ux/bin/upgrade-ux -v
2014-06-10 15:22:47 Using log file: /var/opt/upgrade-ux/log/upgrade-ux-20140610-1522-hostname.log
2014-06-10 15:22:47 Including /opt/upgrade-ux/lib/progresssubsystem.nosh
2014-06-10 15:22:47 Including /etc/opt/upgrade-ux/HP-UX.conf
2014-06-10 15:22:47 Including /etc/opt/upgrade-ux/local.conf
2014-06-10 15:22:47 Running upgrade workflow
2014-06-10 15:22:47 Running 'init' stage
2014-06-10 15:22:47 Including init/default/03_prepare_tmp_build_area.sh
2014-06-10 15:22:47 Including init/default/04_create_var_dir.sh
2014-06-10 15:22:47 Including init/default/05_select_ini_file.sh
2014-06-10 15:22:47 Found ini file /etc/opt/upgrade-ux/HP-UX-11.11-2014.ini
2014-06-10 15:22:47 Including init/default/08_set_preview_var.sh
2014-06-10 15:22:47 Including init/default/10_check_current_status.sh
2014-06-10 15:22:47 Including init/default/12_upgrade_allowed.sh
2014-06-10 15:22:47 Including init/default/15_check_preview_run.sh
2014-06-10 15:22:47 Last preview run was executed on Tue Jun 10 14:28:36 METDST 2014  (preview ended successfully)
2014-06-10 15:22:47 Running in "upgrade mode"
2014-06-10 15:22:47 =-=-=-=-=-=-=-=-=-=-=-=-=

From the Chapter "Workflow" you probably remember that the default workflow is upgrade (even if you did not mention it). So, as example running upgrade-ux in preview mode with verbose option is done as /opt/upgrade-ux/bin/upgrade-ux -vp

The last option that we bring to your attention in this Chapter is the force option (-F) which is handy in situation that for some reasons upgrade-ux does not want to continue due to serious software (patches) problems. For example, within HP-UX we run the check_patches command which when errors are detected will force an exit from upgrade-ux so that the System Administrator can first fix these patches (or any other issue) before re-running upgrade-ux again. We have seen cases it was impossible to get everything fixed and for that reason you may use the force option, but please do not use it by default.

Note
 We advise to run the preview mode a few weeks in advance, but on a given day we must run the preview first again before we can run in upgrade mode. This is done on purpose to avoid mistakes.

6. Upgrade Operation

The upgrade operation (or workflow) is the default one and does not need to be mentioned explecitely on the command line. The upgrade operation goes through different stages to accomplish a successful upgrade or patch installation. The stages in use are:

init

The init stage is what we call the initialization stage where we create a temporary work directory, read the INI file, decides if we are running in preview or upgrade mode, read the current status

prep

The prep stage is the preparation stage where we can save, copy lots of files as evidence (before we start patching). You could also use it to investigate if the health of the system is good enough to start with an upgrade and if not, warn the user and exit.

preremove

The prepremove stage is doing what its name applies - remove software before upgrading. It may be a handy if you know old pieces of software could lead to inconsistencies. Usually, we make sure that a more recent version gets installed during or after the upgrade.

preinstall

The preinstall stage is used by scripts to stop daemons and other processes which may generate conflicts during the upgrade.

install

The install stage is the part where we actually install software, do the patching or start with the updates of software bundles and drivers. This part must be described in the INI file (install section).

postinstall

The postinstall stage is mainly used to install extra software bundles which were mot part of the global patch bundles or update depots. Also here, these must be described in the INI file (postinstall section). Furthermore, we tend to save evidence during this stage (as we did in the prep stage) so we can compare if something trial was modified and if so, warn the user about it.

postremove

The postremove stage is just there in case some software bundles must be removed again to avoid conflicts. Usually, this stage is empty.

configure

The configure stage is used to setup cron entries, user permission or whatever you can think of.

postexecute

The postexecute stage is used to execute some program, such as cfg2html to grab a new base point of the system. Again, you can run other programs as well such as HPSIM-HealthCheck.sh and so on

Every time you enter or leave a stage the /var/opt/upgrade-ux/status gets updated with a timestamp and the stage name with an addtional notification of start or ended. Upgrade-ux will not delete this status file, but will always append to it so you get a nice historic view of all the runs.

# cat /var/opt/upgrade-ux/status
2014-06-13 13:12:26 init:start
2014-06-13 13:12:27 init:ended
2014-06-13 13:12:27 prep:start
2014-06-13 13:12:36 prep:ended
2014-06-13 13:12:36 preremove:start
2014-06-13 13:12:45 preremove:ended
2014-06-13 13:12:45 preinstall:start
2014-06-13 13:12:51 preinstall:ended
2014-06-13 13:12:51 install:start
2014-06-13 13:25:30 install:ended
2014-06-13 13:25:30 postinstall:start
2014-06-13 13:27:41 postinstall:ended
2014-06-13 13:27:41 postremove:start
2014-06-13 13:27:41 postremove:ended
2014-06-13 13:27:41 configure:start
2014-06-13 13:27:41 configure:ended
2014-06-13 13:27:41 postexecute:start
2014-06-13 13:28:19 postexecute:ended
2014-06-13 13:28:19 preview:ended   (preview ended successfully)
2014-06-13 13:34:09 init:start
2014-06-13 13:34:10 init:ended
2014-06-13 13:34:10 prep:start
2014-06-13 13:34:19 prep:ended
2014-06-13 13:34:19 preremove:start
2014-06-13 13:34:31 preremove:ended
2014-06-13 13:34:31 preinstall:start
2014-06-13 13:35:56 preinstall:ended
2014-06-13 13:35:56 install:start
2014-06-13 15:36:57 install:ended
2014-06-13 15:36:58 postinstall:start
2014-06-13 15:45:49 postinstall:ended
2014-06-13 15:45:49 postremove:start
2014-06-13 15:45:49 postremove:ended
2014-06-13 15:45:49 configure:start
2014-06-13 15:45:49 configure:ended
2014-06-13 15:45:49 postexecute:start
2014-06-13 15:55:21 postexecute:ended
2014-06-13 15:55:21 upgrade:ended   (upgrade ended successfully)

7. The upgrade-ux scripts

The scripts that are sourced by the main script upgrade-ux reside under /opt/upgrade-ux/scripts/ directory and the easiest way to know what will be sourced is by running /opt/upgrade-ux/bin/upgrade-ux -s:

Note
 It depends on the OS architecture (see dump workflow) which scripts will be sources. In above example it was on HP hardware.

In every stage directory you will find minumum a default directory which is sourced by every OS and a hardware specific directory, such as:

  • hp

  • GNU/Linux

  • sunos

  • aix

The scripts found under these directories are only sourced when you run upgrade-ux on those HW architectures (make sense, no?). If you need new scripts just write a small script called my_script.sh (the .sh is important!) and it will be picked up the next time automatically.

Note
 there is no need to make these small scripts executable (nor is it required to start with #!/bin/sh or whatever).

An example of such a script is /opt/upgrade-ux/scripts/preinstall/default/05_reboot_required.sh

# cat preinstall/default/05_reboot_required.sh
# 05_reboot_required.sh
# if the uptime of the system is higher then 30 days then we propose to reboot first

# pre-define daysup as 0 (we can check this variable later [after a reboot])
daysup=0

# when uptime is not expressed in days then we probably just rebooted our system
uptime | grep -q days || return

daysup=$( uptime | awk '{print $3}' )
IsDigit $daysup || daysup=$( w | head -1 | awk '{print $3}' )  # alternative method
IsDigit $daysup || daysup=0

if [[ $daysup -gt $DAYSUPTIME ]]; then
    if (( PREVIEW )) ; then
        LogPrint "Uptime of system is $daysup (>$DAYSUPTIME days) - recommend to reboot before patching"
    else
        Error "Uptime of system is $daysup (>$DAYSUPTIME days) - reboot is required before patching with $PRODUCT"
    fi
fi

Now it is up to you! If you wish to add new scripts it is always usefull to first make a new issue at GitHub: https://github.com/gdha/upgrade-ux/issues

8. Frequently Asked Questions

8.1. Upgrade-ux not found

If you get the following error when you try to run upgrade-ux

# upgrade-ux
sh: upgrade-ux:  not found.

The reason is that the absolute path /opt/upgrade-ux/bin is not added the the PATH variable. This is done on purpose to avoid mistakes! Therefore, always use the full path /opt/upgrade-ux/bin/upgrade-ux

8.2. Why upgrade-ux as we know update-ux

This question is only valid for HP-UX 11i systems which can be upgraded to a newer version of the Operation System (say HP-UX 11.23 to HP-UX 11.31), or even using update-ux to upgrade software bundles on the same OS version. We have encountered situations where the UNIX engineer by accident started update-ux on HP-UX 11.23 to patch with HP-UX 11.23 bundles, but using the HP-UX 11.31 depot, and therefore, update-ux started the upgrade process to HP-UX 11.31. As a result we needed to recover from an Ignite/UX image before restarting the patching round again. By using upgrade-ux this simply becomes impossible as all update paths are described in the configuration files.

8.3. How do we install a patch bundle from 1 or 2 years ago?

The YEAR variable defines the current year ( $(date +%Y) ) of the patch bundles in the /etc/opt/upgrade-ux/default.conf file. However, suppose we are in the year 2015 and still would like to install the patch bundle of 2014? The easiest way is to overrule the YEAR variable in the /etc/opt/upgrade-ux/local.conf as

YEAR=2014

8.4. How gets the SDSERVER variable defined

You might wonder how we define the SDSERVER? And, is it possible to overrule it with your preference? The SDSERVER variable is used a lot in the INI files and points to an IP address or FQDN of an software depot server where the software depots are stored.

The SDSERVER variable is defined by a script scripts/init/hp/30_define_sdserver.sh and tries to figure out the region you are located in. Be aware, this script only works well for one particular customer (the sponsor of this project).

Therefore, for other users, you need to define the SDSERVER variable in the /etc/opt/upgrade-ux/local.conf file as

SDSERVER=my_sdserver.company.com

Obviously, you need to replace the name my_sdserver.company.com with the correct name of the software depot server.

8.5. Upgrade-ux forces me to reboot the server if system is running for more then 30 days

The forced reboot was introduced into upgrade-ux, because sometimes servers got patches after running over 1 year without a single reboot and to avoid pin-points to bad patch bundles we decided a recent reboot was required (by default 30 days uptime is the maximum we tolerate).

However, in rare cases, some customers want to extend this period to 60 days. So, how to do this?

The variable which defines the uptime is called DAYSUPTIME and is defined in /etc/opt/upgrade-ux/default.conf. As you should know by now, you can overrule this by defining a new value in the /etc/opt/upgrade-ux/local.conf file as

DAYSUPTIME=60

However, be aware, if you increase this value then do not file an issue against upgrade-ux!