mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-29 13:53:33 +00:00
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 <mchehab+huawei@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
parent
e98aa68223
commit
d9d6ef25ec
7 changed files with 84 additions and 54 deletions
|
@ -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]
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -80,6 +80,7 @@ Contents:
|
||||||
mac80211-injection
|
mac80211-injection
|
||||||
mpls-sysctl
|
mpls-sysctl
|
||||||
multiqueue
|
multiqueue
|
||||||
|
netconsole
|
||||||
|
|
||||||
.. only:: subproject and html
|
.. only:: subproject and html
|
||||||
|
|
||||||
|
|
|
@ -1,7 +1,16 @@
|
||||||
|
.. 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>
|
||||||
'netcat -u -l -p <port>' / 'netcat -u -l <port>'
|
|
||||||
|
or::
|
||||||
|
|
||||||
|
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::
|
||||||
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
|
the default target ethernet setting uses the broadcast
|
||||||
so it is advised to explicitly specify the remote agents' MAC addresses
|
ethernet address to send packets, which can cause increased load on
|
||||||
from the config parameters passed to netconsole.
|
other systems on the same ethernet segment.
|
||||||
|
|
||||||
TIP: to find out the MAC address of, say, 10.0.0.2, you may try using:
|
.. 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
|
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::
|
||||||
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
|
in case the remote logging agent is on a separate LAN subnet than
|
||||||
of other network traffic, netconsole is not intrusive. Netconsole
|
the sender, it is suggested to try specifying the MAC address of the
|
||||||
might cause slight delays in other traffic if the volume of kernel
|
default gateway (you may use /sbin/route -n to find it out) as the
|
||||||
messages is high, but should have no other impact.
|
remote MAC address instead.
|
||||||
|
|
||||||
NOTE: if you find that the remote logging agent is not receiving or
|
.. note::
|
||||||
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 network device (eth1 in the above case) can run any kind
|
||||||
priority messages to the console. You can change this at runtime using:
|
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
|
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
|
|
@ -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
|
||||||
|
|
|
@ -1150,7 +1150,7 @@ static irqreturn_t gelic_card_interrupt(int irq, void *ptr)
|
||||||
* gelic_net_poll_controller - artificial interrupt for netconsole etc.
|
* gelic_net_poll_controller - artificial interrupt for netconsole etc.
|
||||||
* @netdev: interface device structure
|
* @netdev: interface device structure
|
||||||
*
|
*
|
||||||
* see Documentation/networking/netconsole.txt
|
* see Documentation/networking/netconsole.rst
|
||||||
*/
|
*/
|
||||||
void gelic_net_poll_controller(struct net_device *netdev)
|
void gelic_net_poll_controller(struct net_device *netdev)
|
||||||
{
|
{
|
||||||
|
|
|
@ -1615,7 +1615,7 @@ spider_net_interrupt(int irq, void *ptr)
|
||||||
* spider_net_poll_controller - artificial interrupt for netconsole etc.
|
* spider_net_poll_controller - artificial interrupt for netconsole etc.
|
||||||
* @netdev: interface device structure
|
* @netdev: interface device structure
|
||||||
*
|
*
|
||||||
* see Documentation/networking/netconsole.txt
|
* see Documentation/networking/netconsole.rst
|
||||||
*/
|
*/
|
||||||
static void
|
static void
|
||||||
spider_net_poll_controller(struct net_device *netdev)
|
spider_net_poll_controller(struct net_device *netdev)
|
||||||
|
|
Loading…
Reference in a new issue