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