path: root/lib/sasl/doc/src/release_handler.xml

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2011</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>release_handler</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module>release_handler</module>
  <modulesummary>Unpacking and Installation of Release Packages</modulesummary>
  <description>
    <p>The <em>release handler</em> is a process belonging to the SASL
      application which is responsible for <em>release handling</em>,
      that is, unpacking, installation, and removal of release packages.</p>
    <p>An introduction to release handling and a usage example can be
      found in
      <seealso marker="doc/design_principles:release_handling">Design Principles</seealso>.
      </p>
    <p>A <em>release package</em> is a compressed tar file containing
      code for a certain version of a release, created by calling
      <seealso marker="systools#make_tar/1">systools:make_tar/1,2</seealso>.
      The release package should be placed in the <c>$ROOT/releases</c>
      directory of the previous version of the release where
      <c>$ROOT</c> is the installation root directory,
      <c>code:root_dir()</c>.
      Another <c>releases</c> directory can be specified using the SASL
      configuration parameter <c>releases_dir</c>, or the OS environment
      variable <c>RELDIR</c>. 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 <c>RELEASES</c>.</p>
    <p>A release package should always contain the release resource file
      <c>Name.rel</c> and a boot script <c>Name.boot</c>. It may contain
      a release upgrade file <c>relup</c> and a system configuration
      file <c>sys.config</c>. The <c>.rel</c> file contains information
      about the release: its name, version, and which ERTS and
      application versions it uses. The <c>relup</c> file contains
      scripts for how to upgrade to, or downgrade from, this version of
      the release.</p>
    <p>The release package can be <em>unpacked</em>, which extracts
      the files. An unpacked release can be <em>installed</em>.
      The currently used version of the release is then upgraded or
      downgraded to the specified version by evaluating the instructions
      in <c>relup</c>. An installed release can be made
      <em>permanent</em>. 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 <em>removed</em>. When a release is removed, all files
      that belong to that release only are deleted.</p>
    <p>Each version of the release has a status. The status can be
      <c>unpacked</c>, <c>current</c>, <c>permanent</c>, or <c>old</c>.
      There is always one latest release which either has status
      <c>permanent</c> (normal case), or <c>current</c> (installed, but
      not yet made permanent). The following table illustrates
      the meaning of the status values:</p>
    <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>
    <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. This is taken care of automatically if Erlang is
      started as an embedded system. Read about this in <em>Embedded System</em>. In this case, the system configuration file
      <c>sys.config</c> is mandatory.</p>
    <p>The installation of a new release may restart the system. Which
      program to use is specified by the SASL configuration
      parameter <c>start_prg</c> which defaults
      to <c>$ROOT/bin/start</c>.</p>
    <p>The emulator restart on Windows NT expects that the system is
      started using the <c>erlsrv</c> program (as a service).
      Furthermore the release handler expects that the service is named 
      <em>NodeName</em>_<em>Release</em>, where <em>NodeName</em> is
      the first part of the Erlang nodename (up to, but not including
      the "@") and <em>Release</em> is the current version of
      the release. The release handler furthermore expects that a
      program like <c>start_erl.exe</c> is specified as "machine" to
      <c>erlsrv</c>. 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>
    <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 <c>sasl</c> configuration parameters (see
      <seealso marker="sasl_app">sasl(6)</seealso> for details):</p>
    <taglist>
      <tag><c>masters</c></tag>
      <item>
        <p>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.</p>
      </item>
      <tag><c>client_directory</c></tag>
      <item>
        <p>The <c>client_directory</c> in the directory structure of
          the master nodes must be specified.</p>
      </item>
      <tag><c>static_emulator</c></tag>
      <item>
        <p>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.</p>
      </item>
    </taglist>
    <p>It is also possible to use the release handler to unpack and
      install release packages when not running Erlang as an embedded
      system, but in this case the user must somehow make sure that
      correct boot scripts and configuration files are used if
      the system needs to be restarted.</p>
    <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.</p>
  </description>
  <funcs>
    <func>
      <name>check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
      <name>check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
      <fsummary>Check installation of a release in the system.</fsummary>
      <type>
        <v>Vsn = OtherVsn = string()</v>
	<v>Opts = [Opt]</v>
	<v>Opt = purge</v>
        <v>Descr = term()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Checks if the specified version <c>Vsn</c> of the release
          can be installed. The release must not have status
          <c>current</c>. Issues warnings if <c>relup</c> or
          <c>sys.config</c> are not present. If <c>relup</c> is present,
          its contents are checked and <c>{error,Reason}</c> is
          returned if an error is found. Also checks that all required
          applications are present and that all new code can be loaded,
          or <c>{error,Reason}</c> is returned.</p>
        <p>This function evaluates all instructions that occur before
          the <c>point_of_no_return</c> instruction in the release
          upgrade script.</p>
        <p>Returns the same as <c>install_release/1</c>. <c>Descr</c>
          defaults to "" if no <c>relup</c> file is found.</p>
	<p>If the option <c>purge</c> is given, all old code that can
          be soft purged will be purged after all other checks are
          successfully completed. This can be useful in order to
          reduce the time needed by <seealso
          marker="#install_release/1">install_release</seealso>.</p>
      </desc>
    </func>
    <func>
      <name>create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name>
      <fsummary>Create an initial RELEASES file.</fsummary>
      <type>
        <v>Root = RelDir = RelFile = string()</v>
        <v>AppDirs = [{App, Vsn, Dir}]</v>
        <v>&nbsp;App = atom()</v>
        <v>&nbsp;Vsn = Dir = string()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Creates an initial RELEASES file to be used by the release
          handler. This file must exist in order to install new
          releases.</p>
        <p><c>Root</c> is the root of the installation (<c>$ROOT</c>) as
          described above. <c>RelDir</c> is the the directory where
          the <c>RELEASES</c> file should be created (normally
          <c>$ROOT/releases</c>). <c>RelFile</c> is the name
          of the <c>.rel</c> file that describes the initial release,
          including the extension <c>.rel</c>.</p>
        <p><c>AppDirs</c> can be used to specify from where the modules
          for the specified applications should be loaded. <c>App</c> is
          the name of an application, <c>Vsn</c> is the version, and
          <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
          is located. The corresponding modules should be located under
          <c>Dir/App-Vsn/ebin</c>. The directories for applications not
          specified in <c>AppDirs</c> are assumed to be located in
          <c>$ROOT/lib</c>.</p>
      </desc>
    </func>
    <func>
      <name>install_file(Vsn, File) -> ok | {error, Reason}</name>
      <fsummary>Install a release file in the release structure.</fsummary>
      <type>
        <v>Vsn = File = string()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <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:
          <c>start.boot</c>, <c>relup</c> and <c>sys.config</c>.</p>
        <p>The function can be called, for example, when these files
          are generated at the target. It should be called after
          <c>set_unpacked/2</c> has been called.</p>
      </desc>
    </func>
    <func>
      <name>install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
      <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name>
      <fsummary>Install a release in the system.</fsummary>
      <type>
        <v>Vsn = OtherVsn = string()</v>
        <v>Opt = {error_action, Action} | {code_change_timeout, Timeout}</v>
        <v>&nbsp;&nbsp;&nbsp;| {suspend_timeout, Timeout} | {update_paths, Bool}</v>
        <v>&nbsp;Action = restart | reboot</v>
        <v>&nbsp;Timeout = default | infinity | int()>0</v>
        <v>&nbsp;Bool = boolean()</v>
        <v>Descr = term()</v>
        <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</v>
	<v>App = atom()</v>
      </type>
      <desc>
        <p>Installs the specified version <c>Vsn</c> of the release.
          Looks first for a <c>relup</c> file for <c>Vsn</c> and a
          script <c>{UpFromVsn,Descr1,Instructions1}</c> in this file
          for upgrading from the current version. If not found,
          the function looks for a <c>relup</c> file for the current
          version and a script <c>{Vsn,Descr2,Instructions2}</c> in this
          file for downgrading to <c>Vsn</c>.</p>
        <p>If a script is found, the first thing that happens is that
          the applications specifications are updated according to
          the <c>.app</c> files and <c>sys.config</c> belonging to
          the release version <c>Vsn</c>.</p>
        <p>After the application specifications have been updated,
          the instructions in the script are evaluated and the function
          returns <c>{ok,OtherVsn,Descr}</c> if successful.
          <c>OtherVsn</c> and <c>Descr</c> are the version
          (<c>UpFromVsn</c> or <c>Vsn</c>) and description
          (<c>Descr1</c> or <c>Descr2</c>) as specified in the script.</p>
	  <p>If <c>{continue_after_restart,OtherVsn,Descr}</c> is
	  returned, it means that the emulator will be restarted
	  before the upgrade instructions are executed. This will
	  happen if the emulator or any of the applications kernel,
	  stdlib or sasl are updated. The new version of the emulator
	  and these core applications will execute after the restart,
	  but for all other applications the old versions will be
	  started and the upgrade will be performed as normal by
	  executing the upgrade instructions.</p>
        <p>If a recoverable error occurs, the function returns
          <c>{error,Reason}</c> and the original application
          specifications are restored. If a non-recoverable error
          occurs, the system is restarted.</p>
        <p>The option <c>error_action</c> defines if the node should be
          restarted (<c>init:restart()</c>) or rebooted
          (<c>init:reboot()</c>) in case of an error during
          the installation. Default is <c>restart</c>.</p>
        <p>The option <c>code_change_timeout</c> defines the timeout
          for all calls to <c>sys:change_code</c>. If no value is
          specified or <c>default</c> is given, the default value
          defined in <c>sys</c> is used.</p>
        <p>The option <c>suspend_timeout</c> defines the timeout for 
          all calls to <c>sys:suspend</c>. If no value is specified,
          the values defined by the <c>Timeout</c> parameter of
          the <c>upgrade</c> or <c>suspend</c> instructions are used.
          If <c>default</c> is specified, the default value defined in
          <c>sys</c> is used.</p>
        <p>The option <c>{update_paths,Bool}</c> indicates if all
          application code paths should be updated (<c>Bool==true</c>),
          or if only code paths for modified applications should be
          updated (<c>Bool==false</c>, default). This option only has
          effect for other application directories than the default
          <c>$ROOT/lib/App-Vsn</c>, that is, application directories
          provided in the <c>AppDirs</c> argument in a call to
          <c>create_RELEASES/4</c> or <c>set_unpacked/2</c>.</p>
        <p>Example: In the current version <c>CurVsn</c> of a release,
          the application directory of <c>myapp</c> is
          <c>$ROOT/lib/myapp-1.0</c>. A new version <c>NewVsn</c> is
          unpacked outside the release handler, and the release handler
          is informed about this with a call to:</p>
        <code type="none">
release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
=> {ok,NewVsn}
        </code>
        <p>If <c>NewVsn</c> is installed with the option
          <c>{update_paths,true}</c>, afterwards
          <c>code:lib_dir(myapp)</c> will return
          <c>/home/user/myapp-1.0</c>.</p>
	<note>
	  <p>Installing a new release might be quite 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 might lead to
	  garbage collections and copying of data.</p>
	  <p>If you wish to speed up the execution of
	  <c>install_release</c>, then you may call <seealso
	  marker="#check_install_release/1">check_install_release</seealso>
	  first, using the option <c>purge</c>. This will do the same
	  check for old code, and then purge all modules that can be
	  soft purged. The purged modules will then no longer have any
	  old code, and <c>install_release</c> will not need to do the
	  checks.</p>
	  <p>Obviously, this will not reduce the overall time for the
	  upgrade, but it will allow checks and purge to be executed
	  in the background before the real upgrade is started.</p>
	</note>
	<note>
	  <p>When upgrading the emulator from a version older than OTP
	  R15, there will be an attempt to load new application beam
	  code into the old emulator. In some cases, the new beam
	  format can not be read by the old emulator, and so the code
	  loading will fail and terminate the complete upgrade. To
	  overcome this problem, the new application code should be
	  compiled with the old emulator. See <seealso
	  marker="doc/design_principles:appup_cookbook">Design
	  Principles</seealso> for more information about emulator
	  upgrade from pre OTP R15 versions.</p>
	</note>
      </desc>
    </func>
    <func>
      <name>make_permanent(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Make the specified release version permanent.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {bad_status, Status} | term()</v>
      </type>
      <desc>
        <p>Makes the specified version <c>Vsn</c> of the release
          permanent.</p>
      </desc>
    </func>
    <func>
      <name>remove_release(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Remove a release from the system.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {permanent, Vsn} | client_node | term()</v>
      </type>
      <desc>
        <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.</p>
      </desc>
    </func>
    <func>
      <name>reboot_old_release(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Reboot the system from an old release.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {bad_status, Status} | term()</v>
      </type>
      <desc>
        <p>Reboots the system by making the old release permanent, and
          calls <c>init:reboot()</c> directly. The release must have
          status <c>old</c>.</p>
      </desc>
    </func>
    <func>
      <name>set_removed(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Mark a release as removed.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {permanent, Vsn} | term()</v>
      </type>
      <desc>
        <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.</p>
      </desc>
    </func>
    <func>
      <name>set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</name>
      <fsummary>Mark a release as unpacked.</fsummary>
      <type>
        <v>RelFile = string()</v>
        <v>AppDirs = [{App, Vsn, Dir}]</v>
        <v>&nbsp;App = atom()</v>
        <v>&nbsp;Vsn = Dir = string()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Makes it possible to handle unpacking of releases outside
          the release handler. Tells the release handler that
          the release is unpacked. <c>Vsn</c> is extracted from
          the release resource file <c>RelFile</c>.</p>
        <p><c>AppDirs</c> can be used to specify from where the modules
          for the specified applications should be loaded. <c>App</c> is
          the name of an application, <c>Vsn</c> is the version, and
          <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
          is located. The corresponding modules should be located under
          <c>Dir/App-Vsn/ebin</c>. The directories for applications not
          specified in <c>AppDirs</c> are assumed to be located in
          <c>$ROOT/lib</c>.</p>
      </desc>
    </func>
    <func>
      <name>unpack_release(Name) -> {ok, Vsn} | {error, Reason}</name>
      <fsummary>Unpack a release package.</fsummary>
      <type>
        <v>Name = Vsn = string()</v>
        <v>Reason = client_node | term()</v>
      </type>
      <desc>
        <p>Unpacks a release package <c>Name.tar.gz</c> located in
          the <c>releases</c> directory.</p>
        <p>Performs some checks on the package - for example checks
          that all mandatory files are present - and extracts its
          contents.</p>
      </desc>
    </func>
    <func>
      <name>which_releases() -> [{Name, Vsn, Apps, Status}]</name>
      <fsummary>Return all known releases</fsummary>
      <type>
        <v>Name = Vsn = string()</v>
        <v>Apps = ["App-Vsn"]</v>
        <v>Status = unpacked | current | permanent | old</v>
      </type>
      <desc>
        <p>Returns all releases known to the release handler.</p>
      </desc>
    </func>
    <func>
      <name>which_releases(Status) -> [{Name, Vsn, Apps, Status}]</name>
      <fsummary>Return all known releases of a specific status</fsummary>
      <type>
        <v>Name = Vsn = string()</v>
        <v>Apps = ["App-Vsn"]</v>
        <v>Status = unpacked | current | permanent | old</v>
      </type>
      <desc>
        <p>Returns all releases known to the release handler of a specific status.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Application Upgrade/Downgrade</title>
    <p>The following functions can be used to test upgrade and downgrade
      of single applications (instead of upgrading/downgrading an entire
      release). A script corresponding to <c>relup</c> is created
      on-the-fly, based on the <c>.appup</c> file for the application,
      and evaluated exactly in the same way as <c>release_handler</c>
      does.</p>
    <warning>
      <p>These functions are primarily intended for simplified testing
        of <c>.appup</c> files. They are not run within the context of
        the <c>release_handler</c> process. They must therefore
        <em>not</em> be used together with calls to
        <c>install_release/1,2</c>, as this will cause
        <c>release_handler</c> to end up in an inconsistent state.</p>
      <p>No persistent information is updated, why these functions can
        be used on any Erlang node, embedded or not. Also, using these
        functions does not affect which code will be loaded in case of
        a reboot.</p>
      <p>If the upgrade or downgrade fails, the application may end up
        in an inconsistent state.</p>
    </warning>
  </section>
  <funcs>
    <func>
      <name>upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
      <fsummary>Upgrade to a new application version</fsummary>
      <type>
        <v>App = atom()</v>
        <v>Dir = string()</v>
        <v>Unpurged = [Module]</v>
        <v>&nbsp;Module = atom()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Upgrades an application <c>App</c> from the current
          version to a new version located in <c>Dir</c> according to
          the <c>.appup</c> script.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>Dir</c> is the new library directory of
          <c>App</c>, the corresponding modules as well as
          the <c>.app</c> and <c>.appup</c> files should be located
          under <c>Dir/ebin</c>.</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find an upgrade script from the current version of
          the application using
          <seealso marker="#upgrade_script/2">upgrade_script/2</seealso>.
          This script is evaluated using
          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>,
          exactly in the same way as
          <seealso marker="#install_release/1">install_release/1,2</seealso>
          does.</p>
        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
          successful, where <c>Unpurged</c> is a list of unpurged
          modules, or <c>restart_emulator</c> if this instruction is
          encountered in the script, or <c>{error, Reason}</c> if
          an error occurred when finding or evaluating the script.</p>
	<p>If the <c>restart_new_emulator</c> instruction is found in
	  the script, <c>upgrade_app/2</c> will return
	  <c>{error,restart_new_emulator}</c>. The reason for this is
	  that this instruction requires that a new version of the
	  emulator is started before the rest of the upgrade
	  instructions can be executed, and this can only be done by
          <c>install_release/1,2</c>.</p>
      </desc>
    </func>
    <func>
      <name>downgrade_app(App, Dir) -></name>
      <name>downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
      <fsummary>Downgrade to a previous application version</fsummary>
      <type>
        <v>App = atom()</v>
        <v>Dir = OldVsn = string()</v>
        <v>Unpurged = [Module]</v>
        <v>&nbsp;Module = atom()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Downgrades an application <c>App</c> from the current
          version to a previous version <c>OldVsn</c> located in
          <c>Dir</c> according to the <c>.appup</c> script.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>OldVsn</c> is the previous version of
          the application and can be omitted if <c>Dir</c> is of
          the format <c>"App-OldVsn"</c>. <c>Dir</c> is the library
          directory of this previous version of <c>App</c>,
          the corresponding modules as well as the old <c>.app</c> file
          should be located under <c>Dir/ebin</c>. The <c>.appup</c>
          file should be located in the <c>ebin</c> directory of
          the <em>current</em> library directory of the application
          (<c>code:lib_dir(App)</c>).</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find an downgrade script to the previous version of
          the application using
          <seealso marker="#downgrade_script/3">downgrade_script/3</seealso>.
          This script is evaluated using
          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>,
          exactly in the same way as
          <seealso marker="#install_release/1">install_release/1,2</seealso>
          does.</p>
        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
          successful, where <c>Unpurged</c> is a list of unpurged
          modules, or <c>restart_emulator</c> if this instruction is
          encountered in the script, or <c>{error, Reason}</c> if
          an error occurred when finding or evaluating the script.</p>
      </desc>
    </func>
    <func>
      <name>upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name>
      <fsummary>Find an application upgrade script</fsummary>
      <type>
        <v>App = atom()</v>
        <v>Dir = string()</v>
        <v>NewVsn = string()</v>
        <v>Script = Instructions -- see appup(4)</v>
      </type>
      <desc>
        <p>Tries to find an application upgrade script for <c>App</c>
          from the current version to a new version located in
          <c>Dir</c>.</p>
        <p>The upgrade script can then be evaluated using
          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>.
          It is recommended to use
          <seealso marker="#upgrade_app/2">upgrade_app/2</seealso>
          instead, but this function is useful in order to inspect
          the contents of the script.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>Dir</c> is the new library directory of
          <c>App</c>, the corresponding modules as well as
          the <c>.app</c> and <c>.appup</c> files should be located
          under <c>Dir/ebin</c>.</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find an upgrade script from the current version of
          the application. High-level instructions are translated to
          low-level instructions and the instructions are sorted in
          the same manner as when generating a <c>relup</c> script.</p>
        <p>Returns <c>{ok, NewVsn, Script}</c> if successful, where
          <c>NewVsn</c> is the new application version.</p>
        <p>Failure: If a script cannot be found, the function fails
          with an appropriate error reason.</p>
      </desc>
    </func>
    <func>
      <name>downgrade_script(App, OldVsn, Dir) -> {ok, Script}</name>
      <fsummary>Find an application downgrade script</fsummary>
      <type>
        <v>App = atom()</v>
        <v>OldVsn = Dir = string()</v>
        <v>Script = Instructions -- see appup(4)</v>
      </type>
      <desc>
        <p>Tries to find an application downgrade script for <c>App</c>
          from the current version to a previous version <c>OldVsn</c>
          located in <c>Dir</c>.</p>
        <p>The downgrade script can then be evaluated using
          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>.
          It is recommended to use
          <seealso marker="#downgrade_app/2">downgrade_app/2,3</seealso>
          instead, but this function is useful in order to inspect
          the contents of the script.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>Dir</c> is the previous library directory of
          <c>App</c>, the corresponding modules as well as
          the old <c>.app</c> file should be located under
          <c>Dir/ebin</c>. The <c>.appup</c> file should be located in
          the <c>ebin</c> directory of the <em>current</em> library
          directory of the application (<c>code:lib_dir(App)</c>).</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find an downgrade script from the current version of
          the application. High-level instructions are translated to
          low-level instructions and the instructions are sorted in
          the same manner as when generating a <c>relup</c> script.</p>
        <p>Returns <c>{ok, Script}</c> if successful.</p>
        <p>Failure: If a script cannot be found, the function fails
          with an appropriate error reason.</p>
      </desc>
    </func>
    <func>
      <name>eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
      <fsummary>Evaluate an application upgrade or downgrade script</fsummary>
      <type>
        <v>App = atom()</v>
        <v>ToVsn = ToDir = string()</v>
        <v>Script -- see upgrade_script/2, downgrade_script/3</v>
        <v>Unpurged = [Module]</v>
        <v>&nbsp;Module = atom()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Evaluates an application upgrade or downgrade script
          <c>Script</c>, the result from calling
          <seealso marker="#upgrade_app/2">upgrade_script/2</seealso> or
          <seealso marker="#downgrade_app/3">downgrade_script/3</seealso>,
          exactly in the same way as
          <seealso marker="#install_release/1">install_release/1,2</seealso>
          does.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>ToVsn</c> is the version to be upgraded/downgraded
          to, and <c>ToDir</c> is the library directory of this version.
          The corresponding modules as well as the <c>.app</c> and
          <c>.appup</c> files should be located under <c>Dir/ebin</c>.</p>
        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
          successful, where <c>Unpurged</c> is a list of unpurged
          modules, or <c>restart_emulator</c> if this instruction is
          encountered in the script, or <c>{error, Reason}</c> if
          an error occurred when evaluating the script.</p>
	<p>If the <c>restart_new_emulator</c> instruction is found in
	  the script, <c>eval_appup_script/4</c> will return
	  <c>{error,restart_new_emulator}</c>. The reason for this is
	  that this instruction requires that a new version of the
	  emulator is started before the rest of the upgrade
	  instructions can be executed, and this can only be done by
          <c>install_release/1,2</c>.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Typical Error Reasons</title>
    <list type="bulleted">
      <item>
        <p><c>{bad_masters, Masters}</c> - The master nodes
          <c>Masters</c> are not alive.</p>
      </item>
      <item>
        <p><c>{bad_rel_file, File}</c> - Specified <c>.rel</c> file
          <c>File</c> can not be read, or does not contain a single
          term.</p>
      </item>
      <item>
        <p><c>{bad_rel_data, Data}</c> - Specified <c>.rel</c> file
          does not contain a recognized release specification, but
          another term <c>Data</c>.</p>
      </item>
      <item>
        <p><c>{bad_relup_file, File}</c> - Specified <c>relup</c> file
          <c>Relup</c> contains bad data.</p>
      </item>
      <item>
        <p><c>{cannot_extract_file, Name, Reason}</c> - Problems when
          extracting from a tar file, <c>erl_tar:extract/2</c> returned
          <c>{error, {Name, Reason}}</c>.</p>
      </item>
      <item>
        <p><c>{existing_release, Vsn}</c> - Specified release version
          <c>Vsn</c> is already in use.</p>
      </item>
      <item>
        <p><c>{Master, Reason, When}</c> - Some operation, indicated by
          the term <c>When</c>, failed on the master node <c>Master</c>
          with the specified error reason <c>Reason</c>.</p>
      </item>
      <item>
        <p><c>{no_matching_relup, Vsn, CurrentVsn}</c> - Cannot find a
          script for up/downgrading between <c>CurrentVsn</c> and
          <c>Vsn</c>.</p>
      </item>
      <item>
        <p><c>{no_such_directory, Path}</c> - The directory <c>Path</c>
          does not exist.</p>
      </item>
      <item>
        <p><c>{no_such_file, Path}</c> - The path <c>Path</c> (file or
          directory) does not exist.</p>
      </item>
      <item>
        <p><c>{no_such_file, {Master, Path}}</c> - The path <c>Path</c>
          (file or directory) does not exist at the master node
          <c>Master</c>.</p>
      </item>
      <item>
        <p><c>{no_such_release, Vsn}</c> - The specified version
          <c>Vsn</c> of the release does not exist.</p>
      </item>
      <item>
        <p><c>{not_a_directory, Path}</c> - <c>Path</c> exists, but is
          not a directory.</p>
      </item>
      <item>
        <p><c>{Posix, File}</c> - Some file operation failed for
          <c>File</c>. <c>Posix</c> is an atom named from the Posix
          error codes, such as <c>enoent</c>, <c>eacces</c> or
          <c>eisdir</c>. See <c>file(3)</c>.</p>
      </item>
      <item>
        <p><c>Posix</c> - Some file operation failed, as above.</p>
      </item>
    </list>
  </section>

  <section>
    <title>SEE ALSO</title>
    <p><seealso marker="doc/design_principles:release_handling">OTP Design Principles</seealso>,
      <seealso marker="kernel:config">config(4)</seealso>,
      <seealso marker="relup">relup(4)</seealso>,
      <seealso marker="rel">rel(4)</seealso>,
      <seealso marker="script">script(4)</seealso>,
      <seealso marker="stdlib:sys">sys(3)</seealso>,
      <seealso marker="systools">systools(3)</seealso></p>
  </section>
</erlref>