1appup(5)                             Files                            appup(5)
2
3
4

NAME

6       appup - Application upgrade file
7

DESCRIPTION

9       The  application upgrade file defines how an application is upgraded or
10       downgraded in a running system.
11
12       This file is used by the functions in systools when  generating  a  re‐
13       lease upgrade file relup.
14

FILE SYNTAX

16       The  application  upgrade file is to be called Application.appup, where
17       Application is the application name. The file is to be located  in  the
18       ebin directory for the application.
19
20       The  .appup file contains one single Erlang term, which defines the in‐
21       structions used to upgrade or downgrade the application. The  file  has
22       the following syntax:
23
24       {Vsn,
25         [{UpFromVsn, Instructions}, ...],
26         [{DownToVsn, Instructions}, ...]}.
27
28         Vsn = string():
29           Current application version.
30
31         UpFromVsn = string() | binary():
32           An  earlier application version to upgrade from. If it is a string,
33           it is interpreted as a specific version number. If it is a  binary,
34           it  is  interpreted as a regular expression that can match multiple
35           version numbers.
36
37         DownToVsn = string() | binary():
38           An earlier application version to downgrade to. If it is a  string,
39           it  is interpreted as a specific version number. If it is a binary,
40           it is interpreted as a regular expression that can  match  multiple
41           version numbers.
42
43         Instructions:
44           A  list  of  release  upgrade instructions, see Release Upgrade In‐
45           structions. It is recommended to use high-level instructions  only.
46           These  are  automatically  translated  to low-level instructions by
47           systools when creating the relup file.
48
49       To avoid duplication of upgrade instructions, it is allowed to use reg‐
50       ular expressions to specify UpFromVsn and DownToVsn. To be considered a
51       regular expression, the version identifier must be specified as  a  bi‐
52       nary.  For  example, the following match all versions 2.1.x, where x is
53       any number:
54
55       <<"2\\.1\\.[0-9]+">>
56
57       Notice that the regular expression  must  match  the  complete  version
58       string,  so  this  example  works  for, for example, 2.1.1, but not for
59       2.1.1.1.
60

RELEASE UPGRADE INSTRUCTIONS

62       Release upgrade instructions are interpreted  by  the  release  handler
63       when  an  upgrade  or downgrade is made. For more information about re‐
64       lease handling, see OTP Design Principles in System Documentation.
65
66       A process is said to use a module Mod if Mod is listed in  the  Modules
67       part of the child specification used to start the process, see supervi‐
68       sor(3). In the case of gen_event, an event manager process is  said  to
69       use Mod if Mod is an installed event handler.
70
71   High-Level Instructions
72       {update, Mod}
73       {update, Mod, supervisor}
74       {update, Mod, Change}
75       {update, Mod, DepMods}
76       {update, Mod, Change, DepMods}
77       {update, Mod, Change, PrePurge, PostPurge, DepMods}
78       {update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
79       {update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
80         Mod = atom()
81         ModType = static | dynamic
82         Timeout = int()>0 | default | infinity
83         Change = soft | {advanced,Extra}
84           Extra = term()
85         PrePurge = PostPurge = soft_purge | brutal_purge
86         DepMods = [Mod]
87
88       Synchronized code replacement of processes using module Mod.
89
90       All  those  processes  are  suspended using sys:suspend, the new module
91       version is loaded, and then the processes are resumed using sys:resume.
92
93         Change:
94           Defaults to soft and defines the type of code change. If it is  set
95           to   {advanced,Extra},   implemented  processes  using  gen_server,
96           gen_fsm, gen_statem, or gen_event transform their internal state by
97           calling  the  callback function code_change. Special processes call
98           the callback function system_code_change/4. In both cases, the term
99           Extra is passed as an argument to the callback function.
100
101         PrePurge:
102           Defaults to brutal_purge. It controls what action to take with pro‐
103           cesses executing old code before loading the new module version. If
104           the  value  is brutal_purge, the processes are killed. If the value
105           is  soft_purge,  release_handler:install_release/1   returns   {er‐
106           ror,{old_processes,Mod}}.
107
108         PostPurge:
109           Defaults to brutal_purge. It controls what action to take with pro‐
110           cesses that are executing old code when the new module version  has
111           been  loaded. If the value is brutal_purge, the code is purged when
112           the release is made permanent and the processes are killed. If  the
113           value  is  soft_purge, the release handler purges the old code when
114           no remaining processes execute the code.
115
116         DepMods:
117           Defaults to [] and defines other modules that Mod is dependent  on.
118           In  the relup file, instructions for suspending processes using Mod
119           come before instructions for suspending processes using modules  in
120           DepMods when upgrading, and conversely when downgrading. In case of
121           circular dependencies, the order of the instructions in  the  appup
122           file is kept.
123
124         Timeout:
125           Defines  the time-out when suspending processes. If no value or de‐
126           fault is specified, the default value for sys:suspend is used.
127
128         ModType:
129           Defaults to dynamic. It specifies if the code  is  "dynamic",  that
130           is,  if  a  process  using the module spontaneously switches to new
131           code, or if it is "static". When doing an advanced update  and  up‐
132           grade,  the  new  version  of a dynamic module is loaded before the
133           process is asked to change code. When downgrading, the  process  is
134           asked  to  change  code  before loading the new version. For static
135           modules, the new version is loaded before the process is  asked  to
136           change  code,  both in the case of upgrading and downgrading. Call‐
137           back modules are dynamic.
138
139       update with argument supervisor is used when changing the start  speci‐
140       fication of a supervisor.
141
142       {load_module, Mod}
143       {load_module, Mod, DepMods}
144       {load_module, Mod, PrePurge, PostPurge, DepMods}
145         Mod = atom()
146         PrePurge = PostPurge = soft_purge | brutal_purge
147         DepMods = [Mod]
148
149       Simple code replacement of the module Mod.
150
151       For a description of PrePurge and PostPurge, see update above.
152
153       DepMods defaults to [] and defines which other modules Mod is dependent
154       on. In the relup file, instructions for loading these modules come  be‐
155       fore  the  instruction  for  loading Mod when upgrading, and conversely
156       when downgrading.
157
158       {add_module, Mod}
159       {add_module, Mod, DepMods}
160         Mod = atom()
161         DepMods = [Mod]
162
163       Loads a new module Mod.
164
165       DepMods defaults to [] and defines which other modules Mod is dependent
166       on.  In  the relup file, instructions related to these modules come be‐
167       fore the instruction for loading Mod  when  upgrading,  and  conversely
168       when downgrading.
169
170       {delete_module, Mod}
171       {delete_module, Mod, DepMods}
172         Mod = atom()
173
174       Deletes a module Mod using the low-level instructions remove and purge.
175
176       DepMods defaults to [] and defines which other modules Mod is dependent
177       on. In the relup file, instructions related to these modules  come  be‐
178       fore  the  instruction  for removing Mod when upgrading, and conversely
179       when downgrading.
180
181       {add_application, Application}
182       {add_application, Application, Type}
183         Application = atom()
184         Type = permanent | transient | temporary | load | none
185
186       Adding an application means that the modules defined by the modules key
187       in the .app file are loaded using add_module.
188
189       Type defaults to permanent and specifies the start type of the applica‐
190       tion. If Type = permanent | transient | temporary, the  application  is
191       loaded  and  started  in  the corresponding way, see application(3). If
192       Type = load, the application is only loaded. If Type = none, the appli‐
193       cation is not loaded and not started, although the code for its modules
194       is loaded.
195
196       {remove_application, Application}
197         Application = atom()
198
199       Removing an application means that the application is stopped, the mod‐
200       ules  are unloaded using delete_module, and then the application speci‐
201       fication is unloaded from the application controller.
202
203       {restart_application, Application}
204         Application = atom()
205
206       Restarting an application means that the  application  is  stopped  and
207       then  started  again, similar to using the instructions remove_applica‐
208       tion and add_application in sequence. Note that, even if  the  applica‐
209       tion  has  been  started  before  the  release  upgrade  is  performed,
210       restart_application may only load it rather than start it, depending on
211       the  application's  start type: If Type = load, the application is only
212       loaded. If Type = none, the application is not loaded and not  started,
213       although the code for its modules is loaded.
214
215   Low-Level Instructions
216       {load_object_code, {App, Vsn, [Mod]}}
217         App = Mod = atom()
218         Vsn = string()
219
220       Reads  each  Mod  from  directory App-Vsn/ebin as a binary. It does not
221       load the modules. The instruction is to be placed first in  the  script
222       to  read all new code from the file to make the suspend-load-resume cy‐
223       cle less time-consuming.
224
225       point_of_no_return
226
227       If a crash occurs after this instruction, the system cannot recover and
228       is  restarted  from  the old release version. The instruction must only
229       occur once in a script. It is to be placed after  all  load_object_code
230       instructions.
231
232       {load, {Mod, PrePurge, PostPurge}}
233         Mod = atom()
234         PrePurge = PostPurge = soft_purge | brutal_purge
235
236       Before  this  instruction  occurs,  Mod  must  have  been  loaded using
237       load_object_code. This instruction loads the module.  PrePurge  is  ig‐
238       nored.  For  a description of PostPurge, see the high-level instruction
239       update earlier.
240
241       {remove, {Mod, PrePurge, PostPurge}}
242         Mod = atom()
243         PrePurge = PostPurge = soft_purge | brutal_purge
244
245       Makes the current version of Mod old. PrePurge is ignored.  For  a  de‐
246       scription of PostPurge, see the high-level instruction update earlier.
247
248       {purge, [Mod]}
249         Mod = atom()
250
251       Purges  each module Mod, that is, removes the old code. Notice that any
252       process executing purged code is killed.
253
254       {suspend, [Mod | {Mod, Timeout}]}
255         Mod = atom()
256         Timeout = int()>0 | default | infinity
257
258       Tries to suspend all processes using a module Mod. If  a  process  does
259       not  respond,  it is ignored. This can cause the process to die, either
260       because it crashes when it spontaneously switches to new code, or as  a
261       result  of  a purge operation. If no Timeout is specified or default is
262       specified, the default value for sys:suspend is used.
263
264       {resume, [Mod]}
265         Mod = atom()
266
267       Resumes all suspended processes using a module Mod.
268
269       {code_change, [{Mod, Extra}]}
270       {code_change, Mode, [{Mod, Extra}]}
271         Mod = atom()
272         Mode = up | down
273         Extra = term()
274
275       Mode defaults to up and specifies if it is  an  upgrade  or  downgrade.
276       This  instruction  sends  a code_change system message to all processes
277       using a module Mod by calling function  sys:change_code,  passing  term
278       Extra as argument.
279
280       {stop, [Mod]}
281         Mod = atom()
282
283       Stops  all  processes  using  a module Mod by calling supervisor:termi‐
284       nate_child/2. This instruction is  useful  when  the  simplest  way  to
285       change code is to stop and restart the processes that run the code.
286
287       {start, [Mod]}
288         Mod = atom()
289
290       Starts  all  stopped  processes  using a module Mod by calling supervi‐
291       sor:restart_child/2.
292
293       {sync_nodes, Id, [Node]}
294       {sync_nodes, Id, {M, F, A}}
295         Id = term()
296         Node = node()
297         M = F = atom()
298         A = [term()]
299
300       apply(M, F, A) must return a list of nodes.
301
302       This instruction  synchronizes  the  release  installation  with  other
303       nodes. Each Node must evaluate this command with the same Id. The local
304       node waits for all other nodes to evaluate the instruction before  exe‐
305       cution  continues. If a node goes down, it is considered to be an unre‐
306       coverable error, and the local node is restarted from the old  release.
307       There is no time-out for this instruction, which means that it can hang
308       forever.
309
310       {apply, {M, F, A}}
311         M = F = atom()
312         A = [term()]
313
314       Evaluates apply(M, F, A).
315
316       If the instruction appears  before  instruction  point_of_no_return,  a
317       failure  is caught. release_handler:install_release/1 then returns {er‐
318       ror,{'EXIT',Reason}}, unless {error,Error} is thrown or returned.  Then
319       it returns {error,Error}.
320
321       If the instruction appears after instruction point_of_no_return and the
322       function call fails, the system is restarted.
323
324       restart_new_emulator
325
326       This instruction is used when the application ERTS, Kernel, STDLIB,  or
327       SASL  is  upgraded. It shuts down the current emulator and starts a new
328       one. All processes are terminated gracefully, and the  new  version  of
329       ERTS,  Kernel,  STDLIB,  and  SASL are used when the emulator restarts.
330       Only one restart_new_emulator instruction is allowed in the relup file,
331       and  it must be placed first. systools:make_relup/3,4 ensures this when
332       the relup file is generated. The rest of the instructions in the  relup
333       file is executed after the restart as a part of the boot script.
334
335       An info report is written when the upgrade is completed. To programmat‐
336       ically  determine  if  the  upgrade  is  complete,  call   release_han‐
337       dler:which_releases/0,1  and  check  if the expected release has status
338       current.
339
340       The new release must still be made permanent after the upgrade is  com‐
341       pleted,  otherwise  the old emulator is started if there is an emulator
342       restart.
343
344   Warning:
345       As stated earlier, instruction restart_new_emulator causes the emulator
346       to  be  restarted with new versions of ERTS>, Kernel, STDLIB, and SASL.
347       However, all other applications do at startup run their old versions in
348       this  new  emulator. This is usually no problem, but every now and then
349       incompatible changes occur to the core applications,  which  can  cause
350       trouble  in this setting. Such incompatible changes (when functions are
351       removed) are normally preceded by a  deprecation  over  two  major  re‐
352       leases. To ensure that your application is not crashed by an incompati‐
353       ble change, always remove any call to deprecated functions as  soon  as
354       possible.
355
356
357       restart_emulator
358
359       This  instruction is similar to restart_new_emulator, except it must be
360       placed at the end of the relup file. It is not related to an upgrade of
361       the  emulator or the core applications, but can be used by any applica‐
362       tion when a complete reboot of the system is required.
363
364       When generating the relup file,  systools:make_relup/3,4  ensures  that
365       there  is only one restart_emulator instruction and that it is the last
366       instruction in the relup file.
367

SEE ALSO

369       release_handler(3), relup(4), supervisor(3), systools(3)
370
371
372
373Ericsson AB                        sasl 4.1                           appup(5)
Impressum