docs: networking: convert netconsole.txt to ReST

			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,<addr>[,options]

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

   mac80211-injection

   mpls-sysctl

   multiqueue

   netconsole

.. only::  subproject and html

.. SPDX-License-Identifier: GPL-2.0

==========

Netconsole

==========

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

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

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

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

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

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]

	tgt-ip        IP address for logging agent

	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

  or

or::

 insmod netconsole netconsole=@/,@10.0.0.2/

  or using IPv6

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:

complete string enclosed in "quotes", thusly::

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

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

   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

   'socat udp-recv:<port> -'

::

   socat udp-recv:<port> -

Dynamic reconfiguration:

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

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

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/

 mkdir target1

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

as described below.

To remove a target:

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)

	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:

To update a target's parameters::

 cat enabled				# check if enabled is 1

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

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.

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.

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

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

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.

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

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

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=16/31; the 2nd chunk.

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

   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

   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

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

   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

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

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

   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.

   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

	tristate "Network console logging support"

	---help---

	  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

	bool "Dynamic reconfiguration of logging targets"

	  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 <file:Documentation/networking/netconsole.txt> for details.

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

config NETPOLL

	def_bool NETCONSOLE