1MAKEDUMPFILE.CONF(5)  Linux System Administrator's Manual MAKEDUMPFILE.CONF(5)
2
3
4

NAME

6       makedumpfile.conf - The filter configuration file for makedumpfile(8).
7

DESCRIPTION

9       The  makedumpfile.conf  is  a configuration file for makedumpfile tool.
10       makedumpfile.conf file contains the erase commands to  filter  out  de‐
11       sired  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

FILE FORMAT

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
22       "["<ModuleName>"]"
23       <FilterCommands>
24
25       where
26       "[" is the character [
27       "]" is the character ]
28
29       <ModuleName>
30              is either 'vmlinux' or name of a Linux kernel module.
31
32       <FilterCommands>
33              is  a  list  of  one or more filter commands as described in the
34              section FILTER COMMANDS of this manual page.
35
36       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 de‐
42       buginfo 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

FILTER COMMANDS

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
55       <EraseCommands>|<LoopConstruct>
56
57       where
58
59       <EraseCommands>
60              Described in the subsection erase command of this manual page.
61
62       <LoopConstruct>
63              Described in the subsection Loop construct of this manual page.
64
65   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
69       erase <Symbol>[.member[...]] [size <SizeValue>[K|M]]
70       erase <Symbol>[.member[...]] [size <SizeSymbol>]
71       erase <Symbol>[.member[...]] [nullify]
72
73       where
74
75       <Symbol>
76              A kernel or module symbol (variable) name that is part of global
77              symbols /proc/kallsyms.
78
79       <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
86       <SizeSymbol>
87              A  simple expression of the form <Symbol>[.member[...]] that de‐
88              notes a symbol which contains a positive integer value as a size
89              of the data in bytes to be erased.
90
91       <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
97       member[...]
98              Member or component of member in <Symbol>.
99
100       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 us‐
105       ing  dwarf info from debuginfo file. In case of 'char *' data type, the
106       length of string pointed by 'char *' pointer is determined with an  up‐
107       per limit of 1024. The size can be specified in two forms 1.  a integer
108       value as explained above (<SizeValue>) and 2. a  simple  expression  in
109       the  form of <Symbol>[.member[...]]] that results into base type (inte‐
110       ger) variable.
111
112       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
116       The nullify option only works if specified <Symbol> is a pointer.   In‐
117       stead  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
123       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 de‐
136       termine  the  size  of  the  data  pointed  by  void  *  pointer  'mys‐
137       truct2.addr'.
138
139       Example:
140
141       Assuming the following piece of code is from kernel module 'mymodule':
142
143       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
154       /* Global symbols */
155       char array_var[100];
156       struct s1 mystruct1;
157       struct s2 *mystruct2;
158
159       int foo()
160       {
161            ...
162            s1.name = "Hello World";
163            ...
164       }
165
166       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
177
178   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
182       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
190       where
191
192       <id>   Arbitrary name used to temporarily  point  to  elements  of  the
193              list. This is also called iteration variable.
194
195       <ArrayVar>
196              A  simple  expression in the form of <Symbol>[.member[...]] that
197              results into an array variable.
198
199       <StructVar>
200              A simple expression in the form of  <Symbol>[.member[...]]  that
201              results into a variable that points to a structure.
202
203       <NextMember>
204              Member  within <StructVar> that points to an object of same type
205              that of <StructVar>.
206
207       <ListHeadVar>
208              A simple expression in the form of  <Symbol>[.member[...]]  that
209              results into a variable of type struct list_head.
210
211       <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
216       <ListHeadMember>
217              Name of a member in <StructName>, of type struct list_head.
218
219       <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
224       <SizeExpression>
225              Size  value  in the form of <SizeValue>, <id>[.MemberExpression]
226              or <Symbol>[.member[...]].
227
228       The for loop construct allows to iterate on list of elements in an  ar‐
229       ray  or linked lists. Each element in the list is assigned to iteration
230       variable <id>. The type of the iteration variable is determined by that
231       of the list elements. The entry specified after 'in' terminal is called
232       LIST entry. The LIST entry can be an array  variable,  structure  vari‐
233       able/pointer or a struct list_head type variable. The set of erase com‐
234       mands specified between for and endfor, will be executed for each  ele‐
235       ment in the LIST entry.
236
237       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
241       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
247       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
254       The below example illustrates how to use loop construct for  traversing
255       Array, linked list via next member and list_head.
256
257       Example:
258
259       Assuming following piece of code is from kernel module 'mymodule':
260
261       struct s1 {
262            struct *next;
263            struct list_head list;
264            char private[100];
265            void *key;
266            long key_size;
267       };
268
269       /* Global symbols */
270       struct s1 mystruct1;
271       static LIST_HEAD(s1_list_head);
272       struct s1 myarray[100];
273
274       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
286       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
295       # 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
302       # 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
309       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
315       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
324       The third for construct traverses the array elements specified  through
325       a array variable myarray.
326

SEE ALSO

328       makedumpfile(8)
329
330
331
332
333makedumpfile v1.7.0               8 Nov 2021              MAKEDUMPFILE.CONF(5)
Impressum