Install Now
release_handler - Unpacking and Installation of Release Packages
Contents
Application Upgrade/Downgrade
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 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 any 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.
Description
The releasehandler process belongs to the SASL application, which is responsible for releasehandling,
that is, unpacking, installation, and removal of release packages.
An introduction to release handling and an example is provided in OTP Design Principles in SystemDocumentation.
A releasepackage 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 SystemDocumentation. 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(7)):
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.
Exports
upgrade_app(App,Dir)->{ok,Unpurged}|restart_emulator|{error,Reason}
Types:
App = atom()
Dir = string()
Unpurged = [Module]
Module = atom()
Reason = term()
Upgrades an application App from the current version to a new version located in Dir according to
the .appup file.
App is the name of the application, which must be started. Dir is the new library directory of
App. The corresponding modules as well as the .app and .appup files are to be located under
Dir/ebin.
The function looks in the .appup file and tries to find an upgrade script from the current version
of the application using upgrade_script/2. This script is evaluated using eval_appup_script/4,
exactly in the same way as install_release/1,2 does.
Returns one of the following:
* {ok,Unpurged} if evaluating the script is successful, where Unpurged is a list of unpurged
modules
* restart_emulator if this instruction is encountered in the script
* {error,Reason} if an error occurred when finding or evaluating the script
If the restart_new_emulator instruction is found in the script, upgrade_app/2 returns
{error,restart_new_emulator}. This because restart_new_emulator requires a new version of the
emulator to be started before the rest of the upgrade instructions can be executed, and this can
only be done by install_release/1,2.
downgrade_app(App,Dir)->downgrade_app(App,OldVsn,Dir)->{ok,Unpurged}|restart_emulator|{error,Reason}
Types:
App = atom()
Dir = OldVsn = string()
Unpurged = [Module]
Module = atom()
Reason = term()
Downgrades an application App from the current version to a previous version OldVsn located in Dir
according to the .appup file.
App is the name of the application, which must be started. OldVsn is the previous application
version and can be omitted if Dir is of the format "App-OldVsn". Dir is the library directory of
the previous version of App. The corresponding modules and the old .app file are to be located
under Dir/ebin. The .appup file is to be located in the ebin directory of the current library
directory of the application (code:lib_dir(App)).
The function looks in the .appup file and tries to find a downgrade script to the previous version
of the application using downgrade_script/3. This script is evaluated using eval_appup_script/4,
exactly in the same way as install_release/1,2 does.
Returns one of the following:
* {ok,Unpurged} if evaluating the script is successful, where Unpurged is a list of unpurged
modules
* restart_emulator if this instruction is encountered in the script
* {error,Reason} if an error occurred when finding or evaluating the script
upgrade_script(App,Dir)->{ok,NewVsn,Script}
Types:
App = atom()
Dir = string()
NewVsn = string()
Script = Instructions
Tries to find an application upgrade script for App from the current version to a new version
located in Dir.
The upgrade script can then be evaluated using eval_appup_script/4. It is recommended to use
upgrade_app/2 instead, but this function (upgrade_script) is useful to inspect the contents of the
script.
App is the name of the application, which must be started. Dir is the new library directory of
App. The corresponding modules as well as the .app and .appup files are to be located under
Dir/ebin.
The function looks in the .appup file and tries to find an upgrade script from the current
application version. High-level instructions are translated to low-level instructions. The
instructions are sorted in the same manner as when generating a relup file.
Returns {ok,NewVsn,Script} if successful, where NewVsn is the new application version. For
details about Script, see appup(5).
Failure: If a script cannot be found, the function fails with an appropriate error reason.
downgrade_script(App,OldVsn,Dir)->{ok,Script}
Types:
App = atom()
OldVsn = Dir = string()
Script = Instructions
Tries to find an application downgrade script for App from the current version to a previous
version OldVsn located in Dir.
The downgrade script can then be evaluated using eval_appup_script/4. It is recommended to use
downgrade_app/2,3 instead, but this function (downgrade_script) is useful to inspect the contents
of the script.
App is the name of the application, which must be started. Dir is the previous library directory
of App. The corresponding modules and the old .app file are to be located under Dir/ebin. The
.appup file is to be located in the ebin directory of the current library directory of the
application (code:lib_dir(App)).
The function looks in the .appup file and tries to find a downgrade script from the current
application version. High-level instructions are translated to low-level instructions. The
instructions are sorted in the same manner as when generating a relup file.
Returns {ok,Script} if successful. For details about Script, see appup(5).
Failure: If a script cannot be found, the function fails with an appropriate error reason.
eval_appup_script(App,ToVsn,ToDir,Script)->{ok,Unpurged}|restart_emulator|{error,Reason}
Types:
App = atom()
ToVsn = ToDir = string()
Script
See upgrade_script/2, downgrade_script/3
Unpurged = [Module]
Module = atom()
Reason = term()
Evaluates an application upgrade or downgrade script Script, the result from calling
upgrade_script/2 or downgrade_script/3, exactly in the same way as install_release/1,2 does.
App is the name of the application, which must be started. ToVsn is the version to be
upgraded/downgraded to, and ToDir is the library directory of this version. The corresponding
modules as well as the .app and .appup files are to be located under Dir/ebin.
Returns one of the following:
* {ok,Unpurged} if evaluating the script is successful, where Unpurged is a list of unpurged
modules
* restart_emulator if this instruction is encountered in the script
* {error,Reason} if an error occurred when finding or evaluating the script
If the restart_new_emulator instruction is found in the script, eval_appup_script/4 returns
{error,restart_new_emulator}. This because restart_new_emulator requires a new version of the
emulator to be started before the rest of the upgrade instructions can be executed, and this can
only be done by install_release/1,2.
Name
release_handler - Unpacking and Installation of Release Packages
See Also
OTP Design Principles, config(5), rel(5), relup(5), script(5), sys(3erl), systools(3erl)
Ericsson AB sasl 4.1.1 release_handler(3erl)
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(3erl) in Kernel.
Posix:
Some file operation failed, as for the previous item in the list.
PNG Icons
