1.. _acrnprobe-conf: 2 3Acrnprobe Configuration 4####################### 5 6Description 7*********** 8``acrnprobe`` uses XML as the format of its configuration file, namely 9``acrnprobe.xml``, following the `XML standard`_. 10 11Layout 12****** 13 14.. code-block:: xml 15 16 <?xml version="1.0" encoding="UTF-8"?> 17 <conf> 18 Root node of configuration. 19 20 <senders> 21 Configuration section of senders. 22 <sender id='1'>Configuration of sender 1</sender> 23 <sender id='2'>Configuration of sender 2</sender> 24 </senders> 25 26 <triggers> 27 Configuration section of triggers. 28 <trigger id='1'>Configuration of trigger 1</trigger> 29 <trigger id='2'>Configuration of trigger 2</trigger> 30 </triggers> 31 32 <vms> 33 Configuration section of virtual machines. 34 <vm id='1'>Configuration of vm 1</vm> 35 <vm id='2'>Configuration of vm 2</vm> 36 </vms> 37 38 <logs> 39 Configuration section of logs. 40 <log id='1'>Configuration of log 1</log> 41 <log id='2'>Configuration of log 2</log> 42 </logs> 43 44 <crashes> 45 Configuration section of crashes. 46 Note that this section must be configured after triggers and logs, as 47 crashes depend on these two sections. 48 <crash id='1'>Configuration of crash 1</crash> 49 <crash id='2'>Configuration of crash 2</crash> 50 </crashes> 51 52 <infos> 53 Configuration section of infos. 54 Note that this section must be configured after triggers and logs, as 55 infos depend on these two sections. 56 <info id='1'>Configuration of info 1</info> 57 <info id='2'>Configuration of info 2</info> 58 </infos> 59 60 </conf> 61 62As for the definition of ``sender``, ``trigger``, ``crash`` and ``info`` 63please refer to :ref:`acrnprobe_doc`. 64 65Properties of Group Members 66*************************** 67 68``acrnprobe`` defined different groups in configuration file, which are 69``senders``, ``triggers``, ``crashes`` and ``infos``. 70 71Common Properties 72================= 73 74- ``id``: 75 The index, which grows from 1 consecutively, in its group. 76- ``enable``: 77 This group member will be ignored if the value is NOT ``true``. 78 79Other Properties 80================ 81 82- ``inherit``: 83 Specify a parent for a certain crash. 84 The child crash will inherit all configurations from the specified (by ID) 85 crash. These inherited configurations could be overwritten by new ones. 86 Also, this property helps build the crash tree in ``acrnprobe``. 87- ``expression``: 88 See `Crash`_. 89 90Crash Tree in Acrnprobe 91*********************** 92 93There could be a parent/child relationship between crashes. Refer to the 94diagrams below, crash B and D are the children of crash A, because crash B and 95D inherit from crash A, and crash C is the child of crash B. 96 97Build Crash Tree in Configuration 98================================= 99 100.. graphviz:: images/crash-config.dot 101 :name: crash-config 102 :align: center 103 :caption: Build crash tree in configuration 104 105Match Crash at Runtime 106====================== 107 108In order to find a more specific type, if one crash type matches 109successfully ``acrnprobe`` will do a match for each child of it (if it has any) 110continually, and return the last successful one. 111About how to determine a match is successful, please refer to the ``content`` of 112`Crash`_. 113 114Supposing these crash trees are like the diagram above at runtime: 115If a crash E is triggered, crash E will be returned immediately. 116If a crash A is triggered, then the candidates are crash A, B, C and D. 117The following diagram describes what ``acrnprobe`` will do if the matched 118result is crash D. 119 120.. graphviz:: images/crash-match.dot 121 :name: crash-match 122 :align: center 123 :caption: Match crash at runtime 124 125Sections 126******** 127 128Sender 129====== 130 131Example: 132 133.. code-block:: xml 134 135 <sender id="1" enable="true"> 136 <name>crashlog</name> 137 <outdir>/var/log/crashlog</outdir> 138 <maxcrashdirs>1000</maxcrashdirs> 139 <maxlines>5000</maxlines> 140 <spacequota>90</spacequota> 141 <uptime> 142 <name>UPTIME</name> 143 <frequency>5</frequency> 144 <eventhours>6</eventhours> 145 </uptime> 146 </sender> 147 148* ``name``: 149 Name of sender. ``acrnprobe`` uses this label to distinguish different 150 senders. 151 For more information about sender, please refer to :ref:`acrnprobe_doc`. 152* ``outdir``: 153 Directory to store generated files of sender. ``acrnprobe`` will create 154 this directory if it doesn't exist. 155* ``maxcrashdirs``: 156 The maximum serial number of generated ``crash directories``, 157 ``stat directories`` and ``vmevent directories``. The serial number will be 158 reset to 0 if it reaches the specified maximum (``maxcrashdirs``). 159 Only used by sender crashlog. 160* ``maxlines``: 161 If the number of lines in the ``history_event`` file reaches the specified 162 ``maxlines``, the ``history_event`` file will be renamed to 163 ``history_event.bak`` and logging will continue with a now empty 164 ``history_event`` file. 165* ``spacequota``: 166 ``acrnprobe`` will stop collecting logs if 167 ``(used space / total space) * 100 > spacequota``. Only used by sender 168 crashlog. 169* ``uptime``: 170 Configuration to trigger ``UPTIME`` event. 171 sub-nodes: 172 173 + ``name``: 174 The name of event. 175 + ``frequency``: 176 Time interval in seconds to trigger ``uptime`` event. 177 + ``eventhours``: 178 Time interval in hours to generate a record. 179 180 181Trigger 182======= 183 184Example: 185 186.. code-block:: xml 187 188 <trigger id="1" enable="true"> 189 <name>t_pstore</name> 190 <type>node</type> 191 <path>/sys/fs/pstore/console-ramoops-0</path> 192 </trigger> 193 <trigger id="2" enable="true"> 194 <name>t_acrnlog_last</name> 195 <type>file</type> 196 <path>/var/log/acrnlog/acrnlog_last.[*]</path> 197 </trigger> 198 199* ``name``: 200 The name of trigger. It's used by crash and info configuration module. 201* ``type`` and ``path``: 202 These two labels are used to get the content of trigger files. 203 ``type`` have been implemented: 204 205 + ``node``: 206 It means that ``path`` is a device node on virtual file system, which cannot 207 support ``mmap(2)-like`` operations. ``acrnprobe`` can use only ``read(2)`` 208 to get its content. 209 + ``file``: 210 It means that ``path`` is a regular file which supports ``mmap(2)-like`` 211 operations. 212 + ``dir``: 213 It means that ``path`` is a directory. 214 + ``rebootreason``: 215 It means that the trigger's content is the reboot reason of system. The 216 content of ``rebootreason`` is not obtained in a common way. So, it doesn't 217 work with ``path``. 218 + ``cmd``: 219 It means that ``path`` is a command which will be launched by ``execvp(3)``. 220 221 Some programs often use format ``string%d`` instead of static file name to 222 generate target file dynamically. So ``path`` supports simple formats for 223 these cases: 224 225 + /.../dir/string[*] --> all files with prefix "string" under dir. 226 + /.../dir/string[0] --> the first file of files, sorted by ``alphasort(3)``, 227 with prefix "string" under dir. 228 + /.../dir/string[-1] --> the last file of files, sorted by ``alphasort(3)``, 229 with prefix "string" under dir. 230 231 Example of formats: 232 If there are 4 files under ``/tmp``: 233 ``acrnlog_last.1`` ``acrnlog_last.2`` ``acrnlog_last.3`` ``other.txt`` 234 235 + ``/var/log/acrnlog/acrnlog_last.[-1]`` indicates ``acrnlog_last.3``. 236 + ``/var/log/acrnlog/acrnlog_last.[0]`` indicates ``acrnlog_last.1``. 237 + ``/var/log/acrnlog/acrnlog_last.[*]`` indicates the file set including 238 ``acrnlog_last.1``, ``acrnlog_last.2`` and ``acrnlog_last.3``. 239 240 241Vm 242== 243 244Example: 245 246.. code-block:: xml 247 248 <vm id="1" enable="true"> 249 <name>VM1</name> 250 <channel>polling</channel> 251 <interval>60</interval> 252 <syncevent id="1">CRASH/TOMBSTONE</syncevent> 253 <syncevent id="2">CRASH/UIWDT</syncevent> 254 <syncevent id="3">CRASH/IPANIC</syncevent> 255 <syncevent id="4">REBOOT</syncevent> 256 </vm> 257 258* ``name``: 259 The name of virtual machine. 260* ``channel``: 261 The ``channel`` name to get the virtual machine events. 262* ``interval``: 263 Time interval in seconds of polling VM's image. 264* ``syncevent``: 265 Event type ``acrnprobe`` will synchronize from virtual machine's ``crashlog``. 266 User could specify different types by ID. The event type can also be 267 indicated by ``type/subtype``. 268 269Log 270=== 271 272Example: 273 274.. code-block:: xml 275 276 <log id="1" enable="true"> 277 <name>pstore</name> 278 <type>node</type> 279 <path>/sys/fs/pstore/console-ramoops-0</path> 280 </log> 281 282* ``name``: 283 By default, ``acrnprobe`` will take this ``name`` as generated log's name in 284 ``outdir`` of sender crashlog. 285 If ``path`` is specified by simple formats (includes [*], [0] or [-1]) the 286 file name of generated logs will be the same as original. More details about 287 simple formats, see `Trigger`_. 288* ``type`` and ``path``: 289 Same as `Trigger`_. 290* ``lines``: 291 By default, all contents in the original will be copied to generated log. 292 If this label is configured, only the ``lines`` at the end in the original 293 will be copied to the generated log. It takes effect only when the ``type`` is 294 ``file``. 295 296Crash 297===== 298 299Example: 300 301.. code-block:: xml 302 303 <crash id='1' inherit='0' enable='true'> 304 <name>UNKNOWN</name> 305 <trigger>t_rebootreason</trigger> 306 <channel>oneshot</channel> 307 <content id='1'>WARM</content> 308 <log id='1'>pstore</log> 309 <log id='2'>acrnlog_last</log> 310 </crash> 311 <crash id='2' inherit='1' enable='true'> 312 <name>IPANIC</name> 313 <trigger>t_pstore</trigger> 314 <content id='1'> </content> 315 <mightcontent expression='1' id='1'>Kernel panic - not syncing:</mightcontent> 316 <mightcontent expression='1' id='2'>BUG: unable to handle kernel</mightcontent> 317 <data id='1'>kernel BUG at</data> 318 <data id='2'>EIP is at</data> 319 <data id='3'>Comm:</data> 320 </crash> 321 322* ``name``: 323 The type of the ``crash``. 324* ``trigger``: 325 The trigger name of the crash. 326* ``channel``: 327 The name of channel crash use. 328* ``content`` and ``mightcontent``: 329 They're used to match crash type. The match is successful if all the 330 following conditions are met: 331 332 a. All ``contents`` with different ``ids`` are included in trigger's 333 content. 334 b. One of ``mightcontents`` with the same ``expression`` is included in 335 trigger's content at least. 336 c. If there are ``mightcontents`` with different ``expressions``, each group 337 with the same ``expression`` should meet condition b. 338* ``log``: 339 The log to be collected. The value is the configured ``name`` in log module. 340 User could specify different logs by ``id``. 341* ``data``: 342 It is used to generate ``DATA`` fields in ``crashfile``. ``acrnprobe`` will 343 copy the line which starts with configured ``data`` in trigger's content 344 to ``DATA`` fields. There are 3 fields in ``crashfile`` and they could be 345 specified by ``id`` 1, 2, 3. 346 347Info 348===== 349 350Example: 351 352.. code-block:: xml 353 354 <info id='1' enable='true'> 355 <name>BOOT_LOGS</name> 356 <trigger>t_boot</trigger> 357 <channel>oneshot</channel> 358 <log id='1'>kmsg</log> 359 <log id='2'>cmdline</log> 360 <log id='3'>acrnlog_cur</log> 361 <log id='4'>acrnlog_last</log> 362 </info> 363 364* ``name``: 365 The type of info. 366* ``trigger``: 367 The trigger name of the info. 368* ``channel``: 369 The name of channel info use. 370* ``log``: 371 The log to be collected. The value is the configured name in log module. User 372 could specify different logs by ID. 373 374.. _`XML standard`: http://www.w3.org/TR/REC-xml 375