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
47 unpacked release can be installed. The currently used version of the
48 release is then upgraded or downgraded to the specified version by
49 evaluating the instructions in the relup file. An installed release can
50 be made permanent. Only one permanent release can exist in the system,
51 and this release is used if the system is restarted. An installed
52 release, except the permanent one, can be removed. When a release is
53 removed, 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
115 information 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
123 installed 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
134 upgrade 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
150 installed. The release must not have status current. Issues
151 warnings if relup file or sys.config is not present. If relup
152 file is present, its contents are checked and {error,Reason} is
153 returned if an error is found. Also checks that all required
154 applications are present and that all new code can be loaded;
155 {error,Reason} is returned if an error is found.
156 Evaluates all instructions that occur before the
158 point_of_no_return 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
166 install_release/1.
167 create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}
169 Types:
171 Root = RelDir = RelFile = string()
173 AppDirs = [{App, Vsn, Dir}]
174 App = atom()
175 Vsn = Dir = string()
176 Reason = term()
177 Creates an initial RELEASES file to be used by the release han‐
179 dler. This file must exist to install new releases.
180 Root is the root of the installation ($ROOT) as described ear‐
182 lier. RelDir is the directory where the RELEASES file is to be
183 created (normally $ROOT/releases). RelFile is the name of the
184 .rel file that describes the initial release, including the
185 extension .rel.
186 AppDirs can be used to specify from where the modules for the
188 specified applications are to be loaded. App is the name of an
189 application, Vsn is the version, and Dir is the name of the
190 directory where App-Vsn is located. The corresponding modules
191 are to be located under Dir/App-Vsn/ebin. The directories for
192 applications not specified in AppDirs are assumed to be located
193 in $ROOT/lib.
194 install_file(Vsn, File) -> ok | {error, Reason}
196 Types:
198 Vsn = File = string()
200 Reason = term()
201 Installs a release-dependent file in the release structure. The
203 release-dependent file must be in the release structure when a
204 new release is installed: start.boot, relup, and sys.config.
205 The function can be called, for example, when these files are
207 generated at the target. The function is to be called after
208 set_unpacked/2 has been called.
209 install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
211 install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {con‐
212 tinue_after_restart, OtherVsn, Descr} | {error, Reason}
213 Types:
215 Vsn = OtherVsn = string()
217 Opt = {error_action, Action} | {code_change_timeout, Timeout}
218 | {suspend_timeout, Timeout} | {update_paths, Bool}
219 Action = restart | reboot
220 Timeout = default | infinity | pos_integer()
221 Bool = boolean()
222 Descr = term()
223 Reason = {illegal_option, Opt} | {already_installed, Vsn} |
224 {change_appl_data, term()} | {missing_base_app, OtherVsn,
225 App} | {could_not_create_hybrid_boot, term()} | term()
226 App = atom()
227 Installs the specified version Vsn of the release. Looks first
229 for a relup file for Vsn and a script {UpFromVsn,Descr1,Instruc‐
230 tions1} in this file for upgrading from the current version. If
231 not found, the function looks for a relup file for the current
232 version and a script {Vsn,Descr2,Instructions2} in this file for
233 downgrading to Vsn.
234 If a script is found, the first thing that happens is that the
236 application specifications are updated according to the .app
237 files and sys.config belonging to the release version Vsn.
238 After the application specifications have been updated, the
240 instructions in the script are evaluated and the function
241 returns {ok,OtherVsn,Descr} if successful. OtherVsn and Descr
242 are the version (UpFromVsn or Vsn) and description (Descr1 or
243 Descr2) as specified in the script.
244 If {continue_after_restart,OtherVsn,Descr} is returned, the emu‐
246 lator is restarted before the upgrade instructions are executed.
247 This occurs if the emulator or any of the applications Kernel,
248 STDLIB, or SASL are updated. The new emulator version and these
249 core applications execute after the restart. For all other
250 applications the old versions are started and the upgrade is
251 performed as normal by executing the upgrade instructions.
252 If a recoverable error occurs, the function returns {error,Rea‐
254 son} and the original application specifications are restored.
255 If a non-recoverable error occurs, the system is restarted.
256 Options:
258 error_action:
260 Defines if the node is to be restarted (init:restart()) or
261 rebooted (init:reboot()) if there is an error during the
262 installation. Default is restart.
263 code_change_timeout:
265 Defines the time-out for all calls to sys:change_code. If no
266 value is specified or default is specified, the default
267 value defined in sys is used.
268 suspend_timeout:
270 Defines the time-out for all calls to sys:suspend. If no
271 value is specified, the values defined by the Timeout param‐
272 eter of the upgrade or suspend instructions are used. If
273 default is specified, the default value defined in sys is
274 used.
275 {update_paths,Bool}:
277 Indicates if all application code paths are to be updated
278 (Bool==true) or if only code paths for modified applications
279 are to be updated (Bool==false, default). This option has
280 only effect for other application directories than the
281 default $ROOT/lib/App-Vsn, that is, application directories
282 specified in argument AppDirs in a call to create_RELEASES/4
283 or set_unpacked/2.
284 Example:
286 In the current version CurVsn of a release, the application
288 directory of myapp is $ROOT/lib/myapp-1.0. A new version
289 NewVsn is unpacked outside the release handler and the
290 release handler is informed about this with a call as fol‐
291 lows:
292 release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
294 => {ok,NewVsn}
295 If NewVsn is installed with option {update_paths,true}, then
297 code:lib_dir(myapp) returns /home/user/myapp-1.0.
298 Note:
300 Installing a new release can be time consuming if there are many
301 processes in the system. The reason is that each process must be
302 checked for references to old code before a module can be
303 purged. This check can lead to garbage collections and copying
304 of data.
305 To speed up the execution of install_release, first call
307 check_install_release, using option purge. This does the same
308 check for old code. Then purges all modules that can be soft-
309 purged. The purged modules do then no longer have any old code,
310 and install_release does not need to do the checks.
311 This does not reduce the overall time for the upgrade, but it
313 allows checks and purge to be executed in the background before
314 the real upgrade is started.
315 Note:
318 When upgrading the emulator from a version older than OTP R15,
319 an attempt is made to load new application beam code into the
320 old emulator. Sometimes the new beam format cannot be read by
321 the old emulator, so the code loading fails and the complete
322 upgrade is terminated. To overcome this problem, the new appli‐
323 cation code is to be compiled with the old emulator. For more
324 information about emulator upgrade from pre OTP R15 versions,
325 see Design Principles in System Documentation.
326 make_permanent(Vsn) -> ok | {error, Reason}
329 Types:
331 Vsn = string()
333 Reason = {bad_status, Status} | term()
334 Makes the specified release version Vsn permanent.
336 remove_release(Vsn) -> ok | {error, Reason}
338 Types:
340 Vsn = string()
342 Reason = {permanent, Vsn} | client_node | term()
343 Removes a release and its files from the system. The release
345 must not be the permanent release. Removes only the files and
346 directories not in use by another release.
347 reboot_old_release(Vsn) -> ok | {error, Reason}
349 Types:
351 Vsn = string()
353 Reason = {bad_status, Status} | term()
354 Reboots the system by making the old release permanent, and
356 calls init:reboot() directly. The release must have status old.
357 set_removed(Vsn) -> ok | {error, Reason}
359 Types:
361 Vsn = string()
363 Reason = {permanent, Vsn} | term()
364 Makes it possible to handle removal of releases outside the
366 release handler. Tells the release handler that the release is
367 removed from the system. This function does not delete any
368 files.
369 set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}
371 Types:
373 RelFile = string()
375 AppDirs = [{App, Vsn, Dir}]
376 App = atom()
377 Vsn = Dir = string()
378 Reason = term()
379 Makes it possible to handle unpacking of releases outside the
381 release handler. Tells the release handler that the release is
382 unpacked. Vsn is extracted from the release resource file
383 RelFile.
384 AppDirs can be used to specify from where the modules for the
386 specified applications are to be loaded. App is the name of an
387 application, Vsn is the version, and Dir is the name of the
388 directory where App-Vsn is located. The corresponding modules
389 are to be located under Dir/App-Vsn/ebin. The directories for
390 applications not specified in AppDirs are assumed to be located
391 in $ROOT/lib.
392 unpack_release(Name) -> {ok, Vsn} | {error, Reason}
394 Types:
396 Name = Vsn = string()
398 Reason = client_node | term()
399 Unpacks a release package Name.tar.gz located in the releases
401 directory.
402 Performs some checks on the package, for example, checks that
404 all mandatory files are present, and extracts its contents.
405 which_releases() -> [{Name, Vsn, Apps, Status}]
407 Types:
409 Name = Vsn = string()
411 Apps = ["App-Vsn"]
412 Status = unpacked | current | permanent | old
413 Returns all releases known to the release handler.
415 which_releases(Status) -> [{Name, Vsn, Apps, Status}]
417 Types:
419 Name = Vsn = string()
421 Apps = ["App-Vsn"]
422 Status = unpacked | current | permanent | old
423 Returns all releases, known to the release handler, of a spe‐
425 cific status.
426
428 The following functions can be used to test upgrade and downgrade of
429 single applications (instead of upgrading/downgrading an entire
430 release). A script corresponding to the instructions in the relup file
431 is created on-the-fly, based on the .appup file for the application,
432 and evaluated exactly in the same way as release_handler does.
433 Warning:
435 These functions are primarily intended for simplified testing of .appup
436 files. They are not run within the context of the release_handler
437 process. They must therefore not be used together with calls to
438 install_release/1,2, as this causes the release_handler to end up in an
439 inconsistent state.
440 No persistent information is updated, so these functions can be used on
442 any Erlang node, embedded or not. Also, using these functions does not
443 affect which code is loaded if there is a reboot.
444 If the upgrade or downgrade fails, the application can end up in an
446 inconsistent state.
447
450 upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error,
451 Reason}
452 Types:
454 App = atom()
456 Dir = string()
457 Unpurged = [Module]
458 Module = atom()
459 Reason = term()
460 Upgrades an application App from the current version to a new
462 version located in Dir according to the .appup file.
463 App is the name of the application, which must be started. Dir
465 is the new library directory of App. The corresponding modules
466 as well as the .app and .appup files are to be located under
467 Dir/ebin.
468 The function looks in the .appup file and tries to find an
470 upgrade script from the current version of the application using
471 upgrade_script/2. This script is evaluated using
472 eval_appup_script/4, exactly in the same way as
473 install_release/1,2 does.
474 Returns one of the following:
476 * {ok, Unpurged} if evaluating the script is successful, where
478 Unpurged is a list of unpurged modules
479 * restart_emulator if this instruction is encountered in the
481 script
482 * {error, Reason} if an error occurred when finding or evalu‐
484 ating the script
485 If the restart_new_emulator instruction is found in the script,
487 upgrade_app/2 returns {error,restart_new_emulator}. This because
488 restart_new_emulator requires a new version of the emulator to
489 be started before the rest of the upgrade instructions can be
490 executed, and this can only be done by install_release/1,2.
491 downgrade_app(App, Dir) ->
493 downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator |
494 {error, Reason}
495 Types:
497 App = atom()
499 Dir = OldVsn = string()
500 Unpurged = [Module]
501 Module = atom()
502 Reason = term()
503 Downgrades an application App from the current version to a pre‐
505 vious version OldVsn located in Dir according to the .appup
506 file.
507 App is the name of the application, which must be started. Old‐
509 Vsn is the previous application version and can be omitted if
510 Dir is of the format "App-OldVsn". Dir is the library directory
511 of the previous version of App. The corresponding modules and
512 the old .app file are to be located under Dir/ebin. The .appup
513 file is to be located in the ebin directory of the current
514 library directory of the application (code:lib_dir(App)).
515 The function looks in the .appup file and tries to find a down‐
517 grade script to the previous version of the application using
518 downgrade_script/3. This script is evaluated using
519 eval_appup_script/4, exactly in the same way as
520 install_release/1,2 does.
521 Returns one of the following:
523 * {ok, Unpurged} if evaluating the script is successful, where
525 Unpurged is a list of unpurged modules
526 * restart_emulator if this instruction is encountered in the
528 script
529 * {error, Reason} if an error occurred when finding or evalu‐
531 ating the script
532 upgrade_script(App, Dir) -> {ok, NewVsn, Script}
534 Types:
536 App = atom()
538 Dir = string()
539 NewVsn = string()
540 Script = Instructions
541 Tries to find an application upgrade script for App from the
543 current version to a new version located in Dir.
544 The upgrade script can then be evaluated using
546 eval_appup_script/4. It is recommended to use upgrade_app/2
547 instead, but this function (upgrade_script) is useful to inspect
548 the contents of the script.
549 App is the name of the application, which must be started. Dir
551 is the new library directory of App. The corresponding modules
552 as well as the .app and .appup files are to be located under
553 Dir/ebin.
554 The function looks in the .appup file and tries to find an
556 upgrade script from the current application version. High-level
557 instructions are translated to low-level instructions. The
558 instructions are sorted in the same manner as when generating a
559 relup file.
560 Returns {ok, NewVsn, Script} if successful, where NewVsn is the
562 new application version. For details about Script, see appup(4).
563 Failure: If a script cannot be found, the function fails with an
565 appropriate error reason.
566 downgrade_script(App, OldVsn, Dir) -> {ok, Script}
568 Types:
570 App = atom()
572 OldVsn = Dir = string()
573 Script = Instructions
574 Tries to find an application downgrade script for App from the
576 current version to a previous version OldVsn located in Dir.
577 The downgrade script can then be evaluated using
579 eval_appup_script/4. It is recommended to use downgrade_app/2,3
580 instead, but this function (downgrade_script) is useful to
581 inspect the contents of the script.
582 App is the name of the application, which must be started. Dir
584 is the previous library directory of App. The corresponding mod‐
585 ules and the old .app file are to be located under Dir/ebin. The
586 .appup file is to be located in the ebin directory of the cur‐
587 rent library directory of the application (code:lib_dir(App)).
588 The function looks in the .appup file and tries to find a down‐
590 grade script from the current application version. High-level
591 instructions are translated to low-level instructions. The
592 instructions are sorted in the same manner as when generating a
593 relup file.
594 Returns {ok, Script} if successful. For details about Script,
596 see appup(4).
597 Failure: If a script cannot be found, the function fails with an
599 appropriate error reason.
600 eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} |
602 restart_emulator | {error, Reason}
603 Types:
605 App = atom()
607 ToVsn = ToDir = string()
608 Script
609 See upgrade_script/2, downgrade_script/3
610 Unpurged = [Module]
611 Module = atom()
612 Reason = term()
613 Evaluates an application upgrade or downgrade script Script, the
615 result from calling upgrade_script/2 or downgrade_script/3,
616 exactly in the same way as install_release/1,2 does.
617 App is the name of the application, which must be started. ToVsn
619 is the version to be upgraded/downgraded to, and ToDir is the
620 library directory of this version. The corresponding modules as
621 well as the .app and .appup files are to be located under
622 Dir/ebin.
623 Returns one of the following:
625 * {ok, Unpurged} if evaluating the script is successful, where
627 Unpurged is a list of unpurged modules
628 * restart_emulator if this instruction is encountered in the
630 script
631 * {error, Reason} if an error occurred when finding or evalu‐
633 ating the script
634 If the restart_new_emulator instruction is found in the script,
636 eval_appup_script/4 returns {error,restart_new_emulator}. This
637 because restart_new_emulator requires a new version of the emu‐
638 lator to be started before the rest of the upgrade instructions
639 can be executed, and this can only be done by
640 install_release/1,2.
641
643 {bad_masters, Masters}:
644 The master nodes Masters are not alive.
645 {bad_rel_file, File}:
647 Specified .rel file File cannot be read or does not contain a sin‐
648 gle term.
649 {bad_rel_data, Data}:
651 Specified .rel file does not contain a recognized release specifi‐
652 cation, but another term Data.
653 {bad_relup_file, File}:
655 Specified relup file Relup contains bad data.
656 {cannot_extract_file, Name, Reason}:
658 Problems when extracting from a tar file, erl_tar:extract/2
659 returned {error, {Name, Reason}}.
660 {existing_release, Vsn}:
662 Specified release version Vsn is already in use.
663 {Master, Reason, When}:
665 Some operation, indicated by the term When, failed on the master
666 node Master with the specified error reason Reason.
667 {no_matching_relup, Vsn, CurrentVsn}:
669 Cannot find a script for upgrading/downgrading between CurrentVsn
670 and Vsn.
671 {no_such_directory, Path}:
673 The directory Pathdoes not exist.
674 {no_such_file, Path}:
676 The path Path (file or directory) does not exist.
677 {no_such_file, {Master, Path}}:
679 The path Path (file or directory) does not exist at the master node
680 Master.
681 {no_such_release, Vsn}:
683 The specified release version Vsn does not exist.
684 {not_a_directory, Path}:
686 Path exists but is not a directory.
687 {Posix, File}:
689 Some file operation failed for File. Posix is an atom named from
690 the Posix error codes, such as enoent, eacces, or eisdir. See
691 file(3) in Kernel.
692 Posix:
694 Some file operation failed, as for the previous item in the list.
695
697 OTP Design Principles, config(4), rel(4), relup(4), script(4), sys(3),
698 systools(3)
699Ericsson AB sasl 3.3 release_handler(3)