1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==========
4 Netconsole
5 ==========
6
7
8 started by Ingo Molnar <mingo@redhat.com>, 2001
9
10 2.6 port and netpoll api by Matt Mackall <mpm@s
11
12 IPv6 support by Cong Wang <xiyou.wangcong@gmail
13
14 Extended console support by Tejun Heo <tj@kerne
15
16 Release prepend support by Breno Leitao <leitao
17
18 Userdata append support by Matthew Wood <thepac
19
20 Please send bug reports to Matt Mackall <mpm@se
21 Satyam Sharma <satyam.sharma@gmail.com>, and Co
22
23 Introduction:
24 =============
25
26 This module logs kernel printk messages over U
27 problem where disk logging fails and serial co
28
29 It can be used either built-in or as a module.
30 netconsole initializes immediately after NIC c
31 the specified interface as soon as possible. W
32 capture of early kernel panics, it does captur
33 process.
34
35 Sender and receiver configuration:
36 ==================================
37
38 It takes a string configuration parameter "net
39 following format::
40
41 netconsole=[+][r][src-port]@[src-ip]/[<dev>],[
42
43 where
44 + if present, enable exten
45 r if present, prepend kern
46 src-port source for UDP packets (
47 src-ip source IP to use (interf
48 dev network interface (eth0)
49 tgt-port port for logging agent (
50 tgt-ip IP address for logging a
51 tgt-macaddr ethernet MAC address for
52
53 Examples::
54
55 linux netconsole=4444@10.0.0.1/eth1,9353@10.0
56
57 or::
58
59 insmod netconsole netconsole=@/,@10.0.0.2/
60
61 or using IPv6::
62
63 insmod netconsole netconsole=@/,@fd00:1:2:3::
64
65 It also supports logging to multiple remote ag
66 parameters for the multiple agents separated b
67 complete string enclosed in "quotes", thusly::
68
69 modprobe netconsole netconsole="@/,@10.0.0.2/
70
71 Built-in netconsole starts immediately after t
72 initialized and attempts to bring up the suppl
73 address.
74
75 The remote host has several options to receive
76 for example:
77
78 1) syslogd
79
80 2) netcat
81
82 On distributions using a BSD-based netcat v
83 openSUSE and Ubuntu) the listening port mus
84 the -p switch::
85
86 nc -u -l -p <port>' / 'nc -u -l <port>
87
88 or::
89
90 netcat -u -l -p <port>' / 'netcat -u -
91
92 3) socat
93
94 ::
95
96 socat udp-recv:<port> -
97
98 Dynamic reconfiguration:
99 ========================
100
101 Dynamic reconfigurability is a useful addition
102 remote logging targets to be dynamically added
103 parameters reconfigured at runtime from a conf
104
105 To include this feature, select CONFIG_NETCONS
106 netconsole module (or kernel, if netconsole is
107
108 Some examples follow (where configfs is mounte
109 mountpoint).
110
111 To add a remote logging target (target names c
112
113 cd /sys/kernel/config/netconsole/
114 mkdir target1
115
116 Note that newly created targets have default p
117 above) and are disabled by default -- they mus
118 "1" to the "enabled" attribute (usually after
119 as described below.
120
121 To remove a target::
122
123 rmdir /sys/kernel/config/netconsole/othertarg
124
125 The interface exposes these parameters of a ne
126
127 ============== ======================
128 enabled Is this target current
129 extended Extended mode enabled
130 release Prepend kernel release
131 dev_name Local network interfac
132 local_port Source UDP port to use
133 remote_port Remote agent's UDP por
134 local_ip Source IP address to u
135 remote_ip Remote agent's IP addr
136 local_mac Local interface's MAC
137 remote_mac Remote agent's MAC add
138 ============== ======================
139
140 The "enabled" attribute is also used to contro
141 a target can be updated or not -- you can modi
142 disabled targets (i.e. if "enabled" is 0).
143
144 To update a target's parameters::
145
146 cat enabled # chec
147 echo 0 > enabled # disa
148 echo eth2 > dev_name # set
149 echo 10.0.0.4 > remote_ip # upda
150 echo cb:a9:87:65:43:21 > remote_mac # upda
151 echo 1 > enabled # enab
152
153 You can also update the local interface dynami
154 useful if you want to use interfaces that have
155 have existed when netconsole was loaded / init
156
157 Netconsole targets defined at boot time (or mo
158 `netconsole=` param are assigned the name `cmd
159 first target in the parameter is named `cmdlin
160 these targets by creating configfs directories
161
162 Let's suppose you have two netconsole targets
163
164 netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/1
165
166 You can modify these targets in runtime by cre
167
168 mkdir cmdline0
169 cat cmdline0/remote_ip
170 10.0.0.2
171
172 mkdir cmdline1
173 cat cmdline1/remote_ip
174 10.0.0.3
175
176 Append User Data
177 ----------------
178
179 Custom user data can be appended to the end of
180 dynamic configuration enabled. User data entri
181 changing the "enabled" attribute of a target.
182
183 Directories (keys) under `userdata` are limite
184 data in `userdata/<key>/value` are limited to
185
186 cd /sys/kernel/config/netconsole && mkdir cmd
187 cd cmdline0
188 mkdir userdata/foo
189 echo bar > userdata/foo/value
190 mkdir userdata/qux
191 echo baz > userdata/qux/value
192
193 Messages will now include this additional user
194
195 echo "This is a message" > /dev/kmsg
196
197 Sends::
198
199 12,607,22085407756,-;This is a message
200 foo=bar
201 qux=baz
202
203 Preview the userdata that will be appended wit
204
205 cd /sys/kernel/config/netconsole/cmdline0/use
206 for f in `ls userdata`; do echo $f=$(cat user
207
208 If a `userdata` entry is created but no data i
209 the entry will be omitted from netconsole mess
210
211 cd /sys/kernel/config/netconsole && mkdir cmd
212 cd cmdline0
213 mkdir userdata/foo
214 echo bar > userdata/foo/value
215 mkdir userdata/qux
216
217 The `qux` key is omitted since it has no value
218
219 echo "This is a message" > /dev/kmsg
220 12,607,22085407756,-;This is a message
221 foo=bar
222
223 Delete `userdata` entries with `rmdir`::
224
225 rmdir /sys/kernel/config/netconsole/cmdline0/
226
227 .. warning::
228 When writing strings to user data values, i
229 configfs store calls and this can cause con
230
231 mkdir userdata/testing
232 printf "val1\nval2" > userdata/testing/va
233 # userdata store value is called twice, f
234 # so "val2" is stored, being the last val
235 cat userdata/testing/value
236 val2
237
238 It is recommended to not write user data va
239
240 Extended console:
241 =================
242
243 If '+' is prefixed to the configuration line o
244 is set to 1, extended console support is enabl
245 param follows::
246
247 linux netconsole=+4444@10.0.0.1/eth1,9353@10.
248
249 Log messages are transmitted with extended met
250 following format which is the same as /dev/kms
251
252 <level>,<sequnum>,<timestamp>,<contflag>;<mes
253
254 If 'r' (release) feature is enabled, the kerne
255 prepended to the start of the message. Example
256
257 6.4.0,6,444,501151268,-;netconsole: network l
258
259 Non printable characters in <message text> are
260 notation. If the message contains optional dic
261 newline is used as the delimiter.
262
263 If a message doesn't fit in certain number of
264 the message is split into multiple fragments b
265 fragments are transmitted with "ncfrag" header
266
267 ncfrag=<byte-offset>/<total-bytes>
268
269 For example, assuming a lot smaller chunk size
270 chunk, the 2nd chunk." may be split as follows
271
272 6,416,1758426,-,ncfrag=0/31;the first chunk,
273 6,416,1758426,-,ncfrag=16/31; the 2nd chunk.
274
275 Miscellaneous notes:
276 ====================
277
278 .. Warning::
279
280 the default target ethernet setting uses th
281 ethernet address to send packets, which can
282 other systems on the same ethernet segment.
283
284 .. Tip::
285
286 some LAN switches may be configured to supp
287 so it is advised to explicitly specify the
288 from the config parameters passed to netcon
289
290 .. Tip::
291
292 to find out the MAC address of, say, 10.0.0
293
294 ping -c 1 10.0.0.2 ; /sbin/arp -n | gr
295
296 .. Tip::
297
298 in case the remote logging agent is on a se
299 the sender, it is suggested to try specifyi
300 default gateway (you may use /sbin/route -n
301 remote MAC address instead.
302
303 .. note::
304
305 the network device (eth1 in the above case)
306 of other network traffic, netconsole is not
307 might cause slight delays in other traffic
308 messages is high, but should have no other
309
310 .. note::
311
312 if you find that the remote logging agent i
313 printing all messages from the sender, it i
314 the "console_loglevel" parameter (on the se
315 priority messages to the console. You can c
316
317 dmesg -n 8
318
319 or by specifying "debug" on the kernel comm
320 all kernel messages to the console. A speci
321 can also be set using the "loglevel" kernel
322 dmesg(8) man page and Documentation/admin-g
323 for details.
324
325 Netconsole was designed to be as instantaneous
326 enable the logging of even the most critical k
327 from IRQ contexts as well, and does not enable
328 sending packets. Due to these unique needs, co
329 be more automatic, and some fundamental limita
330 only IP networks, UDP packets and ethernet dev
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.