Description
The release handler process belongs to the SASL application, which is responsible for release handling, that is, unpacking, installation, and removal of release packages.
An introduction to release handling and an example is provided in OTP Design Principles
in System Documentation.
A release package is a compressed tar file containing code for a certain version of a release, created by calling systools:make_tar/1,2
. The release package is to be located in the $ROOT/releases
directory of the previous version of the release, where $ROOT
is the installation root directory, code:root_dir()
. Another releases
directory can be specified using the SASL configuration parameter releases_dir
or the OS environment variable RELDIR
. The release handler must have write access to this directory to install the new release. The persistent state of the release handler is stored there in a file called RELEASES
.
A release package is always to contain:
- A release resource file,
Name.rel
- A boot script,
Name.boot
The .rel
file contains information about the release: its name, version, and which ERTS and application versions it uses.
A release package can also contain:
- A release upgrade file,
relup
- A system configuration file,
sys.config
- A system configuration source file,
sys.config.src
The relup
file contains instructions for how to upgrade to, or downgrade from, this version of the release.
The release package can be unpacked, which extracts the files. An unpacked release can be installed. The currently used version of the release is then upgraded or downgraded to the specified version by evaluating the instructions in the relup
file. An installed release can be made permanent. Only one permanent release can exist in the system, and this release is used if the system is restarted. An installed release, except the permanent one, can be removed. When a release is removed, all files belonging to that release only are deleted.
Each release version has a status, which can be unpacked
, current
, permanent
, or old
. There is always one latest release, which either has status permanent
(normal case) or current
(installed, but not yet made permanent). The meaning of the status values are illustrated in the following table:
Status Action NextStatus
-------------------------------------------
- unpack unpacked
unpacked install current
remove -
current make_permanent permanent
install other old
remove -
permanent make other permanent old
install permanent
old reboot_old permanent
install current
remove -
The release handler process is a locally registered process on each node. When a release is installed in a distributed system, the release handler on each node must be called. The release installation can be synchronized between nodes. From an operator view, it can be unsatisfactory to specify each node. The aim is to install one release package in the system, no matter how many nodes there are. It is recommended that software management functions are written that take care of this problem. Such a function can have knowledge of the system architecture, so it can contact each individual release handler to install the package.
For release handling to work properly, the runtime system must know which release it is running. It must also be able to change (in runtime) which boot script and system configuration file are to be used if the system is restarted. This is taken care of automatically if Erlang is started as an embedded system. Read about this in Embedded System
in System Documentation. In this case, the system configuration file sys.config
is mandatory.
The installation of a new release can restart the system. Which program to use is specified by the SASL configuration parameter start_prg
, which defaults to $ROOT/bin/start
.
The emulator restart on Windows NT expects that the system is started using the erlsrv
program (as a service). Furthermore, the release handler expects that the service is named NodeName
_Release
, where NodeName
is the first part of the Erlang node name (up to, but not including the "@") and Release
is the current release version. The release handler furthermore expects that a program like start_erl.exe
is specified as "machine" to erlsrv
. During upgrading with restart, a new service is registered and started. The new service is set to automatic and the old service is removed when the new release is made permanent.
The release handler at a node running on a diskless machine, or with a read-only file system, must be configured accordingly using the following SASL configuration parameters (for details, see sasl(6)
):
-
masters
-
This node uses some master nodes to store and fetch release information. All master nodes must be operational whenever release information is written by this node.
-
client_directory
-
The client_directory
in the directory structure of the master nodes must be specified.
-
static_emulator
-
This parameter specifies if the Erlang emulator is statically installed at the client node. A node with a static emulator cannot dynamically switch to a new emulator, as the executable files are statically written into memory.
The release handler can also be used to unpack and install release packages when not running Erlang as an embedded system. However, in this case the user must somehow ensure that correct boot scripts and configuration files are used if the system must be restarted.
Functions are provided for using another file structure than the structure defined in OTP. These functions can be used to test a release upgrade locally.