Commit aa7b608d authored by Matthew Wood's avatar Matthew Wood Committed by David S. Miller
Browse files

net: netconsole: add docs for appending netconsole user data 



Add a new User Data section to the netconsole docs to describe the
appending of user data capability (for netconsole dynamic configuration)
with usage and netconsole output examples.

Co-developed-by: default avatarBreno Leitao <leitao@debian.org>
Signed-off-by: default avatarBreno Leitao <leitao@debian.org>
Signed-off-by: default avatarMatthew Wood <thepacketgeek@gmail.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent ae001dc6

Documentation/networking/netconsole.rst

+66 −0
Original line number Diff line number Diff line
@@ -15,6 +15,8 @@ Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015 


Release prepend support by Breno Leitao <leitao@debian.org>, Jul 7 2023



Userdata append support by Matthew Wood <thepacketgeek@gmail.com>, Jan 22 2024



Please send bug reports to Matt Mackall <mpm@selenic.com>

Satyam Sharma <satyam.sharma@gmail.com>, and Cong Wang <xiyou.wangcong@gmail.com>
@@ -171,6 +173,70 @@ You can modify these targets in runtime by creating the following targets:: 
 cat cmdline1/remote_ip

 10.0.0.3



Append User Data

----------------



Custom user data can be appended to the end of messages with netconsole

dynamic configuration enabled. User data entries can be modified without

changing the "enabled" attribute of a target.



Directories (keys) under `userdata` are limited to 54 character length, and

data in `userdata/<key>/value` are limited to 200 bytes::



 cd /sys/kernel/config/netconsole && mkdir cmdline0

 cd cmdline0

 mkdir userdata/foo

 echo bar > userdata/foo/value

 mkdir userdata/qux

 echo baz > userdata/qux/value



Messages will now include this additional user data::



 echo "This is a message" > /dev/kmsg



Sends::



 12,607,22085407756,-;This is a message

 foo=bar

 qux=baz



Preview the userdata that will be appended with::



 cd /sys/kernel/config/netconsole/cmdline0/userdata

 for f in `ls userdata`; do echo $f=$(cat userdata/$f/value); done



If a `userdata` entry is created but no data is written to the `value` file,

the entry will be omitted from netconsole messages::



 cd /sys/kernel/config/netconsole && mkdir cmdline0

 cd cmdline0

 mkdir userdata/foo

 echo bar > userdata/foo/value

 mkdir userdata/qux



The `qux` key is omitted since it has no value::



 echo "This is a message" > /dev/kmsg

 12,607,22085407756,-;This is a message

 foo=bar



Delete `userdata` entries with `rmdir`::



 rmdir /sys/kernel/config/netconsole/cmdline0/userdata/qux



.. warning::

   When writing strings to user data values, input is broken up per line in

   configfs store calls and this can cause confusing behavior::



     mkdir userdata/testing

     printf "val1\nval2" > userdata/testing/value

     # userdata store value is called twice, first with "val1\n" then "val2"

     # so "val2" is stored, being the last value stored

     cat userdata/testing/value

     val2



   It is recommended to not write user data values with newlines.



Extended console:

=================