1appup(5) Files appup(5)
2
6 appup - Application upgrade file
7
9 The application upgrade file defines how an application is upgraded or
10 downgraded in a running system.
11 This file is used by the functions in systools when generating a
13 release upgrade file relup.
14
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 The .appup file contains one single Erlang term, which defines the
21 instructions used to upgrade or downgrade the application. The file has
22 the following syntax:
23 {Vsn,
25 [{UpFromVsn, Instructions}, ...],
26 [{DownToVsn, Instructions}, ...]}.
27 Vsn = string():
29 Current application version.
30 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 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 Instructions:
44 A list of release upgrade instructions, see Release Upgrade
45 Instructions. It is recommended to use high-level instructions
46 only. These are automatically translated to low-level instructions
47 by systools when creating the relup file.
48 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
52 binary. For example, the following match all versions 2.1.x, where x is
53 any number:
54 <<"2\\.1\\.[0-9]+">>
56 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
62 Release upgrade instructions are interpreted by the release handler
63 when an upgrade or downgrade is made. For more information about
64 release handling, see OTP Design Principles in System Documentation.
65 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 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 Synchronized code replacement of processes using module Mod.
89 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 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 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
106 {error,{old_processes,Mod}}.
107 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 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 Timeout:
125 Defines the time-out when suspending processes. If no value or
126 default is specified, the default value for sys:suspend is used.
127 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
132 upgrade, 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 update with argument supervisor is used when changing the start speci‐
140 fication of a supervisor.
141 {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 Simple code replacement of the module Mod.
150 For a description of PrePurge and PostPurge, see update above.
152 DepMods defaults to [] and defines which other modules Mod is dependent
154 on. In the relup file, instructions for loading these modules come
155 before the instruction for loading Mod when upgrading, and conversely
156 when downgrading.
157 {add_module, Mod}
159 {add_module, Mod, DepMods}
160 Mod = atom()
161 DepMods = [Mod]
162 Loads a new module Mod.
164 DepMods defaults to [] and defines which other modules Mod is dependent
166 on. In the relup file, instructions related to these modules come
167 before the instruction for loading Mod when upgrading, and conversely
168 when downgrading.
169 {delete_module, Mod}
171 {delete_module, Mod, DepMods}
172 Mod = atom()
173 Deletes a module Mod using the low-level instructions remove and purge.
175 DepMods defaults to [] and defines which other modules Mod is dependent
177 on. In the relup file, instructions related to these modules come
178 before the instruction for removing Mod when upgrading, and conversely
179 when downgrading.
180 {add_application, Application}
182 {add_application, Application, Type}
183 Application = atom()
184 Type = permanent | transient | temporary | load | none
185 Adding an application means that the modules defined by the modules key
187 in the .app file are loaded using add_module.
188 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 {remove_application, Application}
197 Application = atom()
198 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 {restart_application, Application}
204 Application = atom()
205 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 Low-Level Instructions
216 {load_object_code, {App, Vsn, [Mod]}}
217 App = Mod = atom()
218 Vsn = string()
219 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
223 cycle less time-consuming.
224 point_of_no_return
226 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 {load, {Mod, PrePurge, PostPurge}}
233 Mod = atom()
234 PrePurge = PostPurge = soft_purge | brutal_purge
235 Before this instruction occurs, Mod must have been loaded using
237 load_object_code. This instruction loads the module. PrePurge is
238 ignored. For a description of PostPurge, see the high-level instruction
239 update earlier.
240 {remove, {Mod, PrePurge, PostPurge}}
242 Mod = atom()
243 PrePurge = PostPurge = soft_purge | brutal_purge
244 Makes the current version of Mod old. PrePurge is ignored. For a
246 description of PostPurge, see the high-level instruction update ear‐
247 lier.
248 {purge, [Mod]}
250 Mod = atom()
251 Purges each module Mod, that is, removes the old code. Notice that any
253 process executing purged code is killed.
254 {suspend, [Mod | {Mod, Timeout}]}
256 Mod = atom()
257 Timeout = int()>0 | default | infinity
258 Tries to suspend all processes using a module Mod. If a process does
260 not respond, it is ignored. This can cause the process to die, either
261 because it crashes when it spontaneously switches to new code, or as a
262 result of a purge operation. If no Timeout is specified or default is
263 specified, the default value for sys:suspend is used.
264 {resume, [Mod]}
266 Mod = atom()
267 Resumes all suspended processes using a module Mod.
269 {code_change, [{Mod, Extra}]}
271 {code_change, Mode, [{Mod, Extra}]}
272 Mod = atom()
273 Mode = up | down
274 Extra = term()
275 Mode defaults to up and specifies if it is an upgrade or downgrade.
277 This instruction sends a code_change system message to all processes
278 using a module Mod by calling function sys:change_code, passing term
279 Extra as argument.
280 {stop, [Mod]}
282 Mod = atom()
283 Stops all processes using a module Mod by calling supervisor:termi‐
285 nate_child/2. This instruction is useful when the simplest way to
286 change code is to stop and restart the processes that run the code.
287 {start, [Mod]}
289 Mod = atom()
290 Starts all stopped processes using a module Mod by calling supervi‐
292 sor:restart_child/2.
293 {sync_nodes, Id, [Node]}
295 {sync_nodes, Id, {M, F, A}}
296 Id = term()
297 Node = node()
298 M = F = atom()
299 A = [term()]
300 apply(M, F, A) must return a list of nodes.
302 This instruction synchronizes the release installation with other
304 nodes. Each Node must evaluate this command with the same Id. The local
305 node waits for all other nodes to evaluate the instruction before exe‐
306 cution continues. If a node goes down, it is considered to be an unre‐
307 coverable error, and the local node is restarted from the old release.
308 There is no time-out for this instruction, which means that it can hang
309 forever.
310 {apply, {M, F, A}}
312 M = F = atom()
313 A = [term()]
314 Evaluates apply(M, F, A).
316 If the instruction appears before instruction point_of_no_return, a
318 failure is caught. release_handler:install_release/1 then returns
319 {error,{'EXIT',Reason}}, unless {error,Error} is thrown or returned.
320 Then it returns {error,Error}.
321 If the instruction appears after instruction point_of_no_return and the
323 function call fails, the system is restarted.
324 restart_new_emulator
326 This instruction is used when the application ERTS, Kernel, STDLIB, or
328 SASL is upgraded. It shuts down the current emulator and starts a new
329 one. All processes are terminated gracefully, and the new version of
330 ERTS, Kernel, STDLIB, and SASL are used when the emulator restarts.
331 Only one restart_new_emulator instruction is allowed in the relup file,
332 and it must be placed first. systools:make_relup/3,4 ensures this when
333 the relup file is generated. The rest of the instructions in the relup
334 file is executed after the restart as a part of the boot script.
335 An info report is written when the upgrade is completed. To programmat‐
337 ically determine if the upgrade is complete, call release_han‐
338 dler:which_releases/0,1 and check if the expected release has status
339 current.
340 The new release must still be made permanent after the upgrade is com‐
342 pleted, otherwise the old emulator is started if there is an emulator
343 restart.
344 Warning:
346 As stated earlier, instruction restart_new_emulator causes the emulator
347 to be restarted with new versions of ERTS>, Kernel, STDLIB, and SASL.
348 However, all other applications do at startup run their old versions in
349 this new emulator. This is usually no problem, but every now and then
350 incompatible changes occur to the core applications, which can cause
351 trouble in this setting. Such incompatible changes (when functions are
352 removed) are normally preceded by a deprecation over two major
353 releases. To ensure that your application is not crashed by an incom‐
354 patible change, always remove any call to deprecated functions as soon
355 as possible.
356 restart_emulator
359 This instruction is similar to restart_new_emulator, except it must be
361 placed at the end of the relup file. It is not related to an upgrade of
362 the emulator or the core applications, but can be used by any applica‐
363 tion when a complete reboot of the system is required.
364 When generating the relup file, systools:make_relup/3,4 ensures that
366 there is only one restart_emulator instruction and that it is the last
367 instruction in the relup file.
368
370 release_handler(3), relup(4), supervisor(3), systools(3)
371Ericsson AB sasl 3.3 appup(5)