Unpacking and Installation of Release Packages

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.

Typical Error Reasons

• {bad_masters, Masters} - The master nodes Masters are not alive.

• {bad_rel_file, File} - Specified .rel file File cannot be read or does not contain a single term.

• {bad_rel_data, Data} - Specified .rel file does not contain a recognized release specification, but another term Data.

• {bad_relup_file, File} - Specified relup file Relup contains bad data.

• {cannot_extract_file, Name, Reason} - Problems when extracting from a tar file, erl_tar:extract/2 returned {error, {Name, Reason}}.

• {existing_release, Vsn} - Specified release version Vsn is already in use.

• {Master, Reason, When} - Some operation, indicated by the term When, failed on the master node Master with the specified error reason Reason.

• {no_matching_relup, Vsn, CurrentVsn} - Cannot find a script for upgrading/downgrading between CurrentVsn and Vsn.

• {no_such_directory, Path} - The directory Pathdoes not exist.

• {no_such_file, Path} - The path Path (file or directory) does not exist.

• {no_such_file, {Master, Path}} - The path Path (file or directory) does not exist at the master node Master.

• {no_such_release, Vsn} - The specified release version Vsn does not exist.

• {not_a_directory, Path} - Path exists but is not a directory.

• {Posix, File} - Some file operation failed for File. Posix is an atom named from the Posix error codes, such as enoent, eacces, or eisdir. See file in Kernel.

• Posix - Some file operation failed, as for the previous item in the list.

Application Upgrade/Downgrade

The functions in the Application Upgrade/Downgrade section can be used to test upgrade and downgrade of single applications (instead of upgrading/downgrading an entire release). A script corresponding to the instructions in the relup file is created on-the-fly, based on the .appup file for the application, and evaluated exactly in the same way as release_handler does.

Warning

These functions are primarily intended for simplified testing of .appup files. They are not run within the context of the release_handler process. They must therefore not be used together with calls to install_release/1,2, as this causes the release_handler to end up in an inconsistent state.

No persistent information is updated, so these functions can be used on ay Erlang node, embedded or not. Also, using these functions does not affect which code is loaded if there is a reboot.

If the upgrade or downgrade fails, the application can end up in an inconsistent state.

See Also

OTP Design Principles, config), rel, relup, script, sys, systools