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.
209 Low-Level Instructions
211 {load_object_code, {App, Vsn, [Mod]}}
212 App = Mod = atom()
213 Vsn = string()
214 Reads each Mod from directory App-Vsn/ebin as a binary. It does not
216 load the modules. The instruction is to be placed first in the script
217 to read all new code from the file to make the suspend-load-resume
218 cycle less time-consuming.
219 point_of_no_return
221 If a crash occurs after this instruction, the system cannot recover and
223 is restarted from the old release version. The instruction must only
224 occur once in a script. It is to be placed after all load_object_code
225 instructions.
226 {load, {Mod, PrePurge, PostPurge}}
228 Mod = atom()
229 PrePurge = PostPurge = soft_purge | brutal_purge
230 Before this instruction occurs, Mod must have been loaded using
232 load_object_code. This instruction loads the module. PrePurge is
233 ignored. For a description of PostPurge, see the high-level instruction
234 update earlier.
235 {remove, {Mod, PrePurge, PostPurge}}
237 Mod = atom()
238 PrePurge = PostPurge = soft_purge | brutal_purge
239 Makes the current version of Mod old. PrePurge is ignored. For a
241 description of PostPurge, see the high-level instruction update ear‐
242 lier.
243 {purge, [Mod]}
245 Mod = atom()
246 Purges each module Mod, that is, removes the old code. Notice that any
248 process executing purged code is killed.
249 {suspend, [Mod | {Mod, Timeout}]}
251 Mod = atom()
252 Timeout = int()>0 | default | infinity
253 Tries to suspend all processes using a module Mod. If a process does
255 not respond, it is ignored. This can cause the process to die, either
256 because it crashes when it spontaneously switches to new code, or as a
257 result of a purge operation. If no Timeout is specified or default is
258 specified, the default value for sys:suspend is used.
259 {resume, [Mod]}
261 Mod = atom()
262 Resumes all suspended processes using a module Mod.
264 {code_change, [{Mod, Extra}]}
266 {code_change, Mode, [{Mod, Extra}]}
267 Mod = atom()
268 Mode = up | down
269 Extra = term()
270 Mode defaults to up and specifies if it is an upgrade or downgrade.
272 This instruction sends a code_change system message to all processes
273 using a module Mod by calling function sys:change_code, passing term
274 Extra as argument.
275 {stop, [Mod]}
277 Mod = atom()
278 Stops all processes using a module Mod by calling supervisor:termi‐
280 nate_child/2. This instruction is useful when the simplest way to
281 change code is to stop and restart the processes that run the code.
282 {start, [Mod]}
284 Mod = atom()
285 Starts all stopped processes using a module Mod by calling supervi‐
287 sor:restart_child/2.
288 {sync_nodes, Id, [Node]}
290 {sync_nodes, Id, {M, F, A}}
291 Id = term()
292 Node = node()
293 M = F = atom()
294 A = [term()]
295 apply(M, F, A) must return a list of nodes.
297 This instruction synchronizes the release installation with other
299 nodes. Each Node must evaluate this command with the same Id. The local
300 node waits for all other nodes to evaluate the instruction before exe‐
301 cution continues. If a node goes down, it is considered to be an unre‐
302 coverable error, and the local node is restarted from the old release.
303 There is no time-out for this instruction, which means that it can hang
304 forever.
305 {apply, {M, F, A}}
307 M = F = atom()
308 A = [term()]
309 Evaluates apply(M, F, A).
311 If the instruction appears before instruction point_of_no_return, a
313 failure is caught. release_handler:install_release/1 then returns
314 {error,{'EXIT',Reason}}, unless {error,Error} is thrown or returned.
315 Then it returns {error,Error}.
316 If the instruction appears after instruction point_of_no_return and the
318 function call fails, the system is restarted.
319 restart_new_emulator
321 This instruction is used when the application ERTS, Kernel, STDLIB, or
323 SASL is upgraded. It shuts down the current emulator and starts a new
324 one. All processes are terminated gracefully, and the new version of
325 ERTS, Kernel, STDLIB, and SASL are used when the emulator restarts.
326 Only one restart_new_emulator instruction is allowed in the relup file,
327 and it must be placed first. systools:make_relup/3,4 ensures this when
328 the relup file is generated. The rest of the instructions in the relup
329 file is executed after the restart as a part of the boot script.
330 An info report is written when the upgrade is completed. To programmat‐
332 ically determine if the upgrade is complete, call release_han‐
333 dler:which_releases/0,1 and check if the expected release has status
334 current.
335 The new release must still be made permanent after the upgrade is com‐
337 pleted, otherwise the old emulator is started if there is an emulator
338 restart.
339 Warning:
341 As stated earlier, instruction restart_new_emulator causes the emulator
342 to be restarted with new versions of ERTS>, Kernel, STDLIB, and SASL.
343 However, all other applications do at startup run their old versions in
344 this new emulator. This is usually no problem, but every now and then
345 incompatible changes occur to the core applications, which can cause
346 trouble in this setting. Such incompatible changes (when functions are
347 removed) are normally preceded by a deprecation over two major
348 releases. To ensure that your application is not crashed by an incom‐
349 patible change, always remove any call to deprecated functions as soon
350 as possible.
351 restart_emulator
354 This instruction is similar to restart_new_emulator, except it must be
356 placed at the end of the relup file. It is not related to an upgrade of
357 the emulator or the core applications, but can be used by any applica‐
358 tion when a complete reboot of the system is required.
359 When generating the relup file, systools:make_relup/3,4 ensures that
361 there is only one restart_emulator instruction and that it is the last
362 instruction in the relup file.
363
365 release_handler(3), relup(4), supervisor(3), systools(3)
366Ericsson AB sasl 3.1.2 appup(5)