1.. SPDX-License-Identifier: GPL-2.0
2
3==========
4Netconsole
5==========
6
7
8started by Ingo Molnar <mingo@redhat.com>, 2001.09.17
9
102.6 port and netpoll api by Matt Mackall <mpm@selenic.com>, Sep 9 2003
11
12IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013
13
14Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015
15
16Please send bug reports to Matt Mackall <mpm@selenic.com>
17Satyam Sharma <satyam.sharma@gmail.com>, and Cong Wang <xiyou.wangcong@gmail.com>
18
19Introduction:
20=============
21
22This module logs kernel printk messages over UDP allowing debugging of
23problem where disk logging fails and serial consoles are impractical.
24
25It can be used either built-in or as a module. As a built-in,
26netconsole initializes immediately after NIC cards and will bring up
27the specified interface as soon as possible. While this doesn't allow
28capture of early kernel panics, it does capture most of the boot
29process.
30
31Sender and receiver configuration:
32==================================
33
34It takes a string configuration parameter "netconsole" in the
35following format::
36
37 netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
38
39   where
40	+             if present, enable extended console support
41	src-port      source for UDP packets (defaults to 6665)
42	src-ip        source IP to use (interface address)
43	dev           network interface (eth0)
44	tgt-port      port for logging agent (6666)
45	tgt-ip        IP address for logging agent
46	tgt-macaddr   ethernet MAC address for logging agent (broadcast)
47
48Examples::
49
50 linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc
51
52or::
53
54 insmod netconsole netconsole=@/,@10.0.0.2/
55
56or using IPv6::
57
58 insmod netconsole netconsole=@/,@fd00:1:2:3::1/
59
60It also supports logging to multiple remote agents by specifying
61parameters for the multiple agents separated by semicolons and the
62complete string enclosed in "quotes", thusly::
63
64 modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/"
65
66Built-in netconsole starts immediately after the TCP stack is
67initialized and attempts to bring up the supplied dev at the supplied
68address.
69
70The remote host has several options to receive the kernel messages,
71for example:
72
731) syslogd
74
752) netcat
76
77   On distributions using a BSD-based netcat version (e.g. Fedora,
78   openSUSE and Ubuntu) the listening port must be specified without
79   the -p switch::
80
81	nc -u -l -p <port>' / 'nc -u -l <port>
82
83    or::
84
85	netcat -u -l -p <port>' / 'netcat -u -l <port>
86
873) socat
88
89::
90
91   socat udp-recv:<port> -
92
93Dynamic reconfiguration:
94========================
95
96Dynamic reconfigurability is a useful addition to netconsole that enables
97remote logging targets to be dynamically added, removed, or have their
98parameters reconfigured at runtime from a configfs-based userspace interface.
99[ Note that the parameters of netconsole targets that were specified/created
100from the boot/module option are not exposed via this interface, and hence
101cannot be modified dynamically. ]
102
103To include this feature, select CONFIG_NETCONSOLE_DYNAMIC when building the
104netconsole module (or kernel, if netconsole is built-in).
105
106Some examples follow (where configfs is mounted at the /sys/kernel/config
107mountpoint).
108
109To add a remote logging target (target names can be arbitrary)::
110
111 cd /sys/kernel/config/netconsole/
112 mkdir target1
113
114Note that newly created targets have default parameter values (as mentioned
115above) and are disabled by default -- they must first be enabled by writing
116"1" to the "enabled" attribute (usually after setting parameters accordingly)
117as described below.
118
119To remove a target::
120
121 rmdir /sys/kernel/config/netconsole/othertarget/
122
123The interface exposes these parameters of a netconsole target to userspace:
124
125	==============  =================================       ============
126	enabled		Is this target currently enabled?	(read-write)
127	extended	Extended mode enabled			(read-write)
128	dev_name	Local network interface name		(read-write)
129	local_port	Source UDP port to use			(read-write)
130	remote_port	Remote agent's UDP port			(read-write)
131	local_ip	Source IP address to use		(read-write)
132	remote_ip	Remote agent's IP address		(read-write)
133	local_mac	Local interface's MAC address		(read-only)
134	remote_mac	Remote agent's MAC address		(read-write)
135	==============  =================================       ============
136
137The "enabled" attribute is also used to control whether the parameters of
138a target can be updated or not -- you can modify the parameters of only
139disabled targets (i.e. if "enabled" is 0).
140
141To update a target's parameters::
142
143 cat enabled				# check if enabled is 1
144 echo 0 > enabled			# disable the target (if required)
145 echo eth2 > dev_name			# set local interface
146 echo 10.0.0.4 > remote_ip		# update some parameter
147 echo cb:a9:87:65:43:21 > remote_mac	# update more parameters
148 echo 1 > enabled			# enable target again
149
150You can also update the local interface dynamically. This is especially
151useful if you want to use interfaces that have newly come up (and may not
152have existed when netconsole was loaded / initialized).
153
154Extended console:
155=================
156
157If '+' is prefixed to the configuration line or "extended" config file
158is set to 1, extended console support is enabled. An example boot
159param follows::
160
161 linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc
162
163Log messages are transmitted with extended metadata header in the
164following format which is the same as /dev/kmsg::
165
166 <level>,<sequnum>,<timestamp>,<contflag>;<message text>
167
168Non printable characters in <message text> are escaped using "\xff"
169notation. If the message contains optional dictionary, verbatim
170newline is used as the delimiter.
171
172If a message doesn't fit in certain number of bytes (currently 1000),
173the message is split into multiple fragments by netconsole. These
174fragments are transmitted with "ncfrag" header field added::
175
176 ncfrag=<byte-offset>/<total-bytes>
177
178For example, assuming a lot smaller chunk size, a message "the first
179chunk, the 2nd chunk." may be split as follows::
180
181 6,416,1758426,-,ncfrag=0/31;the first chunk,
182 6,416,1758426,-,ncfrag=16/31; the 2nd chunk.
183
184Miscellaneous notes:
185====================
186
187.. Warning::
188
189   the default target ethernet setting uses the broadcast
190   ethernet address to send packets, which can cause increased load on
191   other systems on the same ethernet segment.
192
193.. Tip::
194
195   some LAN switches may be configured to suppress ethernet broadcasts
196   so it is advised to explicitly specify the remote agents' MAC addresses
197   from the config parameters passed to netconsole.
198
199.. Tip::
200
201   to find out the MAC address of, say, 10.0.0.2, you may try using::
202
203	ping -c 1 10.0.0.2 ; /sbin/arp -n | grep 10.0.0.2
204
205.. Tip::
206
207   in case the remote logging agent is on a separate LAN subnet than
208   the sender, it is suggested to try specifying the MAC address of the
209   default gateway (you may use /sbin/route -n to find it out) as the
210   remote MAC address instead.
211
212.. note::
213
214   the network device (eth1 in the above case) can run any kind
215   of other network traffic, netconsole is not intrusive. Netconsole
216   might cause slight delays in other traffic if the volume of kernel
217   messages is high, but should have no other impact.
218
219.. note::
220
221   if you find that the remote logging agent is not receiving or
222   printing all messages from the sender, it is likely that you have set
223   the "console_loglevel" parameter (on the sender) to only send high
224   priority messages to the console. You can change this at runtime using::
225
226	dmesg -n 8
227
228   or by specifying "debug" on the kernel command line at boot, to send
229   all kernel messages to the console. A specific value for this parameter
230   can also be set using the "loglevel" kernel boot option. See the
231   dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst
232   for details.
233
234Netconsole was designed to be as instantaneous as possible, to
235enable the logging of even the most critical kernel bugs. It works
236from IRQ contexts as well, and does not enable interrupts while
237sending packets. Due to these unique needs, configuration cannot
238be more automatic, and some fundamental limitations will remain:
239only IP networks, UDP packets and ethernet devices are supported.
240