1release_handler(3) Erlang Module Definition release_handler(3)
2
6 release_handler - Unpacking and Installation of Release Packages
7
9 The release handler process belongs to the SASL application, which is
10 responsible for release handling, that is, unpacking, installation, and
11 removal of release packages.
12 An introduction to release handling and an example is provided in OTP
14 Design Principles in System Documentation.
15 A release package is a compressed tar file containing code for a cer‐
17 tain version of a release, created by calling systools:make_tar/1,2.
18 The release package is to be located in the $ROOT/releases directory of
19 the previous version of the release, where $ROOT is the installation
20 root directory, code:root_dir(). Another releases directory can be
21 specified using the SASL configuration parameter releases_dir or the OS
22 environment variable RELDIR. The release handler must have write access
23 to this directory to install the new release. The persistent state of
24 the release handler is stored there in a file called RELEASES.
25 A release package is always to contain:
27 * A release resource file, Name.rel
29 * A boot script, Name.boot
31 The .rel file contains information about the release: its name, ver‐
33 sion, and which ERTS and application versions it uses.
34 A release package can also contain:
36 * A release upgrade file, relup
38 * A system configuration file, sys.config
40 * A system configuration source file, sys.config.src
42 The relup file contains instructions for how to upgrade to, or down‐
44 grade from, this version of the release.
45 The release package can be unpacked, which extracts the files. An un‐
47 packed release can be installed. The currently used version of the re‐
48 lease is then upgraded or downgraded to the specified version by evalu‐
49 ating the instructions in the relup file. An installed release can be
50 made permanent. Only one permanent release can exist in the system, and
51 this release is used if the system is restarted. An installed release,
52 except the permanent one, can be removed. When a release is removed,
53 all files belonging to that release only are deleted.
54 Each release version has a status, which can be unpacked, current, per‐
56 manent, or old. There is always one latest release, which either has
57 status permanent (normal case) or current (installed, but not yet made
58 permanent). The meaning of the status values are illustrated in the
59 following table:
60 Status Action NextStatus
62 -------------------------------------------
63 - unpack unpacked
64 unpacked install current
65 remove -
66 current make_permanent permanent
67 install other old
68 remove -
69 permanent make other permanent old
70 install permanent
71 old reboot_old permanent
72 install current
73 remove -
74 The release handler process is a locally registered process on each
76 node. When a release is installed in a distributed system, the release
77 handler on each node must be called. The release installation can be
78 synchronized between nodes. From an operator view, it can be unsatis‐
79 factory to specify each node. The aim is to install one release package
80 in the system, no matter how many nodes there are. It is recommended
81 that software management functions are written that take care of this
82 problem. Such a function can have knowledge of the system architecture,
83 so it can contact each individual release handler to install the pack‐
84 age.
85 For release handling to work properly, the runtime system must know
87 which release it is running. It must also be able to change (in run‐
88 time) which boot script and system configuration file are to be used if
89 the system is restarted. This is taken care of automatically if Erlang
90 is started as an embedded system. Read about this in Embedded System in
91 System Documentation. In this case, the system configuration file
92 sys.config is mandatory.
93 The installation of a new release can restart the system. Which program
95 to use is specified by the SASL configuration parameter start_prg,
96 which defaults to $ROOT/bin/start.
97 The emulator restart on Windows NT expects that the system is started
99 using the erlsrv program (as a service). Furthermore, the release han‐
100 dler expects that the service is named NodeName_Release, where NodeName
101 is the first part of the Erlang node name (up to, but not including the
102 "@") and Release is the current release version. The release handler
103 furthermore expects that a program like start_erl.exe is specified as
104 "machine" to erlsrv. During upgrading with restart, a new service is
105 registered and started. The new service is set to automatic and the old
106 service is removed when the new release is made permanent.
107 The release handler at a node running on a diskless machine, or with a
109 read-only file system, must be configured accordingly using the follow‐
110 ing SASL configuration parameters (for details, see sasl(6)):
111 masters:
113 This node uses some master nodes to store and fetch release infor‐
114 mation. All master nodes must be operational whenever release in‐
115 formation is written by this node.
116 client_directory:
118 The client_directory in the directory structure of the master nodes
119 must be specified.
120 static_emulator:
122 This parameter specifies if the Erlang emulator is statically in‐
123 stalled at the client node. A node with a static emulator cannot
124 dynamically switch to a new emulator, as the executable files are
125 statically written into memory.
126 The release handler can also be used to unpack and install release
128 packages when not running Erlang as an embedded system. However, in
129 this case the user must somehow ensure that correct boot scripts and
130 configuration files are used if the system must be restarted.
131 Functions are provided for using another file structure than the struc‐
133 ture defined in OTP. These functions can be used to test a release up‐
134 grade locally.
135
137 check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
138 check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Rea‐
139 son}
140 Types:
142 Vsn = OtherVsn = string()
144 Opts = [Opt]
145 Opt = purge
146 Descr = term()
147 Reason = term()
148 Checks if the specified version Vsn of the release can be in‐
150 stalled. The release must not have status current. Issues warn‐
151 ings if relup file or sys.config is not present. If relup file
152 is present, its contents are checked and {error,Reason} is re‐
153 turned if an error is found. Also checks that all required ap‐
154 plications are present and that all new code can be loaded; {er‐
155 ror,Reason} is returned if an error is found.
156 Evaluates all instructions that occur before the point_of_no_re‐
158 turn instruction in the release upgrade script.
159 Returns the same as install_release/1. Descr defaults to "" if
161 no relup file is found.
162 If option purge is specified, all old code that can be soft-
164 purged is purged after all other checks are successfully com‐
165 pleted. This can be useful to reduce the time needed by in‐
166 stall_release/1.
167 create_RELEASES(RelDir, RelFile, AppDirs) -> ok | {error, Reason}
169 create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}
170 Types:
172 Root = RelDir = RelFile = string()
174 AppDirs = [{App, Vsn, Dir}]
175 App = atom()
176 Vsn = Dir = string()
177 Reason = term()
178 Creates an initial RELEASES file to be used by the release han‐
180 dler. This file must exist to install new releases.
181 Root is the root of the installation ($ROOT) as described ear‐
183 lier. RelDir is the directory where the RELEASES file is to be
184 created (normally $ROOT/releases). RelFile is the name of the
185 .rel file that describes the initial release, including the ex‐
186 tension .rel. If Root is not given, the RELEASES file will be
187 location independent (i.e, it will not contain absolute paths
188 unless there are absolute paths in AppDirs). A RELEASES file
189 should be made location independent if the installation's $ROOT
190 is unknown. The release_handler module will interpret relative
191 paths in a running system's RELEASES file as being relative to
192 $ROOT.
193 AppDirs can be used to specify from where the modules for the
195 specified applications are to be loaded. App is the name of an
196 application, Vsn is the version, and Dir is the name of the di‐
197 rectory where App-Vsn is located. The corresponding modules are
198 to be located under Dir/App-Vsn/ebin. The directories for appli‐
199 cations not specified in AppDirs are assumed to be located in
200 $ROOT/lib.
201 install_file(Vsn, File) -> ok | {error, Reason}
203 Types:
205 Vsn = File = string()
207 Reason = term()
208 Installs a release-dependent file in the release structure. The
210 release-dependent file must be in the release structure when a
211 new release is installed: start.boot, relup, and sys.config.
212 The function can be called, for example, when these files are
214 generated at the target. The function is to be called after
215 set_unpacked/2 has been called.
216 install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
218 install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_af‐
219 ter_restart, OtherVsn, Descr} | {error, Reason}
220 Types:
222 Vsn = OtherVsn = string()
224 Opt = {error_action, Action} | {code_change_timeout, Timeout}
225 | {suspend_timeout, Timeout} | {update_paths, Bool}
226 Action = restart | reboot
227 Timeout = default | infinity | pos_integer()
228 Bool = boolean()
229 Descr = term()
230 Reason = {illegal_option, Opt} | {already_installed, Vsn} |
231 {change_appl_data, term()} | {missing_base_app, OtherVsn,
232 App} | {could_not_create_hybrid_boot, term()} | term()
233 App = atom()
234 Installs the specified version Vsn of the release. Looks first
236 for a relup file for Vsn and a script {UpFromVsn,Descr1,Instruc‐
237 tions1} in this file for upgrading from the current version. If
238 not found, the function looks for a relup file for the current
239 version and a script {Vsn,Descr2,Instructions2} in this file for
240 downgrading to Vsn.
241 If a script is found, the first thing that happens is that the
243 application specifications are updated according to the .app
244 files and sys.config belonging to the release version Vsn.
245 After the application specifications have been updated, the in‐
247 structions in the script are evaluated and the function returns
248 {ok,OtherVsn,Descr} if successful. OtherVsn and Descr are the
249 version (UpFromVsn or Vsn) and description (Descr1 or Descr2) as
250 specified in the script.
251 If {continue_after_restart,OtherVsn,Descr} is returned, the emu‐
253 lator is restarted before the upgrade instructions are executed.
254 This occurs if the emulator or any of the applications Kernel,
255 STDLIB, or SASL are updated. The new emulator version and these
256 core applications execute after the restart. For all other ap‐
257 plications the old versions are started and the upgrade is per‐
258 formed as normal by executing the upgrade instructions.
259 If a recoverable error occurs, the function returns {error,Rea‐
261 son} and the original application specifications are restored.
262 If a non-recoverable error occurs, the system is restarted.
263 Options:
265 error_action:
267 Defines if the node is to be restarted (init:restart()) or
268 rebooted (init:reboot()) if there is an error during the in‐
269 stallation. Default is restart.
270 code_change_timeout:
272 Defines the time-out for all calls to sys:change_code. If no
273 value is specified or default is specified, the default
274 value defined in sys is used.
275 suspend_timeout:
277 Defines the time-out for all calls to sys:suspend. If no
278 value is specified, the values defined by the Timeout param‐
279 eter of the upgrade or suspend instructions are used. If de‐
280 fault is specified, the default value defined in sys is
281 used.
282 {update_paths,Bool}:
284 Indicates if all application code paths are to be updated
285 (Bool==true) or if only code paths for modified applications
286 are to be updated (Bool==false, default). This option has
287 only effect for other application directories than the de‐
288 fault $ROOT/lib/App-Vsn, that is, application directories
289 specified in argument AppDirs in a call to create_RELEASES/4
290 or set_unpacked/2.
291 Example:
293 In the current version CurVsn of a release, the application
295 directory of myapp is $ROOT/lib/myapp-1.0. A new version
296 NewVsn is unpacked outside the release handler and the re‐
297 lease handler is informed about this with a call as follows:
298 release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
300 => {ok,NewVsn}
301 If NewVsn is installed with option {update_paths,true}, then
303 code:lib_dir(myapp) returns /home/user/myapp-1.0.
304 Note:
306 Installing a new release can be time consuming if there are many
307 processes in the system. The reason is that each process must be
308 checked for references to old code before a module can be
309 purged. This check can lead to garbage collections and copying
310 of data.
311 To speed up the execution of install_release, first call
313 check_install_release, using option purge. This does the same
314 check for old code. Then purges all modules that can be soft-
315 purged. The purged modules do then no longer have any old code,
316 and install_release does not need to do the checks.
317 This does not reduce the overall time for the upgrade, but it
319 allows checks and purge to be executed in the background before
320 the real upgrade is started.
321 Note:
324 When upgrading the emulator from a version older than OTP R15,
325 an attempt is made to load new application beam code into the
326 old emulator. Sometimes the new beam format cannot be read by
327 the old emulator, so the code loading fails and the complete up‐
328 grade is terminated. To overcome this problem, the new applica‐
329 tion code is to be compiled with the old emulator. For more in‐
330 formation about emulator upgrade from pre OTP R15 versions, see
331 Design Principles in System Documentation.
332 make_permanent(Vsn) -> ok | {error, Reason}
335 Types:
337 Vsn = string()
339 Reason = {bad_status, Status} | term()
340 Makes the specified release version Vsn permanent.
342 remove_release(Vsn) -> ok | {error, Reason}
344 Types:
346 Vsn = string()
348 Reason = {permanent, Vsn} | client_node | term()
349 Removes a release and its files from the system. The release
351 must not be the permanent release. Removes only the files and
352 directories not in use by another release.
353 reboot_old_release(Vsn) -> ok | {error, Reason}
355 Types:
357 Vsn = string()
359 Reason = {bad_status, Status} | term()
360 Reboots the system by making the old release permanent, and
362 calls init:reboot() directly. The release must have status old.
363 set_removed(Vsn) -> ok | {error, Reason}
365 Types:
367 Vsn = string()
369 Reason = {permanent, Vsn} | term()
370 Makes it possible to handle removal of releases outside the re‐
372 lease handler. Tells the release handler that the release is re‐
373 moved from the system. This function does not delete any files.
374 set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}
376 Types:
378 RelFile = string()
380 AppDirs = [{App, Vsn, Dir}]
381 App = atom()
382 Vsn = Dir = string()
383 Reason = term()
384 Makes it possible to handle unpacking of releases outside the
386 release handler. Tells the release handler that the release is
387 unpacked. Vsn is extracted from the release resource file
388 RelFile.
389 AppDirs can be used to specify from where the modules for the
391 specified applications are to be loaded. App is the name of an
392 application, Vsn is the version, and Dir is the name of the di‐
393 rectory where App-Vsn is located. The corresponding modules are
394 to be located under Dir/App-Vsn/ebin. The directories for appli‐
395 cations not specified in AppDirs are assumed to be located in
396 $ROOT/lib.
397 unpack_release(Name) -> {ok, Vsn} | {error, Reason}
399 Types:
401 Name = Vsn = string()
403 Reason = client_node | term()
404 Unpacks a release package Name.tar.gz located in the releases
406 directory.
407 Performs some checks on the package, for example, checks that
409 all mandatory files are present, and extracts its contents.
410 which_releases() -> [{Name, Vsn, Apps, Status}]
412 Types:
414 Name = Vsn = string()
416 Apps = ["App-Vsn"]
417 Status = unpacked | current | permanent | old
418 Returns all releases known to the release handler.
420 which_releases(Status) -> [{Name, Vsn, Apps, Status}]
422 Types:
424 Name = Vsn = string()
426 Apps = ["App-Vsn"]
427 Status = unpacked | current | permanent | old
428 Returns all releases, known to the release handler, of a spe‐
430 cific status.
431
433 The following functions can be used to test upgrade and downgrade of
434 single applications (instead of upgrading/downgrading an entire re‐
435 lease). A script corresponding to the instructions in the relup file is
436 created on-the-fly, based on the .appup file for the application, and
437 evaluated exactly in the same way as release_handler does.
438 Warning:
440 These functions are primarily intended for simplified testing of .appup
441 files. They are not run within the context of the release_handler
442 process. They must therefore not be used together with calls to in‐
443 stall_release/1,2, as this causes the release_handler to end up in an
444 inconsistent state.
445 No persistent information is updated, so these functions can be used on
447 any Erlang node, embedded or not. Also, using these functions does not
448 affect which code is loaded if there is a reboot.
449 If the upgrade or downgrade fails, the application can end up in an in‐
451 consistent state.
452
455 upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error,
456 Reason}
457 Types:
459 App = atom()
461 Dir = string()
462 Unpurged = [Module]
463 Module = atom()
464 Reason = term()
465 Upgrades an application App from the current version to a new
467 version located in Dir according to the .appup file.
468 App is the name of the application, which must be started. Dir
470 is the new library directory of App. The corresponding modules
471 as well as the .app and .appup files are to be located under
472 Dir/ebin.
473 The function looks in the .appup file and tries to find an up‐
475 grade script from the current version of the application using
476 upgrade_script/2. This script is evaluated using eval_ap‐
477 pup_script/4, exactly in the same way as install_release/1,2
478 does.
479 Returns one of the following:
481 * {ok, Unpurged} if evaluating the script is successful, where
483 Unpurged is a list of unpurged modules
484 * restart_emulator if this instruction is encountered in the
486 script
487 * {error, Reason} if an error occurred when finding or evalu‐
489 ating the script
490 If the restart_new_emulator instruction is found in the script,
492 upgrade_app/2 returns {error,restart_new_emulator}. This because
493 restart_new_emulator requires a new version of the emulator to
494 be started before the rest of the upgrade instructions can be
495 executed, and this can only be done by install_release/1,2.
496 downgrade_app(App, Dir) ->
498 downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator |
499 {error, Reason}
500 Types:
502 App = atom()
504 Dir = OldVsn = string()
505 Unpurged = [Module]
506 Module = atom()
507 Reason = term()
508 Downgrades an application App from the current version to a pre‐
510 vious version OldVsn located in Dir according to the .appup
511 file.
512 App is the name of the application, which must be started. Old‐
514 Vsn is the previous application version and can be omitted if
515 Dir is of the format "App-OldVsn". Dir is the library directory
516 of the previous version of App. The corresponding modules and
517 the old .app file are to be located under Dir/ebin. The .appup
518 file is to be located in the ebin directory of the current li‐
519 brary directory of the application (code:lib_dir(App)).
520 The function looks in the .appup file and tries to find a down‐
522 grade script to the previous version of the application using
523 downgrade_script/3. This script is evaluated using eval_ap‐
524 pup_script/4, exactly in the same way as install_release/1,2
525 does.
526 Returns one of the following:
528 * {ok, Unpurged} if evaluating the script is successful, where
530 Unpurged is a list of unpurged modules
531 * restart_emulator if this instruction is encountered in the
533 script
534 * {error, Reason} if an error occurred when finding or evalu‐
536 ating the script
537 upgrade_script(App, Dir) -> {ok, NewVsn, Script}
539 Types:
541 App = atom()
543 Dir = string()
544 NewVsn = string()
545 Script = Instructions
546 Tries to find an application upgrade script for App from the
548 current version to a new version located in Dir.
549 The upgrade script can then be evaluated using eval_ap‐
551 pup_script/4. It is recommended to use upgrade_app/2 instead,
552 but this function (upgrade_script) is useful to inspect the con‐
553 tents of the script.
554 App is the name of the application, which must be started. Dir
556 is the new library directory of App. The corresponding modules
557 as well as the .app and .appup files are to be located under
558 Dir/ebin.
559 The function looks in the .appup file and tries to find an up‐
561 grade script from the current application version. High-level
562 instructions are translated to low-level instructions. The in‐
563 structions are sorted in the same manner as when generating a
564 relup file.
565 Returns {ok, NewVsn, Script} if successful, where NewVsn is the
567 new application version. For details about Script, see appup(4).
568 Failure: If a script cannot be found, the function fails with an
570 appropriate error reason.
571 downgrade_script(App, OldVsn, Dir) -> {ok, Script}
573 Types:
575 App = atom()
577 OldVsn = Dir = string()
578 Script = Instructions
579 Tries to find an application downgrade script for App from the
581 current version to a previous version OldVsn located in Dir.
582 The downgrade script can then be evaluated using eval_ap‐
584 pup_script/4. It is recommended to use downgrade_app/2,3 in‐
585 stead, but this function (downgrade_script) is useful to inspect
586 the contents of the script.
587 App is the name of the application, which must be started. Dir
589 is the previous library directory of App. The corresponding mod‐
590 ules and the old .app file are to be located under Dir/ebin. The
591 .appup file is to be located in the ebin directory of the cur‐
592 rent library directory of the application (code:lib_dir(App)).
593 The function looks in the .appup file and tries to find a down‐
595 grade script from the current application version. High-level
596 instructions are translated to low-level instructions. The in‐
597 structions are sorted in the same manner as when generating a
598 relup file.
599 Returns {ok, Script} if successful. For details about Script,
601 see appup(4).
602 Failure: If a script cannot be found, the function fails with an
604 appropriate error reason.
605 eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} |
607 restart_emulator | {error, Reason}
608 Types:
610 App = atom()
612 ToVsn = ToDir = string()
613 Script
614 See upgrade_script/2, downgrade_script/3
615 Unpurged = [Module]
616 Module = atom()
617 Reason = term()
618 Evaluates an application upgrade or downgrade script Script, the
620 result from calling upgrade_script/2 or downgrade_script/3, ex‐
621 actly in the same way as install_release/1,2 does.
622 App is the name of the application, which must be started. ToVsn
624 is the version to be upgraded/downgraded to, and ToDir is the
625 library directory of this version. The corresponding modules as
626 well as the .app and .appup files are to be located under
627 Dir/ebin.
628 Returns one of the following:
630 * {ok, Unpurged} if evaluating the script is successful, where
632 Unpurged is a list of unpurged modules
633 * restart_emulator if this instruction is encountered in the
635 script
636 * {error, Reason} if an error occurred when finding or evalu‐
638 ating the script
639 If the restart_new_emulator instruction is found in the script,
641 eval_appup_script/4 returns {error,restart_new_emulator}. This
642 because restart_new_emulator requires a new version of the emu‐
643 lator to be started before the rest of the upgrade instructions
644 can be executed, and this can only be done by install_re‐
645 lease/1,2.
646
648 {bad_masters, Masters}:
649 The master nodes Masters are not alive.
650 {bad_rel_file, File}:
652 Specified .rel file File cannot be read or does not contain a sin‐
653 gle term.
654 {bad_rel_data, Data}:
656 Specified .rel file does not contain a recognized release specifi‐
657 cation, but another term Data.
658 {bad_relup_file, File}:
660 Specified relup file Relup contains bad data.
661 {cannot_extract_file, Name, Reason}:
663 Problems when extracting from a tar file, erl_tar:extract/2 re‐
664 turned {error, {Name, Reason}}.
665 {existing_release, Vsn}:
667 Specified release version Vsn is already in use.
668 {Master, Reason, When}:
670 Some operation, indicated by the term When, failed on the master
671 node Master with the specified error reason Reason.
672 {no_matching_relup, Vsn, CurrentVsn}:
674 Cannot find a script for upgrading/downgrading between CurrentVsn
675 and Vsn.
676 {no_such_directory, Path}:
678 The directory Pathdoes not exist.
679 {no_such_file, Path}:
681 The path Path (file or directory) does not exist.
682 {no_such_file, {Master, Path}}:
684 The path Path (file or directory) does not exist at the master node
685 Master.
686 {no_such_release, Vsn}:
688 The specified release version Vsn does not exist.
689 {not_a_directory, Path}:
691 Path exists but is not a directory.
692 {Posix, File}:
694 Some file operation failed for File. Posix is an atom named from
695 the Posix error codes, such as enoent, eacces, or eisdir. See
696 file(3) in Kernel.
697 Posix:
699 Some file operation failed, as for the previous item in the list.
700
702 OTP Design Principles, config(4), rel(4), relup(4), script(4), sys(3),
703 systools(3)
704Ericsson AB sasl 4.2 release_handler(3)