Automatically Updating Platform Agents
When the central Redwood Server is updated to a new version the platform agents need to be upgraded as well. The software tries to make this as painless as possible. Platform agents can update themselves if certain conditions are met.
The central Redwood Server updates the database and other parts of the central system the first time that you run the new version. After this is complete it will (try to) start the platform agents that are marked as having automatic start. As part of the startup procedure the server sends a configuration request to the platform agent, telling it which process server parameters it is supposed to use. As part of this command it also sends its own version ID. The platform agent compares this version ID with its own version ID. If the two do not match it sends a result saying that the configuration failed because the version did not match. It will also tell the server whether it does have the required version installed (but apparently not active for this instance) and whether it is able to restart other versions.
If the server finds that the agent is able to restart but does not have the same version installed it then sends the installer for the platform agent to the existing platform agent. The platform agent stores the installer on the file system and runs the installer in non-interactive mode. The installer installs the software for the agent side-by-side to the existing installation.
Once the software is successfully installed, or if the agent mentioned that the software was already installed but not active it sends a restart request to the agent. The agent activates the new software version and then, as they say, 'magic happens'. The magic is that the old agent stops and the new agent starts. How this is accomplished differs on the platform, and is detailed below.
Requirements
- For the auto-update to function, you must install the agent in the proper manner and start it in the proper manner; by default, these conditions are met.
- On Windows, the agent must be started using a service as
NT Authority\System. - On UNIX, the agent must be started using the
${InstallDir}/<version>/bin/platform-agentshell script, in combination with the native init system. - On HP OpenVMS, the agent must be started using
SCHEDULER.COM.
- On Windows, the agent must be started using a service as
- The agent checks there is sufficient disk space available prior to attempting the update.
UNIX
For UNIX systems the most important requirement is that the platform agent is started by means of the ${InstallDir}/<version>/bin/platform-agent shell script. If this is done then the system can update itself.
The administrator can control whether auto-update is performed by creating or removing the ${InstallDir}/etc/startup/${Instance}/autoupdate directory. This is where the auto-update process will store the downloaded installer for the missing version. If this directory does not exist, the auto-update procedure is disabled. Normally, this directory is created by the installer when you answer positively to the question whether to allow auto-update. If you did not, and do not wish to re-run the installer you can enable this by creating this directory manually. Make sure the privileges are such that the network-processor program can write to that directory.
Microsoft Windows
For Microsoft Windows, ensure that the agent runs as a service running as the LocalSystem account. Only this account is able to run the installer. This is easy to do during the first time install of the platform agent: just keep the Auto update check box selected during the installation.
HP OpenVMS
On systems where no relink is needed (usually 8.x OpenVMS systems) auto-update is supported.
The COM files required are:
[.2023.2.0-20231002_11.etc]SCHEDULER.COM
[.2023.2.0-20231002_11.bin]PLATFORM-AGENT.COM
Instead of the RUN command previously recommended, starts should now be done using the SCHEDULER.COM file.
Multiple instances per tree are installed. Separate trees (installation directories) should not use the same instance names.
How it works - UNIX
When a platform agent is configured as version X, and version Y is requested by the server, the network processor first writes the correct version to file ${InstallDir}/etc/startup/${Instance}/version. Then it stops using a magic exit code. The platform-agent script recognises this and immediately restarts the platform-agent of the correct version.
For this to function you should have started the agent via the platform-agent script directly or via the boot scheduler script (recommended).
How it works - Microsoft Windows
On Microsoft Windows, the agent downloads and unpacks the installer, needs to stop its own service and start the service of the new agent. It does this by calling the Scheduler Service Manager and then waiting for a stop command. The service manager, when it succeeds in creating the new service, will stop the old service and then start the new service. If the service manager fails, it does not send the stop command to the old service, which will just keep running.
note
The Windows agent installer is not signed, however, the agent binaries therein are signed. The installer is NOT executed during auto-upgrades but merely unpacked; the signed applications therein are then used to perform the service installation. The agent checks the integrity of the downloaded file against a hash and will refrain from unpacking if there is a mismatch (meaning the installer was modified or is corrupt).
How it works - HP OpenVMS
Redwood recommends you create a symbol to the SCHEDULER.COM in your LOGIN.COM, for instance like this:
$!
$! Find the latest agent, or at least something.
$!
$loop:
$ x = f$search("[.agent.9*.bin]jtool.exe;")
$ if x .eqs. "" then goto stop
$ bindir = f$parse(x,,,"DEVICE") + f$parse(x,,,"DIRECTORY")
$ write sys$output "- Found agent directory ''bindir' for JTOOL"
$ jtool=="$''bindir'jtool.exe"
$ goto loop
$stop:
$!
$loop2:
$ x = f$search("[.agent.9*.etc]SCHEDULER.COM;")
$ if x .eqs. "" then goto stop2
$ etcdir = f$parse(x,,,"DEVICE") + f$parse(x,,,"DIRECTORY")
$ write sys$output "- Found agent directory ''etcdir' for SCHEDULER"
$ scheduler=="@''etcdir'SCHEDULER.COM"
$ goto loop2
$stop2:
The symbol can be used to stop, start, restart all instances in the installation tree or individual instances using the following syntax:
SCHEDULER {START | STOP | RESTART | START-INSTANCE <instance> | STOP-INSTANCE <instance> | ADD-INSTANCE <instance> <port> }
On an initial installation SCHEDULER.COM can be used to create a new instance:
@SCHEDULER.COM add-instance <name> <port>
This creates a number of files (if not already present):
[.etc.startup.'instance'.autoupdate] ! directory, if present: allow auto-update
[.etc.startup.'instance']version. ! current version to be used
[.etc.startup.'instance']user. ! user to run platform-agent as
[.etc.startup.'instance']loglevel. ! initial loglevel
[.net.instance.'instance'.private]secret. ! Shared secret
[.net.instance.'instance']port. ! Port number to listen on
The system keeps track of which instances are running by process name, by default PA <instance>. This can be overridden by creating a file
[.etc]process_name_fao.txt
for which the default value is:
PA !AS
where!AS is the F$FAO() substition for the process name.
Tuning
When the installation has a larger number of platform agents the system will serialize the process of sending the updated platform agent installer binaries, as these are quite large.
The number of simultaneous updates is governed by the registry parameter/configuration/PlatformAgent/SimultaneousUpdates. Change this as required, but make sure the value is at least 1 (one). The default value is 5.