<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../otp_doc.css" type="text/css">
<title>Erlang -- Release Handling</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-5.9.3.1.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>OTP Design Principles</strong><br><strong>User's Guide</strong><br><small>Version 5.9.3.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../js/flipmenu">
<li id="no" title="Overview" expanded="false">Overview<ul>
<li><a href="des_princ.html">
Top of chapter
</a></li>
<li title="Supervision Trees"><a href="des_princ.html#id65609">Supervision Trees</a></li>
<li title="Behaviours"><a href="des_princ.html#id59741">Behaviours</a></li>
<li title="Applications"><a href="des_princ.html#id66345">Applications</a></li>
<li title="Releases"><a href="des_princ.html#id61095">Releases</a></li>
<li title="Release Handling"><a href="des_princ.html#id60860">Release Handling</a></li>
</ul>
</li>
<li id="no" title="Gen_Server Behaviour" expanded="false">Gen_Server Behaviour<ul>
<li><a href="gen_server_concepts.html">
Top of chapter
</a></li>
<li title="Client-Server Principles"><a href="gen_server_concepts.html#id64192">Client-Server Principles</a></li>
<li title="Example"><a href="gen_server_concepts.html#id61515">Example</a></li>
<li title="Starting a Gen_Server"><a href="gen_server_concepts.html#id67798">Starting a Gen_Server</a></li>
<li title="Synchronous Requests - Call"><a href="gen_server_concepts.html#id66815">Synchronous Requests - Call</a></li>
<li title="Asynchronous Requests - Cast"><a href="gen_server_concepts.html#id62843">Asynchronous Requests - Cast</a></li>
<li title="Stopping"><a href="gen_server_concepts.html#id67345">Stopping</a></li>
<li title="Handling Other Messages"><a href="gen_server_concepts.html#id67435">Handling Other Messages</a></li>
</ul>
</li>
<li id="no" title="Gen_Fsm Behaviour" expanded="false">Gen_Fsm Behaviour<ul>
<li><a href="fsm.html">
Top of chapter
</a></li>
<li title="Finite State Machines"><a href="fsm.html#id68991">Finite State Machines</a></li>
<li title="Example"><a href="fsm.html#id69046">Example</a></li>
<li title="Starting a Gen_Fsm"><a href="fsm.html#id69093">Starting a Gen_Fsm</a></li>
<li title="Notifying About Events"><a href="fsm.html#id69273">Notifying About Events</a></li>
<li title="Timeouts"><a href="fsm.html#id69352">Timeouts</a></li>
<li title="All State Events"><a href="fsm.html#id69391">All State Events</a></li>
<li title="Stopping"><a href="fsm.html#id69423">Stopping</a></li>
<li title="Handling Other Messages"><a href="fsm.html#id69514">Handling Other Messages</a></li>
</ul>
</li>
<li id="no" title="Gen_Event Behaviour" expanded="false">Gen_Event Behaviour<ul>
<li><a href="events.html">
Top of chapter
</a></li>
<li title="Event Handling Principles"><a href="events.html#id69613">Event Handling Principles</a></li>
<li title="Example"><a href="events.html#id69665">Example</a></li>
<li title="Starting an Event Manager"><a href="events.html#id69706">Starting an Event Manager</a></li>
<li title="Adding an Event Handler"><a href="events.html#id70832">Adding an Event Handler</a></li>
<li title="Notifying About Events"><a href="events.html#id70916">Notifying About Events</a></li>
<li title="Deleting an Event Handler"><a href="events.html#id70987">Deleting an Event Handler</a></li>
<li title="Stopping"><a href="events.html#id71062">Stopping</a></li>
<li title="Handling Other Messages"><a href="events.html#id71116">Handling Other Messages</a></li>
</ul>
</li>
<li id="no" title="Supervisor Behaviour" expanded="false">Supervisor Behaviour<ul>
<li><a href="sup_princ.html">
Top of chapter
</a></li>
<li title="Supervision Principles"><a href="sup_princ.html#id71210">Supervision Principles</a></li>
<li title="Example"><a href="sup_princ.html#id71235">Example</a></li>
<li title="Restart Strategy"><a href="sup_princ.html#id71306">Restart Strategy</a></li>
<li title="Maximum Restart Frequency"><a href="sup_princ.html#id71384">Maximum Restart Frequency</a></li>
<li title="Child Specification"><a href="sup_princ.html#id71906">Child Specification</a></li>
<li title="Starting a Supervisor"><a href="sup_princ.html#id72235">Starting a Supervisor</a></li>
<li title="Adding a Child Process"><a href="sup_princ.html#id72349">Adding a Child Process</a></li>
<li title="Stopping a Child Process"><a href="sup_princ.html#id72393">Stopping a Child Process</a></li>
<li title="Simple-One-For-One Supervisors"><a href="sup_princ.html#id72443">Simple-One-For-One Supervisors</a></li>
<li title="Stopping"><a href="sup_princ.html#id72567">Stopping</a></li>
</ul>
</li>
<li id="no" title="Sys and Proc_Lib" expanded="false">Sys and Proc_Lib<ul>
<li><a href="spec_proc.html">
Top of chapter
</a></li>
<li title="Simple Debugging"><a href="spec_proc.html#id72665">Simple Debugging</a></li>
<li title="Special Processes"><a href="spec_proc.html#id72749">Special Processes</a></li>
<li title="User-Defined Behaviours"><a href="spec_proc.html#id73359">User-Defined Behaviours</a></li>
</ul>
</li>
<li id="no" title="Applications" expanded="false">Applications<ul>
<li><a href="applications.html">
Top of chapter
</a></li>
<li title="Application Concept"><a href="applications.html#id73539">Application Concept</a></li>
<li title="Application Callback Module"><a href="applications.html#id73606">Application Callback Module</a></li>
<li title="Application Resource File"><a href="applications.html#id73720">Application Resource File</a></li>
<li title="Directory Structure"><a href="applications.html#id73969">Directory Structure</a></li>
<li title="Application Controller"><a href="applications.html#id74095">Application Controller</a></li>
<li title="Loading and Unloading Applications"><a href="applications.html#id74128">Loading and Unloading Applications</a></li>
<li title="Starting and Stopping Applications"><a href="applications.html#id74190">Starting and Stopping Applications</a></li>
<li title="Configuring an Application"><a href="applications.html#id74278">Configuring an Application</a></li>
<li title="Application Start Types"><a href="applications.html#id74477">Application Start Types</a></li>
</ul>
</li>
<li id="no" title="Included Applications" expanded="false">Included Applications<ul>
<li><a href="included_applications.html">
Top of chapter
</a></li>
<li title="Definition"><a href="included_applications.html#id74617">Definition</a></li>
<li title="Specifying Included Applications"><a href="included_applications.html#id74682">Specifying Included Applications</a></li>
<li title="Synchronizing Processes During Startup"><a href="included_applications.html#id74708">Synchronizing Processes During Startup</a></li>
</ul>
</li>
<li id="no" title="Distributed Applications" expanded="false">Distributed Applications<ul>
<li><a href="distributed_applications.html">
Top of chapter
</a></li>
<li title="Definition"><a href="distributed_applications.html#id74921">Definition</a></li>
<li title="Specifying Distributed Applications"><a href="distributed_applications.html#id74957">Specifying Distributed Applications</a></li>
<li title="Starting and Stopping Distributed Applications"><a href="distributed_applications.html#id75164">Starting and Stopping Distributed Applications</a></li>
<li title="Failover"><a href="distributed_applications.html#id75266">Failover</a></li>
<li title="Takeover"><a href="distributed_applications.html#id75408">Takeover</a></li>
</ul>
</li>
<li id="no" title="Releases" expanded="false">Releases<ul>
<li><a href="release_structure.html">
Top of chapter
</a></li>
<li title="Release Concept"><a href="release_structure.html#id75603">Release Concept</a></li>
<li title="Release Resource File"><a href="release_structure.html#id75656">Release Resource File</a></li>
<li title="Generating Boot Scripts"><a href="release_structure.html#id75803">Generating Boot Scripts</a></li>
<li title="Creating a Release Package"><a href="release_structure.html#id75897">Creating a Release Package</a></li>
<li title="Directory Structure"><a href="release_structure.html#id76046">Directory Structure</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Release Handling" expanded="true">Release Handling<ul>
<li><a href="release_handling.html">
Top of chapter
</a></li>
<li title="Release Handling Principles"><a href="release_handling.html#id76299">Release Handling Principles</a></li>
<li title="Requirements"><a href="release_handling.html#id76543">Requirements</a></li>
<li title="Distributed Systems"><a href="release_handling.html#id76636">Distributed Systems</a></li>
<li title="Release Handling Instructions"><a href="release_handling.html#id76663">Release Handling Instructions</a></li>
<li title="Application Upgrade File"><a href="release_handling.html#id77177">Application Upgrade File</a></li>
<li title="Release Upgrade File"><a href="release_handling.html#id77359">Release Upgrade File</a></li>
<li title="Installing a Release"><a href="release_handling.html#id77515">Installing a Release</a></li>
<li title="Updating Application Specifications"><a href="release_handling.html#id77986">Updating Application Specifications</a></li>
</ul>
</li>
<li id="no" title="Appup Cookbook" expanded="false">Appup Cookbook<ul>
<li><a href="appup_cookbook.html">
Top of chapter
</a></li>
<li title="Changing a Functional Module"><a href="appup_cookbook.html#id78170">Changing a Functional Module</a></li>
<li title="Changing a Residence Module"><a href="appup_cookbook.html#id78193">Changing a Residence Module</a></li>
<li title="Changing a Callback Module"><a href="appup_cookbook.html#id78232">Changing a Callback Module</a></li>
<li title="Changing Internal State"><a href="appup_cookbook.html#id78283">Changing Internal State</a></li>
<li title="Module Dependencies"><a href="appup_cookbook.html#id78417">Module Dependencies</a></li>
<li title="Changing Code For a Special Process"><a href="appup_cookbook.html#id78588">Changing Code For a Special Process</a></li>
<li title="Changing a Supervisor"><a href="appup_cookbook.html#id78755">Changing a Supervisor</a></li>
<li title="Adding or Deleting a Module"><a href="appup_cookbook.html#id79000">Adding or Deleting a Module</a></li>
<li title="Starting or Terminating a Process"><a href="appup_cookbook.html#id79026">Starting or Terminating a Process</a></li>
<li title="Adding or Removing an Application"><a href="appup_cookbook.html#id79044">Adding or Removing an Application</a></li>
<li title="Restarting an Application"><a href="appup_cookbook.html#id79075">Restarting an Application</a></li>
<li title="Changing an Application Specification"><a href="appup_cookbook.html#id79117">Changing an Application Specification</a></li>
<li title="Changing Application Configuration"><a href="appup_cookbook.html#id79141">Changing Application Configuration</a></li>
<li title="Changing Included Applications"><a href="appup_cookbook.html#id79174">Changing Included Applications</a></li>
<li title="Changing Non-Erlang Code"><a href="appup_cookbook.html#id79414">Changing Non-Erlang Code</a></li>
<li title="Emulator Restart and Upgrade"><a href="appup_cookbook.html#id79499">Emulator Restart and Upgrade</a></li>
<li title="Emulator Upgrade from pre OTP R15"><a href="appup_cookbook.html#id79575">Emulator Upgrade from pre OTP R15</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>11 Release Handling</h1>
<h3><a name="id76299">11.1
Release Handling Principles</a></h3>
<p>An important feature of the Erlang programming language is
the ability to change module code in run-time, <strong>code replacement</strong>, as described in <strong>Erlang Reference Manual</strong>.</p>
<p>Based on this feature, the OTP application SASL provides a
framework for upgrading and downgrading between different
versions of an entire release in run-time. This is what we call
<strong>release handling</strong>.</p>
<p>The framework consists of off-line support (<span class="code">systools</span>) for
generating scripts and building release packages, and on-line
support (<span class="code">release_handler</span>) for unpacking and installing
release packages.</p>
<p>Note that the minimal system based on Erlang/OTP, enabling
release handling, thus consists of Kernel, STDLIB and SASL.</p>
<ul>
<li>
<p>A release is created as described in the previous chapter
<span class="bold_code"><a href="release_structure.html">Releases</a></span>.
The release is transferred to and installed at target
environment. Refer to <strong>System Principles</strong> for
information of how to install the first target system.</p>
</li>
<li>
<p>Modifications, for example error corrections, are made to
the code in the development environment.</p>
</li>
<li>
<p>At some point it is time to make a new version of release.
The relevant <span class="code">.app</span> files are updated and a new
<span class="code">.rel</span> file is written.</p>
</li>
<li>
<p>For each modified application, an
<span class="bold_code"><a href="#appup">application upgrade file</a></span>,
<span class="code">.appup</span>, is created. In this file, it is described how
to upgrade and/or downgrade between the old and new version of
the application.</p>
</li>
<li>
<p>Based on the <span class="code">.appup</span> files, a
<span class="bold_code"><a href="#relup">release upgrade file</a></span> called
<span class="code">relup</span>, is created. This file describes how to upgrade
and/or downgrade between the old and new version of
the entire release.</p>
</li>
<li>
<p>A new release package is made and transferred to
the target system.</p>
</li>
<li>
<p>The new release package is unpacked using the release
handler.</p>
</li>
<li>
<p>The new version of the release is installed, also using
the release handler. This is done by evaluating
the instructions in <span class="code">relup</span>. Modules may be added,
deleted or re-loaded, applications may be started, stopped or
re-started etc. In some cases, it is even necessary to restart
the entire emulator.</p>
<p>If the installation fails, the system may be rebooted.
The old release version is then automatically used.</p>
</li>
<li>
<p>If the installation succeeds, the new version is made
the default version, which should now be used in case of a
system reboot.</p>
</li>
</ul>
<p>The next chapter, <span class="bold_code"><a href="appup_cookbook.html">Appup Cookbook</a></span>, contains examples of <span class="code">.appup</span> files
for typical cases of upgrades/downgrades that are normally easy
to handle in run-time. However, there are a many aspects that can
make release handling complicated. To name a few examples:</p>
<ul>
<li>
<p>Complicated or circular dependencies can make it difficult
or even impossible to decide in which order things must be
done without risking run-time errors during an upgrade or
downgrade. Dependencies may be:</p>
<ul>
<li>between nodes,</li>
<li>between processes, and</li>
<li>between modules.</li>
</ul>
</li>
<li>
<p>During release handling, non-affected processes continue
normal execution. This may lead to timeouts or other problems.
For example, new processes created in the time window between
suspending processes using a certain module and loading a new
version of this module, may execute old code.</p>
</li>
</ul>
<p>It is therefore recommended that code is changed in as small
steps as possible, and always kept backwards compatible.</p>
<h3><a name="id76543">11.2
Requirements</a></h3>
<a name="req"></a>
<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
rebooted, for example by <span class="code">heart</span> after a failure.
Therefore, Erlang must be started as an embedded system, see
<strong>Embedded System</strong> for information on how to do this.</p>
<p>For system reboots to work properly, it is also required that
the system is started with heart beat monitoring, see
<span class="code">erl(1)</span> and <span class="code">heart(3)</span>.</p>
<p>Other requirements:</p>
<ul>
<li>
<p>The boot script included in a release package must be
generated from the same <span class="code">.rel</span> file as the release
package itself.</p>
<p>Information about applications are fetched from the script
when an upgrade or downgrade is performed.</p>
</li>
<li>
<p>The system must be configured using one and only one system
configuration file, called <span class="code">sys.config</span>.</p>
<p>If found, this file is automatically included when a release
package is created.</p>
</li>
<li>
<p>All versions of a release, except the first one, must
contain a <span class="code">relup</span> file.</p>
<p>If found, this file is automatically included when a release
package is created.</p>
</li>
</ul>
<h3><a name="id76636">11.3
Distributed Systems</a></h3>
<p>If the system consists of several Erlang nodes, each node may use
its own version of the release. The release handler is a locally
registered process and must be called at each node where an
upgrade or downgrade is required. There is a release handling
instruction that can be used to synchronize the release handler
processes at a number of nodes: <span class="code">sync_nodes</span>. See
<span class="code">appup(4)</span>.</p>
<h3><a name="id76663">11.4
Release Handling Instructions</a></h3>
<a name="instr"></a>
<p>OTP supports a set of <strong>release handling instructions</strong>
that are used when creating <span class="code">.appup</span> files. The release
handler understands a subset of these, the <strong>low-level</strong>
instructions. To make it easier for the user, there are also a
number of <strong>high-level</strong> instructions, which are translated
to low-level instructions by <span class="code">systools:make_relup</span>.</p>
<p>Here, some of the most frequently used instructions are
described. The complete list of instructions can be found in
<span class="code">appup(4)</span>.</p>
<p>First, some definitions:</p>
<dl>
<dt><strong><strong>Residence module</strong></strong></dt>
<dd>
<p>The module where a process has its tail-recursive loop
function(s). If the tail-recursive loop functions are
implemented in several modules, all those modules are residence
modules for the process.</p>
</dd>
<dt><strong><strong>Functional module</strong></strong></dt>
<dd>
<p>A module which is not a residence module for any process.</p>
</dd>
</dl>
<p>Note that for a process implemented using an OTP behaviour,
the behaviour module is the residence module for that process.
The callback module is a functional module.</p>
<h4>load_module</h4>
<p>If a simple extension has been made to a functional module, it
is sufficient to simply load the new version of the module into
the system, and remove the old version. This is called
<strong>simple code replacement</strong> and for this the following
instruction is used:</p>
<div class="example"><pre>
{load_module, Module}</pre></div>
<h4>update</h4>
<p>If a more complex change has been made, for example a change
to the format of the internal state of a gen_server, simple code
replacement is not sufficient. Instead it is necessary to
suspend the processes using the module (to avoid that they try
to handle any requests before the code replacement is
completed), ask them to transform the internal state format and
switch to the new version of the module, remove the old version
and last, resume the processes. This is called <strong>synchronized code replacement</strong> and for this the following instructions
are used:</p>
<div class="example"><pre>
{update, Module, {advanced, Extra}}
{update, Module, supervisor}</pre></div>
<p><span class="code">update</span> with argument <span class="code">{advanced,Extra}</span> is used
when changing the internal state of a behaviour as described
above. It will cause behaviour processes to call the callback
function <span class="code">code_change</span>, passing the term <span class="code">Extra</span> and
some other information as arguments. See the man pages for
the respective behaviours and
<span class="bold_code"><a href="appup_cookbook.html#int_state">Appup Cookbook</a></span>.</p>
<p><span class="code">update</span> with argument <span class="code">supervisor</span> is used when
changing the start specification of a supervisor. See
<span class="bold_code"><a href="appup_cookbook.html#sup">Appup Cookbook</a></span>.</p>
<p>When a module is to be updated, the release handler finds
which processes that are <strong>using</strong> the module by
traversing the supervision tree of each running application
and checking all the child specifications:</p>
<div class="example"><pre>
{Id, StartFunc, Restart, Shutdown, Type, Modules}</pre></div>
<p>A process is using a module if the name is listed in
<span class="code">Modules</span> in the child specification for the process.</p>
<p>If <span class="code">Modules=dynamic</span>, which is the case for event
managers, the event manager process informs the release handler
about the list of currently installed event handlers (gen_fsm)
and it is checked if the module name is in this list instead.</p>
<p>The release handler suspends, asks for code change, and
resumes processes by calling the functions
<span class="code">sys:suspend/1,2</span>, <span class="code">sys:change_code/4,5</span> and
<span class="code">sys:resume/1,2</span> respectively.</p>
<h4>add_module and delete_module</h4>
<p>If a new module is introduced, the following instruction is
used:</p>
<div class="example"><pre>
{add_module, Module}</pre></div>
<p>The instruction loads the module and is absolutely necessary
when running Erlang in embedded mode. It is not strictly
required when running Erlang in interactive (default) mode,
since the code server then automatically searches for and
loads unloaded modules.</p>
<p>The opposite of <span class="code">add_module</span> is <span class="code">delete_module</span> which
unloads a module:</p>
<div class="example"><pre>
{delete_module, Module}</pre></div>
<p>Note that any process, in any application, with <span class="code">Module</span>
as residence module, is killed when the instruction is
evaluated. The user should therefore ensure that all such
processes are terminated before deleting the module, to avoid
a possible situation with failing supervisor restarts.</p>
<h4>Application Instructions</h4>
<p>Instruction for adding an application:</p>
<div class="example"><pre>
{add_application, Application}</pre></div>
<p>Adding an application means that the modules defined by
the <span class="code">modules</span> key in the <span class="code">.app</span> file are loaded using
a number of <span class="code">add_module</span> instructions, then the application
is started.</p>
<p>Instruction for removing an application:</p>
<div class="example"><pre>
{remove_application, Application}</pre></div>
<p>Removing an application means that the application is stopped,
the modules are unloaded using a number of <span class="code">delete_module</span>
instructions and then the application specification is unloaded
from the application controller.</p>
<p>Instruction for restarting an application:</p>
<div class="example"><pre>
{restart_application, Application}</pre></div>
<p>Restarting an application means that the application is stopped
and then started again similar to using the instructions
<span class="code">remove_application</span> and <span class="code">add_application</span> in
sequence.</p>
<h4>apply (low-level)</h4>
<p>To call an arbitrary function from the release handler,
the following instruction is used:</p>
<div class="example"><pre>
{apply, {M, F, A}}</pre></div>
<p>The release handler will evalute <span class="code">apply(M, F, A)</span>.</p>
<h4>restart_new_emulator (low-level)</h4>
<a name="restart_new_emulator_instr"></a>
<p>This instruction is used when changing to a new emulator
version, or when any of the core applications kernel, stdlib
or sasl is upgraded. If a system reboot is needed for some
other reason, the <span class="code">restart_emulator</span> instruction should
be used instead.</p>
<p>Requires that the system is started with heart beat
monitoring, see <span class="code">erl(1)</span> and <span class="code">heart(3)</span>.</p>
<p>The <span class="code">restart_new_emulator</span> instruction shall always be
the very first instruction in a relup. If the relup is
generated by <span class="code">systools:make_relup/3,4</span> this is
automatically ensured.</p>
<p>When the release handler encounters the instruction, it first
generates a temporary boot file, which starts the new versions
of the emulator and the core applications. Then it shuts down
the current emulator by calling <span class="code">init:reboot()</span>, see
<span class="code">init(3)</span>. All processes are terminated gracefully and
the system is rebooted by the heart program, using the
temporary boot file. After the reboot, the rest of the relup
instructions are executed. This is done as a part of the
temporary boot script.</p>
<p>An info report is written when the upgrade is completed. To
programatically find out if the upgrade is complete,
call <span class="code">release_handler:which_releases(current)</span> and check
if it returns the expected (i.e. the new) release.</p>
<p>The new release version must be made permanent when the new
emulator is up and running. Otherwise, the old version will be
used in case of a new system reboot.</p>
<p>On UNIX, the release handler tells the heart program which
command to use to reboot the system. Note that the environment
variable <span class="code">HEART_COMMAND</span>, normally used by the heart
program, in this case is ignored. The command instead defaults
to <span class="code">$ROOT/bin/start</span>. Another command can be set
by using the SASL configuration parameter <span class="code">start_prg</span>, see
<span class="code">sasl(6)</span>.</p>
<h4>restart_emulator (low-level)</h4>
<a name="restart_emulator_instr"></a>
<p>This instruction is not related to upgrades of erts or any of
the core applications. It can be used by any application to
force a restart of the emulator after all upgrade instructions
are executed.</p>
<p>There can only be one <span class="code">restart_emulator</span> instruction in
a relup script, and it shall always be placed at the end. If
the relup is generated by <span class="code">systools:make_relup/3,4</span> this
is automatically ensured.</p>
<p>When the release handler encounters the instruction, it shuts
down the emulator by calling <span class="code">init:reboot()</span>, see
<span class="code">init(3)</span>. All processes are terminated gracefully and
the system can then be rebooted by the heart program using the
new release version. No more upgrade instruction will be
executed after the restart.</p>
<h3><a name="id77177">11.5
Application Upgrade File</a></h3>
<a name="appup"></a>
<p>To define how to upgrade/downgrade between the current version
and previous versions of an application, we create an
<strong>application upgrade file</strong>, or in short <span class="code">.appup</span> file.
The file should be called <span class="code">Application.appup</span>, where
<span class="code">Application</span> is the name of the application:</p>
<div class="example"><pre>
{Vsn,
[{UpFromVsn1, InstructionsU1},
...,
{UpFromVsnK, InstructionsUK}],
[{DownToVsn1, InstructionsD1},
...,
{DownToVsnK, InstructionsDK}]}.</pre></div>
<p><span class="code">Vsn</span>, a string, is the current version of the application,
as defined in the <span class="code">.app</span> file. Each <span class="code">UpFromVsn</span>
is a previous version of the application to upgrade from, and each
<span class="code">DownToVsn</span> is a previous version of the application to
downgrade to. Each <span class="code">Instructions</span> is a list of release
handling instructions.</p>
<p>The syntax and contents of the <span class="code">appup</span> file are described
in detail in <span class="code">appup(4)</span>.</p>
<p>In the chapter <span class="bold_code"><a href="appup_cookbook.html">Appup Cookbook</a></span>, examples of <span class="code">.appup</span> files for typical
upgrade/downgrade cases are given.</p>
<p>Example: Consider the release <span class="code">ch_rel-1</span> from
the <span class="bold_code"><a href="release_structure.html#ch_rel">Releases</a></span>
chapter. Assume we want to add a function <span class="code">available/0</span> to
the server <span class="code">ch3</span> which returns the number of available
channels:</p>
<p>(Hint: When trying out the example, make the changes in a copy of
the original directory, so that the first versions are still
available.)</p>
<div class="example"><pre>
-module(ch3).
-behaviour(gen_server).
-export([start_link/0]).
-export([alloc/0, free/1]).
-export([available/0]).
-export([init/1, handle_call/3, handle_cast/2]).
start_link() ->
gen_server:start_link({local, ch3}, ch3, [], []).
alloc() ->
gen_server:call(ch3, alloc).
free(Ch) ->
gen_server:cast(ch3, {free, Ch}).
available() ->
gen_server:call(ch3, available).
init(_Args) ->
{ok, channels()}.
handle_call(alloc, _From, Chs) ->
{Ch, Chs2} = alloc(Chs),
{reply, Ch, Chs2};
handle_call(available, _From, Chs) ->
N = available(Chs),
{reply, N, Chs}.
handle_cast({free, Ch}, Chs) ->
Chs2 = free(Ch, Chs),
{noreply, Chs2}.</pre></div>
<p>A new version of the <span class="code">ch_app.app</span> file must now be created,
where the version is updated:</p>
<div class="example"><pre>
{application, ch_app,
[{description, "Channel allocator"},
{vsn, "2"},
{modules, [ch_app, ch_sup, ch3]},
{registered, [ch3]},
{applications, [kernel, stdlib, sasl]},
{mod, {ch_app,[]}}
]}.</pre></div>
<p>To upgrade <span class="code">ch_app</span> from <span class="code">"1"</span> to <span class="code">"2"</span> (and
to downgrade from <span class="code">"2"</span> to <span class="code">"1"</span>), we simply need to
load the new (old) version of the <span class="code">ch3</span> callback module.
We create the application upgrade file <span class="code">ch_app.appup</span> in
the <span class="code">ebin</span> directory:</p>
<div class="example"><pre>
{"2",
[{"1", [{load_module, ch3}]}],
[{"1", [{load_module, ch3}]}]
}.</pre></div>
<h3><a name="id77359">11.6
Release Upgrade File</a></h3>
<a name="relup"></a>
<p>To define how to upgrade/downgrade between the new version and
previous versions of a release, we create a <strong>release upgrade file</strong>, or in short <span class="code">relup</span> file.</p>
<p>This file does not need to be created manually, it can be
generated by <span class="code">systools:make_relup/3,4</span>. The relevant versions
of the <span class="code">.rel</span> file, <span class="code">.app</span> files and <span class="code">.appup</span> files
are used as input. It is deducted which applications should be
added and deleted, and which applications that need to be upgraded
and/or downgraded. The instructions for this is fetched from
the <span class="code">.appup</span> files and transformed into a single list of
low-level instructions in the right order.</p>
<p>If the <span class="code">relup</span> file is relatively simple, it can be created
manually. Remember that it should only contain low-level
instructions.</p>
<p>The syntax and contents of the release upgrade file are
described in detail in <span class="code">relup(4)</span>.</p>
<p>Example, continued from the previous section. We have a new
version "2" of <span class="code">ch_app</span> and an <span class="code">.appup</span> file. We also
need a new version of the <span class="code">.rel</span> file. This time the file is
called <span class="code">ch_rel-2.rel</span> and the release version string is
changed changed from "A" to "B":</p>
<div class="example"><pre>
{release,
{"ch_rel", "B"},
{erts, "5.3"},
[{kernel, "2.9"},
{stdlib, "1.12"},
{sasl, "1.10"},
{ch_app, "2"}]
}.</pre></div>
<p>Now the <span class="code">relup</span> file can be generated:</p>
<div class="example"><pre>
1> <span class="bold_code">systools:make_relup("ch_rel-2", ["ch_rel-1"], ["ch_rel-1"]).</span>
ok</pre></div>
<p>This will generate a <span class="code">relup</span> file with instructions for
how to upgrade from version "A" ("ch_rel-1") to version "B"
("ch_rel-2") and how to downgrade from version "B" to version "A".</p>
<p>Note that both the old and new versions of the <span class="code">.app</span> and
<span class="code">.rel</span> files must be in the code path, as well as
the <span class="code">.appup</span> and (new) <span class="code">.beam</span> files. It is possible
to extend the code path by using the option <span class="code">path</span>:</p>
<div class="example"><pre>
1> <span class="bold_code">systools:make_relup("ch_rel-2", ["ch_rel-1"], ["ch_rel-1"],</span>
<span class="bold_code">[{path,["../ch_rel-1",</span>
<span class="bold_code">"../ch_rel-1/lib/ch_app-1/ebin"]}]).</span>
ok</pre></div>
<h3><a name="id77515">11.7
Installing a Release</a></h3>
<a name="rel_handler"></a>
<p>When we have made a new version of a release, a release package
can be created with this new version and transferred to the target
environment.</p>
<p>To install the new version of the release in run-time,
the <strong>release handler</strong> is used. This is a process belonging
to the SASL application, that handles unpacking, installation,
and removal of release packages. It is interfaced through
the module <span class="code">release_handler</span>, which is described in detail in
<span class="code">release_handler(3)</span>.</p>
<p>Assuming there is a target system up and running with
installation root directory <span class="code">$ROOT</span>, the release package with
the new version of the release should be copied to
<span class="code">$ROOT/releases</span>.</p>
<p>The first action is to <strong>unpack</strong> the release package,
the files are then extracted from the package:</p>
<div class="example"><pre>
release_handler:unpack_release(ReleaseName) => {ok, Vsn}</pre></div>
<p><span class="code">ReleaseName</span> is the name of the release package except
the <span class="code">.tar.gz</span> extension. <span class="code">Vsn</span> is the version of
the unpacked release, as defined in its <span class="code">.rel</span> file.</p>
<p>A directory <span class="code">$ROOT/lib/releases/Vsn</span> will be created, where
the <span class="code">.rel</span> file, the boot script <span class="code">start.boot</span>,
the system configuration file <span class="code">sys.config</span> and <span class="code">relup</span>
are placed. For applications with new version numbers,
the application directories will be placed under <span class="code">$ROOT/lib</span>.
Unchanged applications are not affected.</p>
<p>An unpacked release can be <strong>installed</strong>. The release
handler then evaluates the instructions in <span class="code">relup</span>, step by
step:</p>
<div class="example"><pre>
release_handler:install_release(Vsn) => {ok, FromVsn, []}</pre></div>
<p>If an error occurs during the installation, the system is
rebooted using the old version of the release. If installation
succeeds, the system is afterwards using the new version of
the release, but should anything happen and the system is
rebooted, it would start using the previous version again. To be
made the default version, the newly installed release must be made
<strong>permanent</strong>, which means the previous version becomes
<strong>old</strong>:</p>
<div class="example"><pre>
release_handler:make_permanent(Vsn) => ok</pre></div>
<p>The system keeps information about which versions are old and
permanent in the files <span class="code">$ROOT/releases/RELEASES</span> and
<span class="code">$ROOT/releases/start_erl.data</span>.</p>
<p>To downgrade from <span class="code">Vsn</span> to <span class="code">FromVsn</span>,
<span class="code">install_release</span> must be called again:</p>
<div class="example"><pre>
release_handler:install_release(FromVsn) => {ok, Vsn, []}</pre></div>
<p>An installed, but not permanent, release can be <strong>removed</strong>.
Information about the release is then deleted from
<span class="code">$ROOT/releases/RELEASES</span> and the release specific code,
that is the new application directories and
the <span class="code">$ROOT/releases/Vsn</span> directory, are removed.</p>
<div class="example"><pre>
release_handler:remove_release(Vsn) => ok</pre></div>
<p>Example, continued from the previous sections:</p>
<p>1) Create a target system as described in <strong>System Principles</strong> of the first version <span class="code">"A"</span> of <span class="code">ch_rel</span>
from
the <span class="bold_code"><a href="release_structure.html#ch_rel">Releases</a></span>
chapter. This time <span class="code">sys.config</span> must be included in
the release package. If no configuration is needed, the file
should contain the empty list:</p>
<div class="example"><pre>
[].</pre></div>
<p>2) Start the system as a simple target system. Note that in
reality, it should be started as an embedded system. However,
using <span class="code">erl</span> with the correct boot script and config file is
enough for illustration purposes:</p>
<div class="example"><pre>
% <span class="bold_code">cd $ROOT</span>
% <span class="bold_code">bin/erl -boot $ROOT/releases/A/start -config $ROOT/releases/A/sys</span>
...</pre></div>
<p><span class="code">$ROOT</span> is the installation directory of the target system.</p>
<p>3) In another Erlang shell, generate start scripts and create a
release package for the new version <span class="code">"B"</span>. Remember to
include (a possible updated) <span class="code">sys.config</span> and
the <span class="code">relup</span> file, see <span class="bold_code"><a href="#relup">Release Upgrade File</a></span> above.</p>
<div class="example"><pre>
1> <span class="bold_code">systools:make_script("ch_rel-2").</span>
ok
2> <span class="bold_code">systools:make_tar("ch_rel-2").</span>
ok</pre></div>
<p>The new release package now contains version "2" of <span class="code">ch_app</span>
and the <span class="code">relup</span> file as well:</p>
<div class="example"><pre>
% tar tf ch_rel-2.tar
lib/kernel-2.9/ebin/kernel.app
lib/kernel-2.9/ebin/application.beam
...
lib/stdlib-1.12/ebin/stdlib.app
lib/stdlib-1.12/ebin/beam_lib.beam
...
lib/sasl-1.10/ebin/sasl.app
lib/sasl-1.10/ebin/sasl.beam
...
lib/ch_app-2/ebin/ch_app.app
lib/ch_app-2/ebin/ch_app.beam
lib/ch_app-2/ebin/ch_sup.beam
lib/ch_app-2/ebin/ch3.beam
releases/B/start.boot
releases/B/relup
releases/B/sys.config
releases/B/ch_rel-2.rel
releases/ch_rel-2.rel</pre></div>
<p>4) Copy the release package <span class="code">ch_rel-2.tar.gz</span> to
the <span class="code">$ROOT/releases</span> directory.</p>
<p>5) In the running target system, unpack the release package:</p>
<div class="example"><pre>
1> <span class="bold_code">release_handler:unpack_release("ch_rel-2").</span>
{ok,"B"}</pre></div>
<p>The new application version <span class="code">ch_app-2</span> is installed under
<span class="code">$ROOT/lib</span> next to <span class="code">ch_app-1</span>. The <span class="code">kernel</span>,
<span class="code">stdlib</span> and <span class="code">sasl</span> directories are not affected, as
they have not changed.</p>
<p>Under <span class="code">$ROOT/releases</span>, a new directory <span class="code">B</span> is created,
containing <span class="code">ch_rel-2.rel</span>, <span class="code">start.boot</span>,
<span class="code">sys.config</span> and <span class="code">relup</span>.</p>
<p>6) Check if the function <span class="code">ch3:available/0</span> is available:</p>
<div class="example"><pre>
2> <span class="bold_code">ch3:available().</span>
** exception error: undefined function ch3:available/0</pre></div>
<p>7) Install the new release. The instructions in
<span class="code">$ROOT/releases/B/relup</span> are executed one by one, resulting
in the new version of <span class="code">ch3</span> being loaded. The function
<span class="code">ch3:available/0</span> is now available:</p>
<div class="example"><pre>
3> <span class="bold_code">release_handler:install_release("B").</span>
{ok,"A",[]}
4> <span class="bold_code">ch3:available().</span>
3
5> <span class="bold_code">code:which(ch3).</span>
".../lib/ch_app-2/ebin/ch3.beam"
6> <span class="bold_code">code:which(ch_sup).</span>
".../lib/ch_app-1/ebin/ch_sup.beam"</pre></div>
<p>Note that processes in <span class="code">ch_app</span> for which code have not
been updated, for example the supervisor, are still evaluating
code from <span class="code">ch_app-1</span>.</p>
<p>8) If the target system is now rebooted, it will use version "A"
again. The "B" version must be made permanent, in order to be
used when the system is rebooted.</p>
<div class="example"><pre>
7> <span class="bold_code">release_handler:make_permanent("B").</span>
ok</pre></div>
<h3><a name="id77986">11.8
Updating Application Specifications</a></h3>
<a name="sys"></a>
<p>When a new version of a release is installed, the application
specifications are automatically updated for all loaded
applications.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>The information about the new application specifications are
fetched from the boot script included in the release package.
It is therefore important that the boot script is generated from
the same <span class="code">.rel</span> file as is used to build the release
package itself.</p>
</p></div>
</div>
<p>Specifically, the application configuration parameters are
automatically updated according to (in increasing priority
order):</p>
<ul>
<li>The data in the boot script, fetched from the new
application resource file <span class="code">App.app</span>
</li>
<li>The new <span class="code">sys.config</span>
</li>
<li>Command line arguments <span class="code">-App Par Val</span>
</li>
</ul>
<p>This means that parameter values set in the other system
configuration files, as well as values set using
<span class="code">application:set_env/3</span>, are disregarded.</p>
<p>When an installed release is made permanent, the system process
<span class="code">init</span> is set to point out the new <span class="code">sys.config</span>.</p>
<p>After the installation, the application controller will compare
the old and new configuration parameters for all running
applications and call the callback function:</p>
<div class="example"><pre>
Module:config_change(Changed, New, Removed)</pre></div>
<p><span class="code">Module</span> is the application callback module as defined by
the <span class="code">mod</span> key in the <span class="code">.app</span> file. <span class="code">Changed</span> and
<span class="code">New</span> are lists of <span class="code">{Par,Val}</span> for all changed and
added configuration parameters, respectively. <span class="code">Removed</span> is
a list of all parameters <span class="code">Par</span> that have been removed.</p>
<p>The function is optional and may be omitted when implementing an
application callback module.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
20
