release_handler(3)

📦
version 29.0.6 · 2 versions
, in nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 release_handler(3) 💖

Erlang Module Definition · bestie edition ✨

🌸 NAME 🌸

release_handler — Unpacking and Installation of Release Packages 🎀

✨ DESCRIPTION ✨

okay so. The release handler process belongs to the SASL application, and it's the one in charge of release handling — that's unpacking, installation, and removal of release packages. She's the main character of upgrades, periodt. 👑

If you want an intro to release handling plus a whole example, go read the Release Handling section in OTP Design Principles. It's giving required reading fr fr.

So. A release package is a compressed tar file containing code for a certain version of a release, and you make one by calling systools:make_tar/1,2. That package is supposed to live in the $ROOT/releases directory of the previous version of the release, where $ROOT is the installation root directory, code:root_dir(). You can point at a different releases directory with the SASL configuration parameter releases_dir or the OS environment variable RELDIR. Heads up: the release handler must have write access to this directory to install the new release. Her persistent state is stored right there in a file called RELEASES. 💅

A release package is always to contain:

  • release resource file, Name.rel
  • boot script, Name.boot

The .rel file has the info about the release: its name, version, and which ERTS and application versions it uses. iykyk.

A release package can also contain:

  • release upgrade file, relup
  • system configuration file, sys.config
  • 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. Iconic, honestly.

So here's the flow, bestie. The release package can be unpacked — that 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 the one used if the system is restarted. An installed release — any one except the permanent one — can be removed. When a release is removed, all files belonging to that release only are deleted. no crumbs left. 🧹

Every release version has a status, and it can be unpacked, current, permanent, or old. There is always one latest release, which either has status permanent (the normal case) or current (installed, but not yet made permanent). Here's what each status actually means — the full vibe check 🦋:

  • status -
    • action unpack → next status unpacked
  • status unpacked
    • action install → next status current
    • action remove → next status -
  • status current
    • action make_permanent → next status permanent
    • action install other → next status old
    • action remove → next status -
  • status permanent
    • action make other permanent → next status old
    • action install → next status permanent
  • status old
    • action reboot_old → next status permanent
    • action install → next status current
    • action remove → next status -

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 goal is to install one release package in the system, no matter how many nodes there are. So yes, it's 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. Cute, right? 🌈

For release handling to work properly, the runtime system must know which release it's 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 that in Embedded System in System Documentation. In this case, the system configuration file sys.config is mandatory. no skipping, bestie 😭

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. very demure, very mindful of services 💅

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. your problem now 🫶

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 Path does 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. so slay of them honestly ✨

WARNING: These functions are primarily intended for simplified testing of .appup files. They are not run within the context of the release_handler process. They must therefore not be used together with calls to install_release/1,2, as this causes the release_handler to end up in an inconsistent state. No persistent information is updated, so these functions can be used on any Erlang node, embedded or not. Also, using these functions does not affect which code is loaded if there is a reboot. If the upgrade or downgrade fails, the application can end up in an inconsistent state. 😭 read this one twice bestie

See Also

OTP Design Principles, config, rel, relup, script, sys, systools

👑 FUNCTIONS 👑

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. like a vibe check but for releases 💅

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. that's the line you don't cross, fr fr 🌸

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 ✨

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

okay bestie so this one creates an initial RELEASES file that the release handler uses. This file must exist to install new releases. No RELEASES file = no new release, periodt. 💅

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.

🌸 downgrade_app 🌸

       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 🦋

       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 💖

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

Evaluates an application upgrade or downgrade script Script, the result from calling upgrade_script/2 or downgrade_script/3, exactly in the same way as install_release/1,2 does. ✨

App is the name of the application, which must be started. ToVsn is the version to be upgraded/downgraded to, and ToDir is the library directory of this version. The corresponding modules as well as the .app and .appup files are to be located under Dir/ebin.

Returns one of the following:

  • {ok, Unpurged} if evaluating the script is successful, where Unpurged is a list of unpurged modules
  • restart_emulator if this instruction is encountered in the script
  • {error, Reason} if an error occurred when finding or evaluating the script

If the restart_new_emulator instruction is found in the script, eval_appup_script/4 returns {error,restart_new_emulator}. This because restart_new_emulator requires a new version of the emulator to be started before the rest of the upgrade instructions can be executed, and this can only be done by install_release/1,2.

🎀 install_file 🎀

       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 👑

       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 — this one sets the time-out for all the calls to sys:change_code. If you don't pass a value, or you literally pass default, then the default value defined in sys gets used instead. 🫶
  • suspend_timeout — same energy, but for all calls to sys:suspend. If no value is given, the values defined by the Timeout parameter of the upgrade or suspend instructions are used. If you pass default, the default value defined in sys is used. ✨
  • {update_paths,Bool} — tells the system whether all application code paths should be updated (Bool==true) or only the code paths for modified applications (Bool==false, which is the default). Heads up though: this option only has an effect for application directories that are not the default $ROOT/lib/App-Vsn, aka application directories that you specified in the argument AppDirs in a call to create_RELEASES/4 or set_unpacked/2. 👑

Example, bestie:

Say in the current version CurVsn of a release, the application directory of myapp is $ROOT/lib/myapp-1.0. You unpack a new version NewVsn outside the release handler and let it know like this:

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

Now if NewVsn is installed with the option {update_paths,true}, then code:lib_dir(myapp) returns /home/user/myapp-1.0. that's it, that's the whole thing 💅

NOTE: Installing a new release can be time consuming if there are lots of processes in the system. Why? Because every single process has to 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. That does the same check for old code. Then it purges all modules that can be soft-purged. The purged modules then no longer have any old code, and install_release doesn't need to do the checks. It doesn't reduce the overall time for the upgrade, but it lets checks and purge run in the background before the real upgrade is started. main character scheduling fr fr 🧚
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 info about emulator upgrade from pre OTP R15 versions, see Design Principles in System Documentation.

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

when
    Vsn :: string(),
    Reason ::
        {bad_status, Status :: term()} | term().

Makes the specified release version Vsn permanent. Yep, that's the whole vibe — it's now the forever one. ✨

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 has to have status old, or it's not happening.

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, bestie — try it and you get {permanent, Vsn} in your face. It removes only the files and directories that aren't in use by another release.

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

It tells the release handler that the release is removed from the system. Warning though: this function does not delete any files. It's giving "I'm just the messenger."

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. Directories for applications that aren't specified in AppDirs are assumed to be located in $ROOT/lib. periodt 💅

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

It performs some checks on the package — for example, checking that all mandatory files are present — and extracts its contents.

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}. Why? 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. no cap, it's a whole thing. 😭

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's recommended to use upgrade_app/2 instead, but this function (upgrade_script) is useful to inspect the contents of the script. iykyk 👑

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

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. the whole roster, bestie 🌈

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. filter by vibe, iconic behavior ✨

and that's a wrap on this whole page, bestie!! take care of ur releases and they'll take care of u 💖 this queen was brought to you by Ericsson AB, living in sasl 4.4, answering to the name release_handler(3). slay, go upgrade something responsibly 🫶🎀

📦 where this page comes from