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 The relup file contains instructions for how to upgrade to, or down‐
42 grade from, this version of the release.
43 The release package can be unpacked, which extracts the files. An
45 unpacked release can be installed. The currently used version of the
46 release is then upgraded or downgraded to the specified version by
47 evaluating the instructions in the relup file. An installed release can
48 be made permanent. Only one permanent release can exist in the system,
49 and this release is used if the system is restarted. An installed
50 release, except the permanent one, can be removed. When a release is
51 removed, all files belonging to that release only are deleted.
52 Each release version has a status, which can be unpacked, current, per‐
54 manent, or old. There is always one latest release, which either has
55 status permanent (normal case) or current (installed, but not yet made
56 permanent). The meaning of the status values are illustrated in the
57 following table:
58 Status Action NextStatus
60 -------------------------------------------
61 - unpack unpacked
62 unpacked install current
63 remove -
64 current make_permanent permanent
65 install other old
66 remove -
67 permanent make other permanent old
68 install permanent
69 old reboot_old permanent
70 install current
71 remove -
72 The release handler process is a locally registered process on each
74 node. When a release is installed in a distributed system, the release
75 handler on each node must be called. The release installation can be
76 synchronized between nodes. From an operator view, it can be unsatis‐
77 factory to specify each node. The aim is to install one release package
78 in the system, no matter how many nodes there are. It is recommended
79 that software management functions are written that take care of this
80 problem. Such a function can have knowledge of the system architecture,
81 so it can contact each individual release handler to install the pack‐
82 age.
83 For release handling to work properly, the runtime system must know
85 which release it is running. It must also be able to change (in run‐
86 time) which boot script and system configuration file are to be used if
87 the system is restarted. This is taken care of automatically if Erlang
88 is started as an embedded system. Read about this in Embedded System in
89 System Documentation. In this case, the system configuration file
90 sys.config is mandatory.
91 The installation of a new release can restart the system. Which program
93 to use is specified by the SASL configuration parameter start_prg,
94 which defaults to $ROOT/bin/start.
95 The emulator restart on Windows NT expects that the system is started
97 using the erlsrv program (as a service). Furthermore, the release han‐
98 dler expects that the service is named NodeName_Release, where NodeName
99 is the first part of the Erlang node name (up to, but not including the
100 "@") and Release is the current release version. The release handler
101 furthermore expects that a program like start_erl.exe is specified as
102 "machine" to erlsrv. During upgrading with restart, a new service is
103 registered and started. The new service is set to automatic and the old
104 service is removed when the new release is made permanent.
105 The release handler at a node running on a diskless machine, or with a
107 read-only file system, must be configured accordingly using the follow‐
108 ing SASL configuration parameters (for details, see sasl(6)):
109 masters:
111 This node uses some master nodes to store and fetch release infor‐
112 mation. All master nodes must be operational whenever release
113 information is written by this node.
114 client_directory:
116 The client_directory in the directory structure of the master nodes
117 must be specified.
118 static_emulator:
120 This parameter specifies if the Erlang emulator is statically
121 installed at the client node. A node with a static emulator cannot
122 dynamically switch to a new emulator, as the executable files are
123 statically written into memory.
124 The release handler can also be used to unpack and install release
126 packages when not running Erlang as an embedded system. However, in
127 this case the user must somehow ensure that correct boot scripts and
128 configuration files are used if the system must be restarted.
129 Functions are provided for using another file structure than the struc‐
131 ture defined in OTP. These functions can be used to test a release
132 upgrade locally.
133
135 check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
136 check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Rea‐
137 son}
138 Types:
140 Vsn = OtherVsn = string()
142 Opts = [Opt]
143 Opt = purge
144 Descr = term()
145 Reason = term()
146 Checks if the specified version Vsn of the release can be
148 installed. The release must not have status current. Issues
149 warnings if relup file or sys.config is not present. If relup
150 file is present, its contents are checked and {error,Reason} is
151 returned if an error is found. Also checks that all required
152 applications are present and that all new code can be loaded;
153 {error,Reason} is returned if an error is found.
154 Evaluates all instructions that occur before the
156 point_of_no_return instruction in the release upgrade script.
157 Returns the same as install_release/1. Descr defaults to "" if
159 no relup file is found.
160 If option purge is specified, all old code that can be soft-
162 purged is purged after all other checks are successfully com‐
163 pleted. This can be useful to reduce the time needed by
164 install_release/1.
165 create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}
167 Types:
169 Root = RelDir = RelFile = string()
171 AppDirs = [{App, Vsn, Dir}]
172 App = atom()
173 Vsn = Dir = string()
174 Reason = term()
175 Creates an initial RELEASES file to be used by the release han‐
177 dler. This file must exist to install new releases.
178 Root is the root of the installation ($ROOT) as described ear‐
180 lier. RelDir is the directory where the RELEASES file is to be
181 created (normally $ROOT/releases). RelFile is the name of the
182 .rel file that describes the initial release, including the
183 extension .rel.
184 AppDirs can be used to specify from where the modules for the
186 specified applications are to be loaded. App is the name of an
187 application, Vsn is the version, and Dir is the name of the
188 directory where App-Vsn is located. The corresponding modules
189 are to be located under Dir/App-Vsn/ebin. The directories for
190 applications not specified in AppDirs are assumed to be located
191 in $ROOT/lib.
192 install_file(Vsn, File) -> ok | {error, Reason}
194 Types:
196 Vsn = File = string()
198 Reason = term()
199 Installs a release-dependent file in the release structure. The
201 release-dependent file must be in the release structure when a
202 new release is installed: start.boot, relup, and sys.config.
203 The function can be called, for example, when these files are
205 generated at the target. The function is to be called after
206 set_unpacked/2 has been called.
207 install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
209 install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {con‐
210 tinue_after_restart, OtherVsn, Descr} | {error, Reason}
211 Types:
213 Vsn = OtherVsn = string()
215 Opt = {error_action, Action} | {code_change_timeout, Timeout}
216 | {suspend_timeout, Timeout} | {update_paths, Bool}
217 Action = restart | reboot
218 Timeout = default | infinity | pos_integer()
219 Bool = boolean()
220 Descr = term()
221 Reason = {illegal_option, Opt} | {already_installed, Vsn} |
222 {change_appl_data, term()} | {missing_base_app, OtherVsn,
223 App} | {could_not_create_hybrid_boot, term()} | term()
224 App = atom()
225 Installs the specified version Vsn of the release. Looks first
227 for a relup file for Vsn and a script {UpFromVsn,Descr1,Instruc‐
228 tions1} in this file for upgrading from the current version. If
229 not found, the function looks for a relup file for the current
230 version and a script {Vsn,Descr2,Instructions2} in this file for
231 downgrading to Vsn.
232 If a script is found, the first thing that happens is that the
234 application specifications are updated according to the .app
235 files and sys.config belonging to the release version Vsn.
236 After the application specifications have been updated, the
238 instructions in the script are evaluated and the function
239 returns {ok,OtherVsn,Descr} if successful. OtherVsn and Descr
240 are the version (UpFromVsn or Vsn) and description (Descr1 or
241 Descr2) as specified in the script.
242 If {continue_after_restart,OtherVsn,Descr} is returned, the emu‐
244 lator is restarted before the upgrade instructions are executed.
245 This occurs if the emulator or any of the applications Kernel,
246 STDLIB, or SASL are updated. The new emulator version and these
247 core applications execute after the restart. For all other
248 applications the old versions are started and the upgrade is
249 performed as normal by executing the upgrade instructions.
250 If a recoverable error occurs, the function returns {error,Rea‐
252 son} and the original application specifications are restored.
253 If a non-recoverable error occurs, the system is restarted.
254 Options:
256 error_action:
258 Defines if the node is to be restarted (init:restart()) or
259 rebooted (init:reboot()) if there is an error during the
260 installation. Default is restart.
261 code_change_timeout:
263 Defines the time-out for all calls to sys:change_code. If no
264 value is specified or default is specified, the default
265 value defined in sys is used.
266 suspend_timeout:
268 Defines the time-out for all calls to sys:suspend. If no
269 value is specified, the values defined by the Timeout param‐
270 eter of the upgrade or suspend instructions are used. If
271 default is specified, the default value defined in sys is
272 used.
273 {update_paths,Bool}:
275 Indicates if all application code paths are to be updated
276 (Bool==true) or if only code paths for modified applications
277 are to be updated (Bool==false, default). This option has
278 only effect for other application directories than the
279 default $ROOT/lib/App-Vsn, that is, application directories
280 specified in argument AppDirs in a call to create_RELEASES/4
281 or set_unpacked/2.
282 Example:
284 In the current version CurVsn of a release, the application
286 directory of myapp is $ROOT/lib/myapp-1.0. A new version
287 NewVsn is unpacked outside the release handler and the
288 release handler is informed about this with a call as fol‐
289 lows:
290 release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
292 => {ok,NewVsn}
293 If NewVsn is installed with option {update_paths,true}, then
295 code:lib_dir(myapp) returns /home/user/myapp-1.0.
296 Note:
298 Installing a new release can be time consuming if there are many
299 processes in the system. The reason is that each process must be
300 checked for references to old code before a module can be
301 purged. This check can lead to garbage collections and copying
302 of data.
303 To speed up the execution of install_release, first call
305 check_install_release, using option purge. This does the same
306 check for old code. Then purges all modules that can be soft-
307 purged. The purged modules do then no longer have any old code,
308 and install_release does not need to do the checks.
309 This does not reduce the overall time for the upgrade, but it
311 allows checks and purge to be executed in the background before
312 the real upgrade is started.
313 Note:
316 When upgrading the emulator from a version older than OTP R15,
317 an attempt is made to load new application beam code into the
318 old emulator. Sometimes the new beam format cannot be read by
319 the old emulator, so the code loading fails and the complete
320 upgrade is terminated. To overcome this problem, the new appli‐
321 cation code is to be compiled with the old emulator. For more
322 information about emulator upgrade from pre OTP R15 versions,
323 see Design Principles in System Documentation.
324 make_permanent(Vsn) -> ok | {error, Reason}
327 Types:
329 Vsn = string()
331 Reason = {bad_status, Status} | term()
332 Makes the specified release version Vsn permanent.
334 remove_release(Vsn) -> ok | {error, Reason}
336 Types:
338 Vsn = string()
340 Reason = {permanent, Vsn} | client_node | term()
341 Removes a release and its files from the system. The release
343 must not be the permanent release. Removes only the files and
344 directories not in use by another release.
345 reboot_old_release(Vsn) -> ok | {error, Reason}
347 Types:
349 Vsn = string()
351 Reason = {bad_status, Status} | term()
352 Reboots the system by making the old release permanent, and
354 calls init:reboot() directly. The release must have status old.
355 set_removed(Vsn) -> ok | {error, Reason}
357 Types:
359 Vsn = string()
361 Reason = {permanent, Vsn} | term()
362 Makes it possible to handle removal of releases outside the
364 release handler. Tells the release handler that the release is
365 removed from the system. This function does not delete any
366 files.
367 set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}
369 Types:
371 RelFile = string()
373 AppDirs = [{App, Vsn, Dir}]
374 App = atom()
375 Vsn = Dir = string()
376 Reason = term()
377 Makes it possible to handle unpacking of releases outside the
379 release handler. Tells the release handler that the release is
380 unpacked. Vsn is extracted from the release resource file
381 RelFile.
382 AppDirs can be used to specify from where the modules for the
384 specified applications are to be loaded. App is the name of an
385 application, Vsn is the version, and Dir is the name of the
386 directory where App-Vsn is located. The corresponding modules
387 are to be located under Dir/App-Vsn/ebin. The directories for
388 applications not specified in AppDirs are assumed to be located
389 in $ROOT/lib.
390 unpack_release(Name) -> {ok, Vsn} | {error, Reason}
392 Types:
394 Name = Vsn = string()
396 Reason = client_node | term()
397 Unpacks a release package Name.tar.gz located in the releases
399 directory.
400 Performs some checks on the package, for example, checks that
402 all mandatory files are present, and extracts its contents.
403 which_releases() -> [{Name, Vsn, Apps, Status}]
405 Types:
407 Name = Vsn = string()
409 Apps = ["App-Vsn"]
410 Status = unpacked | current | permanent | old
411 Returns all releases known to the release handler.
413 which_releases(Status) -> [{Name, Vsn, Apps, Status}]
415 Types:
417 Name = Vsn = string()
419 Apps = ["App-Vsn"]
420 Status = unpacked | current | permanent | old
421 Returns all releases, known to the release handler, of a spe‐
423 cific status.
424
426 The following functions can be used to test upgrade and downgrade of
427 single applications (instead of upgrading/downgrading an entire
428 release). A script corresponding to the instructions in the relup file
429 is created on-the-fly, based on the .appup file for the application,
430 and evaluated exactly in the same way as release_handler does.
431 Warning:
433 These functions are primarily intended for simplified testing of .appup
434 files. They are not run within the context of the release_handler
435 process. They must therefore not be used together with calls to
436 install_release/1,2, as this causes the release_handler to end up in an
437 inconsistent state.
438 No persistent information is updated, so these functions can be used on
440 any Erlang node, embedded or not. Also, using these functions does not
441 affect which code is loaded if there is a reboot.
442 If the upgrade or downgrade fails, the application can end up in an
444 inconsistent state.
445
448 upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error,
449 Reason}
450 Types:
452 App = atom()
454 Dir = string()
455 Unpurged = [Module]
456 Module = atom()
457 Reason = term()
458 Upgrades an application App from the current version to a new
460 version located in Dir according to the .appup file.
461 App is the name of the application, which must be started. Dir
463 is the new library directory of App. The corresponding modules
464 as well as the .app and .appup files are to be located under
465 Dir/ebin.
466 The function looks in the .appup file and tries to find an
468 upgrade script from the current version of the application using
469 upgrade_script/2. This script is evaluated using
470 eval_appup_script/4, exactly in the same way as
471 install_release/1,2 does.
472 Returns one of the following:
474 * {ok, Unpurged} if evaluating the script is successful, where
476 Unpurged is a list of unpurged modules
477 * restart_emulator if this instruction is encountered in the
479 script
480 * {error, Reason} if an error occurred when finding or evalu‐
482 ating the script
483 If the restart_new_emulator instruction is found in the script,
485 upgrade_app/2 returns {error,restart_new_emulator}. This because
486 restart_new_emulator requires a new version of the emulator to
487 be started before the rest of the upgrade instructions can be
488 executed, and this can only be done by install_release/1,2.
489 downgrade_app(App, Dir) ->
491 downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator |
492 {error, Reason}
493 Types:
495 App = atom()
497 Dir = OldVsn = string()
498 Unpurged = [Module]
499 Module = atom()
500 Reason = term()
501 Downgrades an application App from the current version to a pre‐
503 vious version OldVsn located in Dir according to the .appup
504 file.
505 App is the name of the application, which must be started. Old‐
507 Vsn is the previous application version and can be omitted if
508 Dir is of the format "App-OldVsn". Dir is the library directory
509 of the previous version of App. The corresponding modules and
510 the old .app file are to be located under Dir/ebin. The .appup
511 file is to be located in the ebin directory of the current
512 library directory of the application (code:lib_dir(App)).
513 The function looks in the .appup file and tries to find a down‐
515 grade script to the previous version of the application using
516 downgrade_script/3. This script is evaluated using
517 eval_appup_script/4, exactly in the same way as
518 install_release/1,2 does.
519 Returns one of the following:
521 * {ok, Unpurged} if evaluating the script is successful, where
523 Unpurged is a list of unpurged modules
524 * restart_emulator if this instruction is encountered in the
526 script
527 * {error, Reason} if an error occurred when finding or evalu‐
529 ating the script
530 upgrade_script(App, Dir) -> {ok, NewVsn, Script}
532 Types:
534 App = atom()
536 Dir = string()
537 NewVsn = string()
538 Script = Instructions
539 Tries to find an application upgrade script for App from the
541 current version to a new version located in Dir.
542 The upgrade script can then be evaluated using
544 eval_appup_script/4. It is recommended to use upgrade_app/2
545 instead, but this function (upgrade_script) is useful to inspect
546 the contents of the script.
547 App is the name of the application, which must be started. Dir
549 is the new library directory of App. The corresponding modules
550 as well as the .app and .appup files are to be located under
551 Dir/ebin.
552 The function looks in the .appup file and tries to find an
554 upgrade script from the current application version. High-level
555 instructions are translated to low-level instructions. The
556 instructions are sorted in the same manner as when generating a
557 relup file.
558 Returns {ok, NewVsn, Script} if successful, where NewVsn is the
560 new application version. For details about Script, see appup(4).
561 Failure: If a script cannot be found, the function fails with an
563 appropriate error reason.
564 downgrade_script(App, OldVsn, Dir) -> {ok, Script}
566 Types:
568 App = atom()
570 OldVsn = Dir = string()
571 Script = Instructions
572 Tries to find an application downgrade script for App from the
574 current version to a previous version OldVsn located in Dir.
575 The downgrade script can then be evaluated using
577 eval_appup_script/4. It is recommended to use downgrade_app/2,3
578 instead, but this function (downgrade_script) is useful to
579 inspect the contents of the script.
580 App is the name of the application, which must be started. Dir
582 is the previous library directory of App. The corresponding mod‐
583 ules and the old .app file are to be located under Dir/ebin. The
584 .appup file is to be located in the ebin directory of the cur‐
585 rent library directory of the application (code:lib_dir(App)).
586 The function looks in the .appup file and tries to find a down‐
588 grade script from the current application version. High-level
589 instructions are translated to low-level instructions. The
590 instructions are sorted in the same manner as when generating a
591 relup file.
592 Returns {ok, Script} if successful. For details about Script,
594 see appup(4).
595 Failure: If a script cannot be found, the function fails with an
597 appropriate error reason.
598 eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} |
600 restart_emulator | {error, Reason}
601 Types:
603 App = atom()
605 ToVsn = ToDir = string()
606 Script
607 See upgrade_script/2, downgrade_script/3
608 Unpurged = [Module]
609 Module = atom()
610 Reason = term()
611 Evaluates an application upgrade or downgrade script Script, the
613 result from calling upgrade_script/2 or downgrade_script/3,
614 exactly in the same way as install_release/1,2 does.
615 App is the name of the application, which must be started. ToVsn
617 is the version to be upgraded/downgraded to, and ToDir is the
618 library directory of this version. The corresponding modules as
619 well as the .app and .appup files are to be located under
620 Dir/ebin.
621 Returns one of the following:
623 * {ok, Unpurged} if evaluating the script is successful, where
625 Unpurged is a list of unpurged modules
626 * restart_emulator if this instruction is encountered in the
628 script
629 * {error, Reason} if an error occurred when finding or evalu‐
631 ating the script
632 If the restart_new_emulator instruction is found in the script,
634 eval_appup_script/4 returns {error,restart_new_emulator}. This
635 because restart_new_emulator requires a new version of the emu‐
636 lator to be started before the rest of the upgrade instructions
637 can be executed, and this can only be done by
638 install_release/1,2.
639
641 {bad_masters, Masters}:
642 The master nodes Masters are not alive.
643 {bad_rel_file, File}:
645 Specified .rel file File cannot be read or does not contain a sin‐
646 gle term.
647 {bad_rel_data, Data}:
649 Specified .rel file does not contain a recognized release specifi‐
650 cation, but another term Data.
651 {bad_relup_file, File}:
653 Specified relup file Relup contains bad data.
654 {cannot_extract_file, Name, Reason}:
656 Problems when extracting from a tar file, erl_tar:extract/2
657 returned {error, {Name, Reason}}.
658 {existing_release, Vsn}:
660 Specified release version Vsn is already in use.
661 {Master, Reason, When}:
663 Some operation, indicated by the term When, failed on the master
664 node Master with the specified error reason Reason.
665 {no_matching_relup, Vsn, CurrentVsn}:
667 Cannot find a script for upgrading/downgrading between CurrentVsn
668 and Vsn.
669 {no_such_directory, Path}:
671 The directory Pathdoes not exist.
672 {no_such_file, Path}:
674 The path Path (file or directory) does not exist.
675 {no_such_file, {Master, Path}}:
677 The path Path (file or directory) does not exist at the master node
678 Master.
679 {no_such_release, Vsn}:
681 The specified release version Vsn does not exist.
682 {not_a_directory, Path}:
684 Path exists but is not a directory.
685 {Posix, File}:
687 Some file operation failed for File. Posix is an atom named from
688 the Posix error codes, such as enoent, eacces, or eisdir. See
689 file(3) in Kernel.
690 Posix:
692 Some file operation failed, as for the previous item in the list.
693
695 OTP Design Principles, config(4), rel(4), relup(4), script(4), sys(3),
696 systools(3)
697Ericsson AB sasl 3.1.2 release_handler(3)