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 re‐
13 lease 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 in‐
21 structions 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 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 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 <<"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 re‐
64 lease 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 {er‐
106 ror,{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 de‐
126 fault 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 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 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 be‐
155 fore 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 be‐
167 fore 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 be‐
178 fore 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 cy‐
223 cle 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 ig‐
238 nored. 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 de‐
246 scription of PostPurge, see the high-level instruction update earlier.
247 {purge, [Mod]}
249 Mod = atom()
250 Purges each module Mod, that is, removes the old code. Notice that any
252 process executing purged code is killed.
253 {suspend, [Mod | {Mod, Timeout}]}
255 Mod = atom()
256 Timeout = int()>0 | default | infinity
257 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 {resume, [Mod]}
265 Mod = atom()
266 Resumes all suspended processes using a module Mod.
268 {code_change, [{Mod, Extra}]}
270 {code_change, Mode, [{Mod, Extra}]}
271 Mod = atom()
272 Mode = up | down
273 Extra = term()
274 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 {stop, [Mod]}
281 Mod = atom()
282 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 {start, [Mod]}
288 Mod = atom()
289 Starts all stopped processes using a module Mod by calling supervi‐
291 sor:restart_child/2.
292 {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 apply(M, F, A) must return a list of nodes.
301 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 {apply, {M, F, A}}
311 M = F = atom()
312 A = [term()]
313 Evaluates apply(M, F, A).
315 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 If the instruction appears after instruction point_of_no_return and the
322 function call fails, the system is restarted.
323 restart_new_emulator
325 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 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 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 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 restart_emulator
358 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 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
369 release_handler(3), relup(4), supervisor(3), systools(3)
370Ericsson AB sasl 4.1 appup(5)