aboutsummaryrefslogtreecommitdiffstats
path: root/lib/sasl/doc/src/release_handler.xml
blob: 975188f4896f1fd071df071dff9104bf7d7081f0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>release_handler</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module>release_handler</module>
  <modulesummary>Unpacking and Installation of Release Packages</modulesummary>
  <description>
    <p>The <em>release handler</em> process belongs to the SASL
      application, which is responsible for <em>release handling</em>,
      that is, unpacking, installation, and removal of release packages.</p>
    <p>An introduction to release handling and an example is provided in
      <seealso marker="doc/design_principles:release_handling">OTP Design
      Principles</seealso> in <em>System Documentation</em>.</p>
    <p>A <em>release package</em> is a compressed tar file containing
      code for a certain version of a release, created by calling
      <seealso marker="systools#make_tar/1"><c>systools:make_tar/1,2</c></seealso>.
      The release package is to be located in the <c>$ROOT/releases</c>
      directory of the previous version of the release, where
      <c>$ROOT</c> is the installation root directory,
      <seealso marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seealso>.
      Another <c>releases</c> directory can be specified using the SASL
      configuration parameter <c>releases_dir</c> or the OS environment
      variable <c>RELDIR</c>. The release handler must have write access
      to this directory to install the new release.
      The persistent state of the release handler is stored there in a
      file called <c>RELEASES</c>.</p>
    <p>A release package is always to contain:</p>
    <list type="bulleted">
      <item>A release resource file, <c>Name.rel</c></item>
      <item>A boot script, <c>Name.boot</c></item>
    </list>
    <p>The <c>.rel</c> file contains information about the release: its name,
      version, and which ERTS and application versions it uses.</p>
    <p>A release package can also contain:</p>
    <list type="bulleted">
      <item>A release upgrade file, <c>relup</c></item>
      <item>A system configuration file, <c>sys.config</c></item>
      <item>A system configuration source file, <c>sys.config.src</c></item>
    </list>
    <p>The <c>relup</c> file contains instructions for how to upgrade
      to, or downgrade from, this version of the release.</p>
    <p>The release package can be <em>unpacked</em>, which extracts
      the files. An unpacked release can be <em>installed</em>.
      The currently used version of the release is then upgraded or
      downgraded to the specified version by evaluating the instructions
      in the <c>relup</c> file. An installed release can be made
      <em>permanent</em>. Only one permanent release can exist in
      the system, and this release is used if the system
      is restarted. An installed release, except the permanent one,
      can be <em>removed</em>. When a release is removed, all files
      belonging to that release only are deleted.</p>
    <p>Each release version has a status, which can be
      <c>unpacked</c>, <c>current</c>, <c>permanent</c>, or <c>old</c>.
      There is always one latest release, which either has status
      <c>permanent</c> (normal case) or <c>current</c> (installed, but
      not yet made permanent). The meaning of the status values are
      illustrated in the following table:</p>
    <pre>
        Status     Action                NextStatus
        -------------------------------------------
        -          unpack                unpacked
        unpacked   install               current
                   remove                -
        current    make_permanent        permanent
                   install other         old
                   remove                -
        permanent  make other permanent  old
                   install               permanent
        old        reboot_old            permanent
                   install               current
                   remove                -</pre>
    <p>The release handler process is a locally registered process on
      each node. When a release is installed in a distributed system,
      the release handler on each node must be called. The release
      installation can be synchronized between nodes. From an operator
      view, it can be unsatisfactory to specify each node. The aim is
      to install one release package in the system, no matter how many
      nodes there are. It is recommended that
      software management functions are written that take care of
      this problem. Such a function can have knowledge of the system
      architecture, so it can contact each individual release handler
      to install the package.</p>
    <p>For release handling to work properly, the runtime system must
      know which release it is running. It
      must also be able to change (in runtime) which boot script and
      system configuration file are to be used if the system is
      restarted. This is taken care of automatically if Erlang is
      started as an embedded system. Read about this in
      <seealso marker="doc/embedded:users_guide">Embedded System</seealso> in
      <em>System Documentation</em>. In this case, the system
      configuration file <c>sys.config</c> is mandatory.</p>
    <p>The installation of a new release can restart the system. Which
      program to use is specified by the SASL configuration
      parameter <c>start_prg</c>, which defaults
      to <c>$ROOT/bin/start</c>.</p>
    <p>The emulator restart on Windows NT expects that the system is
      started using the <c>erlsrv</c> program (as a service).
      Furthermore, the release handler expects that the service is named
      <c>NodeName</c>_<c>Release</c>, where <c>NodeName</c> is
      the first part of the Erlang node name (up to, but not including
      the "@") and <c>Release</c> is the current release version.
      The release handler furthermore expects that a
      program like <c>start_erl.exe</c> is specified as "machine" to
      <c>erlsrv</c>. During upgrading with restart, a new service
      is registered and started. The new service is set to
      automatic and the old service is removed when the new release
      is made permanent.</p>
    <p>The release handler at a node running on a diskless machine,
      or with a read-only file system, must be configured accordingly
      using the following SASL configuration parameters (for
      details, see <seealso marker="sasl_app">sasl(6)</seealso>):</p>
    <taglist>
      <tag><c>masters</c></tag>
      <item>
        <p>This node uses some master nodes to store
          and fetch release information. All master nodes must be
          operational whenever release information is written by this
          node.</p>
      </item>
      <tag><c>client_directory</c></tag>
      <item>
        <p>The <c>client_directory</c> in the directory structure of
          the master nodes must be specified.</p>
      </item>
      <tag><c>static_emulator</c></tag>
      <item>
        <p>This parameter specifies if the Erlang emulator is
          statically installed at the client node. A node with a static
          emulator cannot dynamically switch to a new emulator, as
          the executable files are statically written into memory.</p>
      </item>
    </taglist>
    <p>The release handler can also be used to unpack and
      install release packages when not running Erlang as an embedded
      system. However, in this case the user must somehow ensure that
      correct boot scripts and configuration files are used if
      the system must be restarted.</p>
    <p>Functions are provided for using another file structure
      than the structure defined in OTP. These functions can be used
      to test a release upgrade locally.</p>
  </description>

  <funcs>
    <func>
      <name>check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
      <name>check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
      <fsummary>Checks installation of a release in the system.</fsummary>
      <type>
        <v>Vsn = OtherVsn = string()</v>
	<v>Opts = [Opt]</v>
	<v>Opt = purge</v>
        <v>Descr = term()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Checks if the specified version <c>Vsn</c> of the release
          can be installed. The release must not have status
          <c>current</c>. Issues warnings if <c>relup</c> file or
          <c>sys.config</c> is not present. If <c>relup</c> file is present,
          its contents are checked and <c>{error,Reason}</c> is
          returned if an error is found. Also checks that all required
          applications are present and that all new code can be loaded;
          <c>{error,Reason}</c> is returned if an error is found.</p>
        <p>Evaluates all instructions that occur before
          the <c>point_of_no_return</c> instruction in the release
          upgrade script.</p>
        <p>Returns the same as 
	<seealso marker="#install_release/1"><c>install_release/1</c></seealso>.
	<c>Descr</c> defaults to "" if no <c>relup</c> file is found.</p>
        <p>If option <c>purge</c> is specified, all old code that can
          be soft-purged is purged after all other checks are
          successfully completed. This can be useful to
          reduce the time needed by <seealso
          marker="#install_release/1"><c>install_release/1</c></seealso>.</p>
      </desc>
    </func>

    <func>
      <name>create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name>
      <fsummary>Creates an initial <c>RELEASES</c> file.</fsummary>
      <type>
        <v>Root = RelDir = RelFile = string()</v>
        <v>AppDirs = [{App, Vsn, Dir}]</v>
        <v>&nbsp;App = atom()</v>
        <v>&nbsp;Vsn = Dir = string()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Creates an initial <c>RELEASES</c> file to be used by the
          release handler. This file must exist to install new
          releases.</p>
        <p><c>Root</c> is the root of the installation (<c>$ROOT</c>) as
          described earlier. <c>RelDir</c> is the directory where
          the <c>RELEASES</c> file is to be created (normally
          <c>$ROOT/releases</c>). <c>RelFile</c> is the name
          of the <c>.rel</c> file that describes the initial release,
          including the extension <c>.rel</c>.</p>
        <p><c>AppDirs</c> can be used to specify from where the modules
          for the specified applications are to be loaded. <c>App</c> is
          the name of an application, <c>Vsn</c> is the version, and
          <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
          is located. The corresponding modules are to be located under
          <c>Dir/App-Vsn/ebin</c>. The directories for applications not
          specified in <c>AppDirs</c> are assumed to be located in
          <c>$ROOT/lib</c>.</p>
      </desc>
    </func>

    <func>
      <name>install_file(Vsn, File) -> ok | {error, Reason}</name>
      <fsummary>Installs a release file in the release structure.</fsummary>
      <type>
        <v>Vsn = File = string()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Installs a release-dependent file in the release structure.
          The release-dependent file must be in
          the release structure when a new release is installed:
          <c>start.boot</c>, <c>relup</c>, and <c>sys.config</c>.</p>
        <p>The function can be called, for example, when these files
          are generated at the target. The function is to be called after
          <seealso marker="#set_unpacked/2"><c>set_unpacked/2</c></seealso> 
	has been called.</p>
      </desc>
    </func>

    <func>
      <name>install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
      <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name>
      <fsummary>Installs a release in the system.</fsummary>
      <type>
        <v>Vsn = OtherVsn = string()</v>
        <v>Opt = {error_action, Action} | {code_change_timeout, Timeout}</v>
        <v>&nbsp;&nbsp;&nbsp;| {suspend_timeout, Timeout} | {update_paths, Bool}</v>
        <v>&nbsp;Action = restart | reboot</v>
        <v>&nbsp;Timeout = default | infinity | pos_integer()</v>
        <v>&nbsp;Bool = boolean()</v>
        <v>Descr = term()</v>
        <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</v>
	<v>App = atom()</v>
      </type>
      <desc>
        <p>Installs the specified version <c>Vsn</c> of the release.
          Looks first for a <c>relup</c> file for <c>Vsn</c> and a
          script <c>{UpFromVsn,Descr1,Instructions1}</c> in this file
          for upgrading from the current version. If not found,
          the function looks for a <c>relup</c> file for the current
          version and a script <c>{Vsn,Descr2,Instructions2}</c> in this
          file for downgrading to <c>Vsn</c>.</p>
        <p>If a script is found, the first thing that happens is that
          the application specifications are updated according to
          the <c>.app</c> files and <c>sys.config</c> belonging to
          the release version <c>Vsn</c>.</p>
        <p>After the application specifications have been updated,
          the instructions in the script are evaluated and the function
          returns <c>{ok,OtherVsn,Descr}</c> if successful.
          <c>OtherVsn</c> and <c>Descr</c> are the version
          (<c>UpFromVsn</c> or <c>Vsn</c>) and description
          (<c>Descr1</c> or <c>Descr2</c>) as specified in the script.</p>
	<p>If <c>{continue_after_restart,OtherVsn,Descr}</c> is
	  returned, the emulator is restarted
	  before the upgrade instructions are executed. This
	  occurs if the emulator or any of the applications
          Kernel, STDLIB, or SASL
	  are updated. The new emulator version
	  and these core applications execute after the restart.
	  For all other applications the old versions are
	  started and the upgrade is performed as normal by
	  executing the upgrade instructions.</p>
        <p>If a recoverable error occurs, the function returns
          <c>{error,Reason}</c> and the original application
          specifications are restored. If a non-recoverable error
          occurs, the system is restarted.</p>
        <p><em>Options</em>:</p>
        <taglist>
          <tag><c>error_action</c></tag>
            <item><p>Defines if the node is to be
            restarted 
	    (<seealso marker="erts:init#restart/0"><c>init:restart()</c></seealso>) 
	    or rebooted
            (<seealso marker="erts:init#reboot/0"><c>init:reboot()</c></seealso>) 
	    if there is an error during
            the installation. Default is <c>restart</c>.</p></item>
          <tag><c>code_change_timeout</c></tag>
            <item><p>Defines the time-out
            for all calls to 
	    <seealso marker="stdlib:sys#change_code/4"><c>sys:change_code</c></seealso>.
	    If no value is specified or <c>default</c> is specified, the 
	    default value defined in <c>sys</c> is used.</p></item>
          <tag><c>suspend_timeout</c></tag>
            <item><p>Defines the time-out for 
            all calls to 
	    <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso>.
	    If no value is specified, the values defined by the <c>Timeout</c> 
	    parameter of the <c>upgrade</c> or <c>suspend</c> instructions are used.
            If <c>default</c> is specified, the default value defined in
            <c>sys</c> is used.</p></item>
          <tag><c>{update_paths,Bool}</c></tag>
            <item><p>Indicates if all
            application code paths are to be updated (<c>Bool==true</c>)
            or if only code paths for modified applications are to be
            updated (<c>Bool==false</c>, default). This option has only
            effect for other application directories than the default
            <c>$ROOT/lib/App-Vsn</c>, that is, application directories
            specified in argument <c>AppDirs</c> in a call to
            <seealso marker="#create_RELEASES/4"><c>create_RELEASES/4</c></seealso> or 
	    <seealso marker="#set_unpacked/2"><c>set_unpacked/2</c></seealso>.</p>
            <p><em>Example:</em></p>
            <p>In the current version <c>CurVsn</c> of a release, the
              application directory of <c>myapp</c> is
              <c>$ROOT/lib/myapp-1.0</c>. A new version <c>NewVsn</c> is
              unpacked outside the release handler and the release
              handler is informed about this with a call as follows:</p>
            <code type="none">
release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
=> {ok,NewVsn}</code>
            <p>If <c>NewVsn</c> is installed with option
              <c>{update_paths,true}</c>, then
              <seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(myapp)</c></seealso>
	      returns <c>/home/user/myapp-1.0</c>.</p></item>
        </taglist>
	<note>
	  <p>Installing a new release can be time consuming if
	  there are many processes in the system. The reason is that
	  each process must be checked for references to old code
	  before a module can be purged. This check can lead to
	  garbage collections and copying of data.</p>
	  <p>To speed up the execution of
	  <seealso marker="#install_release/1"><c>install_release</c></seealso>, 
	  first call <seealso
	  marker="#check_install_release/1"><c>check_install_release</c></seealso>,
	  using option <c>purge</c>. This does the same
	  check for old code. Then purges all modules that can be
	  soft-purged. The purged modules do then no longer have any
	  old code, and 
	  <seealso marker="#install_release/1"><c>install_release</c></seealso>
	  does not need to do the
	  checks.</p>
	  <p>This does not reduce the overall time for the
	  upgrade, but it allows checks and purge to be executed
	  in the background before the real upgrade is started.</p>
	</note>
	<note>
	  <p>When upgrading the emulator from a version older than OTP
	  R15, an attempt is made to load new application beam
	  code into the old emulator. Sometimes the new beam
	  format cannot be read by the old emulator, so the code
	  loading fails and the complete upgrade is terminated. To
	  overcome this problem, the new application code is to be
	  compiled with the old emulator. For more information about
          emulator upgrade from pre OTP R15 versions, see
          <seealso marker="doc/design_principles:appup_cookbook">Design
          Principles</seealso> in <em>System Documentation</em>.</p>
	</note>
      </desc>
    </func>

    <func>
      <name>make_permanent(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Makes the specified release version permanent.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {bad_status, Status} | term()</v>
      </type>
      <desc>
        <p>Makes the specified release version <c>Vsn</c>
          permanent.</p>
      </desc>
    </func>

    <func>
      <name>remove_release(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Removes a release from the system.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {permanent, Vsn} | client_node | term()</v>
      </type>
      <desc>
        <p>Removes a release and its files from the system.
          The release must not be the permanent release. Removes only
          the files and directories not in use by another release.</p>
      </desc>

    </func>
    <func>
      <name>reboot_old_release(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Reboots the system from an old release.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {bad_status, Status} | term()</v>
      </type>
      <desc>
        <p>Reboots the system by making the old release permanent, and
          calls 
	  <seealso marker="erts:init#reboot/0"><c>init:reboot()</c></seealso> 
	  directly. The release must have status <c>old</c>.</p>
      </desc>
    </func>

    <func>
      <name>set_removed(Vsn) -> ok | {error, Reason}</name>
      <fsummary>Marks a release as removed.</fsummary>
      <type>
        <v>Vsn = string()</v>
        <v>Reason = {permanent, Vsn} | term()</v>
      </type>
      <desc>
        <p>Makes it possible to handle removal of releases outside
          the release handler. Tells the release handler that
          the release is removed from the system. This function does
          not delete any files.</p>
      </desc>
    </func>

    <func>
      <name>set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</name>
      <fsummary>Marks a release as unpacked.</fsummary>
      <type>
        <v>RelFile = string()</v>
        <v>AppDirs = [{App, Vsn, Dir}]</v>
        <v>&nbsp;App = atom()</v>
        <v>&nbsp;Vsn = Dir = string()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Makes it possible to handle unpacking of releases outside
          the release handler. Tells the release handler that
          the release is unpacked. <c>Vsn</c> is extracted from
          the release resource file <c>RelFile</c>.</p>
        <p><c>AppDirs</c> can be used to specify from where the modules
          for the specified applications are to be loaded. <c>App</c> is
          the name of an application, <c>Vsn</c> is the version, and
          <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
          is located. The corresponding modules are to be located under
          <c>Dir/App-Vsn/ebin</c>. The directories for applications not
          specified in <c>AppDirs</c> are assumed to be located in
          <c>$ROOT/lib</c>.</p>
      </desc>
    </func>

    <func>
      <name>unpack_release(Name) -> {ok, Vsn} | {error, Reason}</name>
      <fsummary>Unpacks a release package.</fsummary>
      <type>
        <v>Name = Vsn = string()</v>
        <v>Reason = client_node | term()</v>
      </type>
      <desc>
        <p>Unpacks a release package <c>Name.tar.gz</c> located in
          the <c>releases</c> directory.</p>
        <p>Performs some checks on the package, for example, checks
          that all mandatory files are present, and extracts its
          contents.</p>
      </desc>
    </func>

    <func>
      <name>which_releases() -> [{Name, Vsn, Apps, Status}]</name>
      <fsummary>Returns all known releases.</fsummary>
      <type>
        <v>Name = Vsn = string()</v>
        <v>Apps = ["App-Vsn"]</v>
        <v>Status = unpacked | current | permanent | old</v>
      </type>
      <desc>
        <p>Returns all releases known to the release handler.</p>
      </desc>
    </func>

    <func>
      <name>which_releases(Status) -> [{Name, Vsn, Apps, Status}]</name>
      <fsummary>Returns all known releases of a specific status.</fsummary>
      <type>
        <v>Name = Vsn = string()</v>
        <v>Apps = ["App-Vsn"]</v>
        <v>Status = unpacked | current | permanent | old</v>
      </type>
      <desc>
        <p>Returns all releases, known to the release handler, of a
          specific status.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Application Upgrade/Downgrade</title>
    <p>The following functions can be used to test upgrade and downgrade
      of single applications (instead of upgrading/downgrading an entire
      release). A script corresponding to the instructions in the
      <c>relup</c> file is created
      on-the-fly, based on the <c>.appup</c> file for the application,
      and evaluated exactly in the same way as <c>release_handler</c>
      does.</p>
    <warning>
      <p>These functions are primarily intended for simplified testing
        of <c>.appup</c> files. They are not run within the context of
        the <c>release_handler</c> process. They must therefore
        <em>not</em> be used together with calls to
        <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>, 
	as this causes the
        <c>release_handler</c> to end up in an inconsistent state.</p>
      <p>No persistent information is updated, so these functions can
        be used on any Erlang node, embedded or not. Also, using these
        functions does not affect which code is loaded if there is
        a reboot.</p>
      <p>If the upgrade or downgrade fails, the application can end up
        in an inconsistent state.</p>
    </warning>
  </section>

  <funcs>
    <func>
      <name>upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
      <fsummary>Upgrades to a new application version.</fsummary>
      <type>
        <v>App = atom()</v>
        <v>Dir = string()</v>
        <v>Unpurged = [Module]</v>
        <v>&nbsp;Module = atom()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Upgrades an application <c>App</c> from the current
          version to a new version located in <c>Dir</c> according to
          the <c>.appup</c> file.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>Dir</c> is the new library directory of
          <c>App</c>. The corresponding modules as well as
          the <c>.app</c> and <c>.appup</c> files are to be located
          under <c>Dir/ebin</c>.</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find an upgrade script from the current version of
          the application using
          <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso>.
          This script is evaluated using
          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>,
          exactly in the same way as
          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>
          does.</p>
        <p>Returns one of the following:</p>
        <list type="bulleted">
          <item><c>{ok, Unpurged}</c> if evaluating the script is
            successful, where <c>Unpurged</c> is a list of unpurged
            modules</item>
          <item><c>restart_emulator</c> if this instruction is
            encountered in the script</item>
          <item><c>{error, Reason}</c> if an error occurred when
            finding or evaluating the script</item>
        </list>
	<p>If the <c>restart_new_emulator</c> instruction is found in
          the script, 
	  <seealso marker="#upgrade_app/2"><c>upgrade_app/2</c></seealso> 
	  returns <c>{error,restart_new_emulator}</c>. This because
          <c>restart_new_emulator</c> requires a new version of the
          emulator to be started before the rest of the upgrade
          instructions can be executed, and this can only be done by
          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>.</p>
      </desc>
    </func>

    <func>
      <name>downgrade_app(App, Dir) -></name>
      <name>downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
      <fsummary>Downgrades to a previous application version.</fsummary>
      <type>
        <v>App = atom()</v>
        <v>Dir = OldVsn = string()</v>
        <v>Unpurged = [Module]</v>
        <v>&nbsp;Module = atom()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Downgrades an application <c>App</c> from the current
          version to a previous version <c>OldVsn</c> located in
          <c>Dir</c> according to the <c>.appup</c> file.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>OldVsn</c> is the previous application version
          and can be omitted if <c>Dir</c> is of
          the format <c>"App-OldVsn"</c>. <c>Dir</c> is the library
          directory of the previous version of <c>App</c>.
          The corresponding modules and the old <c>.app</c> file
          are to be located under <c>Dir/ebin</c>. The <c>.appup</c>
          file is to be located in the <c>ebin</c> directory of
          the <em>current</em> library directory of the application
          (<seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(App)</c></seealso>).</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find a downgrade script to the previous version of
          the application using
          <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso>.
          This script is evaluated using
          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>,
          exactly in the same way as
          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>
          does.</p>
        <p>Returns one of the following:</p>
        <list type="bulleted">
          <item><c>{ok, Unpurged}</c> if evaluating the script is
            successful, where <c>Unpurged</c> is a list of unpurged
            modules</item>
          <item><c>restart_emulator</c> if this instruction is
            encountered in the script</item>
          <item><c>{error, Reason}</c> if an error occurred when
            finding or evaluating the script</item>
        </list>
      </desc>
    </func>

    <func>
      <name>upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name>
      <fsummary>Finds an application upgrade script.</fsummary>
      <type>
        <v>App = atom()</v>
        <v>Dir = string()</v>
        <v>NewVsn = string()</v>
        <v>Script = Instructions</v>
      </type>
      <desc>
        <p>Tries to find an application upgrade script for <c>App</c>
          from the current version to a new version located in
          <c>Dir</c>.</p>
        <p>The upgrade script can then be evaluated using
          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>.
          It is recommended to use
          <seealso marker="#upgrade_app/2"><c>upgrade_app/2</c></seealso>
          instead, but this function (<c>upgrade_script</c>) is useful
          to inspect the contents of the script.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>Dir</c> is the new library directory of
          <c>App</c>. The corresponding modules as well as
          the <c>.app</c> and <c>.appup</c> files are to be located
          under <c>Dir/ebin</c>.</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find an upgrade script from the current application version.
          High-level instructions are translated to
          low-level instructions. The instructions are sorted in
          the same manner as when generating a <c>relup</c> file.</p>
        <p>Returns <c>{ok, NewVsn, Script}</c> if successful, where
          <c>NewVsn</c> is the new application version.
	For details about <c>Script</c>, see 
	<seealso marker="appup"><c>appup(4)</c></seealso>.</p>
        <p>Failure: If a script cannot be found, the function fails
          with an appropriate error reason.</p>
      </desc>
    </func>

    <func>
      <name>downgrade_script(App, OldVsn, Dir) -> {ok, Script}</name>
      <fsummary>Finds an application downgrade script.</fsummary>
      <type>
        <v>App = atom()</v>
        <v>OldVsn = Dir = string()</v>
        <v>Script = Instructions</v>
      </type>
      <desc>
        <p>Tries to find an application downgrade script for <c>App</c>
          from the current version to a previous version <c>OldVsn</c>
          located in <c>Dir</c>.</p>
        <p>The downgrade script can then be evaluated using
          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>.
          It is recommended to use
          <seealso marker="#downgrade_app/2"><c>downgrade_app/2,3</c></seealso>
          instead, but this function (<c>downgrade_script</c>) is useful
          to inspect the contents of the script.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>Dir</c> is the previous library directory of
          <c>App</c>. The corresponding modules and
          the old <c>.app</c> file are to be located under
          <c>Dir/ebin</c>. The <c>.appup</c> file is to be located in
          the <c>ebin</c> directory of the <em>current</em> library
          directory of the application 
	(<seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(App)</c>)</seealso>.</p>
        <p>The function looks in the <c>.appup</c> file and tries to
          find a downgrade script from the current application version.
          High-level instructions are translated to
          low-level instructions. The instructions are sorted in
          the same manner as when generating a <c>relup</c> file.</p>
        <p>Returns <c>{ok, Script}</c> if successful. 
	For details about <c>Script</c>, see 
	<seealso marker="appup"><c>appup(4)</c></seealso>.</p>
        <p>Failure: If a script cannot be found, the function fails
          with an appropriate error reason.</p>
      </desc>
    </func>

    <func>
      <name>eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
      <fsummary>Evaluates an application upgrade or downgrade script.</fsummary>
      <type>
        <v>App = atom()</v>
        <v>ToVsn = ToDir = string()</v>
        <v>Script</v>
	<d>See <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso>, <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso></d>
        <v>Unpurged = [Module]</v>
        <v>&nbsp;Module = atom()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Evaluates an application upgrade or downgrade script
          <c>Script</c>, the result from calling
          <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso> or
          <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso>,
          exactly in the same way as
          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>
          does.</p>
        <p><c>App</c> is the name of the application, which must be
          started. <c>ToVsn</c> is the version to be upgraded/downgraded
          to, and <c>ToDir</c> is the library directory of this version.
          The corresponding modules as well as the <c>.app</c> and
          <c>.appup</c> files are to be located under <c>Dir/ebin</c>.</p>
        <p>Returns one of the following:</p>
        <list type="bulleted">
          <item><c>{ok, Unpurged}</c> if evaluating the script is
            successful, where <c>Unpurged</c> is a list of unpurged
            modules</item>
          <item><c>restart_emulator</c> if this instruction is
            encountered in the script</item>
          <item><c>{error, Reason}</c> if an error occurred when
            finding or evaluating the script</item>
        </list>
        <p>If the <c>restart_new_emulator</c> instruction is found in
          the script, 
	  <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>
	  returns <c>{error,restart_new_emulator}</c>. This because
          <c>restart_new_emulator</c> requires a new version of the
          emulator to be started before the rest of the upgrade
          instructions can be executed, and this can only be done by
          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Typical Error Reasons</title>
    <taglist>
      <tag><c>{bad_masters, Masters}</c></tag>
        <item><p>The master nodes <c>Masters</c> are not alive.</p></item>
      <tag><c>{bad_rel_file, File}</c></tag>
        <item><p>Specified <c>.rel</c> file <c>File</c> cannot be read or
          does not contain a single term.</p></item>
      <tag><c>{bad_rel_data, Data}</c></tag>
        <item><p>Specified <c>.rel</c> file does not contain a recognized
          release specification, but another term <c>Data</c>.</p></item>
      <tag><c>{bad_relup_file, File}</c></tag>
        <item><p>Specified <c>relup</c> file <c>Relup</c> contains bad
          data.</p></item>
      <tag><c>{cannot_extract_file, Name, Reason}</c></tag>
        <item><p>Problems when extracting from a tar file,
          <seealso marker="stdlib:erl_tar#extract/2"><c>erl_tar:extract/2</c></seealso>
	  returned <c>{error, {Name, Reason}}</c>.</p></item>
      <tag><c>{existing_release, Vsn}</c></tag>
        <item><p>Specified release version <c>Vsn</c> is already
          in use.</p></item>
      <tag><c>{Master, Reason, When}</c></tag>
        <item><p>Some operation, indicated by the term <c>When</c>, failed
          on the master node <c>Master</c> with the specified error
          reason <c>Reason</c>.</p></item>
      <tag><c>{no_matching_relup, Vsn, CurrentVsn}</c></tag>
        <item><p>Cannot find a script for upgrading/downgrading between
          <c>CurrentVsn</c> and <c>Vsn</c>.</p></item>
      <tag><c>{no_such_directory, Path}</c></tag>
        <item><p>The directory <c>Path</c>does not exist.</p></item>
      <tag><c>{no_such_file, Path}</c></tag>
        <item><p>The path <c>Path</c> (file or directory) does not
          exist.</p></item>
      <tag><c>{no_such_file, {Master, Path}}</c></tag>
        <item><p>The path <c>Path</c> (file or directory) does not exist at
          the master node <c>Master</c>.</p></item>
      <tag><c>{no_such_release, Vsn}</c></tag>
        <item><p>The specified release version <c>Vsn</c> does not
          exist.</p></item>
      <tag><c>{not_a_directory, Path}</c></tag>
        <item><p><c>Path</c> exists but is not a directory.</p></item>
      <tag><c>{Posix, File}</c></tag>
        <item><p>Some file operation failed for <c>File</c>. <c>Posix</c>
          is an atom named from the Posix error codes, such as
          <c>enoent</c>, <c>eacces</c>, or <c>eisdir</c>. See
          <seealso marker="kernel:file"><c>file(3)</c></seealso>
          in Kernel.</p></item>
      <tag><c>Posix</c></tag>
        <item><p>Some file operation failed, as for the previous item in
          the list.</p></item>
    </taglist>
  </section>

  <section>
    <title>See Also</title>
    <p><seealso marker="doc/design_principles:users_guide">OTP Design Principles</seealso>,
      <seealso marker="kernel:config"><c>config(4)</c></seealso>,
      <seealso marker="rel"><c>rel(4)</c></seealso>,
      <seealso marker="relup"><c>relup(4)</c></seealso>,
      <seealso marker="script"><c>script(4)</c></seealso>,
      <seealso marker="stdlib:sys"><c>sys(3)</c></seealso>,
      <seealso marker="systools"><c>systools(3)</c></seealso></p>
  </section>
</erlref>