release_handler - A process to unpack and install releases.

The release handler process belongs to the SASL application and handles unpacking, installation, and removal of release packages.

A release package is a compressed tar file containing code for a release, see systools(3). The release package should be placed in the $ROOT/releases directory of a 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 in order to install the new release. The persistent state of the release handler is stored there in a file called RELEASES.

A release package always contains the release resource file Name.rel and a boot script Name.boot. It may contain a release upgrade file relup and a system configuration file sys.config. The .rel file contains information about the release: its name, version, and which ERTS and application versions it uses. The relup file contains scripts 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 relup. An installed release can be made permanent. There can only be one permanent release in the system, and this is the release that is used if the system is restarted. An installed release, except the permanent one, can be removed. When a release is removed, all files that belong to that release only are deleted.

Each version of the release has a status. The status 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 following table illustrates the meaning of the status values:

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. Therefore, Erlang must be started as an embedded system. Read about this in Embedded System.

A new release may 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 nodename (up to, but not including the "@") and Release is the current release of the application. 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 will be registered and started. The new service will be set to automatic and the old service removed as soon as the new release is made permanent.

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 sasl configuration parameters:

masters: 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.

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 because the executable files are statically written into memory.

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.

check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}

Types

Vsn = OtherVsn = string()

Descr = term()

Checks if the specified version Vsn of the release can be installed. The release must not have status current. Issues warnings if relup or sys.config are not present. If relup is present, its contents are checked and {error, Reason} is returned if an error is found. Also checks that all required applications are present and that all new code can be loaded, or {error, Reason} is returned.

This function evaluates all instructions that occur before the point_of_no_return instruction in the release upgrade script.

Returns the same as install_release/1. Descr defaults to "" if no relup file is found.

create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}

Types

Root = RelDir = RelFile = string()

AppDirs = [{App, Vsn, Dir}]

 App = atom()

 Vsn = Dir = string()

Creates an initial RELEASES file to be used by the release handler. This file must exist in order to install new releases.

Root is the root of the installation as described above. RelDir is the the releases directory where the RELASES file should be created. RelFile is the name of the .rel file that describes the initial release.

AppDirs can be used to specify from where the modules for an application should be loaded. App is the name of the application, Vsn is the version, and Dir is the name of the directory where App-Vsn is located. The corresponding modules should be located under Dir/App-Vsn/ebin.

install_file(Vsn, FileName) -> ok | {error, Reason}

Types

Vsn = FileName = string()

Reason = term()

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: start.boot, relup and sys.config.

The function can be called, for example, when these files are generated at the target. It should be called after set_unpacked/2 has been called.

install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}

install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason}

Types

Vsn = OtherVsn = string()

Opt = {error_action, Action} | {code_change_timeout, Timeout} | {suspend_timeout, Timeout}

 Action = restart | reboot

 Timeout = default | infinity | int()>0

Descr = term()

Installs the specfied version Vsn of the release. The release must not have status current. Looks first for a relup file for Vsn and a script {UpFromVsn, Descr, Instructions} in this file for upgrading from the current version. If not found, the function looks for a relup file for the current version and a script {Vsn, Descr, Instructions} in this file for downgrading to Vsn. Returns {error, Reason} if no script is found.

If a script is found, the first thing that happens is that the applications specifications are updated according to the .app files and sys.config belonging to the release version Vsn.

Note that sys.config is required and that no other system configuration files should be used as that may lead to inconsistent updating of configuration parameters.

After the application specifications have been updated, the instructions in the script are evaluated and the function returns {ok, OtherVsn, Descr} if successful or {error, Reason} if a recoverable error occurs. In the latter case the original application specifications are restored. OtherVsn and Descr are the version and description as specified in the script. If a non-recoverable error occurs, the system is restarted.

The option error_action defines if the node should be restarted (init:restart()) or rebooted init:reboot() in case of an error during the installation. Default is restart.

The option code_change_timeout defines the timeout for all calls to sys:change_code. If no value is specified or default is given, the default value defined in sys is used.

The option suspend_timeout defines the timeout for all calls to sys:suspend. If no value is specified, the values defined by the Timeout parameter of the upgrade or suspend instructions are used. If default is specified, the default value defined in sys is used.

make_permanent(Vsn) -> ok | {error, Reason}

Types

Vsn = string()

Makes the specified version Vsn of the release permanent.

remove_release(Vsn) -> ok | {error, Reason}

Types

Vsn = string()

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.

reboot_old_release(Vsn) -> ok | {error, Reason}

Types

Vsn = string()

Reason = {no_such_release, Vsn}

Reboots the system by making the old release permanent, and calls init:reboot() directly. The release must have status old.

set_removed(Vsn) -> ok | {error, Reason}

Types

Vsn = string()

Reason = {no_such_release, Vsn} | {permanent, Vsn}

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.

set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}

Types

RelFile = string()

AppDirs = [{App, Vsn, Dir}]

 App = atom()

 Vsn = Dir = string()

Vsn = string()

Makes it possible to handle unpacking of releases outside the release handler. Tells the release handler that the release is unpacked. Vsn is extracted from the release resource file RelFile.

AppDirs can be used to specify from where the modules for an application should be loaded. App is the name of the application, Vsn is the version, and Dir is the name of the directory where the directory App-Vsn is located. The corresponding modules should be located under Dir/App-Vsn/ebin.

unpack_release(N) -> {ok, Vsn} | {error, Reason}

Types

Name = Vsn = string()

Reason = term()

Unpacks a release package Name.tar.gz located in the releases directory.

Performs some checks on the package - for example checks that all mandatory files are present - and extracts its contents.

which_releases() -> [{Name, Vsn, Apps, Status}]

Types

Name = Vsn = string()

Apps = ["App-Vsn"]

Status = unpacked | current | permanent | old

Returns all releases known to the release handler.

OTP Design Principles, config(4), relup(4), script(4), sys(3), systools(3)

Martin Björklund - support@erlang.ericsson.se
Gunilla Arendt - support@erlang.ericsson.se