1MAKEDUMPFILE.CONF(5) Linux System Administrator's Manual MAKEDUMPFILE.CONF(5)
2
6 makedumpfile.conf - The filter configuration file for makedumpfile(8).
7
9 The makedumpfile.conf is a configuration file for makedumpfile tool.
10 makedumpfile.conf file contains the erase commands to filter out
11 desired kernel data from the vmcore while creating DUMPFILE using make‐
12 dumpfile tool. makedumpfile reads the filter config and builds the
13 list of memory addresses and its sizes after processing filter com‐
14 mands. The memory locations that require to be filtered out are then
15 poisoned with character X (58 in Hex).
16
18 The file consists of module sections that contains filter commands. A
19 section begins with the name of the section in square brackets and con‐
20 tinues until the next section begins.
21 "["<ModuleName>"]"
23 <FilterCommands>
24 where
26 "[" is the character [
27 "]" is the character ]
28 <ModuleName>
30 is either 'vmlinux' or name of a Linux kernel module.
31 <FilterCommands>
33 is a list of one or more filter commands as described in the
34 section FILTER COMMANDS of this manual page.
35 The section name indicates a kernel module name (including vmlinux)
37 where the symbols specified in subsequent erase commands belong to. The
38 unnamed section defaults to [vmlinux] section. However, a user can also
39 explicitly define [vmlinux] section. The sections help makedumpfile
40 tool to select appropriate kernel or module debuginfo file before pro‐
41 cessing the subsequent erase commands. Before selecting appropriate
42 debuginfo file, the module name is validated against the loaded modules
43 from the vmcore. If no match is found, then the section is ignored and
44 makedumpfile skips to the next module section. If match is found, then
45 makedumpfile will try to load the corresponding module debuginfo file.
46 If module debuginfo is not available then, makedumpfile will skip the
47 section with a warning message.
48
50 filter command
51 A filter command is either an erase command or a loop construct. Each
52 erase command and loop construct must start with a new line. Each fil‐
53 ter command describes data in the dump to be erased. Syntax:
54 <EraseCommands>|<LoopConstruct>
56 where
58 <EraseCommands>
60 Described in the subsection erase command of this manual page.
61 <LoopConstruct>
63 Described in the subsection Loop construct of this manual page.
64 erase command
66 Erase specified size of a kernel data referred by specified kernel/mod‐
67 ule symbol or its member component. The erase command syntax is:
68 erase <Symbol>[.member[...]] [size <SizeValue>[K|M]]
70 erase <Symbol>[.member[...]] [size <SizeSymbol>]
71 erase <Symbol>[.member[...]] [nullify]
72 where
74 <Symbol>
76 A kernel or module symbol (variable) name that is part of global
77 symbols /proc/kallsyms.
78 <SizeValue>
80 A positive integer value as a size of the data in bytes to be
81 erased. The suffixes 'K' and 'M' can be used to specify kilo‐
82 bytes and Megabytes respectively where, K means 1024 bytes and M
83 means 1024 ^ 2 = 1048576 bytes. The suffixes are not case sen‐
84 sitive.
85 <SizeSymbol>
87 A simple expression of the form <Symbol>[.member[...]] that
88 denotes a symbol which contains a positive integer value as a
89 size of the data in bytes to be erased.
90 <Symbol>[.member[...]]
92 A simple expression that results into either a global kernel
93 symbol name or its member components. The expression always uses
94 '.' operator to specify the member component of kernel symbol or
95 its member irrespective of whether it is of pointer type or not.
96 member[...]
98 Member or component of member in <Symbol>.
99 The erase command takes two arguments 1. kernel symbol name or its mem‐
101 ber components and 2. size of the data referred by argument (1) OR nul‐
102 lify keyword. The second argument size OR nullify is optional. The unit
103 for size value is in bytes. If size option is not specified then the
104 size of the first argument is determined according to its data type
105 using dwarf info from debuginfo file. In case of 'char *' data type,
106 the length of string pointed by 'char *' pointer is determined with an
107 upper limit of 1024. The size can be specified in two forms 1. a inte‐
108 ger value as explained above (<SizeValue>) and 2. a simple expression
109 in the form of <Symbol>[.member[...]]] that results into base type
110 (integer) variable.
111 If the specified <Symbol> is of type 'void *', then user needs to pro‐
113 vide either size or nullify option, otherwise the erase command will
114 not have any effect.
115 The nullify option only works if specified <Symbol> is a pointer.
117 Instead of erasing data pointed by the specified pointer nullify erases
118 the pointer value and set it to '0' (NULL). Please note that by nulli‐
119 fying the pointer values may affect the debug ability of created DUMP‐
120 FILE. Use the nullify option only when the size of data to be erased
121 is not known. e.g. data pointed by 'void *'.
122 Let us look at the makedumpfile.conf file from the example below which
124 was configured to erase desired kernel data from the kernel module with
125 name mymodule. At line 1 and 3, the user has not specified size option
126 while erasing 'array_var' and 'mystruct1.name' symbols. Instead the
127 user depends on makedumpfile to automatically determine the sizes to be
128 erased i.e 100 bytes for 'array_var' and 11 bytes for 'mystruct1.name'.
129 At line 2, while erasing the 'mystruct1.buffer' member the user has
130 specified the size value 25 against the actual size of 50. In this case
131 the user specified size takes the precedence and makedumpfile erases
132 only 25 bytes from ´mystruct1.buffer'. At line 4, the size of the data
133 pointed by void * pointer 'mystruct1.addr' is unknown. Hence the nul‐
134 lify option has been specified to reset the pointer value to NULL. At
135 line 5, the ´mystruct2.addr_size' is specified as size argument to
136 determine the size of the data pointed by void * pointer 'mys‐
137 truct2.addr'.
138 Example:
140 Assuming the following piece of code is from kernel module 'mymodule':
142 struct s1 {
144 char *name;
145 void *addr1;
146 void *addr2;
147 char buffer[50];
148 };
149 struct s2 {
150 void *addr;
151 long addr_size;
152 };
153 /* Global symbols */
155 char array_var[100];
156 struct s1 mystruct1;
157 struct s2 *mystruct2;
158 int foo()
160 {
161 ...
162 s1.name = "Hello World";
163 ...
164 }
165 makedumpfile.conf:
167 [mymodule]
168 erase array_var
169 erase mystruct1.buffer size 25
170 erase mystruct1.name
171 erase mystruct1.addr1 nullify
172 # Assuming addr2 points to 1024 bytes
173 erase mystruct1.addr2 size 1K
174 erase mystruct2.addr size mystruct2.addr_size
175 EOF
176 Loop construct
179 A Loop construct allows the user to traverse the linked list or array
180 elements and erase the data contents referred by each element.
181 for <id> in {<ArrayVar> |
183 <StructVar> via <NextMember> |
184 <ListHeadVar> within <StructName>:<ListHeadMember>}
185 erase <id>[.MemberExpression] [size <SizeExpression>|nullify]
186 [erase <id>...]
187 [...]
188 endfor
189 where
191 <id> Arbitrary name used to temporarily point to elements of the
193 list. This is also called iteration variable.
194 <ArrayVar>
196 A simple expression in the form of <Symbol>[.member[...]] that
197 results into an array variable.
198 <StructVar>
200 A simple expression in the form of <Symbol>[.member[...]] that
201 results into a variable that points to a structure.
202 <NextMember>
204 Member within <StructVar> that points to an object of same type
205 that of <StructVar>.
206 <ListHeadVar>
208 A simple expression in the form of <Symbol>[.member[...]] that
209 results into a variable of type struct list_head.
210 <StructName>
212 Name of the structure type that can be traversed using HEAD
213 variable <ListHeadVar> and contains a member named <ListHeadMem‐
214 ber>.
215 <ListHeadMember>
217 Name of a member in <StructName>, of type struct list_head.
218 <MemberExpression>
220 A simple expression in the form of [.member[...]] to specify a
221 member or component of an element in <ArrayVar>, <StructVar> or
222 <StructName>.
223 <SizeExpression>
225 Size value in the form of <SizeValue>, <id>[.MemberExpression]
226 or <Symbol>[.member[...]].
227 The for loop construct allows to iterate on list of elements in an
229 array or linked lists. Each element in the list is assigned to itera‐
230 tion variable <id>. The type of the iteration variable is determined by
231 that of the list elements. The entry specified after 'in' terminal is
232 called LIST entry. The LIST entry can be an array variable, structure
233 variable/pointer or a struct list_head type variable. The set of erase
234 commands specified between for and endfor, will be executed for each
235 element in the LIST entry.
236 If the LIST entry specified is an array variable, then the loop will be
238 executed for each array element. The size of the array will be deter‐
239 mined by using dwarf information.
240 If the LIST entry specified is a structure variable/pointer, then a
242 traversal member (<NextMember>) must be specified using 'via' terminal.
243 The for loop will continue until the value of traversal member is NULL
244 or matches with address of the first node <StructVar> if it is a circu‐
245 lar linked list.
246 If the LIST entry is specified using a struct list_head type variable,
248 then within terminal must be used to specify the structure name
249 <StructName> that is surrounding to it along with the struct list_head
250 type member after ':' which is part of the linked list. In the erase
251 statement <id> then denotes the structure that the list_head is con‐
252 tained in (ELEMENT_OF).
253 The below example illustrates how to use loop construct for traversing
255 Array, linked list via next member and list_head.
256 Example:
258 Assuming following piece of code is from kernel module 'mymodule':
260 struct s1 {
262 struct *next;
263 struct list_head list;
264 char private[100];
265 void *key;
266 long key_size;
267 };
268 /* Global symbols */
270 struct s1 mystruct1;
271 static LIST_HEAD(s1_list_head);
272 struct s1 myarray[100];
273 void foo()
275 {
276 struct s1 *s1_ptr;
277 ...
278 ...
279 s1_ptr = malloc(...);
280 ...
281 ...
282 list_add(&s1_ptr->list, &s1_list_head);
283 ...
284 }
285 makedumpfile.conf:
287 [mymodule]
288 # erase private fields from list starting with mystruct1 connected via
289 # 'next' member:
290 for mys1 in mystruct1 via next
291 erase mys1.private
292 erase mys1.key size mys1.key_size
293 endfor
294 # erase private fields from list starting with list_head variable
296 # s1_list_head.
297 for mys1 in s1_list_head.next within s1:list
298 erase mys1.private
299 erase mys1.key size mys1.key_size
300 endfor
301 # erase private fields from all elements of the array myarray:
303 for mys1 in myarray
304 erase mys1.private
305 erase mys1.key size mys1.key_size
306 endfor
307 EOF
308 In the above example, the first for construct traverses the linked list
310 through a specified structure variable mystruct1 of type struct s1.
311 The linked list can be traversed using 'next' member of mystruct1.
312 Hence a via terminal has been used to specify the traversal member name
313 'next'.
314 The second for construct traverses the linked list through a specified
316 struct list_head variable s1_list_head.next. The global symbol
317 s1_list_head is a start address of the linked list and its next member
318 points to the address of struct list_head type member 'list' from
319 struct s1. Hence a within terminal is used to specify the structure
320 name 's1' that can be traversed using s1_list_head.next variable along
321 with the name of struct list_head type member 'list' which is part of
322 the linked list that starts from s1_list_head global symbol.
323 The third for construct traverses the array elements specified through
325 a array variable myarray.
326
328 makedumpfile(8)
329makedumpfile v1.6.8 16 Nov 2020 MAKEDUMPFILE.CONF(5)