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(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 ex‐
185 tension .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 di‐
190 rectory where App-Vsn is located. The corresponding modules are
191 to be located under Dir/App-Vsn/ebin. The directories for appli‐
192 cations not specified in AppDirs are assumed to be located in
193 $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} | {continue_af‐
212 ter_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 in‐
240 structions in the script are evaluated and the function returns
241 {ok,OtherVsn,Descr} if successful. OtherVsn and Descr are the
242 version (UpFromVsn or Vsn) and description (Descr1 or Descr2) as
243 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 ap‐
250 plications the old versions are started and the upgrade is per‐
251 formed 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 in‐
262 stallation. 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 de‐
273 fault 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 de‐
281 fault $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 re‐
290 lease handler is informed about this with a call as follows:
291 release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
293 => {ok,NewVsn}
294 If NewVsn is installed with option {update_paths,true}, then
296 code:lib_dir(myapp) returns /home/user/myapp-1.0.
297 Note:
299 Installing a new release can be time consuming if there are many
300 processes in the system. The reason is that each process must be
301 checked for references to old code before a module can be
302 purged. This check can lead to garbage collections and copying
303 of data.
304 To speed up the execution of install_release, first call
306 check_install_release, using option purge. This does the same
307 check for old code. Then purges all modules that can be soft-
308 purged. The purged modules do then no longer have any old code,
309 and install_release does not need to do the checks.
310 This does not reduce the overall time for the upgrade, but it
312 allows checks and purge to be executed in the background before
313 the real upgrade is started.
314 Note:
317 When upgrading the emulator from a version older than OTP R15,
318 an attempt is made to load new application beam code into the
319 old emulator. Sometimes the new beam format cannot be read by
320 the old emulator, so the code loading fails and the complete up‐
321 grade is terminated. To overcome this problem, the new applica‐
322 tion code is to be compiled with the old emulator. For more in‐
323 formation about emulator upgrade from pre OTP R15 versions, see
324 Design Principles in System Documentation.
325 make_permanent(Vsn) -> ok | {error, Reason}
328 Types:
330 Vsn = string()
332 Reason = {bad_status, Status} | term()
333 Makes the specified release version Vsn permanent.
335 remove_release(Vsn) -> ok | {error, Reason}
337 Types:
339 Vsn = string()
341 Reason = {permanent, Vsn} | client_node | term()
342 Removes a release and its files from the system. The release
344 must not be the permanent release. Removes only the files and
345 directories not in use by another release.
346 reboot_old_release(Vsn) -> ok | {error, Reason}
348 Types:
350 Vsn = string()
352 Reason = {bad_status, Status} | term()
353 Reboots the system by making the old release permanent, and
355 calls init:reboot() directly. The release must have status old.
356 set_removed(Vsn) -> ok | {error, Reason}
358 Types:
360 Vsn = string()
362 Reason = {permanent, Vsn} | term()
363 Makes it possible to handle removal of releases outside the re‐
365 lease handler. Tells the release handler that the release is re‐
366 moved from the system. This function does not delete any 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 di‐
386 rectory where App-Vsn is located. The corresponding modules are
387 to be located under Dir/App-Vsn/ebin. The directories for appli‐
388 cations not specified in AppDirs are assumed to be located in
389 $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 re‐
428 lease). A script corresponding to the instructions in the relup file is
429 created on-the-fly, based on the .appup file for the application, and
430 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 in‐
436 stall_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 in‐
444 consistent 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 up‐
468 grade script from the current version of the application using
469 upgrade_script/2. This script is evaluated using eval_ap‐
470 pup_script/4, exactly in the same way as install_release/1,2
471 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 li‐
512 brary 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 eval_ap‐
517 pup_script/4, exactly in the same way as install_release/1,2
518 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 eval_ap‐
544 pup_script/4. It is recommended to use upgrade_app/2 instead,
545 but this function (upgrade_script) is useful to inspect the con‐
546 tents 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 up‐
554 grade script from the current application version. High-level
555 instructions are translated to low-level instructions. The in‐
556 structions 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 eval_ap‐
577 pup_script/4. It is recommended to use downgrade_app/2,3 in‐
578 stead, but this function (downgrade_script) is useful to inspect
579 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 in‐
590 structions 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, ex‐
614 actly 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 install_re‐
638 lease/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 re‐
657 turned {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 4.1 release_handler(3)