Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | ||
5 | Please send bug reports to Matt Mackall <mpm@selenic.com> | |
0bcc1816 SS |
6 | and Satyam Sharma <satyam.sharma@gmail.com> |
7 | ||
8 | Introduction: | |
9 | ============= | |
1da177e4 LT |
10 | |
11 | This module logs kernel printk messages over UDP allowing debugging of | |
12 | problem where disk logging fails and serial consoles are impractical. | |
13 | ||
14 | It can be used either built-in or as a module. As a built-in, | |
15 | netconsole initializes immediately after NIC cards and will bring up | |
16 | the specified interface as soon as possible. While this doesn't allow | |
17 | capture of early kernel panics, it does capture most of the boot | |
18 | process. | |
19 | ||
0bcc1816 SS |
20 | Sender and receiver configuration: |
21 | ================================== | |
22 | ||
1da177e4 LT |
23 | It takes a string configuration parameter "netconsole" in the |
24 | following format: | |
25 | ||
26 | netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] | |
27 | ||
28 | where | |
29 | src-port source for UDP packets (defaults to 6665) | |
30 | src-ip source IP to use (interface address) | |
31 | dev network interface (eth0) | |
32 | tgt-port port for logging agent (6666) | |
33 | tgt-ip IP address for logging agent | |
34 | tgt-macaddr ethernet MAC address for logging agent (broadcast) | |
35 | ||
36 | Examples: | |
37 | ||
38 | linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc | |
39 | ||
40 | or | |
41 | ||
42 | insmod netconsole netconsole=@/,@10.0.0.2/ | |
43 | ||
b5427c27 SS |
44 | It also supports logging to multiple remote agents by specifying |
45 | parameters for the multiple agents separated by semicolons and the | |
46 | complete string enclosed in "quotes", thusly: | |
47 | ||
48 | modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/" | |
49 | ||
1da177e4 LT |
50 | Built-in netconsole starts immediately after the TCP stack is |
51 | initialized and attempts to bring up the supplied dev at the supplied | |
52 | address. | |
53 | ||
6556bfde DG |
54 | The remote host has several options to receive the kernel messages, |
55 | for example: | |
56 | ||
57 | 1) syslogd | |
58 | ||
59 | 2) netcat | |
60 | ||
61 | On distributions using a BSD-based netcat version (e.g. Fedora, | |
62 | openSUSE and Ubuntu) the listening port must be specified without | |
63 | the -p switch: | |
64 | ||
65 | 'nc -u -l -p <port>' / 'nc -u -l <port>' or | |
66 | 'netcat -u -l -p <port>' / 'netcat -u -l <port>' | |
67 | ||
68 | 3) socat | |
69 | ||
70 | 'socat udp-recv:<port> -' | |
1da177e4 | 71 | |
0bcc1816 SS |
72 | Dynamic reconfiguration: |
73 | ======================== | |
74 | ||
75 | Dynamic reconfigurability is a useful addition to netconsole that enables | |
76 | remote logging targets to be dynamically added, removed, or have their | |
77 | parameters reconfigured at runtime from a configfs-based userspace interface. | |
78 | [ Note that the parameters of netconsole targets that were specified/created | |
79 | from the boot/module option are not exposed via this interface, and hence | |
80 | cannot be modified dynamically. ] | |
81 | ||
82 | To include this feature, select CONFIG_NETCONSOLE_DYNAMIC when building the | |
83 | netconsole module (or kernel, if netconsole is built-in). | |
84 | ||
85 | Some examples follow (where configfs is mounted at the /sys/kernel/config | |
86 | mountpoint). | |
87 | ||
88 | To add a remote logging target (target names can be arbitrary): | |
89 | ||
90 | cd /sys/kernel/config/netconsole/ | |
91 | mkdir target1 | |
92 | ||
93 | Note that newly created targets have default parameter values (as mentioned | |
94 | above) and are disabled by default -- they must first be enabled by writing | |
95 | "1" to the "enabled" attribute (usually after setting parameters accordingly) | |
96 | as described below. | |
97 | ||
98 | To remove a target: | |
99 | ||
100 | rmdir /sys/kernel/config/netconsole/othertarget/ | |
101 | ||
102 | The interface exposes these parameters of a netconsole target to userspace: | |
103 | ||
104 | enabled Is this target currently enabled? (read-write) | |
105 | dev_name Local network interface name (read-write) | |
106 | local_port Source UDP port to use (read-write) | |
107 | remote_port Remote agent's UDP port (read-write) | |
108 | local_ip Source IP address to use (read-write) | |
109 | remote_ip Remote agent's IP address (read-write) | |
110 | local_mac Local interface's MAC address (read-only) | |
111 | remote_mac Remote agent's MAC address (read-write) | |
112 | ||
113 | The "enabled" attribute is also used to control whether the parameters of | |
114 | a target can be updated or not -- you can modify the parameters of only | |
115 | disabled targets (i.e. if "enabled" is 0). | |
116 | ||
117 | To update a target's parameters: | |
118 | ||
119 | cat enabled # check if enabled is 1 | |
120 | echo 0 > enabled # disable the target (if required) | |
121 | echo eth2 > dev_name # set local interface | |
122 | echo 10.0.0.4 > remote_ip # update some parameter | |
123 | echo cb:a9:87:65:43:21 > remote_mac # update more parameters | |
124 | echo 1 > enabled # enable target again | |
125 | ||
126 | You can also update the local interface dynamically. This is especially | |
127 | useful if you want to use interfaces that have newly come up (and may not | |
128 | have existed when netconsole was loaded / initialized). | |
129 | ||
130 | Miscellaneous notes: | |
131 | ==================== | |
132 | ||
1da177e4 LT |
133 | WARNING: the default target ethernet setting uses the broadcast |
134 | ethernet address to send packets, which can cause increased load on | |
135 | other systems on the same ethernet segment. | |
136 | ||
8d4ef88b SS |
137 | TIP: some LAN switches may be configured to suppress ethernet broadcasts |
138 | so it is advised to explicitly specify the remote agents' MAC addresses | |
139 | from the config parameters passed to netconsole. | |
140 | ||
141 | TIP: to find out the MAC address of, say, 10.0.0.2, you may try using: | |
142 | ||
143 | ping -c 1 10.0.0.2 ; /sbin/arp -n | grep 10.0.0.2 | |
144 | ||
145 | TIP: in case the remote logging agent is on a separate LAN subnet than | |
146 | the sender, it is suggested to try specifying the MAC address of the | |
147 | default gateway (you may use /sbin/route -n to find it out) as the | |
148 | remote MAC address instead. | |
149 | ||
1da177e4 LT |
150 | NOTE: the network device (eth1 in the above case) can run any kind |
151 | of other network traffic, netconsole is not intrusive. Netconsole | |
152 | might cause slight delays in other traffic if the volume of kernel | |
153 | messages is high, but should have no other impact. | |
154 | ||
8d4ef88b SS |
155 | NOTE: if you find that the remote logging agent is not receiving or |
156 | printing all messages from the sender, it is likely that you have set | |
157 | the "console_loglevel" parameter (on the sender) to only send high | |
158 | priority messages to the console. You can change this at runtime using: | |
159 | ||
160 | dmesg -n 8 | |
161 | ||
162 | or by specifying "debug" on the kernel command line at boot, to send | |
163 | all kernel messages to the console. A specific value for this parameter | |
164 | can also be set using the "loglevel" kernel boot option. See the | |
165 | dmesg(8) man page and Documentation/kernel-parameters.txt for details. | |
166 | ||
1da177e4 LT |
167 | Netconsole was designed to be as instantaneous as possible, to |
168 | enable the logging of even the most critical kernel bugs. It works | |
169 | from IRQ contexts as well, and does not enable interrupts while | |
84eb8d06 | 170 | sending packets. Due to these unique needs, configuration cannot |
1da177e4 LT |
171 | be more automatic, and some fundamental limitations will remain: |
172 | only IP networks, UDP packets and ethernet devices are supported. |