File: release_handler.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (481 lines) | stat: -rw-r--r-- 18,112 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>release_handler</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>release_handler</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
release_handler
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
A process to unpack and install releases.

</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>The release handler process belongs to the SASL application and
handles unpacking, installation, and removal of release packages.

<P>A release package is a compressed tar file containing code for a
release, see <CODE>systools(3)</CODE>. The release package should be
placed in the <CODE>$ROOT/releases</CODE> directory of a previous
version of the release where <CODE>$ROOT</CODE> is the installation
root directory, <CODE>code:root_dir()</CODE>. Another <CODE>releases</CODE>
directory can be specified using the SASL configuration parameter
<CODE>releases_dir</CODE>, or the OS environment variable <CODE>RELDIR</CODE>.
The release handler must have write access to this directory in
order to install the new release. The persistent state of
the release handler is stored there in a file called
<CODE>RELEASES</CODE>.
<P>A release package always contains the release resource file
<CODE>Name.rel</CODE> and a boot script <CODE>Name.boot</CODE>. It may
contain a release upgrade file <CODE>relup</CODE> and a system
configuration file <CODE>sys.config</CODE>. The <CODE>.rel</CODE> file
contains information about the release: its name, version, and
which ERTS and application versions it uses. The <CODE>relup</CODE>
file contains scripts for how to upgrade to, or downgrade from,
this version of the release.
<P>The release package can be <STRONG>unpacked</STRONG>, which extracts
the files. An unpacked release can be <STRONG>installed</STRONG>.
The currently used version of the release is then upgraded or
downgraded to the specified version by evaluating the instructions
in <CODE>relup</CODE>. An installed release can be made
<STRONG>permanent</STRONG>. There can only be one permanent release in
the system, and this is the release that is used if the system is
restarted. An installed release, except the permanent one, can be
<STRONG>removed</STRONG>. When a release is removed, all files that
belong to that release only are deleted.
<P>Each version of the release has a status. The status can be
<CODE>unpacked</CODE>, <CODE>current</CODE>, <CODE>permanent</CODE>, or <CODE>old</CODE>.
There is always one latest release which either has status
<CODE>permanent</CODE> (normal case), or <CODE>current</CODE> (installed, but
not yet made permanent). The following table illustrates
the meaning of the status values:
<PRE>
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                  -
    
</PRE>

<P>The release handler process is a locally registered process on
each node. When a release is installed in a distributed system,
the release handler on each node must be called. The release
installation may be synchronized between nodes. From an operator
view, it may be unsatisfactory to specify each node. The aim is
to install one release package in the system, no matter how many
nodes there are. If this is the case, it is recommended that
software management functions are written which take care of
this problem. Such a function may have knowledge of the system
architecture, so it can contact each individual release handler
to install the package.
<P>For release handling to work properly, the runtime system needs
to have knowledge about which release it is currently running. It
must also be able to change (in run-time) which boot script and
system configuration file should be used if the system is
restarted. Therefore, Erlang must be started as an embedded
system. Read about this in <STRONG>Embedded System</STRONG>.
<P>A new release may restart the system. Which program to use is
specified by the SASL configuration parameter <CODE>start_prg</CODE>
which defaults to <CODE>$ROOT/bin/start</CODE>.
<P>The emulator restart on Windows NT expects that the system is
started using the <CODE>erlsrv</CODE> program (as a service).
Furthermore the release handler expects that the service is named 
<STRONG>NodeName</STRONG>_<STRONG>Release</STRONG>, where <STRONG>NodeName</STRONG> is
the first part of the Erlang nodename (up to, but not including
the &#34;@&#34;) and <STRONG>Release</STRONG> is the current release of
the application. The release handler furthermore expects that a
program like <CODE>start_erl.exe</CODE> is specified as &#34;machine&#34; to
<CODE>erlsrv</CODE>. During upgrading with restart, a new service will
be registered and started. The new service will be set to
automatic and the old service removed as soon as the new release
is made permanent.
<P>The release handler at a node which runs on a diskless machine,
or with a read-only file system, must be configured accordingly
using the following <CODE>sasl</CODE> configuration parameters:
<P>
<DL>

<DT>
masters
</DT>

<DD>
        This node uses a number of master nodes in order to store
         and fetch release information. All master nodes must be up
         and running whenever release information is written by this
         node.<BR>


</DD>

<DT>
client_directory
</DT>

<DD>
        The <CODE>client_directory</CODE> in the directory structure of
         the master nodes must be specified.<BR>


</DD>

<DT>
static_emulator
</DT>

<DD>
        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 because
         the executable files are statically written into memory.<BR>


</DD>

</DL>

<P>There are additional functions for using another file structure
than the structure defined in OTP. These functions can be used
to test a release upgrade locally.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="check_install_release/1"><STRONG><CODE>check_install_release(Vsn) -&#62; {ok, OtherVsn, Descr} |
        {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = OtherVsn = string()</CODE></STRONG><BR>
<STRONG><CODE>Descr = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Checks if the specified version <CODE>Vsn</CODE> of the release
         can be installed. The release must not have status
         <CODE>current</CODE>. Issues warnings if <CODE>relup</CODE> or
         <CODE>sys.config</CODE> are not present. If <CODE>relup</CODE> is present,
         its contents are checked and <CODE>{error,Reason}</CODE> is
         returned if an error is found. Also checks that all required
         applications are present and that all new code can be loaded,
         or <CODE>{error,Reason}</CODE> is returned.
<P>This function evaluates all instructions that occur before
         the <CODE>point_of_no_return</CODE> instruction in the release
         upgrade script.
<P>Returns the same as <CODE>install_release/1</CODE>. <CODE>Descr</CODE>
         defaults to &#34;&#34; if no <CODE>relup</CODE> file is found.
</DIV>

<P><A NAME="create_RELEASES/4"><STRONG><CODE>create_RELEASES(Root, RelDir, RelFile, AppDirs) -&#62; ok |
        {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Root = RelDir = RelFile = string()</CODE></STRONG><BR>
<STRONG><CODE>AppDirs = [{App, Vsn, Dir}]</CODE></STRONG><BR>
<STRONG><CODE>App = atom()</CODE></STRONG><BR>
<STRONG><CODE>Vsn = Dir = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates an initial RELEASES file to be used by the release
         handler. This file must exist in order to install new
         releases.
<P><CODE>Root</CODE> is the root of the installation as described
         above. <CODE>RelDir</CODE> is the the releases directory where the
         RELASES file should be created. <CODE>RelFile</CODE> is the name
         of the <CODE>.rel</CODE> file that describes the initial release.
        
<P><CODE>AppDirs</CODE> can be used to specify from where the modules
         for an application should be loaded. <CODE>App</CODE> is the name
         of the application, <CODE>Vsn</CODE> is the version, and <CODE>Dir</CODE>
         is the name of the directory where <CODE>App-Vsn</CODE> is located.
         The corresponding modules should be located under
         <CODE>Dir/App-Vsn/ebin</CODE>.
</DIV>

<P><A NAME="install_file/2"><STRONG><CODE>install_file(Vsn, FileName) -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = FileName = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Installs a release dependent file in the release structure.
         A release dependent file is a file that must be in
         the release structure when a new release is installed:
         <CODE>start.boot</CODE>, <CODE>relup</CODE> and <CODE>sys.config</CODE>.
<P>The function can be called, for example, when these files
         are generated at the target. It should be called after
         <CODE>set_unpacked/2</CODE> has been called.
</DIV>

<P><A NAME="install_release/1"><STRONG><CODE>install_release(Vsn) -&#62; {ok, OtherVsn, Descr}
        | {error, Reason}</CODE></STRONG></A><BR>
<A NAME="install_release/2"><STRONG><CODE>install_release(Vsn, [Opt]) -&#62; {ok, OtherVsn, Descr}
        | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = OtherVsn = string()</CODE></STRONG><BR>
<STRONG><CODE>Opt = {error_action, Action}
         | {code_change_timeout, Timeout} 
         | {suspend_timeout, Timeout}</CODE></STRONG><BR>
<STRONG><CODE>Action = restart | reboot</CODE></STRONG><BR>
<STRONG><CODE>Timeout = default | infinity | int()&#62;0</CODE></STRONG><BR>
<STRONG><CODE>Descr = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Installs the specfied version <CODE>Vsn</CODE> of the release.
         The release must not have status <CODE>current</CODE>. Looks first
         for a <CODE>relup</CODE> file for <CODE>Vsn</CODE> and a script
         <CODE>{UpFromVsn,Descr,Instructions}</CODE> in this file for
         upgrading from the current version. If not found,
         the function looks for a <CODE>relup</CODE> file for the current
         version and a script <CODE>{Vsn,Descr,Instructions}</CODE> in this
         file for downgrading to <CODE>Vsn</CODE>. Returns
         <CODE>{error,Reason}</CODE> if no script is found.
<P>If a script is found, the first thing that happens is that
         the applications specifications are updated according to
         the <CODE>.app</CODE> files and <CODE>sys.config</CODE> belonging to
         the release version <CODE>Vsn</CODE>.
<P>Note that <CODE>sys.config</CODE> is required and that no other
         system configuration files should be used as that may lead to
         inconsistent updating of configuration parameters.
<P>After the application specifications have been updated,
         the instructions in the script are evaluated and the function
         returns <CODE>{ok,OtherVsn,Descr}</CODE> if successful or
         <CODE>{error,Reason}</CODE> if a recoverable error occurs. In
         the latter case the original application specifications are
         restored. <CODE>OtherVsn</CODE> and <CODE>Descr</CODE> are the version and
         description as specified in the script. If a non-recoverable
         error occurs, the system is restarted.
<P>The option <CODE>error_action</CODE> defines if the node should be
         restarted (<CODE>init:restart()</CODE>) or rebooted
         <CODE>init:reboot()</CODE> in case of an error during
         the installation. Default is <CODE>restart</CODE>.
<P>The option <CODE>code_change_timeout</CODE> defines the timeout
         for all calls to <CODE>sys:change_code</CODE>. If no value is
         specified or <CODE>default</CODE> is given, the default value
         defined in <CODE>sys</CODE> is used.
<P>The option <CODE>suspend_timeout</CODE> defines the timeout for 
         all calls to <CODE>sys:suspend</CODE>. If no value is specified,
         the values defined by the <CODE>Timeout</CODE> parameter of
         the <CODE>upgrade</CODE> or <CODE>suspend</CODE> instructions are used.
         If <CODE>default</CODE> is specified, the default value defined in
         <CODE>sys</CODE> is used.
</DIV>

<P><A NAME="make_permanent/1"><STRONG><CODE>make_permanent(Vsn) -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes the specified version <CODE>Vsn</CODE> of the release
         permanent.
</DIV>

<P><A NAME="remove_release/1"><STRONG><CODE>remove_release(Vsn) -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>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.
</DIV>

<P><A NAME="reboot_old_release/1"><STRONG><CODE>reboot_old_release(Vsn) -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = {no_such_release, Vsn}</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Reboots the system by making the old release permanent, and
         calls <CODE>init:reboot()</CODE> directly. The release must have
         status <CODE>old</CODE>.
</DIV>

<P><A NAME="set_removed/1"><STRONG><CODE>set_removed(Vsn) -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Vsn = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = {no_such_release, Vsn} | {permanent, Vsn}</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>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.
</DIV>

<P><A NAME="set_unpacked/2"><STRONG><CODE>set_unpacked(RelFile, AppDirs) -&#62; {ok, Vsn}
        | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>RelFile = string()</CODE></STRONG><BR>
<STRONG><CODE>AppDirs = [{App, Vsn, Dir}]</CODE></STRONG><BR>
<STRONG><CODE>App = atom()</CODE></STRONG><BR>
<STRONG><CODE>Vsn = Dir = string()</CODE></STRONG><BR>
<STRONG><CODE>Vsn = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes it possible to handle unpacking of releases outside
         the release handler. Tells the release handler that
         the release is unpacked. <CODE>Vsn</CODE> is extracted from
         the release resource file <CODE>RelFile</CODE>.
<P><CODE>AppDirs</CODE> can be used to specify from where the modules
         for an application should be loaded. <CODE>App</CODE> is the name
         of the application, <CODE>Vsn</CODE> is the version, and <CODE>Dir</CODE>
         is the name of the directory where the directory
         <CODE>App-Vsn</CODE> is located. The corresponding modules should
         be located under <CODE>Dir/App-Vsn/ebin</CODE>.
</DIV>

<P><A NAME="unpack_release/1"><STRONG><CODE>unpack_release(Name) -&#62; {ok, Vsn} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = Vsn = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Unpacks a release package <CODE>Name.tar.gz</CODE> located in
         the <CODE>releases</CODE> directory.
<P>Performs some checks on the package - for example checks
        that all mandatory files are present - and extracts its
        contents.
</DIV>

<P><A NAME="which_releases/0"><STRONG><CODE>which_releases() -&#62; [{Name, Vsn, Apps, Status}]</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Name = Vsn = string()</CODE></STRONG><BR>
<STRONG><CODE>Apps = [&#34;App-Vsn&#34;]</CODE></STRONG><BR>
<STRONG><CODE>Status = unpacked | current | permanent | old</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns all releases known to the release handler.
</DIV>

<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>

<P><STRONG>OTP Design Principles</STRONG>,
config(4), <A HREF="relup.html">relup(4)</A>,
<A HREF="script.html">script(4)</A>, sys(3),
<A HREF="systools.html">systools(3)</A>
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Martin Bjrklund - support@erlang.ericsson.se<BR>
Gunilla Arendt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>sasl 2.0<BR>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>