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:
client_directory
in the directory structure of
the master nodes must be specified.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(Name) -> {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)