sasl

v4.3.2

alarm_handler

An Alarm Handling Process

The alarm handler process is a gen_event event manager process that receives alarms in the system. This process is not intended to be a complete alarm handler. It defines a place to which alarms can be sent. One simple event handler is installed in the alarm handler at startup, but users are encouraged to write and install their own handlers.

The simple event handler sends all alarms as info reports to the error logger, and saves all in a list. This list can be passed to a user-defined event handler, which can be installed later. The list can grow large if many alarms are generated. This is a good reason to install a better user-defined handler.

Functions are provided to set and clear alarms. The alarm format is defined by the user. For example, an event handler for SNMP can be defined, together with an alarm Management Information Base (MIB).

The alarm handler is part of the SASL application.

When writing new event handlers for the alarm handler, the following events must be handled:

{set_alarm, {AlarmId, AlarmDescr}} - This event is generated by alarm_handler:set_alarm({AlarmId, AlarmDecsr}).

{clear_alarm, AlarmId} - This event is generated by alarm_handler:clear_alarm(AlarmId).

The default simple handler is called alarm_handler and it can be exchanged by calling gen_event:swap_handler/3 as gen_event:swap_handler(alarm_handler, {alarm_handler, swap}, {NewHandler, Args}). NewHandler:init({Args, {alarm_handler, Alarms}}) is called. For more details, see gen_event in STDLIB.

See Also

error_logger, gen_event

Summary

Types

alarm()

alarm_id()

Functions

clear_alarm(AlarmId)

Sends event clear_alarm to all event handlers.

get_alarms()

Returns a list of all active alarms. This function can only be used when the simple handler is installed.

set_alarm(alarm())

Sends event set_alarm to all event handlers.

Types

alarm()

(not exported)

-type alarm() :: {alarm_id(), AlarmDescription :: term()}.

alarm_id()

(not exported)

-type alarm_id() :: term().

Functions

clear_alarm(AlarmId)

-spec clear_alarm(alarm_id()) -> term().

Sends event clear_alarm to all event handlers.

When receiving this event, the default simple handler clears the latest received alarm with id AlarmId.

get_alarms()

-spec get_alarms() -> [alarm()].

Returns a list of all active alarms. This function can only be used when the simple handler is installed.

set_alarm(alarm())

-spec set_alarm(alarm()) -> term().

Sends event set_alarm to all event handlers.

When receiving this event, the default simple handler stores the alarm. AlarmId identifies the alarm and is used when the alarm is cleared.

rb

The Report Browser Tool

The Report Browser (RB) tool is used to browse and format error reports written by the error logger handler log_mf_h in STDLIB.

Summary

Types

filter()

option()

regexp()

type()

Functions

filter(Filters)

Equivalent to filter/2.

filter(Filters, Dates)

Displays the reports that match the provided filters.

grep(RegExp)

All reports matching the regular expression RegExp are displayed. RegExp can be any of the following

h()

Equivalent to help().

help()

Displays online help information.

list()

Equivalent to list(all).

list(Type)

Lists all reports loaded in rb_server. Each report is given a unique number that can be used as a reference to the report in function show/1.

log_list()

Equivalent to log_list(all).

log_list(Type)

Same as functions list/0 or list/1, but the result is printed to a log file, if set; otherwise to standard_io.

rescan()

Equivalent to rescan([]).

rescan(Options)

Rescans the report directory. Options is the same as for function start/1.

show()

All reports are displayed.

show(Report)

If argument Report is specified as one of the values of type(), all loaded reports of that type are displayed. If Report is specified as an integer, the report with this reference number is displayed.

start()

Equivalent to start([]).

start(Options)

Function start/1 starts rb_server with the specified options, whereas function start/0 starts with default options.

start_log(FileName)

Redirects all report output from the RB tool to the specified file, registered name, or io_device.

stop()

Stops rb_server.

stop_log()

Closes the log file. The output from the RB tool is directed to standard_io.

Types

filter()

(not exported)

-type filter() ::
          {Key :: term(), Value :: term()} |
          {Key :: term(), Value :: term(), no} |
          {Key :: term(), RegExp :: regexp(), re} |
          {Key :: term(), RegExp :: regexp(), re, no}.

option()

(not exported)

-type option() ::
          {start_log, FileName :: string() | atom() | pid()} |
          {max, MaxNoOfReports :: integer() | all} |
          {report_dir, DirString :: string()} |
          {type, ReportType :: type() | [type()] | all} |
          {abort_on_error, boolean()}.

regexp()

(not exported)

-type regexp() ::
          string() |
          {string(), Options :: [re:options()]} |
          re:mp() |
          {re:mp(), Options :: [re:compile_options()]}.

type()

(not exported)

-type type() ::
          error | error_report | info_msg | info_report | warning_msg | warning_report | crash_report |
          supervisor_report | progress | all.

Functions

filter(Filters)

(since OTP R13B04)

-spec filter(Filters) -> term() when Filters :: [filter()].

Equivalent to filter/2.

filter(Filters, Dates)

(since OTP R13B04)

-spec filter(Filters, Dates) -> term()
                when
                    Filters :: [filter()],
                    Dates :: {DateFrom, DateTo} | {DateFrom, from} | {DateTo, to},
                    DateFrom :: calendar:datetime(),
                    DateTo :: calendar:datetime().

Displays the reports that match the provided filters.

When a filter includes the no atom, it excludes the reports that match that filter.

The reports are matched using the proplists module in STDLIB. The report must be a proplist to be matched against any of the filters.

If the filter has the form {Key, RegExp, re}, the report must contain an element with key equal to Key and the value must match the regular expression RegExp.

If parameter Dates is specified, the reports are filtered according to the date when they occurred. If Dates has the form {DateFrom, from}, reports that occurred after DateFrom are displayed.

If Dates has the form {DateTo, to}, reports that occurred before DateTo are displayed.

If two Dates are specified, reports that occurred between those dates are returned.

To filter only by dates, specify the empty list as the Filters parameter.

For details about parameter RegExp, see rb:grep/1.

For details about data type mp(), see re:mp/0.

For details about data type datetime(), see calendar:datetime/0.

grep(RegExp)

-spec grep(RegExp :: regexp()) -> term().

All reports matching the regular expression RegExp are displayed. RegExp can be any of the following:

A string containing the regular expression

A tuple with the string and the options for compilation

A compiled regular expression

A compiled regular expression and the options for running it

For a definition of valid regular expressions and options, see the re module in STDLIB and in particular function re:run/3.

For details about data type mp(), see re:mp/0.

h()

-spec h() -> term().

Equivalent to help().

help()

-spec help() -> term().

Displays online help information.

list()

-spec list() -> term().

Equivalent to list(all).

list(Type)

-spec list(Type :: type()) -> term().

Lists all reports loaded in rb_server. Each report is given a unique number that can be used as a reference to the report in function show/1.

If no Type is specified, all reports are listed.

log_list()

(since OTP R16B02)

-spec log_list() -> term().

Equivalent to log_list(all).

log_list(Type)

(since OTP R16B02)

-spec log_list(Type :: type()) -> term().

Same as functions list/0 or list/1, but the result is printed to a log file, if set; otherwise to standard_io.

If no Type is specified, all reports are listed.

rescan()

-spec rescan() -> term().

Equivalent to rescan([]).

rescan(Options)

-spec rescan(Options) -> term() when Options :: [option()].

Rescans the report directory. Options is the same as for function start/1.

show()

-spec show() -> term().

All reports are displayed.

show(Report)

-spec show(Report) -> term() when Report :: integer() | type().

If argument Report is specified as one of the values of type(), all loaded reports of that type are displayed. If Report is specified as an integer, the report with this reference number is displayed.

start()

-spec start() -> term().

Equivalent to start([]).

start(Options)

-spec start(Options) -> term() when Options :: [option()].

Function start/1 starts rb_server with the specified options, whereas function start/0 starts with default options.

rb_server must be started before reports can be browsed. When rb_server is started, the files in the specified directory are scanned. The other functions assume that the server has started.

Options:

{start_log, FileName} - Starts logging to file, registered name, or io_device. All reports are printed to the specified destination. Default is standard_io. Option {start_log, standard_error} is not allowed and will be replaced by default standard_io.

{max, MaxNoOfReports} - Controls how many reports rb_server is to read at startup. This option is useful, as the directory can contain a large amount of reports. If this option is specified, the MaxNoOfReports latest reports are read. Default is all.

{report_dir, DirString} - Defines the directory where the error log files are located. Default is the directory specified by application environment variable error_logger_mf_dir, see sasl(6).

{type, ReportType} - Controls what kind of reports rb_server is to read at startup. ReportType is a supported type, all, or a list of supported types. Default is all.

{abort_on_error, Bool} - Specifies if logging is to be ended if rb encounters an unprintable report. (You can get a report with an incorrect form if function error_logger, error_msg, or info_msg has been called with an invalid format string)

If Bool is true, rb stops logging (and prints an error message to stdout) if it encounters a badly formatted report. If logging to file is enabled, an error message is appended to the log file as well.

If Bool is false (the default value), rb prints an error message to stdout for every bad report it encounters, but the logging process is never ended. All printable reports are written. If logging to file is enabled, rb prints * UNPRINTABLE REPORT * in the log file at the location of an unprintable report.

start_log(FileName)

-spec start_log(FileName) -> term() when FileName :: string() | atom() | pid().

Redirects all report output from the RB tool to the specified file, registered name, or io_device.

stop()

-spec stop() -> term().

Stops rb_server.

stop_log()

-spec stop_log() -> term().

Closes the log file. The output from the RB tool is directed to standard_io.

release_handler

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 by Release Handling section in OTP Design Principles.

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

Summary

Application Upgrade/Downgrade

downgrade_app(App, Dir)

Equivalent to downgrade_app/3.

downgrade_app(App, OldVsn, Dir)

Downgrades an application App from the current version to a previous version OldVsn located in Dir according to the .appup file.

downgrade_script(App, OldVsn, Dir)

Tries to find an application downgrade script for App from the current version to a previous version OldVsn located in Dir.

eval_appup_script(App, ToVsn, ToDir, Script)

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.

upgrade_app(App, Dir)

Upgrades an application App from the current version to a new version located in Dir according to the .appup file.

upgrade_script(App, Dir)

Tries to find an application upgrade script for App from the current version to a new version located in Dir.

Functions

check_install_release(Vsn)

Equivalent to check_install_release(Vsn, []).

check_install_release(Vsn, Opts)

Checks if the specified version Vsn of the release can be installed.

create_RELEASES(RelDir, RelFile, AppDirs)

Equivalent to create_RELEASES("", RelDir, RelFile, Appdirs).

create_RELEASES(Root, RelDir, RelFile, AppDirs)

Creates an initial RELEASES file to be used by the release handler.

install_file(Vsn, File)

Installs a release-dependent file in the release structure.

install_release(Vsn)

Equivalent to install_release(Vsn, []).

install_release(Vsn, [Opt])

Installs the specified version Vsn of the release.

make_permanent(Vsn)

Makes the specified release version Vsn permanent.

reboot_old_release(Vsn)

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

remove_release(Vsn)

Removes a release and its files from the system.

set_removed(Vsn)

Makes it possible to handle removal of releases outside the release handler.

set_unpacked(RelFile, AppDirs)

Makes it possible to handle unpacking of releases outside the release handler.

unpack_release(Name)

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

which_releases()

Returns all releases known to the release handler.

which_releases(Status)

Returns all releases, known to the release handler, of a specific status.

Application Upgrade/Downgrade

downgrade_app(App, Dir)

-spec downgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}
                       when
                           App :: atom(),
                           Dir :: string(),
                           Unpurged :: [Module],
                           Module :: atom(),
                           Reason :: term().

Equivalent to downgrade_app/3.

downgrade_app(App, OldVsn, Dir)

-spec downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}
                       when
                           App :: atom(),
                           Dir :: string(),
                           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

downgrade_script(App, OldVsn, Dir)

-spec downgrade_script(App, OldVsn, Dir) -> {ok, Script}
                          when
                              App :: atom(),
                              OldVsn :: string(),
                              Dir :: string(),
                              Script :: Instructions :: term().

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(4).

Failure: If a script cannot be found, the function fails with an appropriate error reason.

eval_appup_script(App, ToVsn, ToDir, Script)

-spec eval_appup_script(App, ToVsn, ToDir, Script :: term()) ->
                           {ok, Unpurged} | restart_emulator | {error, Reason}
                           when
                               App :: atom(),
                               ToVsn :: string(),
                               ToDir :: string(),
                               Unpurged :: [{Module, PurgeMethod}],
                               Module :: atom(),
                               PurgeMethod :: term(),
                               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.

upgrade_app(App, Dir)

-spec upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}
                     when
                         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.

upgrade_script(App, Dir)

-spec upgrade_script(App, Dir) -> {ok, NewVsn, Script}
                        when
                            App :: atom(),
                            Dir :: string(),
                            NewVsn :: string(),
                            Script :: Instructions :: term().

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(4).

Failure: If a script cannot be found, the function fails with an appropriate error reason.

Functions

check_install_release(Vsn)

-spec check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
                               when
                                   Vsn :: string(),
                                   OtherVsn :: string(),
                                   Descr :: term(),
                                   Reason :: term().

Equivalent to check_install_release(Vsn, []).

check_install_release(Vsn, Opts)

(since OTP R14B04)

-spec check_install_release(Vsn, Opts) -> {ok, OtherVsn, Descr} | {error, Reason}
                               when
                                   Vsn :: string(),
                                   OtherVsn :: string(),
                                   Opts :: [Opt],
                                   Opt :: purge,
                                   Descr :: term(),
                                   Reason :: term().

Checks if the specified version Vsn of the release can be installed.

The release must not have status current. Issues warnings if relup file or sys.config is not present. If relup file 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; {error,Reason} is returned if an error is found.

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.

If option purge is specified, all old code that can be soft-purged is purged after all other checks are successfully completed. This can be useful to reduce the time needed by install_release/1.

create_RELEASES(RelDir, RelFile, AppDirs)

(since OTP 25.0)

-spec create_RELEASES(RelDir, RelFile, AppDirs) -> ok | {error, Reason}
                         when
                             RelDir :: string(),
                             RelFile :: string(),
                             AppDirs :: [{App, Vsn, Dir}],
                             App :: atom(),
                             Vsn :: string(),
                             Dir :: string(),
                             Reason :: term().

Equivalent to create_RELEASES("", RelDir, RelFile, Appdirs).

create_RELEASES(Root, RelDir, RelFile, AppDirs)

-spec create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}
                         when
                             Root :: string(),
                             RelDir :: string(),
                             RelFile :: string(),
                             AppDirs :: [{App, Vsn, Dir}],
                             App :: atom(),
                             Vsn :: string(),
                             Dir :: string(),
                             Reason :: term().

Creates an initial RELEASES file to be used by the release handler.

This file must exist to install new releases.

Root is the root of the installation ($ROOT) as described earlier. RelDir is the directory where the RELEASES file is to be created (normally $ROOT/releases). RelFile is the name of the .rel file that describes the initial release, including the extension .rel. If Root is not given, the RELEASES file will be location independent (i.e, it will not contain absolute paths unless there are absolute paths in AppDirs). A RELEASES file should be made location independent if the installation's $ROOT is unknown. The release_handler module will interpret relative paths in a running system's RELEASES file as being relative to $ROOT.

AppDirs can be used to specify from where the modules for the specified applications are to be loaded. App is the name of an application, Vsn is the version, and Dir is the name of the directory where App-Vsn is located. The corresponding modules are to be located under Dir/App-Vsn/ebin. The directories for applications not specified in AppDirs are assumed to be located in $ROOT/lib.

install_file(Vsn, File)

-spec install_file(Vsn, File) -> ok | {error, Reason}
                      when Vsn :: string(), File :: string(), Reason :: term().

Installs a release-dependent file in the release structure.

The release-dependent file 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. The function is to be called after set_unpacked/2 has been called.

install_release(Vsn)

-spec install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
                         when
                             Vsn :: string(),
                             OtherVsn :: string(),
                             Descr :: term(),
                             Reason ::
                                 {already_installed, Vsn} |
                                 {change_appl_data, term()} |
                                 {missing_base_app, OtherVsn, App} |
                                 {could_not_create_hybrid_boot, term()} |
                                 term(),
                             App :: atom().

Equivalent to install_release(Vsn, []).

install_release(Vsn, [Opt])

-spec install_release(Vsn, [Opt]) ->
                         {ok, OtherVsn, Descr} |
                         {continue_after_restart, OtherVsn, Descr} |
                         {error, Reason}
                         when
                             Vsn :: string(),
                             OtherVsn :: string(),
                             Opt ::
                                 {error_action, Action} |
                                 {code_change_timeout, Timeout} |
                                 {suspend_timeout, Timeout} |
                                 {update_paths, Bool},
                             Action :: restart | reboot,
                             Timeout :: default | infinity | pos_integer(),
                             Bool :: boolean(),
                             Descr :: term(),
                             Reason ::
                                 {illegal_option, Opt} |
                                 {already_installed, Vsn} |
                                 {change_appl_data, term()} |
                                 {missing_base_app, OtherVsn, App} |
                                 {could_not_create_hybrid_boot, term()} |
                                 term(),
                             App :: atom().

Installs the specified version Vsn of the release.

Looks first for a relup file for Vsn and a script {UpFromVsn,Descr1,Instructions1} 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,Descr2,Instructions2} in this file for downgrading to Vsn.

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

After the application specifications have been updated, the instructions in the script are evaluated and the function returns {ok,OtherVsn,Descr} if successful. OtherVsn and Descr are the version (UpFromVsn or Vsn) and description (Descr1 or Descr2) as specified in the script.

If {continue_after_restart,OtherVsn,Descr} is returned, the emulator is restarted before the upgrade instructions are executed. This occurs if the emulator or any of the applications Kernel, STDLIB, or SASL are updated. The new emulator version and these core applications execute after the restart. For all other applications the old versions are started and the upgrade is performed as normal by executing the upgrade instructions.

If a recoverable error occurs, the function returns {error,Reason} and the original application specifications are restored. If a non-recoverable error occurs, the system is restarted.

Options:

error_action - Defines if the node is to be restarted (init:restart()) or rebooted (init:reboot()) if there is an error during the installation. Default is restart.

code_change_timeout - Defines the time-out for all calls to sys:change_code. If no value is specified or default is specified, the default value defined in sys is used.

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.

{update_paths,Bool} - Indicates if all application code paths are to be updated (Bool==true) or if only code paths for modified applications are to be updated (Bool==false, default). This option has only effect for other application directories than the default $ROOT/lib/App-Vsn, that is, application directories specified in argument AppDirs in a call to create_RELEASES/4 or set_unpacked/2.

Example:

In the current version CurVsn of a release, the application directory of myapp is $ROOT/lib/myapp-1.0. A new version NewVsn is unpacked outside the release handler and the release handler is informed about this with a call as follows:

release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
=> {ok,NewVsn}

If NewVsn is installed with option {update_paths,true}, then code:lib_dir(myapp) returns /home/user/myapp-1.0.

Note

Installing a new release can be time consuming if there are many processes in the system. The reason is that each process must be checked for references to old code before a module can be purged. This check can lead to garbage collections and copying of data.

To speed up the execution of install_release, first call check_install_release, using option purge. This does the same check for old code. Then purges all modules that can be soft-purged. The purged modules do then no longer have any old code, and install_release does not need to do the checks.

This does not reduce the overall time for the upgrade, but it allows checks and purge to be executed in the background before the real upgrade is started.

Note

When upgrading the emulator from a version older than OTP R15, an attempt is made to load new application beam code into the old emulator. Sometimes the new beam format cannot be read by the old emulator, so the code loading fails and the complete upgrade is terminated. To overcome this problem, the new application code is to be compiled with the old emulator. For more information about emulator upgrade from pre OTP R15 versions, see Design Principles in System Documentation.

make_permanent(Vsn)

-spec make_permanent(Vsn) -> ok | {error, Reason}
                        when Vsn :: string(), Reason :: {bad_status, Status :: term()} | term().

Makes the specified release version Vsn permanent.

reboot_old_release(Vsn)

-spec reboot_old_release(Vsn) -> ok | {error, Reason}
                            when Vsn :: string(), Reason :: {bad_status, Status :: term()} | term().

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

The release must have status old.

remove_release(Vsn)

-spec remove_release(Vsn) -> ok | {error, Reason}
                        when Vsn :: string(), Reason :: {permanent, Vsn} | client_node | term().

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.

set_removed(Vsn)

-spec set_removed(Vsn) -> ok | {error, Reason} when Vsn :: string(), Reason :: {permanent, Vsn} | term().

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)

-spec set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}
                      when
                          RelFile :: string(),
                          AppDirs :: [{App, Vsn, Dir}],
                          App :: atom(),
                          Vsn :: string(),
                          Dir :: string(),
                          Reason :: term().

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 the specified applications are to be loaded. App is the name of an application, Vsn is the version, and Dir is the name of the directory where App-Vsn is located. The corresponding modules are to be located under Dir/App-Vsn/ebin. The directories for applications not specified in AppDirs are assumed to be located in $ROOT/lib.

unpack_release(Name)

-spec unpack_release(Name) -> {ok, Vsn} | {error, Reason}
                        when Name :: string(), Vsn :: string(), Reason :: client_node | 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()

-spec which_releases() -> [{Name, Vsn, Apps, Status}]
                        when
                            Name :: string(),
                            Vsn :: string(),
                            Apps :: [AppVsn :: string()],
                            Status :: unpacked | current | permanent | old.

Returns all releases known to the release handler.

which_releases(Status)

(since OTP R15B)

-spec which_releases(Status) -> [{Name, Vsn, Apps, Status}]
                        when
                            Name :: string(),
                            Vsn :: string(),
                            Apps :: [AppVsn :: string()],
                            Status :: unpacked | current | permanent | old.

Returns all releases, known to the release handler, of a specific status.

systools

A Set of Release Handling Tools

This module contains functions to generate boot scripts (.boot, .script), a release upgrade file (relup), and release packages.

See Also

app(4), appup(4), erl(1), rel(4), release_handler, relup(4), script(4)

Summary

Functions

make_relup(Name, UpFrom, DownTo)

Equivalent to make_relup(Name, UpFrom, DownTo, []).

make_relup(Name, UpFrom, DownTo, [Opt])

Generates a release upgrade file relup containing instructions for upgrading from or downgrading to one or more previous releases.

make_script(Name)

Equivalent to make_script/2.

make_script(Name, [Opt])

Generates a boot script Name.script and its binary version, the boot file Name.boot, unless the {script_name, ScriptName} option is given, in which case the names are ScriptName.script and ScriptName.boot.

make_tar(Name)

Equivalent to make_tar(Name, []).

make_tar(Name, Opts)

Creates a release package file Name.tar.gz.

script2boot(File)

This function transforms the File.script boot script to a binary term, which is stored in the File.boot file.

Functions

make_relup(Name, UpFrom, DownTo)

-spec make_relup(Name, UpFrom, DownTo) -> Result
                    when
                        Name :: string(),
                        UpFrom :: [Name | {Name, Descr}],
                        DownTo :: [Name | {Name, Descr}],
                        Descr :: term(),
                        Result ::
                            ok | error |
                            {ok, Relup :: term(), Module, Warnings} |
                            {error, Module, Error},
                        Module :: atom(),
                        Warnings :: term(),
                        Error :: term().

Equivalent to make_relup(Name, UpFrom, DownTo, []).

make_relup(Name, UpFrom, DownTo, [Opt])

-spec make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
                    when
                        Name :: string(),
                        UpFrom :: [Name | {Name, Descr}],
                        DownTo :: [Name | {Name, Descr}],
                        Descr :: term(),
                        Opt ::
                            {path, [Dir]} |
                            restart_emulator | silent | noexec |
                            {outdir, Dir} |
                            warnings_as_errors,
                        Dir :: string(),
                        Result ::
                            ok | error |
                            {ok, Relup :: term(), Module, Warnings} |
                            {error, Module, Error},
                        Module :: atom(),
                        Warnings :: term(),
                        Error :: term().

Generates a release upgrade file relup containing instructions for upgrading from or downgrading to one or more previous releases.

The instructions are used by release_handler when installing a new version of a release in runtime.

By default, the relup file is located in the current working directory. If option {outdir,Dir} is specified, the relup file is located in directory Dir instead.

The release resource file Name.rel is compared with all release resource files Name2.rel, specified in UpFrom and DownTo. For each such pair, the following is deducted:

Which applications to be deleted, that is, applications listed in Name.rel but not in Name2.rel

Which applications to be added, that is, applications listed in Name2.rel but not in Name.rel

Which applications to be upgraded/downgraded, that is, applications listed in both Name.rel and Name2.rel but with different versions

If the emulator needs to be restarted after upgrading or downgrading, that is, if the ERTS version differs between Name.rel and Name2.rel

Instructions for this are added to the relup file in the above order. Instructions for upgrading or downgrading between application versions are fetched from the relevant application upgrade files App.appup, sorted in the same order as when generating a boot script, see make_script/1,2. High-level instructions are translated into low-level instructions and the result is printed to the relup file.

The optional Descr parameter is included "as is" in the relup file, see relup(4). Defaults to the empty list.

All the files are searched for in the code path. It is assumed that the .app and .appup files for an application are located in the same directory.

If option {path,[Dir]} is specified, this path is appended to the current path. Wildcard * is expanded to all matching directories, for example, lib/*/ebin.

If option restart_emulator is specified, a low-level instruction to restart the emulator is appended to the relup file. This ensures that a complete reboot of the system is done when the system is upgraded or downgraded.

If an upgrade includes a change from an emulator earlier than OTP R15 to OTP R15 or later, the warning pre_R15_emulator_upgrade is issued. For more information about this, see Design Principles in System Documentation.

By default, errors and warnings are printed to tty and the function returns ok or error. If option silent is specified, the function instead either returns {ok,Relup,Module,Warnings}, where Relup is the release upgrade file, or {error,Module,Error}. Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or Module:format_error(Error).

If option noexec is specified, the function returns the same values as for silent but no relup file is created.

If option warnings_as_errors is specified, warnings are treated as errors.

make_script(Name)

-spec make_script(Name) -> Result
                     when
                         Name :: string(),
                         Result :: ok | error | {ok, Module, Warnings} | {error, Module, Error},
                         Module :: atom(),
                         Warnings :: term(),
                         Error :: term().

Equivalent to make_script/2.

make_script(Name, [Opt])

-spec make_script(Name, [Opt]) -> Result
                     when
                         Name :: string(),
                         Opt ::
                             src_tests |
                             {path, [Dir]} |
                             local |
                             {variables, [Var]} |
                             exref |
                             {exref, [App]} |
                             silent |
                             {outdir, Dir} |
                             no_dot_erlang | no_warn_sasl | warnings_as_errors |
                             {script_name, Name},
                         Dir :: string(),
                         Var :: {VarName, Prefix},
                         VarName :: string(),
                         Prefix :: string(),
                         App :: atom(),
                         Result :: ok | error | {ok, Module, Warnings} | {error, Module, Error},
                         Module :: atom(),
                         Warnings :: term(),
                         Error :: term().

Generates a boot script Name.script and its binary version, the boot file Name.boot, unless the {script_name, ScriptName} option is given, in which case the names are ScriptName.script and ScriptName.boot.

The boot file specifies which code to be loaded and which applications to be started when the Erlang runtime system is started. See script(4).

The release resource file Name.rel is read to determine which applications are included in the release. Then the relevant application resource files App.app are read to determine which modules to be loaded, and if and how the applications are to be started. (Keys modules and mod, see app(4).

By default, the boot script and boot file are located in the same directory as Name.rel. That is, in the current working directory unless Name contains a path. If option {outdir,Dir} is specified, they are located in Dir instead.

The correctness of each application is checked as follows:

The version of an application specified in the .rel file is to be the same as the version specified in the .app file.

There are to be no undefined applications, that is, dependencies to applications that are not included in the release. (Key applications in the .app file).

There are to be no circular dependencies among the applications.

There are to be no duplicated modules, that is, modules with the same name but belonging to different applications.

If option src_tests is specified, a warning is issued if the source code for a module is missing or is newer than the object code.

The applications are sorted according to the dependencies between the applications. Where there are no dependencies, the order in the .rel file is kept.

The function fails if the mandatory applications Kernel and STDLIB are not included in the .rel file and have start type permanent (which is default).

If SASL is not included as an application in the .rel file, a warning is issued because such a release cannot be used in an upgrade. To turn off this warning, add option no_warn_sasl.

All files are searched for in the current path. It is assumed that the .app and .beam files for an application are located in the same directory. The .erl files are also assumed to be located in this directory, unless it is an ebin directory in which case they can be located in the corresponding src directory.

If option {path,[Dir]} is specified, this path is appended to the current path. A directory in the path can be specified with a wildcard *, this is expanded to all matching directories. Example: "lib/*/ebin".

In the generated boot script all application directories are structured as App-Vsn/ebin. They are assumed to be located in $ROOT/lib, where $ROOT is the root directory of the installed release. If option local is specified, the actual directories where the applications were found are used instead. This is a useful way to test a generated boot script locally.

Option variables can be used to specify an installation directory other than $ROOT/lib for some of the applications. If a variable {VarName,Prefix} is specified and an application is found in a directory Prefix/Rest/App[-Vsn]/ebin, this application gets the path VarName/Rest/App-Vsn/ebin in the boot script. If an application is found in a directory Prefix/Rest, the path is VarName/Rest/App-Vsn/ebin. When starting Erlang, all variables VarName are given values using command-line flag boot_var.

Example: If option {variables,[{"TEST","lib"}]} is specified and myapp.app is found in lib/myapp/ebin, the path to this application in the boot script is "$TEST/myapp-1/ebin". If myapp.app is found in lib/test, the path is $TEST/test/myapp-1/ebin.

The checks performed before the boot script is generated can be extended with some cross reference checks by specifying option exref. These checks are performed with the Xref tool. All applications, or the applications specified with {exref,[App]}, are checked by Xref and warnings are issued for calls to undefined functions.

By default, errors and warnings are printed to tty and the function returns ok or error. If option silent is specified, the function instead returns {ok,Module,Warnings} or {error,Module,Error}. Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or Module:format_error(Error).

If option warnings_as_errors is specified, warnings are treated as errors.

If option no_dot_erlang is specified, the instruction to load the .erlang file during boot is not included.

make_tar(Name)

-spec make_tar(Name) -> Result
                  when
                      Name :: string(),
                      Result ::
                          ok | error |
                          {ok, Module :: module(), Warnings :: term()} |
                          {error, Module :: module(), Error :: term()}.

Equivalent to make_tar(Name, []).

make_tar(Name, Opts)

-spec make_tar(Name, Opts) -> Result
                  when
                      Name :: string(),
                      Opts :: [Opt],
                      Opt ::
                          {dirs, [IncDir]} |
                          {path, [Dir]} |
                          {variables, [Var]} |
                          {var_tar, VarTar} |
                          {erts, Dir} |
                          erts_all | src_tests | exref |
                          {exref, [App]} |
                          silent |
                          {outdir, Dir} |
                          no_warn_sasl | warnings_as_errors |
                          {extra_files, ExtraFiles},
                      Dir :: file:filename_all(),
                      IncDir :: src | include | atom(),
                      Var :: {VarName, PreFix},
                      VarName :: string(),
                      PreFix :: string(),
                      VarTar :: include | ownfile | omit,
                      App :: atom(),
                      Result ::
                          ok | error |
                          {ok, Module :: module(), Warnings :: term()} |
                          {error, Module :: module(), Error :: term()},
                      ExtraFiles :: [{file:filename_all(), NameInArchive}],
                      NameInArchive :: string().

Creates a release package file Name.tar.gz.

This file must be uncompressed and unpacked on the target system using release_handler before the new release can be installed.

The release resource file Name.rel is read to determine which applications are included in the release. Then the relevant application resource files App.app are read to determine the version and modules of each application (keys vsn and modules, see app(4)).

By default, the release package file is located in the same directory as Name.rel. That is, in the current working directory unless Name contains a path. If option {outdir,Dir} is specified, it is located in Dir instead.

If SASL is not included as an application in the .rel file, a warning is issued because such a release cannot be used in an upgrade. To turn off this warning, add option no_warn_sasl.

By default, the release package contains the directories lib/App-Vsn/ebin and lib/App-Vsn/priv for each included application. If more directories are to be included, option dirs is specified, for example, {dirs,[src,examples]}.

All these files are searched for in the current path. If option {path,[Dir]} is specified, this path is appended to the current path. Wildcard * is expanded to all matching directories. Example: "lib/*/ebin".

If the {extra_files, ExtraFiles} option is given then the ExtraFiles are added to the tarball after everything else to be included has been added.

Option variables can be used to specify an installation directory other than lib for some of the applications. If variable {VarName,Prefix} is specified and an application is found in directory Prefix/Rest/App[-Vsn]/ebin, this application is packed into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.

Example: If option {variables,[{"TEST","lib"}]} is specified and myapp.app is located in lib/myapp-1/ebin, application myapp is included in TEST.tar.gz:

% tar tf TEST.tar
myapp-1/ebin/myapp.app
...

Option {var_tar,VarTar} can be used to specify if and where a separate package is to be stored. In this option VarTar is one of the following:

include - Each separate (variable) package is included in the main ReleaseName.tar.gz file. This is the default.

ownfile - Each separate (variable) package is generated as a separate file in the same directory as the ReleaseName.tar.gz file.

omit - No separate (variable) packages are generated. Applications that are found underneath a variable directory are ignored.

A directory releases is also included in the release package, containing Name.rel and a subdirectory RelVsn. RelVsn is the release version as specified in Name.rel.

releases/RelVsn contains the boot script Name.boot renamed to start.boot and, if found, the files relup and sys.config or sys.config.src. These files are searched for in the same directory as Name.rel, in the current working directory, and in any directories specified using option path. In the case of sys.config it is not included if sys.config.src is found.

If the release package is to contain a new Erlang runtime system, the erts-ErtsVsn/bin directory of the specified runtime system {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts executables are not copied by default, if you want to include all executables you can give the erts_all option.

All checks with function make_script are performed before the release package is created. Options src_tests and exref are also valid here.

The return value and the handling of errors and warnings are the same as described for make_script.

script2boot(File)

-spec script2boot(File) -> ok | error when File :: string().

This function transforms the File.script boot script to a binary term, which is stored in the File.boot file.

The Erlang runtime system requires that the contents of the script used to boot the system is a binary Erlang term.

A boot script generated using make_script is already transformed to the binary form.