| @@ -1,7 +1,16 @@ |
| 1 | +.. SPDX-License-Identifier: GPL-2.0 |
| 2 | + |
| 3 | +========== |
| 4 | +Netconsole |
| 5 | +========== |
| 6 | + |
| 1 | 7 | |
| 2 | 8 | started by Ingo Molnar <mingo@redhat.com>, 2001.09.17 |
| 9 | + |
| 3 | 10 | 2.6 port and netpoll api by Matt Mackall <mpm@selenic.com>, Sep 9 2003 |
| 11 | + |
| 4 | 12 | IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013 |
| 13 | + |
| 5 | 14 | Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015 |
| 6 | 15 | |
| 7 | 16 | Please send bug reports to Matt Mackall <mpm@selenic.com> |
| @@ -23,34 +32,34 @@ Sender and receiver configuration: · 15 unmodified lines |
| 23 | 32 | ================================== |
| 24 | 33 | |
| 25 | 34 | It takes a string configuration parameter "netconsole" in the |
| 26 | | −following format: |
| 35 | +following format:: |
| 27 | 36 | |
| 28 | 37 | netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] |
| 29 | 38 | |
| 30 | 39 | 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) |
| 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) |
| 38 | 47 | |
| 39 | | −Examples: |
| 48 | +Examples:: |
| 40 | 49 | |
| 41 | 50 | linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc |
| 42 | 51 | |
| 43 | | − or |
| 52 | +or:: |
| 44 | 53 | |
| 45 | 54 | insmod netconsole netconsole=@/,@10.0.0.2/ |
| 46 | 55 | |
| 47 | | − or using IPv6 |
| 56 | +or using IPv6:: |
| 48 | 57 | |
| 49 | 58 | insmod netconsole netconsole=@/,@fd00:1:2:3::1/ |
| 50 | 59 | |
| 51 | 60 | It also supports logging to multiple remote agents by specifying |
| 52 | 61 | parameters for the multiple agents separated by semicolons and the |
| 53 | | −complete string enclosed in "quotes", thusly: |
| 62 | +complete string enclosed in "quotes", thusly:: |
| 54 | 63 | |
| 55 | 64 | modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/" |
| 56 | 65 | |
| @@ -67,14 +76,19 @@ for example: · 10 unmodified lines |
| 67 | 76 | |
| 68 | 77 | On distributions using a BSD-based netcat version (e.g. Fedora, |
| 69 | 78 | openSUSE and Ubuntu) the listening port must be specified without |
| 70 | | − the -p switch: |
| 79 | + the -p switch:: |
| 80 | + |
| 81 | + nc -u -l -p <port>' / 'nc -u -l <port> |
| 82 | + |
| 83 | + or:: |
| 71 | 84 | |
| 72 | | − 'nc -u -l -p <port>' / 'nc -u -l <port>' or |
| 73 | | − 'netcat -u -l -p <port>' / 'netcat -u -l <port>' |
| 85 | + netcat -u -l -p <port>' / 'netcat -u -l <port> |
| 74 | 86 | |
| 75 | 87 | 3) socat |
| 76 | 88 | |
| 77 | | − 'socat udp-recv:<port> -' |
| 89 | +:: |
| 90 | + |
| 91 | + socat udp-recv:<port> - |
| 78 | 92 | |
| 79 | 93 | Dynamic reconfiguration: |
| 80 | 94 | ======================== |
| @@ -92,7 +106,7 @@ netconsole module (or kernel, if netconsole is built-in). · 11 unmodified lines |
| 92 | 106 | Some examples follow (where configfs is mounted at the /sys/kernel/config |
| 93 | 107 | mountpoint). |
| 94 | 108 | |
| 95 | | −To add a remote logging target (target names can be arbitrary): |
| 109 | +To add a remote logging target (target names can be arbitrary):: |
| 96 | 110 | |
| 97 | 111 | cd /sys/kernel/config/netconsole/ |
| 98 | 112 | mkdir target1 |
| @@ -102,12 +116,13 @@ above) and are disabled by default -- they must first be enabled by writing · 3 unmodified lines |
| 102 | 116 | "1" to the "enabled" attribute (usually after setting parameters accordingly) |
| 103 | 117 | as described below. |
| 104 | 118 | |
| 105 | | −To remove a target: |
| 119 | +To remove a target:: |
| 106 | 120 | |
| 107 | 121 | rmdir /sys/kernel/config/netconsole/othertarget/ |
| 108 | 122 | |
| 109 | 123 | The interface exposes these parameters of a netconsole target to userspace: |
| 110 | 124 | |
| 125 | + ============== ================================= ============ |
| 111 | 126 | enabled Is this target currently enabled? (read-write) |
| 112 | 127 | extended Extended mode enabled (read-write) |
| 113 | 128 | dev_name Local network interface name (read-write) |
| @@ -117,12 +132,13 @@ The interface exposes these parameters of a netconsole target to userspace: · 3 unmodified lines |
| 117 | 132 | remote_ip Remote agent's IP address (read-write) |
| 118 | 133 | local_mac Local interface's MAC address (read-only) |
| 119 | 134 | remote_mac Remote agent's MAC address (read-write) |
| 135 | + ============== ================================= ============ |
| 120 | 136 | |
| 121 | 137 | The "enabled" attribute is also used to control whether the parameters of |
| 122 | 138 | a target can be updated or not -- you can modify the parameters of only |
| 123 | 139 | disabled targets (i.e. if "enabled" is 0). |
| 124 | 140 | |
| 125 | | −To update a target's parameters: |
| 141 | +To update a target's parameters:: |
| 126 | 142 | |
| 127 | 143 | cat enabled # check if enabled is 1 |
| 128 | 144 | echo 0 > enabled # disable the target (if required) |
| @@ -140,12 +156,12 @@ Extended console: · 11 unmodified lines |
| 140 | 156 | |
| 141 | 157 | If '+' is prefixed to the configuration line or "extended" config file |
| 142 | 158 | is set to 1, extended console support is enabled. An example boot |
| 143 | | −param follows. |
| 159 | +param follows:: |
| 144 | 160 | |
| 145 | 161 | linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc |
| 146 | 162 | |
| 147 | 163 | Log messages are transmitted with extended metadata header in the |
| 148 | | −following format which is the same as /dev/kmsg. |
| 164 | +following format which is the same as /dev/kmsg:: |
| 149 | 165 | |
| 150 | 166 | <level>,<sequnum>,<timestamp>,<contflag>;<message text> |
| 151 | 167 | |
| @@ -155,12 +171,12 @@ newline is used as the delimeter. · 3 unmodified lines |
| 155 | 171 | |
| 156 | 172 | If a message doesn't fit in certain number of bytes (currently 1000), |
| 157 | 173 | the message is split into multiple fragments by netconsole. These |
| 158 | | −fragments are transmitted with "ncfrag" header field added. |
| 174 | +fragments are transmitted with "ncfrag" header field added:: |
| 159 | 175 | |
| 160 | 176 | ncfrag=<byte-offset>/<total-bytes> |
| 161 | 177 | |
| 162 | 178 | For example, assuming a lot smaller chunk size, a message "the first |
| 163 | | −chunk, the 2nd chunk." may be split as follows. |
| 179 | +chunk, the 2nd chunk." may be split as follows:: |
| 164 | 180 | |
| 165 | 181 | 6,416,1758426,-,ncfrag=0/31;the first chunk, |
| 166 | 182 | 6,416,1758426,-,ncfrag=16/31; the 2nd chunk. |
| @@ -168,39 +184,52 @@ chunk, the 2nd chunk." may be split as follows. · 1 unmodified line |
| 168 | 184 | Miscellaneous notes: |
| 169 | 185 | ==================== |
| 170 | 186 | |
| 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. |
| 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 |
| 174 | 204 | |
| 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. |
| 205 | +.. Tip:: |
| 178 | 206 | |
| 179 | | −TIP: to find out the MAC address of, say, 10.0.0.2, you may try using: |
| 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. |
| 180 | 211 | |
| 181 | | − ping -c 1 10.0.0.2 ; /sbin/arp -n | grep 10.0.0.2 |
| 212 | +.. note:: |
| 182 | 213 | |
| 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. |
| 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. |
| 187 | 218 | |
| 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. |
| 219 | +.. note:: |
| 192 | 220 | |
| 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: |
| 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:: |
| 197 | 225 | |
| 198 | | − dmesg -n 8 |
| 226 | + dmesg -n 8 |
| 199 | 227 | |
| 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. |
| 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. |
| 204 | 233 | |
| 205 | 234 | Netconsole was designed to be as instantaneous as possible, to |
| 206 | 235 | enable the logging of even the most critical kernel bugs. It works |