sasl

v4.2.2

SASL Application

Description

The SASL application provides the following services:

alarm_handler

release_handler

systools

Note

The SASL application in OTP has nothing to do with "Simple Authentication and Security Layer" (RFC 4422).

Configuration

The following configuration parameters are defined for the SASL application. For more information about configuration parameters, see app(4) in Kernel.

All configuration parameters are optional.

start_prg = string() - Specifies the program to be used when restarting the system during release installation. Default is $OTPROOT/bin/start.

masters = [atom()] - Specifies the nodes used by this node to read/write release information. This parameter is ignored if parameter client_directory is not set.

client_directory = string() - This parameter specifies the client directory at the master nodes. For details, see Release Handling in OTP Design Principles. This parameter is ignored if parameter masters is not set.

static_emulator = true | false - Indicates if the Erlang emulator is statically installed. A node with a static emulator cannot switch dynamically to a new emulator, as the executable files are written into memory statically. This parameter is ignored if parameters masters and client_directory are not set.

releases_dir = string() - Indicates where the releases directory is located. The release handler writes all its files to this directory. If this parameter is not set, the OS environment parameter RELDIR is used. By default, this is $OTPROOT/releases.

Deprecated Error Logger Event Handlers and Configuration

In Erlang/OTP 21.0, a new API for logging was added. The old error_logger event manager, and event handlers running on this manager, still work, but they are not used by default.

The error logger event handlers sasl_report_tty_h and sasl_report_file_h, were earlier used for printing the so called SASL reports, that is, supervisor reports, crash reports, and progress reports. These reports are now also printed by the default logger handler started by the Kernel application. Progress reports are by default stopped by the primary log level, but can be enabled by setting this level to info, for example by using the Kernel configuration parameter logger_level.

If the old error logger event handlers are still desired, they must be added by calling error_logger:add_report_handler/1,2.

sasl_report_tty_h - Formats and writes supervisor reports, crash reports, and progress reports to stdio. This error logger event handler uses error_logger_format_depth in the Kernel application to limit how much detail is printed in crash and supervisor reports.

sasl_report_file_h - Formats and writes supervisor reports, crash report, and progress report to a single file. This error logger event handler uses error_logger_format_depth in the Kernel application to limit the details printed in crash and supervisor reports.

A similar behaviour, but still using the new logger API, can be obtained by setting the Kernel application environment variable logger_sasl_compatible to true. This adds a second instance of the standard Logger handler, named sasl, which only prints the SASL reports. No SASL reports are then printed by the Kernel logger handler.

The sasl handler is configured according to the values of the following SASL application environment variables.

sasl_error_logger = Value - Value is one of the following:

tty - Installs sasl_report_tty_h in the error logger. This is the default option.

{file,FileName} - Installs sasl_report_file_h in the error logger. All reports go to file FileName, which is a string. The file is opened in write mode with encoding utf8.

{file,FileName,Modes} - Same as {file,FileName}, except that Modes allows you to specify the modes used for opening the FileName given to the file:open/2 call. By default, the file is opened in write mode with encoding utf8. Use [append] to have the FileName open in append mode. A different encoding can also be specified. FileName is a string.

false - No SASL error logger handler is installed.

errlog_type = error | progress | all - Restricts the error logging performed by the specified sasl_error_logger to error reports or progress reports, or both. Default is all.

utc_log = true | false - If set to true, all dates in textual log outputs are displayed in Universal Coordinated Time with the string UTC appended.

The error logger event handler log_mf_h can also still be used. This event handler writes all events sent to the error logger to disk. Multiple files and log rotation are used. For efficiency reasons, each event is written as a binary. For more information about this handler, see the STDLIB Reference Manual.

To activate this event handler, three SASL configuration parameters must be set:

error_logger_mf_dir = string() | false - Specifies in which directory log_mf_h is to store its files. If this parameter is undefined or false, the log_mf_h handler is not installed.

error_logger_mf_maxbytes = integer() - Specifies the maximum size of each individual file written by log_mf_h. If this parameter is undefined, the log_mf_h handler is not installed.

error_logger_mf_maxfiles = 0<integer()<256 - Specifies the number of files used by log_mf_h. If this parameter is undefined, the log_mf_h handler is not installed.

The new logger_disk_log_h might be an alternative to log_mf_h if log rotation is desired. This does, however, write the log events in clear text and not as binaries.

See Also

alarm_handler, error_logger, logger, log_mf_h, rb, release_handler, systools

SASL Release Notes

This document describes the changes made to the SASL application.

SASL 4.2.2

Improvements and New Features

The documentation has been migrated to use Markdown and ExDoc.

Own Id: OTP-18955 Aux Id: PR-8026

SASL 4.2.1

Fixed Bugs and Malfunctions

Improved error message from systools:make_script, when .app parameters contain duplicates. The parameters that will be checked are modules, applications and registered.

Own Id: OTP-18300 Aux Id: PR-6389

SASL 4.2

Fixed Bugs and Malfunctions

Fix systools:make* to recursively search for source code when doing a src_tests.

Own Id: OTP-17752 Aux Id: PR-5302

Improvements and New Features

An Erlang installation directory is now relocatable on the file system given that the paths in the installation's RELEASES file are paths that are relative to the installations root directory. The `release_handler:create_RELEASES/4 function can generate a RELEASES file with relative paths if its RootDir parameter is set to the empty string.

Own Id: OTP-17304

SASL 4.1.2

Fixed Bugs and Malfunctions

Fix bug in systools:make_script/1 documentation.

Own Id: OTP-17854 Aux Id: PR-5596

SASL 4.1.1

Fixed Bugs and Malfunctions

Make release_handler even more resilient against exiting processes during upgrade. Same kind of bug fix as OTP-16744 released in sasl-4.0.1 (OTP 23.1).

Own Id: OTP-17748 Aux Id: GH-5387, PR-5389

SASL 4.1

Improvements and New Features

The experimental HiPE application has been removed, together with all related functionality in other applications.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-16963

Recognize new key 'optional_applications' in application resource files.

Own Id: OTP-17189 Aux Id: PR-2675

Removed timestamps from files generated by sasl and reltool to enable deterministic builds.

Own Id: OTP-17292 Aux Id: PR-4685, PR-4684

SASL 4.0.2

Fixed Bugs and Malfunctions

Fix dependent application to be stopped after the primary application when upgrading a release and the primary and dependent application is removed.

Example: In a release where app1 depends on app2 and we should remove app1 and app2 using a release upgrade. When the release upgrade is done app1 should be stopped and purged before app2 as otherwise app1 could start crashing when its dependency is removed.

This bugfix changes the order of removal to be correct.

Own Id: OTP-17113 Aux Id: ERL-1410 PR-2882

SASL 4.0.1

Fixed Bugs and Malfunctions

Make release_handler more resilient against exiting processes during upgrade.

Own Id: OTP-16744 Aux Id: ERL-1247, PR-2666

SASL 4.0

Improvements and New Features

Remove usage and documentation of old requests of the I/O-protocol.

Own Id: OTP-15695

systools:make_script/2 now accepts the name of the boot file to create, it is not restricted to only RelName.boot or start.boot.

systools:make_tar/2 now accepts the option extra_files to add any extra non release related files to the tar file.

Own Id: OTP-16561 Aux Id: PR-2420

systools:make_tar/1,2 now filters out any tools from erts if included in the release tar ball. See the documentation for more details.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-16603

SASL 3.4.2

Improvements and New Features

A socket "registry" has been added making it possible to list current open sockets.

Own Id: OTP-16309

SASL 3.4.1

Improvements and New Features

The net module has been split into 'net' (kernel) and prim_net (preloaded).

Own Id: OTP-15765

SASL 3.4

Improvements and New Features

Change the first module called by erts to be named erl_init instead of otp_ring0. systools in sasl have been updated to reflect this change.

Own Id: OTP-15336 Aux Id: PR-1825

SASL 3.3

Improvements and New Features

New counters and atomics modules supplies access to highly efficient operations on mutable fixed word sized variables.

Own Id: OTP-13468

SASL 3.2.1

Fixed Bugs and Malfunctions

Improved documentation.

Own Id: OTP-15190

SASL 3.2

Improvements and New Features

A new logging API is added to Erlang/OTP, see the logger manual page, and section Logging in the Kernel User's Guide.

Calls to error_logger are automatically redirected to the new API, and legacy error logger event handlers can still be used. It is, however, recommended to use the Logger API directly when writing new code.

Notice the following potential incompatibilities:

Kernel configuration parameters error_logger still works, but is overruled if the default handler's output destination is configured with Kernel configuration parameter logger.

In general, parameters for configuring error logger are overwritten by new parameters for configuring Logger.

The concept of SASL error logging is deprecated, meaning that by default the SASL application does not affect which log events are logged.

By default, supervisor reports and crash reports are logged by the default Logger handler started by Kernel, and end up at the same destination (terminal or file) as other standard log event from Erlang/OTP.

Progress reports are not logged by default, but can be enabled by setting the primary log level to info, for example with the Kernel configuration parameter logger_level.

To obtain backwards compatibility with the SASL error logging functionality from earlier releases, set Kernel configuration parameter logger_sasl_compatible to true. This prevents the default Logger handler from logging any supervisor-, crash-, or progress reports. Instead, SASL adds a separate Logger handler during application start, which takes care of these log events. The SASL configuration parameters sasl_error_logger and sasl_errlog_type specify the destination (terminal or file) and severity level to log for these events.

Since Logger is new in Erlang/OTP 21.0, we do reserve the right to introduce changes to the Logger API and functionality in patches following this release. These changes might or might not be backwards compatible with the initial version.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-13295

The old and outdated "Status Inspection" tool (modules si and si_sasl_sup) is removed.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-14469

When creating the release tar file, systools now includes sys.config.src if it exists in the $ROOT/releases/<vsn>/ directory. This is to allow adjustments, e.g. resolving environment variables, after unpacking the release, but before installing it. This functionality requires a custom tool which uses sys.config.src as input and creates a correct sys.config file.

Own Id: OTP-14950 Aux Id: PR-1560

SASL 3.1.2

Fixed Bugs and Malfunctions

When upgrading with instruction 'restart_new_emulator', the generated temporary boot file used 'kernelProcess' statements from the old release instead of the new release. This is now corrected.

This correction is needed for upgrade to OTP-21.

Own Id: OTP-15017

SASL 3.1.1

Fixed Bugs and Malfunctions

The Report Browser, rb, could earlier not handle reports that were not lists, for example generated by error_logger:info_report({some, tuple}). This term is allowed as input to error_logger, but rb would state that "A report on bad form was encountered". This is now corrected.

Own Id: OTP-13906 Aux Id: ERL-261

SASL 3.1

Improvements and New Features

General Unicode improvements.

Own Id: OTP-14462

Files generated by release_handler and reltool, which might contain Unicode characters, are now encoded as UTF-8 and written with format "~tp" or "~ts". If the file is to be read by file:consult/1, an encoding comment is added.

Own Id: OTP-14463

The SASL error logger event handler, sasl_report_file_h, will now by default open its log file with encoding UTF-8. This can be overridden when configuring SASL, see configuration parameter sasl_error_logger in the SASL reference manual.

Own Id: OTP-14618

SASL 3.0.4

Fixed Bugs and Malfunctions

Documented default values for the 'mod' and 'start_phases' fields in .app files were not allowed as actual values in a .app file. This is now corrected.

Own Id: OTP-14029

Improvements and New Features

Miscellaneous updates due to atoms containing arbitrary Unicode characters.

Own Id: OTP-14285

SASL 3.0.3

Fixed Bugs and Malfunctions

When both options 'warnings_as_errors' and 'silent' were given to systools:make_script or systools:make_relup, no error reason would be returned if warnings occurred. Instead only the atom 'error' was returned. This is now corrected.

Options 'warnings_as_errors' and 'no_warn_sasl' are now also allowed for systools:make_tar.

Own Id: OTP-14170

SASL 3.0.2

Fixed Bugs and Malfunctions

code:add_pathsa/1 and command line option -pa both revert the given list of directories when adding it at the beginning of the code path. This is now documented.

Own Id: OTP-13920 Aux Id: ERL-267

SASL 3.0.1

Improvements and New Features

Improved dirty scheduler support. A purge of a module can now be performed without having to wait for completion of all ongoing dirty NIF calls.

Note that when enabling support for dirty schedulers, a new purge strategy will as of ERTS version 8.1 be enabled. This new strategy is not fully backwards compatible with the strategy used by default. For more information see the documentation of erlang:check_process_code/3.

Own Id: OTP-13808 Aux Id: OTP-13833

A new purge strategy has been introduced. The new strategy will by default be disabled during the OTP 19 release, but will be the only strategy available as of the OTP 20 release.

The new strategy is slightly incompatible with the strategy being used by default in OTP 19. Using the default strategy, processes holding funs that refer to the module being purged either fail a soft purge, or will be killed during a hard purge. The new strategy completely ignores funs. If funs referring to the code being purged exist, and are used after a purge, an exception will be raised upon usage. That is, the behavior will be exactly the same as the case when a fun is received by a process after the purge.

The new strategy can optionally be enabled when building OTP during OTP 19, and will automatically be enabled if the runtime system is built with support for dirty schedulers.

For more information see the documentation of erlang:check_process_code/3.

Own Id: OTP-13833

SASL 3.0

Improvements and New Features

The module 'overload' is removed.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-13184

SASL 2.7

Fixed Bugs and Malfunctions

During upgrade, the release_handler collects a list of supervisor pids in order to list all processes in the supervisor tree. If one of the supervisors (legitimately) exits before release_handler can examine it, then sys:get_status/1 would earlier be called with a dead pid, causing a 'noproc' error. This has been corrected.

Own Id: OTP-13291

Improvements and New Features

The module overload is deprecated and will be removed in OTP 19.

Own Id: OTP-13057

Improve implementation of supervisor child count, making it faster and more accurate for dynamic processes of a simple_one_for_one supervisor.

Own Id: OTP-13290

SASL 2.6.1

Improvements and New Features

Documentation improvements

Own Id: OTP-13000

SASL 2.6

Improvements and New Features

A mechanism for limiting the amount of text that the built-in error logger events will produce has been introduced. It is useful for limiting both the size of log files and the CPU time used to produce them.

This mechanism is experimental in the sense that it may be changed if it turns out that it does not solve the problem it is supposed to solve. In that case, there may be backward incompatible improvements to this mechanism.

See the documentation for the config parameter error_logger_format_depth in the Kernel application for information about how to turn on this feature.

Own Id: OTP-12864

SASL 2.5

Fixed Bugs and Malfunctions

The undocumented upgrade instruction {remove_module,PrePurge,PostPurge,DepMods} is removed. This instruction was added for symmetry reasons in OTP R7B, but was never documented or tested.

The existing instruction {add_module,Mod,DepMods} is now documented, and the complementing instruction {delete_module,Mod,DepMods} is added.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-11540

Improvements and New Features

The sasl_error_logger configuration parameter now supports the value {file,FileName,Modes} which allows the log file to be opened in other mode than write (for example, append mode).

Own Id: OTP-12778

SASL 2.4.1

Fixed Bugs and Malfunctions

The documentation erroneously specified that alarm_handler:clear_alarm/1 would clear all alarms with id AlarmId. This is now corrected according to the implementation - only the latest received alarm with the given AlarmId is cleared by the simple default handler.

Own Id: OTP-12025

SASL 2.4

Fixed Bugs and Malfunctions

The upgrade instruction 'restart_application' would earlier ignore the restart type configured in the .rel file and always restart the application as permanent. This is now changed, and the restart type from the .rel file is used. If restart type is 'load', the application will only be loaded and not started. If the restart type is 'none', the application will not be loaded nor started, but all modules in the application will be loaded. (Thanks to Tobias Schlager for reporting this problem)

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-11716

If systools:make_script/2 failed with reason duplicate_modules, and the silent flag was not used, a crash with reason function_clause would occur when systools tried to format the error message. This has been corrected. (Thanks to Jean-Sébastien Pédron)

Own Id: OTP-11819

Improvements and New Features

Calls to erlang:open_port/2 with 'spawn' are updated to handle space in the command path.

Own Id: OTP-10842

Some more documentation is added to explain the behavior when an upgrade includes new versions of ERTS, Kernel, STDLIB or SASL.

Own Id: OTP-11717

SASL 2.3.4

Fixed Bugs and Malfunctions

Don't try to add the log_mf_h handler in sasl unless configured to do so. Thanks to Richard Carlsson.

Own Id: OTP-11464

Fix confusing documentation about error handlers in SASL.(Thanks to Richard Carlsson)

Own Id: OTP-11507

A bug in the mechanism for upgrading core parts of Erlang/OTP (emulator, kernel, stdlib, sasl) caused a switch of paths between stdlib and sasl in the intermediate .script/.boot file. The bug was introduces along with this upgrade mechanism in R15B. It has now been corrected. (Thanks to Tobias Schlager)

Own Id: OTP-11529

Improvements and New Features

Added a boot file which skips loading the "$HOME/.erlang" file on startup. Enable by starting erlang with "erl -boot no_dot_erlang".

* INCOMPATIBILITY with false *

Own Id: OTP-8479 Aux Id: seq11510

SASL 2.3.3

Improvements and New Features

Add Fd usage in rb logging. Thanks to Eric Pailleau.

Own Id: OTP-11252

SASL 2.3.2

Fixed Bugs and Malfunctions

Fix receive support in erl_eval with a BEAM module. Thanks to Anthony Ramine.

Own Id: OTP-11137

SASL 2.3.1

Improvements and New Features

Some updates are made to systools and release_handler for handling of unicode.

Own Id: OTP-10782

SASL 2.3

Fixed Bugs and Malfunctions

release_handler_SUITE:otp_9864 deleted parts of the release_handler_SUITE_data directory so the test suite could not be executed twice without re-installation. This has been corrected.

Own Id: OTP-10394 Aux Id: kunagi-187 [98]

It is no longer possible to have {Mod,Vsn} in the 'modules' list in a .app file.

This was earlier possible, although never documented in the .app file reference manual. It was however visible in the documentation of application:load/[1,2], where the same term as in a .app file can be used as the first argument.

The possibility has been removed since the Vsn part was never used.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-10417

release_handler:upgrade_script and release_handler:downgrade_script could not read appup files with regexps. This has been corrected. (Thanks to Ulf Wiger)

Own Id: OTP-10463

Improvements and New Features

Where necessary a comment stating encoding has been added to Erlang files. The comment is meant to be removed in Erlang/OTP R17B when UTF-8 becomes the default encoding.

Own Id: OTP-10630

SASL 2.2.1

Fixed Bugs and Malfunctions

If sys.config existed, but was not readable or parseable, this would not be detected until after the upgrade and at the next node restart. The possibility for this to happen is now reduced by adding a check to systools:make_tar which fails the creation of the tar file if sys.config or relup does not have reasonable contents. Note that there are no detailed checks, only parsing and erlang term format check.

Own Id: OTP-9539

systools:make_script would allow {kernel,Vsn,load} in the .rel file, causing a .boot file which only loaded kernel and did not start it. This has been corrected. Only start type 'permanent', which is the default, is now allowed for kernel and stdlib.

Own Id: OTP-9652

release_handler:remove_release/1 now handles symlinked files properly

Own Id: OTP-9864

If stdlib was stated with a start type different from permanent in a .rel file, systools would incorrectly say that sasl had faulty start type. This has been corrected.

Own Id: OTP-9888

Sasl documentation earlier said that the InclApps parameters in a .rel file defaults to the empty list. This is not correct. It defaults to the same value as specified in the .app file. This has been corrected.

Own Id: OTP-9980

Applications that are listed in {applications,Apps} in the .app file were not sorted correctly by systools:make_script/1,2. They got the reverse order of how they were listed in the .app file. This is corrected so they are now sorted (internally between each other) in the same order as they are listed in the .rel file (i.e. the order they are listed in the .app file does no longer matter).

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-9984

Documentation of .appup files now also states that UpFromVsn and DownToVsn can be specified as regular expressions in order to avoid duplicated upgrade instructions.

Own Id: OTP-10001

Reltool would sometimes generate a .app file containing {start_phases,undefined}, which would cause an exception in systools at parse time. This has been corrected so reltool now omits the start_phases entry if the value is undefined. (Thanks to Juan Jose Comellas)

In order to align with reltool, sasl will also omit start_phases entries with value undefined in .script files.

Own Id: OTP-10003

SASL 2.2

Fixed Bugs and Malfunctions

Fix the mechanism for upgrading emulator.

The appup files for kernel, stdlib and sasl do now recognize two major releases back and include a 'restart_new_emulator' instruction.

Appup files can include regular expressions for matching earlier releases.

The mechanism for upgrading the emulator is changed so 'restart_new_emulator' will be the first instruction executed. The rest of the upgrade instruction will be executed after the emulator restart.

A new upgrade instruction 'restart_emulator' is added for the case where the emulator shall be restarted after all other upgrade instructions.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-9438

Add release_handler:which_releases/1

This is an extension to which_releases that allows a user to specify the status of the releases they wish to be returned. For instance it allows for quickly determining which release is 'permanent' without the need of parsing the entire release list. (Thanks to Joe Williams)

Own Id: OTP-9717

Add copy of rel file in releases/Vsn in release tar file

systool:make_tar stores the rel file in the releases directory. When unpacking with release_handler:unpack_release, the file is automatically moved to releases/Vsn/. If, however, the tar file is unpacked manually, the rel file might not be moved, and the next release unpacked might overwrite the rel file. To overcome this, systools:make_tar now stores a copy of the rel file in releases/Vsn/ directly and it is not longer necessary to move the file after unpacking.

The reason for keeping the file in the releases directory also is that is needs to be extracted separately before the release version (Vsn) is known.

Own Id: OTP-9746

SASL 2.1.10

Fixed Bugs and Malfunctions

The release_handler functionality on windows services was broken. This has been corrected.

Own Id: OTP-9306

If a new version of an application did not include any erlang module changes, the code path of the application was not updated by the release_handler unless a 'load_object_code' instruction was added for the application. This would be a problem if e.g. only some files in the priv dir were changed since calls to code:lib_dir or code:priv_dir would then point to the old location of the application. This has been corrected - now code:replace_path/2 will be called for all applications that are changed (i.e. when the application's vsn is changed in the .rel file).

Own Id: OTP-9402

The appup instruction 'delete_module' would cause a crash during upgrade if the module to be deleted was not loaded. This has been corrected.

Own Id: OTP-9417

If a path was given as ONLY 'ebin' and not for example './ebin', then systools:make_tar would fail with a function_clause exception in filename:join/1. This has been corrected. (Thanks to Nikola Skoric for reporting).

Own Id: OTP-9507

Implement or fix -Werror option

If -Werror is enabled and there are warnings no output file is written. Also make sure that error/warning reporting is consistent. (Thanks to Tuncer Ayaz)

Own Id: OTP-9536

Improved error information for timeouts during release_handler:install_release.

This patch addresses two cases where a timeout will occur during upgrade. 1) if a supervisor is suspended (call to get children from supervisor will hang) 2) if the child spec for a supervisor incorrectly states that it is a worker with a dynamic set of modules (call to get modules from gen_event will hang)

An error report will now be printed, and the return value of release_handler:install_release will indicate what happened. (Thanks to joe williams)

Own Id: OTP-9546

Improvements and New Features

release_handler:install_release could be very slow when there are many processes in the system. Some optimization work has been done both in erts and in the release handler in order to improve this.

A new option, purge, is added to release_handler:check_install_release which can be called first in order to speed up the execution of release_handler:install_release.

Own Id: OTP-9395

SASL 2.1.9.4

Fixed Bugs and Malfunctions

Remove traces of release_handler reading from filesystem when it has Masters list

There are a couple of places in release_handler and release_handler_1 that assumed it has a disk to read from, which in the case of an erl_prim_loader Loader other than efile is not necessarily true

Add check_paths/2 to do the equivalent of check_path/1 for when there is a Masters list

Change get_vsn to no longer get sent File paths but instead use the Bin since beam_lib:version being sent a file path causes it to read the local file system

Add get_current_vsn/1 as an equivalent to beam_lib:version(code:which(Mod)), but using erl_prim_loader:get_file instead of reading from local file system

(Thanks to Steven Gravell)

Own Id: OTP-9142

rb:stop did sometimes return {error,running}. This came from supervisor:delete_child and happened when the rb_server has not yet terminated when this function was called. Instead of having a separate gen_server call to rb_server for stopping the process, supervisor:terminate_child is now called. This is a synchronous function - i.e. it waits for the process to actually terminate before it returns.

A file descriptor leak in rb:scan_files is corrected. The index file was never closed after reading.

A mismatch in the behavior of rb:filter, when filter included 'no', is corrected. Such filters will now return all non-matching reports, not only the 'proplist' reports.

Own Id: OTP-9149

Start and end date for rb:filter/2 was specified as {{Y-M-D},...} in the help text instead of {{Y,M,D},...}. This has been corrected.

Own Id: OTP-9166

If some, but not all, of the sasl environment variables related to the log_mf_h error handler were missing sasl would successfully start but silently skip starting log_mf_h. This is corrected so sasl startup will now fail if one or two of the three variables are given. If none of the variables are given, sasl will start as before without starting log_mf_h.

Own Id: OTP-9185

Improvements and New Features

Change default behaviour to not check src code when creating release

Add new option src_tests to systools:make_script and systools:make_tar. The old option no_module_tests is now ignored as this is the default behaviour.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-9146 Aux Id: seq11803

SASL 2.1.9.3

Improvements and New Features

Honor start type in .rel files when building relup files

Previously, relup file always included an application:start(Application, permanent) apply instruction for every application that appear in the UpTo/DowFrom release file, whatever their start type in the release file.

The new implementation fixes this bug by honoring the start type according to the rel(5) format. If the start type is none, no apply line is included in the relup. If the start type is load, the relup includes instruction to only load the application. Otherwise, the relup includes an instruction to start the application to the according type.

The fix is implemented by adding a new parameter to the add_application high level appup instruction. This new parameter is documented in appup(5).

Own Id: OTP-9097

SASL 2.1.9.2

Fixed Bugs and Malfunctions

In R13B04 sys:get_status was modified to invoke format_status/2 in the callback module if the module exports that function. This resulted in a change to the term returned from calling sys:get_status on the supervisor module, since supervisor is a gen_server and gen_server exports format_status. The sasl release_handler_1 module had a dependency on the pre-R13B04 term returned by sys:get_status when invoked on a supervisor, so the R13B04 change broke that dependency.

This problem has been fixed by change release_handler_1 to handle both the pre-R13B04 and R13B04 terms that sys:get_status can return from a supervisor.

Own Id: OTP-8619 Aux Id: seq11570

SASL 2.1.9.1

Improvements and New Features

Use an infinity timeout in all calls to gen_server:call() in the SASL application.

Own Id: OTP-8506 Aux Id: seq11509

SASL 2.1.9

Improvements and New Features

The re:grep/1 function now uses the 're' module instead of the deprecated 'regexp' module. There are new functions rb:filter/1 and rb:filter/2 for easier filtering of reports. (Thanks to Alvaro Videla.)

Own Id: OTP-8443

There is new function sasl_report:format_report/3 that works like the existing sasl_report:write_report/3 function except that it returns a formatted string. Note that there is currently no documentation for the sasl_report module. (Thanks to Jay Nelson.)

Own Id: OTP-8445

Cleanups suggested by tidier and modernization of types and specs.

Own Id: OTP-8455

SASL 2.1.8

Improvements and New Features

The documentation is now built with open source tools (xsltproc and fop) that exists on most platforms. One visible change is that the frames are removed.

Own Id: OTP-8201

SASL 2.1.7

Improvements and New Features

The Windows utility Erlsrv, run in interactive mode now accepts options for registering internal service name and description field of Windows registry database.

Own Id: OTP-8132

SASL 2.1.6

Fixed Bugs and Malfunctions

When using the SASL application configuration parameter masters the error tuple {error,{no_such_file,{Master,FileName}}} was sometimes returned even though the file FileName existed.

Own Id: OTP-7667

Improvements and New Features

Missing preloaded modules added

Own Id: OTP-7820

SASL 2.1.5.4

Improvements and New Features

A Dialyzer warning was eliminated

Own Id: OTP-7635

SASL 2.1.5.3

Improvements and New Features

Minor changes.

Own Id: OTP-7388

SASL 2.1.5.2

Improvements and New Features

Minor updates.

Own Id: OTP-6998

SASL 2.1.5.1

Improvements and New Features

Minor Makefile changes.

Own Id: OTP-6689

Obsolete guard tests (such as list()) have been replaced with the modern guard tests (such as is_list()).

Own Id: OTP-6725

SASL 2.1.5

Fixed Bugs and Malfunctions

Removed some dead code from erlsrv:get_service/2, release_handler:do_write_file/2, systools_relup:foreach_baserel_up/7 and systools_relup:foreach_baserel_dn/7.

Own Id: OTP-6499

SASL 2.1.4

Improvements and New Features

Added an option {outdir,Dir} to the functions in systools, making it possible to specify in which directory a boot script, relup file or release package file should be placed.

Also, when using systools:make_tar/2 to create a release package file, the boot script, relup file and sys.config are now searched for also in the current working directory and any directory specified by the path option, not only in the directory of the .rel file.

As part of the work some minor bugs have been corrected:

systools:make_script/1,2 now returns error if the .script and/or .boot file could not be opened for writing, not ok.

systools:make_tar/1,2 can now handle a RelName argument which includes a path. Previously this would cause the .rel file to end up in the wrong directory in the resulting tar file.

A documentation error for systools:make_tar/1,2: The .rel file is placed in the releases directory in the tar file, not releases/RelVsn.

Own Id: OTP-6226

SASL 2.1.3

Fixed Bugs and Malfunctions

release_handler:upgrade_app/2 and release_handler:downgrade_app/2,3 -- used for testing application upgrade and downgrade according to the .appup file -- now update application configuration parameters correctly. (Thanks to Serge Aleynikov)

Own Id: OTP-6162

SASL 2.1.2

Fixed Bugs and Malfunctions

Fixed some minor bugs in release_handler found by Dialyzer.

Own Id: OTP-6039

SASL 2.1.1

Improvements and New Features

Added a number of functions to release_handler which makes it possible to test upgrade and downgrade of applications according to an .appup file "on the fly":
- upgrade_app/2
- upgrade_script/2
- downgrade_app/2,3
- downgrade_script/3
- eval_appup_script/4

Own Id: OTP-5858

SASL 2.1

Improvements and New Features

A new option {update_paths,Bool} has been added for release_handler:install_release/2. It indicates if all application code paths should be updated (Bool==true), or if only code paths for modified applications should be updated (Bool==false, default).

release_handler:set_unpacked/2 now returns an error tuple if a specified application directory does not exist.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-5761

SASL 2.0.1

Improvements and New Features

A bug that made it impossible to call rb:show(N) (N being an integer) twice without getting an error has been fixed.

Own Id: OTP-5287

Introduction

Scope

The SASL application provides support for:

Error logging

Alarm handling

Release handling

Report browsing

Section SASL Error Logging describes the error handler that produces the supervisor, progress, and crash reports, which can be written to screen or to a specified file. It also describes the Report Browser (RB).

The sections about release structure and release handling have been moved to section OTP Design Principles in System Documentation.

Prerequisites

It is assumed that the reader is familiar with the Erlang programming language.

SASL Error Logging

Note

The SASL error logging concept described in this section is deprecated since Erlang/OTP 21.0, when the new logging API was introduced.

The new default behaviour is that the SASL application no longer affects which log events that are logged. Supervisor reports and crash reports are logged via the default logger handler which is setup by Kernel. Progress reports are by default not logged, but can be enabled by setting the primary log level to info, for example by using the Kernel configuration parameter logger_level.

The old SASL error logging behaviour can be re-enabled by setting the Kernel configuration parameter logger_sasl_compatible to true.

The mechanism for multi-file error report logging as described in this section is also kept for backwards compatibility. However, the new logging API also introduces logger_disk_log_h, which is a logger handler that can print to multiple files using disk_log.

SASL reports

The SASL application introduces three types of reports:

Supervisor report

Progress report

Crash report

When the SASL application is started, it adds a Logger handler that formats and writes these reports, as specified in the configuration parameters for SASL.

Supervisor Report

A supervisor report is issued when a supervised child terminates unexpectedly. A supervisor report contains the following items:

Supervisor - Name of the reporting supervisor.

Context - Indicates in which phase the child terminated from the supervisor's point of view. This can be start_error, child_terminated, or shutdown_error.

Reason - Termination reason.

Offender - Start specification for the child.

Progress Report

A progress report is issued when a supervisor starts or restarts a child. A progress report contains the following items:

Supervisor - Name of the reporting supervisor.

Started - Start specification for the successfully started child.

Crash Report

Processes started with functions proc_lib:spawn or proc_lib:spawn_link are wrapped within a catch. A crash report is issued when such a process terminates with an unexpected reason, which is any reason other than normal, shutdown, or {shutdown,Term}. Processes using behaviors gen_server, gen_fsm or gen_statem are examples of such processes. A crash report contains the following items:

Crasher - Information about the crashing process, such as initial function call, exit reason, and message queue.

Neighbours - Information about processes that are linked to the crashing process and do not trap exits. These processes are the neighbours that terminate because of this process crash. The information gathered is the same as the information for Crasher, described in the previous item.

Example

The following example shows the reports generated when a process crashes. The example process is a permanent process supervised by the test_sup supervisor. A division by zero is executed and the error is first reported by the faulty process. A crash report is generated, as the process was started using function proc_lib:spawn/3. The supervisor generates a supervisor report showing the crashed process. A progress report is generated when the process is finally restarted.

        =ERROR REPORT==== 27-May-1996::13:38:56 ===
        <0.63.0>: Divide by zero !

        =CRASH REPORT==== 27-May-1996::13:38:56 ===
        crasher:
        pid: <0.63.0>
        registered_name: []
        error_info: {badarith,{test,s,[]}}
        initial_call: {test,s,[]}
        ancestors: [test_sup,<0.46.0>]
        messages: []
        links: [<0.47.0>]
        dictionary: []
        trap_exit: false
        status: running
        heap_size: 128
        stack_size: 128
        reductions: 348
        neighbours:

        =SUPERVISOR REPORT==== 27-May-1996::13:38:56 ===
        Supervisor: {local,test_sup}
        Context:    child_terminated
        Reason:     {badarith,{test,s,[]}}
        Offender:   [{pid,<0.63.0>},
        {name,test},
        {mfa,{test,t,[]}},
        {restart_type,permanent},
        {shutdown,200},
        {child_type,worker}]

        =PROGRESS REPORT==== 27-May-1996::13:38:56 ===
        Supervisor: {local,test_sup}
        Started:  [{pid,<0.64.0>},
        {name,test},
        {mfa,{test,t,[]}},
        {restart_type,permanent},
        {shutdown,200},
        {child_type,worker}]

Multi-File Error Report Logging

Multi-file error report logging is used to store error messages received by error_logger. The error messages are stored in several files and each file is smaller than a specified number of kilobytes. No more than a specified number of files exist at the same time. The logging is very fast, as each error message is written as a binary term.

For more details, see the sasl(6) application in the Reference Manual.

Report Browser

The report browser is used to browse and format error reports written by the error logger handler log_mf_h defined in STDLIB.

The log_mf_h handler writes all reports to a report logging directory, which is specified when configuring the SASL application.

If the report browser is used offline, the reports can be copied to another directory specified when starting the browser. If no such directory is specified, the browser reads reports from the SASL error_logger_mf_dir.

Starting Report Browser

Start the rb_server with function rb:start([Options]) as shown in the following example:

        5> rb:start([{max, 20}]).
        rb: reading report...done.
        rb: reading report...done.
        rb: reading report...done.
        rb: reading report...done.
        {ok,<0.199.0>}

Online Help

Enter command rb:help() to access the report browser online help system.

List Reports in Server

Use function rb:list() to list all loaded reports:

        4> rb:list().
        No                Type          Process       Date     Time
        ==                ====          =======       ====     ====
        20            progress         <0.17.0> 1996-10-16 16:14:54
        19            progress         <0.14.0> 1996-10-16 16:14:55
        18               error         <0.15.0> 1996-10-16 16:15:02
        17            progress         <0.14.0> 1996-10-16 16:15:06
        16            progress         <0.38.0> 1996-10-16 16:15:12
        15            progress         <0.17.0> 1996-10-16 16:16:14
        14            progress         <0.17.0> 1996-10-16 16:16:14
        13            progress         <0.17.0> 1996-10-16 16:16:14
        12            progress         <0.14.0> 1996-10-16 16:16:14
        11               error         <0.17.0> 1996-10-16 16:16:21
        10               error         <0.17.0> 1996-10-16 16:16:21
        9        crash_report  release_handler 1996-10-16 16:16:21
        8   supervisor_report         <0.17.0> 1996-10-16 16:16:21
        7            progress         <0.17.0> 1996-10-16 16:16:21
        6            progress         <0.17.0> 1996-10-16 16:16:36
        5            progress         <0.17.0> 1996-10-16 16:16:36
        4            progress         <0.17.0> 1996-10-16 16:16:36
        3            progress         <0.14.0> 1996-10-16 16:16:36
        2               error         <0.15.0> 1996-10-16 16:17:04
        1            progress         <0.14.0> 1996-10-16 16:17:09
        ok

Show Reports

Use function rb:show(Number) to show details of a specific report:

7> rb:show(4).

PROGRESS REPORT  <0.20.0>                                   1996-10-16 16:16:36
===============================================================================
supervisor                                                     {local,sasl_sup}
started
[{pid,<0.24.0>},
{name,release_handler},
{mfa,{release_handler,start_link,[]}},
{restart_type,permanent},
{shutdown,2000},
{child_type,worker}]

ok
8> rb:show(9).

CRASH REPORT  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================
Crashing process
pid                                                                 <0.24.0>
registered_name                                              release_handler
error_info                             {undef,{release_handler,mbj_func,[]}}
initial_call
{gen,init_it,
[gen_server,
<0.20.0>,
<0.20.0>,
{erlang,register},
release_handler,
release_handler,
[],
[]]}
ancestors                                                [sasl_sup,<0.18.0>]
messages                                                                  []
links                                                    [<0.23.0>,<0.20.0>]
dictionary                                                                []
trap_exit                                                              false
status                                                               running
heap_size                                                                610
stack_size                                                               142
reductions                                                                54

ok

Search Reports

All reports containing a common pattern can be shown. Suppose a process crashes because it tries to call a non-existing function release_handler:mbj_func/1. The reports can then be shown as follows:

12> rb:grep("mbj_func").
Found match in report number 11

ERROR REPORT  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================

** undefined function: release_handler:mbj_func[] **
Found match in report number 10

ERROR REPORT  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================

** Generic server release_handler terminating
** Last message in was {unpack_release,hej}
** When Server state == {state,[],
"/home/dup/otp2/otp_beam_sunos5_p1g_7",
[{release,
"OTP  APN 181 01",
"P1G",
undefined,
[],
permanent}],
undefined}
** Reason for termination ==
** {undef,{release_handler,mbj_func,[]}}
Found match in report number 9

CRASH REPORT  <0.24.0>                                      1996-10-16 16:16:21
===============================================================================
Crashing process
pid                                                                 <0.24.0>
registered_name                                              release_handler
error_info                             {undef,{release_handler,mbj_func,[]}}
initial_call
{gen,init_it,
[gen_server,
<0.20.0>,
<0.20.0>,
{erlang,register},
release_handler,
release_handler,
[],
[]]}
ancestors                                                [sasl_sup,<0.18.0>]
messages                                                                  []
links                                                    [<0.23.0>,<0.20.0>]
dictionary                                                                []
trap_exit                                                              false
status                                                               running
heap_size                                                                610
stack_size                                                               142
reductions                                                                54

Found match in report number 8

SUPERVISOR REPORT  <0.20.0>                                 1996-10-16 16:16:21
===============================================================================
Reporting supervisor                                           {local,sasl_sup}

Child process
errorContext                                                child_terminated
reason                                 {undef,{release_handler,mbj_func,[]}}
pid                                                                 <0.24.0>
name                                                         release_handler
start_function                               {release_handler,start_link,[]}
restart_type                                                       permanent
shutdown                                                                2000
child_type                                                            worker

ok

Stop Server

Use function rb:stop() to stop the rb_server:

13> rb:stop().
ok

appup

Application upgrade file

Description

The application upgrade file defines how an application is upgraded or downgraded in a running system.

This file is used by the functions in systools when generating a release upgrade file relup.

File Syntax

The application upgrade file is to be called Application.appup, where Application is the application name. The file is to be located in the ebin directory for the application.

The .appup file contains one single Erlang term, which defines the instructions used to upgrade or downgrade the application. The file has the following syntax:

{Vsn,
  [{UpFromVsn, Instructions}, ...],
  [{DownToVsn, Instructions}, ...]}.

Vsn = string() - Current application version.

UpFromVsn = string() | binary() - An earlier application version to upgrade from. If it is a string, it is interpreted as a specific version number. If it is a binary, it is interpreted as a regular expression that can match multiple version numbers.

DownToVsn = string() | binary() - An earlier application version to downgrade to. If it is a string, it is interpreted as a specific version number. If it is a binary, it is interpreted as a regular expression that can match multiple version numbers.

Instructions - A list of release upgrade instructions, see Release Upgrade Instructions. It is recommended to use high-level instructions only. These are automatically translated to low-level instructions by systools when creating the relup file.

To avoid duplication of upgrade instructions, it is allowed to use regular expressions to specify UpFromVsn and DownToVsn. To be considered a regular expression, the version identifier must be specified as a binary. For example, the following match all versions 2.1.x, where x is any number:

<<"2\\.1\\.[0-9]+">>

Notice that the regular expression must match the complete version string, so this example works for, for example, 2.1.1, but not for 2.1.1.1.

Release Upgrade Instructions

Release upgrade instructions are interpreted by the release handler when an upgrade or downgrade is made. For more information, see Release Handling in OTP Design Principles.

A process is said to use a module Mod if Mod is listed in the Modules part of the child specification used to start the process, see supervisor. In the case of gen_event, an event manager process is said to use Mod if Mod is an installed event handler.

High-Level Instructions

{update, Mod}
{update, Mod, supervisor}
{update, Mod, Change}
{update, Mod, DepMods}
{update, Mod, Change, DepMods}
{update, Mod, Change, PrePurge, PostPurge, DepMods}
{update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
{update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
  Mod = atom()
  ModType = static | dynamic
  Timeout = int()>0 | default | infinity
  Change = soft | {advanced,Extra}
    Extra = term()
  PrePurge = PostPurge = soft_purge | brutal_purge
  DepMods = [Mod]

Synchronized code replacement of processes using module Mod.

All those processes are suspended using sys:suspend, the new module version is loaded, and then the processes are resumed using sys:resume.

Change - Defaults to soft and defines the type of code change. If it is set to {advanced,Extra}, implemented processes using gen_server, gen_fsm, gen_statem, or gen_event transform their internal state by calling the callback function code_change. Special processes call the callback function system_code_change/4. In both cases, the term Extra is passed as an argument to the callback function.

PrePurge - Defaults to brutal_purge. It controls what action to take with processes executing old code before loading the new module version. If the value is brutal_purge, the processes are killed. If the value is soft_purge, release_handler:install_release/1 returns {error,{old_processes,Mod}}.

PostPurge - Defaults to brutal_purge. It controls what action to take with processes that are executing old code when the new module version has been loaded. If the value is brutal_purge, the code is purged when the release is made permanent and the processes are killed. If the value is soft_purge, the release handler purges the old code when no remaining processes execute the code.

DepMods - Defaults to [] and defines other modules that Mod is dependent on. In the relup file, instructions for suspending processes using Mod come before instructions for suspending processes using modules in DepMods when upgrading, and conversely when downgrading. In case of circular dependencies, the order of the instructions in the appup file is kept.

Timeout - Defines the time-out when suspending processes. If no value or default is specified, the default value for sys:suspend is used.

ModType - Defaults to dynamic. It specifies if the code is "dynamic", that is, if a process using the module spontaneously switches to new code, or if it is "static". When doing an advanced update and upgrade, the new version of a dynamic module is loaded before the process is asked to change code. When downgrading, the process is asked to change code before loading the new version. For static modules, the new version is loaded before the process is asked to change code, both in the case of upgrading and downgrading. Callback modules are dynamic.

update with argument supervisor is used when changing the start specification of a supervisor.

{load_module, Mod}
{load_module, Mod, DepMods}
{load_module, Mod, PrePurge, PostPurge, DepMods}
  Mod = atom()
  PrePurge = PostPurge = soft_purge | brutal_purge
  DepMods = [Mod]

Simple code replacement of the module Mod.

For a description of PrePurge and PostPurge, see update above.

DepMods defaults to [] and defines which other modules Mod is dependent on. In the relup file, instructions for loading these modules come before the instruction for loading Mod when upgrading, and conversely when downgrading.

{add_module, Mod}
{add_module, Mod, DepMods}
  Mod = atom()
  DepMods = [Mod]

Loads a new module Mod.

DepMods defaults to [] and defines which other modules Mod is dependent on. In the relup file, instructions related to these modules come before the instruction for loading Mod when upgrading, and conversely when downgrading.

{delete_module, Mod}
{delete_module, Mod, DepMods}
  Mod = atom()

Deletes a module Mod using the low-level instructions remove and purge.

DepMods defaults to [] and defines which other modules Mod is dependent on. In the relup file, instructions related to these modules come before the instruction for removing Mod when upgrading, and conversely when downgrading.

{add_application, Application}
{add_application, Application, Type}
  Application = atom()
  Type = permanent | transient | temporary | load | none

Adding an application means that the modules defined by the modules key in the .app file are loaded using add_module.

Type defaults to permanent and specifies the start type of the application. If Type = permanent | transient | temporary, the application is loaded and started in the corresponding way, see application. If Type = load, the application is only loaded. If Type = none, the application is not loaded and not started, although the code for its modules is loaded.

{remove_application, Application}
  Application = atom()

Removing an application means that the application is stopped, the modules are unloaded using delete_module, and then the application specification is unloaded from the application controller.

{restart_application, Application}
  Application = atom()

Restarting an application means that the application is stopped and then started again, similar to using the instructions remove_application and add_application in sequence. Note that, even if the application has been started before the release upgrade is performed, restart_application may only load it rather than start it, depending on the application's start type: If Type = load, the application is only loaded. If Type = none, the application is not loaded and not started, although the code for its modules is loaded.

Low-Level Instructions

{load_object_code, {App, Vsn, [Mod]}}
  App = Mod = atom()
  Vsn = string()

Reads each Mod from directory App-Vsn/ebin as a binary. It does not load the modules. The instruction is to be placed first in the script to read all new code from the file to make the suspend-load-resume cycle less time-consuming.

point_of_no_return

If a crash occurs after this instruction, the system cannot recover and is restarted from the old release version. The instruction must only occur once in a script. It is to be placed after all load_object_code instructions.

{load, {Mod, PrePurge, PostPurge}}
  Mod = atom()
  PrePurge = PostPurge = soft_purge | brutal_purge

Before this instruction occurs, Mod must have been loaded using load_object_code. This instruction loads the module. PrePurge is ignored. For a description of PostPurge, see the high-level instruction update earlier.

{remove, {Mod, PrePurge, PostPurge}}
  Mod = atom()
  PrePurge = PostPurge = soft_purge | brutal_purge

Makes the current version of Mod old. PrePurge is ignored. For a description of PostPurge, see the high-level instruction update earlier.

{purge, [Mod]}
  Mod = atom()

Purges each module Mod, that is, removes the old code. Notice that any process executing purged code is killed.

{suspend, [Mod | {Mod, Timeout}]}
  Mod = atom()
  Timeout = int()>0 | default | infinity

Tries to suspend all processes using a module Mod. If a process does not respond, it is ignored. This can cause the process to die, either because it crashes when it spontaneously switches to new code, or as a result of a purge operation. If no Timeout is specified or default is specified, the default value for sys:suspend is used.

{resume, [Mod]}
  Mod = atom()

Resumes all suspended processes using a module Mod.

{code_change, [{Mod, Extra}]}
{code_change, Mode, [{Mod, Extra}]}
  Mod = atom()
  Mode = up | down
  Extra = term()

Mode defaults to up and specifies if it is an upgrade or downgrade. This instruction sends a code_change system message to all processes using a module Mod by calling function sys:change_code, passing term Extra as argument.

{stop, [Mod]}
  Mod = atom()

Stops all processes using a module Mod by calling supervisor:terminate_child/2. This instruction is useful when the simplest way to change code is to stop and restart the processes that run the code.

{start, [Mod]}
  Mod = atom()

Starts all stopped processes using a module Mod by calling supervisor:restart_child/2.

{sync_nodes, Id, [Node]}
{sync_nodes, Id, {M, F, A}}
  Id = term()
  Node = node()
  M = F = atom()
  A = [term()]

apply(M, F, A) must return a list of nodes.

This instruction synchronizes the release installation with other nodes. Each Node must evaluate this command with the same Id. The local node waits for all other nodes to evaluate the instruction before execution continues. If a node goes down, it is considered to be an unrecoverable error, and the local node is restarted from the old release. There is no time-out for this instruction, which means that it can hang forever.

{apply, {M, F, A}}
  M = F = atom()
  A = [term()]

Evaluates apply(M, F, A).

If the instruction appears before instruction point_of_no_return, a failure is caught. release_handler:install_release/1 then returns {error,{'EXIT',Reason}}, unless {error,Error} is thrown or returned. Then it returns {error,Error}.

If the instruction appears after instruction point_of_no_return and the function call fails, the system is restarted.

restart_new_emulator

This instruction is used when the application ERTS, Kernel, STDLIB, or SASL is upgraded. It shuts down the current emulator and starts a new one. All processes are terminated gracefully, and the new version of ERTS, Kernel, STDLIB, and SASL are used when the emulator restarts. Only one restart_new_emulator instruction is allowed in the relup file, and it must be placed first. systools:make_relup/3,4 ensures this when the relup file is generated. The rest of the instructions in the relup file is executed after the restart as a part of the boot script.

An info report is written when the upgrade is completed. To programmatically determine if the upgrade is complete, call release_handler:which_releases/0,1 and check if the expected release has status current.

The new release must still be made permanent after the upgrade is completed, otherwise the old emulator is started if there is an emulator restart.

Warning

As stated earlier, instruction restart_new_emulator causes the emulator to be restarted with new versions of ERTS, Kernel, STDLIB, and SASL. However, all other applications do at startup run their old versions in this new emulator. This is usually no problem, but every now and then incompatible changes occur to the core applications, which can cause trouble in this setting. Such incompatible changes (when functions are removed) are normally preceded by a deprecation over two major releases. To ensure that your application is not crashed by an incompatible change, always remove any call to deprecated functions as soon as possible.

restart_emulator

This instruction is similar to restart_new_emulator, except it must be placed at the end of the relup file. It is not related to an upgrade of the emulator or the core applications, but can be used by any application when a complete reboot of the system is required.

When generating the relup file, systools:make_relup/3,4 ensures that there is only one restart_emulator instruction and that it is the last instruction in the relup file.

See Also

release_handler, relup(4), supervisor, systools

rel

Release resource file

Description

The release resource file specifies which applications are included in a release (system) based on Erlang/OTP.

This file is used by the functions in systools when generating start scripts (.script, .boot) and release upgrade files (relup).

File Syntax

The release resource file is to be called Name.rel.

The .rel file contains one single Erlang term, which is called a release specification. The file has the following syntax:

{release, {RelName,Vsn}, {erts, EVsn},
  [{Application, AppVsn} |
   {Application, AppVsn, Type} |
   {Application, AppVsn, IncApps} |
   {Application, AppVsn, Type, IncApps}]}.

RelName = string() - Release name.

Vsn = string() - Release version.

EVsn = string() - ERTS version the release is intended for.

Application = atom() - Name of an application included in the release.

AppVsn = string() - Version of an application included in the release.

Type = permanent | transient | temporary | load | none - Start type of an application included in the release.

If Type = permanent | transient | temporary, the application is loaded and started in the corresponding way, see application.

If Type = load, the application is only loaded.

If Type = none, the application is not loaded and not started, although the code for its modules is loaded.

Defaults to permanent

IncApps = [atom()] - A list of applications that are included by an application included in the release. The list must be a subset of the included applications specified in the application resource file (Application.app) and overrides this value. Defaults to the same value as in the application resource file.

Note

The list of applications must contain the Kernel and STDLIB applications.

See Also

application, relup(4), systools

relup

Release upgrade file

Description

The release upgrade file describes how a release is upgraded in a running system.

This file is automatically generated by systools:make_relup/3,4, using a release resource file (.rel), application resource files (.app), and application upgrade files (.appup) as input.

File Syntax

In a target system, the release upgrade file is to be located in directory $ROOT/releases/Vsn.

The relup file contains one single Erlang term, which defines the instructions used to upgrade the release. The file has the following syntax:

{Vsn,
  [{UpFromVsn, Descr, Instructions}, ...],
  [{DownToVsn, Descr, Instructions}, ...]}.

Vsn = string() - Current release version.

UpFromVsn = string() - Earlier version of the release to upgrade from.

Descr = term() - A user-defined parameter passed from the function systools:make_relup/3,4. It is used in the return value of release_handler:install_release/1,2.

Instructions - A list of low-level release upgrade instructions, see appup(4). It consists of the release upgrade instructions from the respective application upgrade files (high-level instructions are translated to low-level instructions), in the same order as in the start script.

DownToVsn = string() - Earlier version of the release to downgrade to.

See Also

app(4), appup(4), rel(4), release_handler, systools

script

Boot script

Description

The boot script describes how the Erlang runtime system is started. It contains instructions for which code to load, and which processes and applications to start.

Command erl -boot Name starts the system with a boot file called Name.boot, which is generated from the Name.script file, using systools:script2boot/1.

The .script file is generated by systools from a .rel file and from .app files.

File Syntax

The boot script is stored in a file with extension .script. The file has the following syntax:

{script, {Name, Vsn},
 [
  {progress, loading},
  {preLoaded, [Mod1, Mod2, ...]},
  {path, [Dir1,"$ROOT/Dir",...]}.
  {primLoad, [Mod1, Mod2, ...]},
  ...
  {kernel_load_completed},
  {progress, loaded},
  {kernelProcess, Name, {Mod, Func, Args}},
  ...
  {apply, {Mod, Func, Args}},
  ...
  {progress, started}]}.

Name = string() - Defines the system name.

Vsn = string() - Defines the system version.

{progress, Term} - Sets the "progress" of the initialization program. The init:get_status/0 function returns the current value of the progress, which is {InternalStatus,Term}.

{path, [Dir]} - Dir is a string. This argument sets the load path of the system to [Dir]. The load path used to load modules is obtained from the initial load path, which is given in the script file, together with any path flags that were supplied in the command-line arguments. The command-line arguments modify the path as follows:

-pa Dir1 Dir2 ... DirN adds the directories DirN, DirN-1, ..., Dir2, Dir1 to the front of the initial load path.

-pz Dir1 Dir2 ... DirN adds the directories Dir1, Dir2, ..., DirN to the end of the initial load path.

-path Dir1 Dir2 ... DirN defines a set of directories Dir1, Dir2, ..., DirN, which replace the search path given in the script file. Directory names in the path are interpreted as follows:

Directory names starting with / are assumed to be absolute path names.

Directory names not starting with / are assumed to be relative the current working directory.

The special $ROOT variable can only be used in the script, not as a command-line argument. The given directory is relative the Erlang installation directory.

{primLoad, [Mod]} - Loads the modules [Mod] from the directories specified in Path. The script interpreter fetches the appropriate module by calling erl_prim_loader:get_file(Mod). A fatal error that terminates the system occurs if the module cannot be located.

{kernel_load_completed} - Indicates that all modules that must be loaded before any processes are started are loaded. In interactive mode, all {primLoad,[Mod]} commands interpreted after this command are ignored, and these modules are loaded on demand. In embedded mode, kernel_load_completed is ignored, and all modules are loaded during system start.

{kernelProcess, Name, {Mod, Func, Args}} - Starts the "kernel process" Name by evaluating apply(Mod, Func, Args). The start function is to return {ok, Pid} or ignore. The init process monitors the behavior of Pid and terminates the system if Pid dies. Kernel processes are key components of the runtime system. Users do not normally add new kernel processes.

{apply, {Mod, Func, Args}}. - The init process evaluates apply(Mod, Func, Args). The system terminates if this results in an error. The boot procedure hangs if this function never returns.

Note

In an interactive system, the code loader provides demand-driven code loading, but in an embedded system the code loader loads all code immediately. The same version of code is used in both cases. The code server calls init:get_argument(mode) to determine if it is to run in demand mode or non-demand driven mode.

See Also

systools

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],
                               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.

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.