Commit d9d6ef25 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files

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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent e98aa682

Documentation/admin-guide/kernel-parameters.txt

+1 −1
Original line number Original line Diff line number Diff line
@@ -638,7 +638,7 @@ 




			See Documentation/admin-guide/serial-console.rst for more

			See Documentation/admin-guide/serial-console.rst for more

			information.  See

			information.  See

			Documentation/networking/netconsole.txt for an

			Documentation/networking/netconsole.rst for an

			alternative.

			alternative.





		uart[8250],io,<addr>[,options]

		uart[8250],io,<addr>[,options]

Documentation/admin-guide/serial-console.rst

+1 −1
Original line number Original line Diff line number Diff line
@@ -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.

``/dev/console`` is now character device 5,1.





(You can also use a network device as a console.  See

(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.

Here's an example that will use ``/dev/ttyS1`` (COM2) as the console.

Replace the sample values as needed.

Replace the sample values as needed.

Documentation/networking/index.rst

+1 −0
Original line number Original line Diff line number Diff line
@@ -80,6 +80,7 @@ Contents: 
   mac80211-injection

   mac80211-injection

   mpls-sysctl

   mpls-sysctl

   multiqueue

   multiqueue

   netconsole





.. only::  subproject and html

.. only::  subproject and html

Documentation/networking/netconsole.txt→Documentation/networking/netconsole.rst

+77 −48
Original line number Original line Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



==========

Netconsole

==========







started by Ingo Molnar <mingo@redhat.com>, 2001.09.17

started by Ingo Molnar <mingo@redhat.com>, 2001.09.17



2.6 port and netpoll api by Matt Mackall <mpm@selenic.com>, Sep 9 2003

2.6 port and netpoll api by Matt Mackall <mpm@selenic.com>, Sep 9 2003



IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013

IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013



Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015

Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015





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

Please send bug reports to Matt Mackall <mpm@selenic.com>
@@ -23,7 +32,7 @@ Sender and receiver configuration: 
==================================

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





It takes a string configuration parameter "netconsole" in the

It takes a string configuration parameter "netconsole" in the

following format:

following format::





 netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]

 netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
@@ -36,21 +45,21 @@ following format: 
	tgt-ip        IP address for logging agent

	tgt-ip        IP address for logging agent

	tgt-macaddr   ethernet MAC address for logging agent (broadcast)

	tgt-macaddr   ethernet MAC address for logging agent (broadcast)





Examples:

Examples::





 linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc

 linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc





  or

or::





 insmod netconsole netconsole=@/,@10.0.0.2/

 insmod netconsole netconsole=@/,@10.0.0.2/





  or using IPv6

or using IPv6::





 insmod netconsole netconsole=@/,@fd00:1:2:3::1/

 insmod netconsole netconsole=@/,@fd00:1:2:3::1/





It also supports logging to multiple remote agents by specifying

It also supports logging to multiple remote agents by specifying

parameters for the multiple agents separated by semicolons and the

parameters for the multiple agents separated by semicolons and the

complete string enclosed in "quotes", thusly:

complete string enclosed in "quotes", thusly::





 modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/"

 modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/"
@@ -67,14 +76,19 @@ for example: 




   On distributions using a BSD-based netcat version (e.g. Fedora,

   On distributions using a BSD-based netcat version (e.g. Fedora,

   openSUSE and Ubuntu) the listening port must be specified without

   openSUSE and Ubuntu) the listening port must be specified without

   the -p switch:

   the -p switch::



	nc -u -l -p <port>' / 'nc -u -l <port>



    or::





   'nc -u -l -p <port>' / 'nc -u -l <port>' or

	netcat -u -l -p <port>' / 'netcat -u -l <port>

   'netcat -u -l -p <port>' / 'netcat -u -l <port>'





3) socat

3) socat





   'socat udp-recv:<port> -'

::



   socat udp-recv:<port> -





Dynamic reconfiguration:

Dynamic reconfiguration:

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

========================
@@ -92,7 +106,7 @@ netconsole module (or kernel, if netconsole is built-in). 
Some examples follow (where configfs is mounted at the /sys/kernel/config

Some examples follow (where configfs is mounted at the /sys/kernel/config

mountpoint).

mountpoint).





To add a remote logging target (target names can be arbitrary):

To add a remote logging target (target names can be arbitrary)::





 cd /sys/kernel/config/netconsole/

 cd /sys/kernel/config/netconsole/

 mkdir target1

 mkdir target1
@@ -102,12 +116,13 @@ above) and are disabled by default -- they must first be enabled by writing 
"1" to the "enabled" attribute (usually after setting parameters accordingly)

"1" to the "enabled" attribute (usually after setting parameters accordingly)

as described below.

as described below.





To remove a target:

To remove a target::





 rmdir /sys/kernel/config/netconsole/othertarget/

 rmdir /sys/kernel/config/netconsole/othertarget/





The interface exposes these parameters of a netconsole target to userspace:

The interface exposes these parameters of a netconsole target to userspace:





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

	enabled		Is this target currently enabled?	(read-write)

	enabled		Is this target currently enabled?	(read-write)

	extended	Extended mode enabled			(read-write)

	extended	Extended mode enabled			(read-write)

	dev_name	Local network interface name		(read-write)

	dev_name	Local network interface name		(read-write)
@@ -117,12 +132,13 @@ The interface exposes these parameters of a netconsole target to userspace: 
	remote_ip	Remote agent's IP address		(read-write)

	remote_ip	Remote agent's IP address		(read-write)

	local_mac	Local interface's MAC address		(read-only)

	local_mac	Local interface's MAC address		(read-only)

	remote_mac	Remote agent's MAC address		(read-write)

	remote_mac	Remote agent's MAC address		(read-write)

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





The "enabled" attribute is also used to control whether the parameters of

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

a target can be updated or not -- you can modify the parameters of only

disabled targets (i.e. if "enabled" is 0).

disabled targets (i.e. if "enabled" is 0).





To update a target's parameters:

To update a target's parameters::





 cat enabled				# check if enabled is 1

 cat enabled				# check if enabled is 1

 echo 0 > enabled			# disable the target (if required)

 echo 0 > enabled			# disable the target (if required)
@@ -140,12 +156,12 @@ Extended console: 




If '+' is prefixed to the configuration line or "extended" config file

If '+' is prefixed to the configuration line or "extended" config file

is set to 1, extended console support is enabled. An example boot

is set to 1, extended console support is enabled. An example boot

param follows.

param follows::





 linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc

 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

Log messages are transmitted with extended metadata header in the

following format which is the same as /dev/kmsg.

following format which is the same as /dev/kmsg::





 <level>,<sequnum>,<timestamp>,<contflag>;<message text>

 <level>,<sequnum>,<timestamp>,<contflag>;<message text>
@@ -155,12 +171,12 @@ newline is used as the delimeter. 




If a message doesn't fit in certain number of bytes (currently 1000),

If a message doesn't fit in certain number of bytes (currently 1000),

the message is split into multiple fragments by netconsole. These

the message is split into multiple fragments by netconsole. These

fragments are transmitted with "ncfrag" header field added.

fragments are transmitted with "ncfrag" header field added::





 ncfrag=<byte-offset>/<total-bytes>

 ncfrag=<byte-offset>/<total-bytes>





For example, assuming a lot smaller chunk size, a message "the first

For example, assuming a lot smaller chunk size, a message "the first

chunk, the 2nd chunk." may be split as follows.

chunk, the 2nd chunk." may be split as follows::





 6,416,1758426,-,ncfrag=0/31;the first chunk,

 6,416,1758426,-,ncfrag=0/31;the first chunk,

 6,416,1758426,-,ncfrag=16/31; the 2nd chunk.

 6,416,1758426,-,ncfrag=16/31; the 2nd chunk.
@@ -168,39 +184,52 @@ chunk, the 2nd chunk." may be split as follows. 
Miscellaneous notes:

Miscellaneous notes:

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

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





WARNING: the default target ethernet setting uses the broadcast

.. Warning::



   the default target ethernet setting uses the broadcast

   ethernet address to send packets, which can cause increased load on

   ethernet address to send packets, which can cause increased load on

   other systems on the same ethernet segment.

   other systems on the same ethernet segment.





TIP: some LAN switches may be configured to suppress ethernet broadcasts

.. Tip::



   some LAN switches may be configured to suppress ethernet broadcasts

   so it is advised to explicitly specify the remote agents' MAC addresses

   so it is advised to explicitly specify the remote agents' MAC addresses

   from the config parameters passed to netconsole.

   from the config parameters passed to netconsole.





TIP: to find out the MAC address of, say, 10.0.0.2, you may try using:

.. 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

	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

.. 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

   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

   default gateway (you may use /sbin/route -n to find it out) as the

   remote MAC address instead.

   remote MAC address instead.





NOTE: the network device (eth1 in the above case) can run any kind

.. note::



   the network device (eth1 in the above case) can run any kind

   of other network traffic, netconsole is not intrusive. Netconsole

   of other network traffic, netconsole is not intrusive. Netconsole

   might cause slight delays in other traffic if the volume of kernel

   might cause slight delays in other traffic if the volume of kernel

   messages is high, but should have no other impact.

   messages is high, but should have no other impact.





NOTE: if you find that the remote logging agent is not receiving or

.. 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

   printing all messages from the sender, it is likely that you have set

   the "console_loglevel" parameter (on the sender) to only send high

   the "console_loglevel" parameter (on the sender) to only send high

priority messages to the console. You can change this at runtime using:

   priority messages to the console. You can change this at runtime using::





	dmesg -n 8

	dmesg -n 8





   or by specifying "debug" on the kernel command line at boot, to send

   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

   all kernel messages to the console. A specific value for this parameter

   can also be set using the "loglevel" kernel boot option. See the

   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.

   dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst

   for details.





Netconsole was designed to be as instantaneous as possible, to

Netconsole was designed to be as instantaneous as possible, to

enable the logging of even the most critical kernel bugs. It works

enable the logging of even the most critical kernel bugs. It works

drivers/net/Kconfig

+2 −2
Original line number Original line Diff line number Diff line
@@ -302,7 +302,7 @@ config NETCONSOLE 
	tristate "Network console logging support"

	tristate "Network console logging support"

	---help---

	---help---

	  If you want to log kernel messages over the network, enable this.

	  If you want to log kernel messages over the network, enable this.

	  See <file:Documentation/networking/netconsole.txt> for details.

	  See <file:Documentation/networking/netconsole.rst> for details.





config NETCONSOLE_DYNAMIC

config NETCONSOLE_DYNAMIC

	bool "Dynamic reconfiguration of logging targets"

	bool "Dynamic reconfiguration of logging targets"
@@ -312,7 +312,7 @@ config NETCONSOLE_DYNAMIC 
	  This option enables the ability to dynamically reconfigure target

	  This option enables the ability to dynamically reconfigure target

	  parameters (interface, IP addresses, port numbers, MAC addresses)

	  parameters (interface, IP addresses, port numbers, MAC addresses)

	  at runtime through a userspace interface exported using configfs.

	  at runtime through a userspace interface exported using configfs.

	  See <file:Documentation/networking/netconsole.txt> for details.

	  See <file:Documentation/networking/netconsole.rst> for details.





config NETPOLL

config NETPOLL

	def_bool NETCONSOLE

	def_bool NETCONSOLE