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.