# release_handler

### MODULE

release_handler

### MODULE SUMMARY

A process to Unpack and Install Releases

### DESCRIPTION

The release handler process is a SASL process that handles unpacking, installation, and removal of release packages. As an example, a release package could contain applications, a new emulator, and new configuration parameters. In this text, the directory `ROOT` refers to the installation root directory (`code:root_dir()`). A release package is a compressed `tar` file that is written to the releases directory, for example via ftp. The location of this directory is specified with the configuration parameter `releases_dir`, or the OS environment variable `RELDIR`. Default is `ROOT/releases`. The release handler must have write access to this directory in order to install new releases. The persistent state of the release handler, for example information about installed releases, is stored in a file called `RELEASES` in the releases directory.

The package can be unpacked, which extracts the files from the package. When the release is unpacked, it can be installed. This operation evaluates the release upgrade script. 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 when the system is started. 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. The system can be rebooted from an old release.

Each 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                  -

A release package always contains two special files, the `ReleaseName.rel` file and the `relup` file. The `ReleaseName.rel` file contains information about the release, such as its name, version, and which system and library versions it uses. The `relup` file contains release upgrade scripts. There is one release upgrade script for each old version that can be updated to the new version.

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.

A new release may restart the system, using `start_prg`. This is a configuration parameter to the application `sasl`. The default is `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.

### EXPORTS

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

Types:

`Vsn = FromVsn = string()`
`Descr = term()`

The release must not have status `current`. Checks that there is a `relup` release upgrade script from the `FromVsn` (current version) to `Vsn`. Checks that all required libs (or applications) are present and that all new code can be loaded. Checks that there is a `start.boot` file and a `sys.config` for the new release.

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`.

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

Types:

`Root = RelDir = RelFile = string()`
`LibDirs = [{LibName, LibVsn, Dir}]`
`LibName = atom()`
`LibVsn = Dir = string()`

This function can be called to create an initial RELEASES file to be used by the release_handler. This file must exist in order to install new releases. When the system is installed, a default RELEASES file is created in the default releases directory `ROOT/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.

`LibDirs` can be used to specify from where the modules for an application should be loaded. `LibName` is the name of the lib (or application), `LibVsn` is the version, and `Dir` is the name of the directory where the lib directory `LibName-LibVsn` is located. The corresponding modules should be located under `Dir/LibName-LibVsn/ebin`.

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

Types:

`FileName = string()`
`Vsn = string()`

Installs a release dependent file in the release structure. A release dependent file is a file that must be in the release structure when the release is installed. Currently there are three such mandatory files, `start.boot`, `sys.config` and `relup`.

This function should be called to install release dependent files, for example when these files are generated at the target. It should be called when `set_unpacked/2` has been called.

`install_release(Vsn) -> {ok, FromVsn, Descr} | {error, Reason}`
`install_release(Vsn, Opt) -> {ok, FromVsn, Descr} | {error, Reason}`

Types:

`Vsn = FromVsn = string()`
`Opt = [{error_action, Error_action} | {code_change_timeout, Timeout} | {suspend_timeout, Timeout}]`
`Error_action = restart | reboot`
`Descr = term()`
`Timeout = default | infinity | int() > 0`

The release must not have status `current`. Installs the delivered release in the system by evaluating the release upgrade script found in the `relup` file. This function returns `{ok, FromVsn, Descr}` if successful, or `{error, Reason}` if a recoverable error occurs. `Descr` is a user defined parameter, found in the `relup` file, used to describe the release. The system is restarted if a non-recoverable error occurs. There can be many installed releases at the same time in the system.

It is possible to define if the node should be restarted or rebooted in case of an error during the installation. Default is `restart`.

The option `code_change_timeout` defines the time-out 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 time-out 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.

Note that if an `old` or the `permanent` release is installed, a downgrade will occur. There must a corresponding downgrade script in the `relup` file.

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

Types:

`Vsn = string()`

Makes the current release permanent. This causes the specified release to be used at system start-up.

`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, LibDirs) -> {ok, Vsn} | {error, Reason}`

Types:

`RelFile = string()`
`LibDirs = [{LibName, LibVsn, Dir}]`
`LibName = atom()`
`LibVsn = Dir = string()`
`Vsn = string()`

Makes it possible to handle the unpacking of releases outside the `release_handler`. Makes the `release_handler` aware that the release is unpacked. `Vsn` is extracted from the release file `RelFile` and is used as parameter to the other functions.

`LibDirs` can be used to specify from where the modules for an application should be loaded. `LibName` is the name of the lib (or application), `LibVsn` is the version, and `Dir` is the name of the directory where the lib directory `LibName-LibVsn` is located. The corresponding modules should be located under `Dir/LibName-LibVsn/ebin`.

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

Types:

`ReleaseName = string()`
`Vsn = string()`

The `ReleaseName` is the name of the release package. This is the name of the package file, without `.tar.gz`. `ReleaseName` may or may not be the same as the release version. `Vsn` is extracted from the release package and is used as parameter to the other functions.

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

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

Types:

`Name = string()`
`Vsn = string()`
`Lib = string()`
`Status = unpacked | current | permanent | old`

Returns all releases known to the release handler. `Name` is the name of the system. `Lib` is the name of a library. This name may be the application name followed by its version, for example "kernel-1.0".

### See Also

systools(3)

### AUTHORS

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

sasl 1.10
Copyright © 1991-2003 Ericsson Utvecklings AB