👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for release_handler (linux section 3erl)

release_handler(3erl)		     Erlang Module Definition		    release_handler(3erl)

NAME
       release_handler - Unpacking and Installation of Release Packages

DESCRIPTION
       The  release  handler  is a process belonging to the SASL application which is responsible
       for release handling , that is, unpacking, installation, and removal of release packages.

       An introduction to release handling and a usage example can be found in Design  Principles
       .

       A  release  package  is	a  compressed tar file containing code for a certain version of a
       release, created by calling systools:make_tar/1,2 . The release package should  be  placed
       in  the $ROOT/releases directory of the previous version of the release where $ROOT is the
       installation root directory, code:root_dir() . Another releases directory can be specified
       using  the  SASL  configuration	parameter  releases_dir  , or the OS environment variable
       RELDIR . The release handler must have write access to this directory in order to  install
       the  new  release.  The	persistent state of the release handler is stored there in a file
       called RELEASES .

       A release package should always contain the release resource  file  Name.rel  and  a  boot
       script  Name.boot . It may contain a release upgrade file relup and a system configuration
       file sys.config . The .rel file contains information about the release: its name, version,
       and  which  ERTS and application versions it uses. The relup file contains scripts for how
       to upgrade to, or downgrade from, this version of the release.

       The release package can be unpacked , which extracts the files. An unpacked release can be
       installed  .  The  currently used version of the release is then upgraded or downgraded to
       the specified version by evaluating the instructions in relup . An installed  release  can
       be made permanent . 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  perma-
       nent  one,  can	be  removed  .	When  a release is removed, all files that belong to that
       release only are deleted.

       Each version of the release has a status. The status can be unpacked , current , permanent
       ,  or  old  . There is always one latest release which either has status permanent (normal
       case), or current (installed, but not yet made permanent). The following table illustrates
       the meaning of the status values:

       Status	  Action		NextStatus
       -------------------------------------------
	 -	  unpack		unpacked
       unpacked   install		current
		  remove		  -
       current	  make_permanent	permanent
		  install other 	old
		  remove		  -
       permanent  make other permanent	old
		  install		permanent
       old	  reboot_old		permanent
		  install		current
		  remove		  -

       The  release  handler process is a locally registered process on each node. When a release
       is installed in a distributed system, the release handler on each node must be called. The
       release	installation  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 sys-
       tem, no matter how many nodes there are. If this is the case, it is recommended that soft-
       ware 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 han-
       dler to install the package.

       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 Embedded System . In this case, the system configuration file sys.config is mandatory.

       A new release may restart the system. Which program to use is specified by the  SASL  con-
       figuration parameter start_prg which defaults to $ROOT/bin/start .

       The  emulator  restart  on  Windows NT expects that the system is started using the erlsrv
       program (as a service). Furthermore the release handler expects that the service is  named
       NodeName  _  Release , where NodeName is the first part of the Erlang nodename (up to, but
       not including the "@") and Release is the current release of the application. The  release
       handler furthermore expects that a program like start_erl.exe is specified as "machine" to
       erlsrv . During upgrading with restart, a new service 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.

       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 sasl configuration parameters
       (see sasl(7) for details):

	 masters :
	   This node uses a number of master nodes in order to store and fetch	release  informa-
	   tion.  All master nodes must be up and running whenever release information is written
	   by this node.

	 client_directory :
	   The client_directory in the directory structure of the master nodes must be specified.

	 static_emulator :
	   This parameter specifies if the Erlang emulator is statically installed at the  client
	   node.  A  node  with  a  static  emulator  cannot dynamically switch to a new emulator
	   because the executable files are statically written into memory.

       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.

       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.

EXPORTS
       check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}

	      Types  Vsn = OtherVsn = string()
		     Descr = term()
		     Reason = term()

	      Checks if the specified version Vsn of the release can be  installed.  The  release
	      must  not  have  status  current	.  Issues warnings if relup or sys.config are not
	      present. If relup is present,  its  contents  are  checked  and  {error,Reason}  is
	      returned	if  an	error  is  found.  Also checks that all required applications are
	      present and that all new code can be loaded, or {error,Reason} is returned.

	      This function evaluates all instructions that occur before  the  point_of_no_return
	      instruction in the release upgrade script.

	      Returns  the  same  as install_release/1 . Descr defaults to "" if no relup file is
	      found.

       create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}

	      Types  Root = RelDir = RelFile = string()
		     AppDirs = [{App, Vsn, Dir}]
		     App = atom()
		     Vsn = Dir = string()
		     Reason = term()

	      Creates an initial RELEASES file to be used by the release handler. This file  must
	      exist in order to install new releases.

	      Root  is	the  root of the installation ( $ROOT ) as described above. RelDir is the
	      the directory where the RELEASES file should be created (normally $ROOT/releases ).
	      RelFile  is the name of the .rel file that describes the initial release, including
	      the extension .rel .

	      AppDirs can be used to specify from where the modules for  the  specified  applica-
	      tions  should be loaded. App is the name of an application, Vsn is the version, and
	      Dir is the name of the directory where App-Vsn is located. The  corresponding  mod-
	      ules  should  be	located under Dir/App-Vsn/ebin . The directories for applications
	      not specified in AppDirs are assumed to be located in $ROOT/lib .

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

	      Types  Vsn = File = string()
		     Reason = term()

	      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: start.boot , relup and sys.config .

	      The function can be called, for example, when these files are generated at the tar-
	      get. It should be called after set_unpacked/2 has been called.

       install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
       install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason}

	      Types  Vsn = OtherVsn = string()
		     Opt = {error_action, Action} | {code_change_timeout, Timeout}
		     | {suspend_timeout, Timeout} | {update_paths, Bool}
		     Action = restart | reboot
		     Timeout = default | infinity | int()>0
		     Bool = boolean()
		     Descr = term()
		     Reason    =    {illegal_option,	Opt}   |   {already_installed,	 Vsn}	|
		     {change_appl_data, term()} | term()

	      Installs the specified version Vsn of the release. Looks first for a relup file for
	      Vsn  and	a script {UpFromVsn,Descr1,Instructions1} in this file for upgrading from
	      the current version. If not found, the function looks for a relup file for the cur-
	      rent  version  and a script {Vsn,Descr2,Instructions2} in this file for downgrading
	      to Vsn .

	      If a script is found, the first thing that happens is that the applications  speci-
	      fications  are  updated according to the .app files and sys.config belonging to the
	      release version Vsn .

	      After the application specifications have been updated,  the  instructions  in  the
	      script  are  evaluated  and the function returns {ok,OtherVsn,Descr} if successful.
	      OtherVsn and Descr are the version ( UpFromVsn or Vsn ) and description ( Descr1 or
	      Descr2 ) as specified in the script.

	      If a recoverable error occurs, the function returns {error,Reason} and the original
	      application specifications are restored. If a  non-recoverable  error  occurs,  the
	      system is restarted.

	      The  option error_action defines if the node should be restarted ( init:restart() )
	      or rebooted ( init:reboot() ) in case of an error during the installation.  Default
	      is restart .

	      The option code_change_timeout defines the timeout for all calls to sys:change_code
	      . If no value is specified or default is given, the default value defined in sys is
	      used.

	      The option suspend_timeout defines the timeout for all calls to sys:suspend . If no
	      value is specified, the values defined by the Timeout parameter of the  upgrade  or
	      suspend  instructions  are used. If default is specified, the default value defined
	      in sys is used.

	      The option {update_paths,Bool} indicates if all application code	paths  should  be
	      updated  (  Bool==true ), or if only code paths for modified applications should be
	      updated ( Bool==false , default). This option only has effect for other application
	      directories  than  the default $ROOT/lib/App-Vsn , that is, application directories
	      provided in the AppDirs argument in a call to create_RELEASES/4 or set_unpacked/2 .

	      Example: In the current version CurVsn of a release, the application  directory  of
	      myapp is $ROOT/lib/myapp-1.0 . A new version NewVsn is unpacked outside the release
	      handler, and the release handler is informed about this with a call to:

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

	      If  NewVsn  is  installed  with  the  option   {update_paths,true}   ,   afterwards
	      code:lib_dir(myapp) will return /home/user/myapp-1.0 .

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

	      Types  Vsn = string()
		     Reason = {bad_status, Status} | term()

	      Makes the specified version Vsn of the release permanent.

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

	      Types  Vsn = string()
		     Reason = {permanent, Vsn} | client_node | term()

	      Removes a release and its files from the system. The release must not be the perma-
	      nent release. Removes only the files and directories not in use by another release.

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

	      Types  Vsn = string()
		     Reason = {bad_status, Status} | term()

	      Reboots the system by making the old release  permanent,	and  calls  init:reboot()
	      directly. The release must have status old .

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

	      Types  Vsn = string()
		     Reason = {permanent, Vsn} | term()

	      Makes  it possible to handle removal of releases outside the release handler. Tells
	      the release handler that the release is removed from the system. This function does
	      not delete any files.

       set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}

	      Types  RelFile = string()
		     AppDirs = [{App, Vsn, Dir}]
		     App = atom()
		     Vsn = Dir = string()
		     Reason = term()

	      Makes  it  possible  to  handle  unpacking of releases outside the release handler.
	      Tells the release handler that the release is unpacked. Vsn is extracted	from  the
	      release resource file RelFile .

	      AppDirs  can  be	used to specify from where the modules for the specified applica-
	      tions should be loaded. App is the name of an application, Vsn is the version,  and
	      Dir  is  the name of the directory where App-Vsn is located. The corresponding mod-
	      ules should be located under Dir/App-Vsn/ebin . The  directories	for  applications
	      not specified in AppDirs are assumed to be located in $ROOT/lib .

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

	      Types  Name = Vsn = string()
		     Reason = client_node | term()

	      Unpacks a release package Name.tar.gz located in the releases directory.

	      Performs	some  checks on the package - for example checks that all mandatory files
	      are present - and extracts its contents.

       which_releases() -> [{Name, Vsn, Apps, Status}]

	      Types  Name = Vsn = string()
		     Apps = ["App-Vsn"]
		     Status = unpacked | current | permanent | old

	      Returns all releases known to the release handler.

APPLICATION UPGRADE/DOWNGRADE
       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 relup is
       created on-the-fly, based on the .appup file for the application, and evaluated exactly in
       the same way as release_handler does.

   Warning:
       These  function	is primarily intended for simplified testing of of .appup files. They are
       not run within the context of the release_handler process. They must therefore not be used
       together  with calls to install_release/1,2 , as this will cause release_handler to end up
       in an inconsistent state.

       No persistent information is updated, why these functions can be used on any Erlang  node,
       embedded  or not. Also, using these functions does not effect which code will be loaded in
       case of a reboot.

       If the upgrade or downgrade fails, the application may end up in an inconsistent state.

EXPORTS
       upgrade_app(App, Dir) -> {ok, Unpurged} | restart_new_emulator | {error, Reason}

	      Types  App = atom()
		     Dir = string()
		     Unpurged = [Module]
		     Module = atom()
		     Reason = term()

	      Upgrades an application App from the current version to a new  version  located  in
	      Dir according to the .appup script.

	      App  is  the name of the application, which must be started. Dir is the new library
	      directory of App , the corresponding modules as well as the .app and  .appup  files
	      should be located under Dir/ebin .

	      The  function looks in the .appup file and tries to find an upgrade script from the
	      current version of the application using upgrade_script/2 . This script  is  evalu-
	      ated  using  eval_appup_script/4	,  exactly in the same way as install_release/1,2
	      does.

	      Returns {ok, Unpurged} if evaluating the script is successful, where Unpurged is	a
	      list  of	unpurged  modules, or restart_new_emulator if this instruction is encoun-
	      tered in the script, or {error, Reason} if an error occurred when finding or evalu-
	      ating the script.

       downgrade_app(App, Dir) ->
       downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_new_emulator | {error, Reason}

	      Types  App = atom()
		     Dir = OldVsn = string()
		     Unpurged = [Module]
		     Module = atom()
		     Reason = term()

	      Downgrades an application App from the current version to a previous version OldVsn
	      located in Dir according to the .appup script.

	      App is the name of the application, which must be started. OldVsn is  the  previous
	      version  of the application and can be omitted if Dir is of the format "App-OldVsn"
	      . Dir is the library directory of this previous version of App , the  corresponding
	      modules  as well as the old .app file should be located under Dir/ebin . The .appup
	      file should be located in the ebin directory of the current  library  directory  of
	      the application ( code:lib_dir(App) ).

	      The  function looks in the .appup file and tries to find an downgrade script to the
	      previous version of the application using downgrade_script/3 . This script is eval-
	      uated  using  eval_appup_script/4  , exactly in the same way as install_release/1,2
	      does.

	      Returns {ok, Unpurged} if evaluating the script is successful, where Unpurged is	a
	      list  of	unpurged  modules, or restart_new_emulator if this instruction is encoun-
	      tered in the script, or {error, Reason} if an error occurred when finding or evalu-
	      ating the script.

       upgrade_script(App, Dir) -> {ok, NewVsn, Script}

	      Types  App = atom()
		     Dir = string()
		     NewVsn = string()
		     Script = Instructions -- see appup(5)

	      Tries  to  find an application upgrade script for App from the current version to a
	      new version located in Dir .

	      The upgrade script can then be evaluated using eval_appup_script/4 . It  is  recom-
	      mended  to  use  upgrade_app/2  instead,	but  this  function is useful in order to
	      inspect the contents of the script.

	      App is the name of the application, which must be started. Dir is the  new  library
	      directory  of  App , the corresponding modules as well as the .app and .appup files
	      should be located under Dir/ebin .

	      The function looks in the .appup file and tries to find an upgrade script from  the
	      current  version of the application. High-level instructions are translated to low-
	      level instructions and the instructions are sorted in the same manner as when  gen-
	      erating a relup script.

	      Returns  {ok,  NewVsn,  Script}  if successful, where NewVsn is the new application
	      version.

	      Failure: If a script cannot be found, the function fails with an appropriate  error
	      reason.

       downgrade_script(App, OldVsn, Dir) -> {ok, Script}

	      Types  App = atom()
		     OldVsn = Dir = string()
		     Script = Instructions -- see appup(5)

	      Tries to find an application downgrade script for App from the current version to a
	      previous version OldVsn located in Dir .

	      The downgrade script can then be evaluated using eval_appup_script/4 . It is recom-
	      mended  to  use  downgrade_app/2,3 instead, but this function is useful in order to
	      inspect the contents of the script.

	      App is the name of the application, which must be  started.  Dir	is  the  previous
	      library  directory  of App , the corresponding modules as well as the old .app file
	      should be located under Dir/ebin . The .appup file should be located  in	the  ebin
	      directory  of  the current library directory of the application ( code:lib_dir(App)
	      ).

	      The function looks in the .appup file and tries to find 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 relup script.

	      Returns {ok, Script} if successful.

	      Failure:	If a script cannot be found, the function fails with an appropriate error
	      reason.

       eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged}  |  restart_new_emulator	|
       {error, Reason}

	      Types  App = atom()
		     ToVsn = ToDir = string()
		     Script -- see upgrade_script/2, downgrade_script/3
		     Unpurged = [Module]
		     Module = atom()
		     Reason = term()

	      Evaluates an application upgrade or downgrade script Script , the result from call-
	      ing  upgrade_app/2  or  downgrade_app/2,3  ,   exactly   in   the   same	 way   as
	      install_release/1,2 does.

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

	      Returns {ok, Unpurged} if evaluating the script is successful, where Unpurged is	a
	      list  of	unpurged  modules, or restart_new_emulator if this instruction is encoun-
	      tered in the script, or {error, Reason} if an error occurred  when  evaluating  the
	      script.

TYPICAL ERROR REASONS
	 * {bad_masters, Masters} - The master nodes Masters are not alive.

	 * {bad_rel_file, File} - Specified .rel file File can not be read, or does not contain a
	   single term.

	 * {bad_rel_data, Data} - Specified .rel file does not contain a recognized release spec-
	   ification, but another term Data .

	 * {bad_relup_file, File} - Specified relup file Relup contains bad data.

	 * {cannot_extract_file,  Name,  Reason}  -  Problems  when  extracting  from a tar file,
	   erl_tar:extract/2 returned {error, {Name, Reason}} .

	 * {existing_release, Vsn} - Specified release version Vsn is already in use.

	 * {Master, Reason, When} - Some operation, indicated by the term When ,  failed  on  the
	   master node Master with the specified error reason Reason .

	 * {no_matching_relup, Vsn, CurrentVsn} - Cannot find a script for up/downgrading between
	   CurrentVsn and Vsn .

	 * {no_such_directory, Path} - The directory Path does not exist.

	 * {no_such_file, Path} - The path Path (file or directory) does not exist.

	 * {no_such_file, {Master, Path}} - The path Path (file or directory) does not	exist  at
	   the master node Master .

	 * {no_such_release, Vsn} - The specified version Vsn of the release does not exist.

	 * {not_a_directory, Path} - Path exists, but is not a directory.

	 * {Posix,  File} - Some file operation failed for File . Posix is an atom named from the
	   Posix error codes, such as enoent , eacces or eisdir . See file(3erl) .

	 * Posix - Some file operation failed, as above.

SEE ALSO
       OTP Design Principles , config(5) , relup(5) , rel(5)  ,  script(5)  ,  sys(3erl)  ,  sys-
       tools(3erl)

Ericsson AB				   sasl 2.1.9.3 		    release_handler(3erl)


All times are GMT -4. The time now is 03:06 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?