About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / netconsole.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 EST.

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