The release handler is a process belonging 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 a usage example can be
found in
A release package is a compressed tar file containing
code for a certain version of a release, created by calling
A release package should always contain the release resource file
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
Each version of the release has a status. The status can be
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 may be synchronized between nodes. From an operator view, it may be unsatisfactory to specify each node. The aim is to install one release package in the system, no matter how many nodes there are. If this is the case, it is recommended that software management functions are written which take care of this problem. Such a function may 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 needs
to have knowledge about which release it is currently running. It
must also be able to change (in run-time) which boot script and
system configuration file should 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 this case, the system configuration file
A new release may restart the system. Which program to use is
specified by the SASL configuration parameter
The emulator restart on Windows NT expects that the system is
started using the
The release handler at a node which runs on a diskless machine,
or with a read-only file system, must be configured accordingly
using the following
This node uses a number of master nodes in order to store and fetch release information. All master nodes must be up and running whenever release information is written by this node.
The
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 because the executable files are statically written into memory.
It is also possible to use the release handler to unpack and install release packages when not running Erlang as an embedded system, but in this case the user must somehow make sure that correct boot scripts and configuration files are used if the system needs to be restarted.
There are additional functions for using another file structure than the structure defined in OTP. These functions can be used to test a release upgrade locally.
Checks if the specified version
This function evaluates all instructions that occur before
the
Returns the same as
If the option
Creates an initial RELEASES file to be used by the release handler. This file must exist in order to install new releases.
Installs a release dependent file in the release structure.
A release dependent file is a file that must be in
the release structure when a new release is installed:
The function can be called, for example, when these files
are generated at the target. It should be called after
Installs the specified version
If a script is found, the first thing that happens is that
the applications specifications are updated according to
the
After the application specifications have been updated,
the instructions in the script are evaluated and the function
returns
If
If a recoverable error occurs, the function returns
The option
The option
The option
The option
Example: In the current version
release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
=> {ok,NewVsn}
If
Installing a new release might be quite time consuming if there are many processes in the system. The reason is that each process must be checked for references to old code before a module can be purged. This check might lead to garbage collections and copying of data.
If you wish to speed up the execution of
Obviously, this will not reduce the overall time for the upgrade, but it will allow checks and purge to be executed in the background before the real upgrade is started.
Makes the specified version
Removes a release and its files from the system. The release must not be the permanent release. Removes only the files and directories not in use by another release.
Reboots the system by making the old release permanent, and
calls
Makes it possible to handle removal of releases outside the release handler. Tells the release handler that the release is removed from the system. This function does not delete any files.
Makes it possible to handle unpacking of releases outside
the release handler. Tells the release handler that
the release is unpacked.
Unpacks a release package
Performs some checks on the package - for example checks that all mandatory files are present - and extracts its contents.
Returns all releases known to the release handler.
The following functions can be used to test upgrade and downgrade
of single applications (instead of upgrading/downgrading an entire
release). A script corresponding to
These functions are primarily intended for simplified testing
of
No persistent information is updated, why these functions can be used on any Erlang node, embedded or not. Also, using these functions does not effect which code will be loaded in case of a reboot.
If the upgrade or downgrade fails, the application may end up in an inconsistent state.
Upgrades an application
The function looks in the
Returns
Downgrades an application
The function looks in the
Returns
Tries to find an application upgrade script for
The upgrade script can then be evaluated using
The function looks in the
Returns
Failure: If a script cannot be found, the function fails with an appropriate error reason.
Tries to find an application downgrade script for
The downgrade script can then be evaluated using
The function looks in the
Returns
Failure: If a script cannot be found, the function fails with an appropriate error reason.
Evaluates an application upgrade or downgrade script
Returns