From: Mauro Carvalho Chehab Date: Thu, 30 Apr 2020 16:04:02 +0000 (+0200) Subject: docs: networking: convert netconsole.txt to ReST X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=d9d6ef25ecab3e10966981bc58d014576da74272;p=linux.git docs: networking: convert netconsole.txt to ReST - add SPDX header; - add a document title; - mark code blocks and literals as such; - mark tables as such; - add notes markups; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index e43f2e1f29584..398c34804bb8f 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -638,7 +638,7 @@ See Documentation/admin-guide/serial-console.rst for more information. See - Documentation/networking/netconsole.txt for an + Documentation/networking/netconsole.rst for an alternative. uart[8250],io,[,options] diff --git a/Documentation/admin-guide/serial-console.rst b/Documentation/admin-guide/serial-console.rst index a8d1e36b627a1..58b32832e50aa 100644 --- a/Documentation/admin-guide/serial-console.rst +++ b/Documentation/admin-guide/serial-console.rst @@ -54,7 +54,7 @@ You will need to create a new device to use ``/dev/console``. The official ``/dev/console`` is now character device 5,1. (You can also use a network device as a console. See -``Documentation/networking/netconsole.txt`` for information on that.) +``Documentation/networking/netconsole.rst`` for information on that.) Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. Replace the sample values as needed. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 492658bf7c0d4..e58f872d401dd 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -80,6 +80,7 @@ Contents: mac80211-injection mpls-sysctl multiqueue + netconsole .. only:: subproject and html diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst new file mode 100644 index 0000000000000..1f5c4a04027c4 --- /dev/null +++ b/Documentation/networking/netconsole.rst @@ -0,0 +1,239 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========== +Netconsole +========== + + +started by Ingo Molnar , 2001.09.17 + +2.6 port and netpoll api by Matt Mackall , Sep 9 2003 + +IPv6 support by Cong Wang , Jan 1 2013 + +Extended console support by Tejun Heo , May 1 2015 + +Please send bug reports to Matt Mackall +Satyam Sharma , and Cong Wang + +Introduction: +============= + +This module logs kernel printk messages over UDP allowing debugging of +problem where disk logging fails and serial consoles are impractical. + +It can be used either built-in or as a module. As a built-in, +netconsole initializes immediately after NIC cards and will bring up +the specified interface as soon as possible. While this doesn't allow +capture of early kernel panics, it does capture most of the boot +process. + +Sender and receiver configuration: +================================== + +It takes a string configuration parameter "netconsole" in the +following format:: + + netconsole=[+][src-port]@[src-ip]/[],[tgt-port]@/[tgt-macaddr] + + where + + if present, enable extended console support + src-port source for UDP packets (defaults to 6665) + src-ip source IP to use (interface address) + dev network interface (eth0) + tgt-port port for logging agent (6666) + tgt-ip IP address for logging agent + tgt-macaddr ethernet MAC address for logging agent (broadcast) + +Examples:: + + linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc + +or:: + + insmod netconsole netconsole=@/,@10.0.0.2/ + +or using IPv6:: + + insmod netconsole netconsole=@/,@fd00:1:2:3::1/ + +It also supports logging to multiple remote agents by specifying +parameters for the multiple agents separated by semicolons and the +complete string enclosed in "quotes", thusly:: + + modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/" + +Built-in netconsole starts immediately after the TCP stack is +initialized and attempts to bring up the supplied dev at the supplied +address. + +The remote host has several options to receive the kernel messages, +for example: + +1) syslogd + +2) netcat + + On distributions using a BSD-based netcat version (e.g. Fedora, + openSUSE and Ubuntu) the listening port must be specified without + the -p switch:: + + nc -u -l -p ' / 'nc -u -l + + or:: + + netcat -u -l -p ' / 'netcat -u -l + +3) socat + +:: + + socat udp-recv: - + +Dynamic reconfiguration: +======================== + +Dynamic reconfigurability is a useful addition to netconsole that enables +remote logging targets to be dynamically added, removed, or have their +parameters reconfigured at runtime from a configfs-based userspace interface. +[ Note that the parameters of netconsole targets that were specified/created +from the boot/module option are not exposed via this interface, and hence +cannot be modified dynamically. ] + +To include this feature, select CONFIG_NETCONSOLE_DYNAMIC when building the +netconsole module (or kernel, if netconsole is built-in). + +Some examples follow (where configfs is mounted at the /sys/kernel/config +mountpoint). + +To add a remote logging target (target names can be arbitrary):: + + cd /sys/kernel/config/netconsole/ + mkdir target1 + +Note that newly created targets have default parameter values (as mentioned +above) and are disabled by default -- they must first be enabled by writing +"1" to the "enabled" attribute (usually after setting parameters accordingly) +as described below. + +To remove a target:: + + rmdir /sys/kernel/config/netconsole/othertarget/ + +The interface exposes these parameters of a netconsole target to userspace: + + ============== ================================= ============ + enabled Is this target currently enabled? (read-write) + extended Extended mode enabled (read-write) + dev_name Local network interface name (read-write) + local_port Source UDP port to use (read-write) + remote_port Remote agent's UDP port (read-write) + local_ip Source IP address to use (read-write) + remote_ip Remote agent's IP address (read-write) + local_mac Local interface's MAC address (read-only) + remote_mac Remote agent's MAC address (read-write) + ============== ================================= ============ + +The "enabled" attribute is also used to control whether the parameters of +a target can be updated or not -- you can modify the parameters of only +disabled targets (i.e. if "enabled" is 0). + +To update a target's parameters:: + + cat enabled # check if enabled is 1 + echo 0 > enabled # disable the target (if required) + echo eth2 > dev_name # set local interface + echo 10.0.0.4 > remote_ip # update some parameter + echo cb:a9:87:65:43:21 > remote_mac # update more parameters + echo 1 > enabled # enable target again + +You can also update the local interface dynamically. This is especially +useful if you want to use interfaces that have newly come up (and may not +have existed when netconsole was loaded / initialized). + +Extended console: +================= + +If '+' is prefixed to the configuration line or "extended" config file +is set to 1, extended console support is enabled. An example boot +param follows:: + + linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc + +Log messages are transmitted with extended metadata header in the +following format which is the same as /dev/kmsg:: + + ,,,; + +Non printable characters in are escaped using "\xff" +notation. If the message contains optional dictionary, verbatim +newline is used as the delimeter. + +If a message doesn't fit in certain number of bytes (currently 1000), +the message is split into multiple fragments by netconsole. These +fragments are transmitted with "ncfrag" header field added:: + + ncfrag=/ + +For example, assuming a lot smaller chunk size, a message "the first +chunk, the 2nd chunk." may be split as follows:: + + 6,416,1758426,-,ncfrag=0/31;the first chunk, + 6,416,1758426,-,ncfrag=16/31; the 2nd chunk. + +Miscellaneous notes: +==================== + +.. Warning:: + + the default target ethernet setting uses the broadcast + ethernet address to send packets, which can cause increased load on + other systems on the same ethernet segment. + +.. Tip:: + + some LAN switches may be configured to suppress ethernet broadcasts + so it is advised to explicitly specify the remote agents' MAC addresses + from the config parameters passed to netconsole. + +.. Tip:: + + to find out the MAC address of, say, 10.0.0.2, you may try using:: + + ping -c 1 10.0.0.2 ; /sbin/arp -n | grep 10.0.0.2 + +.. Tip:: + + in case the remote logging agent is on a separate LAN subnet than + the sender, it is suggested to try specifying the MAC address of the + default gateway (you may use /sbin/route -n to find it out) as the + remote MAC address instead. + +.. note:: + + the network device (eth1 in the above case) can run any kind + of other network traffic, netconsole is not intrusive. Netconsole + might cause slight delays in other traffic if the volume of kernel + messages is high, but should have no other impact. + +.. note:: + + if you find that the remote logging agent is not receiving or + printing all messages from the sender, it is likely that you have set + the "console_loglevel" parameter (on the sender) to only send high + priority messages to the console. You can change this at runtime using:: + + dmesg -n 8 + + or by specifying "debug" on the kernel command line at boot, to send + all kernel messages to the console. A specific value for this parameter + can also be set using the "loglevel" kernel boot option. See the + dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst + for details. + +Netconsole was designed to be as instantaneous as possible, to +enable the logging of even the most critical kernel bugs. It works +from IRQ contexts as well, and does not enable interrupts while +sending packets. Due to these unique needs, configuration cannot +be more automatic, and some fundamental limitations will remain: +only IP networks, UDP packets and ethernet devices are supported. diff --git a/Documentation/networking/netconsole.txt b/Documentation/networking/netconsole.txt deleted file mode 100644 index 296ea00fd3eb6..0000000000000 --- a/Documentation/networking/netconsole.txt +++ /dev/null @@ -1,210 +0,0 @@ - -started by Ingo Molnar , 2001.09.17 -2.6 port and netpoll api by Matt Mackall , Sep 9 2003 -IPv6 support by Cong Wang , Jan 1 2013 -Extended console support by Tejun Heo , May 1 2015 - -Please send bug reports to Matt Mackall -Satyam Sharma , and Cong Wang - -Introduction: -============= - -This module logs kernel printk messages over UDP allowing debugging of -problem where disk logging fails and serial consoles are impractical. - -It can be used either built-in or as a module. As a built-in, -netconsole initializes immediately after NIC cards and will bring up -the specified interface as soon as possible. While this doesn't allow -capture of early kernel panics, it does capture most of the boot -process. - -Sender and receiver configuration: -================================== - -It takes a string configuration parameter "netconsole" in the -following format: - - netconsole=[+][src-port]@[src-ip]/[],[tgt-port]@/[tgt-macaddr] - - where - + if present, enable extended console support - src-port source for UDP packets (defaults to 6665) - src-ip source IP to use (interface address) - dev network interface (eth0) - tgt-port port for logging agent (6666) - tgt-ip IP address for logging agent - tgt-macaddr ethernet MAC address for logging agent (broadcast) - -Examples: - - linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc - - or - - insmod netconsole netconsole=@/,@10.0.0.2/ - - or using IPv6 - - insmod netconsole netconsole=@/,@fd00:1:2:3::1/ - -It also supports logging to multiple remote agents by specifying -parameters for the multiple agents separated by semicolons and the -complete string enclosed in "quotes", thusly: - - modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/" - -Built-in netconsole starts immediately after the TCP stack is -initialized and attempts to bring up the supplied dev at the supplied -address. - -The remote host has several options to receive the kernel messages, -for example: - -1) syslogd - -2) netcat - - On distributions using a BSD-based netcat version (e.g. Fedora, - openSUSE and Ubuntu) the listening port must be specified without - the -p switch: - - 'nc -u -l -p ' / 'nc -u -l ' or - 'netcat -u -l -p ' / 'netcat -u -l ' - -3) socat - - 'socat udp-recv: -' - -Dynamic reconfiguration: -======================== - -Dynamic reconfigurability is a useful addition to netconsole that enables -remote logging targets to be dynamically added, removed, or have their -parameters reconfigured at runtime from a configfs-based userspace interface. -[ Note that the parameters of netconsole targets that were specified/created -from the boot/module option are not exposed via this interface, and hence -cannot be modified dynamically. ] - -To include this feature, select CONFIG_NETCONSOLE_DYNAMIC when building the -netconsole module (or kernel, if netconsole is built-in). - -Some examples follow (where configfs is mounted at the /sys/kernel/config -mountpoint). - -To add a remote logging target (target names can be arbitrary): - - cd /sys/kernel/config/netconsole/ - mkdir target1 - -Note that newly created targets have default parameter values (as mentioned -above) and are disabled by default -- they must first be enabled by writing -"1" to the "enabled" attribute (usually after setting parameters accordingly) -as described below. - -To remove a target: - - rmdir /sys/kernel/config/netconsole/othertarget/ - -The interface exposes these parameters of a netconsole target to userspace: - - enabled Is this target currently enabled? (read-write) - extended Extended mode enabled (read-write) - dev_name Local network interface name (read-write) - local_port Source UDP port to use (read-write) - remote_port Remote agent's UDP port (read-write) - local_ip Source IP address to use (read-write) - remote_ip Remote agent's IP address (read-write) - local_mac Local interface's MAC address (read-only) - remote_mac Remote agent's MAC address (read-write) - -The "enabled" attribute is also used to control whether the parameters of -a target can be updated or not -- you can modify the parameters of only -disabled targets (i.e. if "enabled" is 0). - -To update a target's parameters: - - cat enabled # check if enabled is 1 - echo 0 > enabled # disable the target (if required) - echo eth2 > dev_name # set local interface - echo 10.0.0.4 > remote_ip # update some parameter - echo cb:a9:87:65:43:21 > remote_mac # update more parameters - echo 1 > enabled # enable target again - -You can also update the local interface dynamically. This is especially -useful if you want to use interfaces that have newly come up (and may not -have existed when netconsole was loaded / initialized). - -Extended console: -================= - -If '+' is prefixed to the configuration line or "extended" config file -is set to 1, extended console support is enabled. An example boot -param follows. - - linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc - -Log messages are transmitted with extended metadata header in the -following format which is the same as /dev/kmsg. - - ,,,; - -Non printable characters in are escaped using "\xff" -notation. If the message contains optional dictionary, verbatim -newline is used as the delimeter. - -If a message doesn't fit in certain number of bytes (currently 1000), -the message is split into multiple fragments by netconsole. These -fragments are transmitted with "ncfrag" header field added. - - ncfrag=/ - -For example, assuming a lot smaller chunk size, a message "the first -chunk, the 2nd chunk." may be split as follows. - - 6,416,1758426,-,ncfrag=0/31;the first chunk, - 6,416,1758426,-,ncfrag=16/31; the 2nd chunk. - -Miscellaneous notes: -==================== - -WARNING: the default target ethernet setting uses the broadcast -ethernet address to send packets, which can cause increased load on -other systems on the same ethernet segment. - -TIP: some LAN switches may be configured to suppress ethernet broadcasts -so it is advised to explicitly specify the remote agents' MAC addresses -from the config parameters passed to netconsole. - -TIP: to find out the MAC address of, say, 10.0.0.2, you may try using: - - ping -c 1 10.0.0.2 ; /sbin/arp -n | grep 10.0.0.2 - -TIP: in case the remote logging agent is on a separate LAN subnet than -the sender, it is suggested to try specifying the MAC address of the -default gateway (you may use /sbin/route -n to find it out) as the -remote MAC address instead. - -NOTE: the network device (eth1 in the above case) can run any kind -of other network traffic, netconsole is not intrusive. Netconsole -might cause slight delays in other traffic if the volume of kernel -messages is high, but should have no other impact. - -NOTE: if you find that the remote logging agent is not receiving or -printing all messages from the sender, it is likely that you have set -the "console_loglevel" parameter (on the sender) to only send high -priority messages to the console. You can change this at runtime using: - - dmesg -n 8 - -or by specifying "debug" on the kernel command line at boot, to send -all kernel messages to the console. A specific value for this parameter -can also be set using the "loglevel" kernel boot option. See the -dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst for details. - -Netconsole was designed to be as instantaneous as possible, to -enable the logging of even the most critical kernel bugs. It works -from IRQ contexts as well, and does not enable interrupts while -sending packets. Due to these unique needs, configuration cannot -be more automatic, and some fundamental limitations will remain: -only IP networks, UDP packets and ethernet devices are supported. diff --git a/drivers/net/Kconfig b/drivers/net/Kconfig index c822f4a6d166c..ad64be98330f4 100644 --- a/drivers/net/Kconfig +++ b/drivers/net/Kconfig @@ -302,7 +302,7 @@ config NETCONSOLE tristate "Network console logging support" ---help--- If you want to log kernel messages over the network, enable this. - See for details. + See for details. config NETCONSOLE_DYNAMIC bool "Dynamic reconfiguration of logging targets" @@ -312,7 +312,7 @@ config NETCONSOLE_DYNAMIC This option enables the ability to dynamically reconfigure target parameters (interface, IP addresses, port numbers, MAC addresses) at runtime through a userspace interface exported using configfs. - See for details. + See for details. config NETPOLL def_bool NETCONSOLE diff --git a/drivers/net/ethernet/toshiba/ps3_gelic_net.c b/drivers/net/ethernet/toshiba/ps3_gelic_net.c index 070dd6fa9401a..310e6839c6e54 100644 --- a/drivers/net/ethernet/toshiba/ps3_gelic_net.c +++ b/drivers/net/ethernet/toshiba/ps3_gelic_net.c @@ -1150,7 +1150,7 @@ static irqreturn_t gelic_card_interrupt(int irq, void *ptr) * gelic_net_poll_controller - artificial interrupt for netconsole etc. * @netdev: interface device structure * - * see Documentation/networking/netconsole.txt + * see Documentation/networking/netconsole.rst */ void gelic_net_poll_controller(struct net_device *netdev) { diff --git a/drivers/net/ethernet/toshiba/spider_net.c b/drivers/net/ethernet/toshiba/spider_net.c index 6576271642c14..3902b3aeb0c26 100644 --- a/drivers/net/ethernet/toshiba/spider_net.c +++ b/drivers/net/ethernet/toshiba/spider_net.c @@ -1615,7 +1615,7 @@ spider_net_interrupt(int irq, void *ptr) * spider_net_poll_controller - artificial interrupt for netconsole etc. * @netdev: interface device structure * - * see Documentation/networking/netconsole.txt + * see Documentation/networking/netconsole.rst */ static void spider_net_poll_controller(struct net_device *netdev)