| @@ -1,7 +1,16 @@ |
| | 1 | .. SPDX-License-Identifier: GPL-2.0 |
| | 2 | |
| | 3 | ========== |
| | 4 | Netconsole |
| | 5 | ========== |
| | 6 | |
| 1 | | 7 | |
| 2 | started by Ingo Molnar <mingo@redhat.com>, 2001.09.17 | 8 | started by Ingo Molnar <mingo@redhat.com>, 2001.09.17 |
| | 9 | |
| 3 | 2.6 port and netpoll api by Matt Mackall <mpm@selenic.com>, Sep 9 2003 | 10 | 2.6 port and netpoll api by Matt Mackall <mpm@selenic.com>, Sep 9 2003 |
| | 11 | |
| 4 | IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013 | 12 | IPv6 support by Cong Wang <xiyou.wangcong@gmail.com>, Jan 1 2013 |
| | 13 | |
| 5 | Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015 | 14 | Extended console support by Tejun Heo <tj@kernel.org>, May 1 2015 |
| 6 | | 15 | |
| 7 | Please send bug reports to Matt Mackall <mpm@selenic.com> | 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 | It takes a string configuration parameter "netconsole" in the | 34 | It takes a string configuration parameter "netconsole" in the |
| 26 | following format: | 35 | following format:: |
| 27 | | 36 | |
| 28 | netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] | 37 | netconsole=[+][src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] |
| 29 | | 38 | |
| 30 | where | 39 | where |
| 31 | + if present, enable extended console support | 40 | + if present, enable extended console support |
| 32 | src-port source for UDP packets (defaults to 6665) | 41 | src-port source for UDP packets (defaults to 6665) |
| 33 | src-ip source IP to use (interface address) | 42 | src-ip source IP to use (interface address) |
| 34 | dev network interface (eth0) | 43 | dev network interface (eth0) |
| 35 | tgt-port port for logging agent (6666) | 44 | tgt-port port for logging agent (6666) |
| 36 | tgt-ip IP address for logging agent | 45 | tgt-ip IP address for logging agent |
| 37 | tgt-macaddr ethernet MAC address for logging agent (broadcast) | 46 | tgt-macaddr ethernet MAC address for logging agent (broadcast) |
| 38 | | 47 | |
| 39 | Examples: | 48 | Examples:: |
| 40 | | 49 | |
| 41 | linux netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc | 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 | insmod netconsole netconsole=@/,@10.0.0.2/ | 54 | insmod netconsole netconsole=@/,@10.0.0.2/ |
| 46 | | 55 | |
| 47 | or using IPv6 | 56 | or using IPv6:: |
| 48 | | 57 | |
| 49 | insmod netconsole netconsole=@/,@fd00:1:2:3::1/ | 58 | insmod netconsole netconsole=@/,@fd00:1:2:3::1/ |
| 50 | | 59 | |
| 51 | It also supports logging to multiple remote agents by specifying | 60 | It also supports logging to multiple remote agents by specifying |
| 52 | parameters for the multiple agents separated by semicolons and the | 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 | modprobe netconsole netconsole="@/,@10.0.0.2/;@/eth1,6892@10.0.0.3/" | 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 | On distributions using a BSD-based netcat version (e.g. Fedora, | 77 | On distributions using a BSD-based netcat version (e.g. Fedora, |
| 69 | openSUSE and Ubuntu) the listening port must be specified without | 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 | 85 | netcat -u -l -p <port>' / 'netcat -u -l <port> |
| 73 | 'netcat -u -l -p <port>' / 'netcat -u -l <port>' | | |
| 74 | | 86 | |
| 75 | 3) socat | 87 | 3) socat |
| 76 | | 88 | |
| 77 | 'socat udp-recv:<port> -' | 89 | :: |
| | 90 | |
| | 91 | socat udp-recv:<port> - |
| 78 | | 92 | |
| 79 | Dynamic reconfiguration: | 93 | Dynamic reconfiguration: |
| 80 | ======================== | 94 | ======================== |
| @@ -92,7 +106,7 @@ netconsole module (or kernel, if netconsole is built-in). · 11 unmodified lines |
| 92 | Some examples follow (where configfs is mounted at the /sys/kernel/config | 106 | Some examples follow (where configfs is mounted at the /sys/kernel/config |
| 93 | mountpoint). | 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 | cd /sys/kernel/config/netconsole/ | 111 | cd /sys/kernel/config/netconsole/ |
| 98 | mkdir target1 | 112 | mkdir target1 |
| @@ -102,12 +116,13 @@ above) and are disabled by default -- they must first be enabled by writing · 3 unmodified lines |
| 102 | "1" to the "enabled" attribute (usually after setting parameters accordingly) | 116 | "1" to the "enabled" attribute (usually after setting parameters accordingly) |
| 103 | as described below. | 117 | as described below. |
| 104 | | 118 | |
| 105 | To remove a target: | 119 | To remove a target:: |
| 106 | | 120 | |
| 107 | rmdir /sys/kernel/config/netconsole/othertarget/ | 121 | rmdir /sys/kernel/config/netconsole/othertarget/ |
| 108 | | 122 | |
| 109 | The interface exposes these parameters of a netconsole target to userspace: | 123 | The interface exposes these parameters of a netconsole target to userspace: |
| 110 | | 124 | |
| | 125 | ============== ================================= ============ |
| 111 | enabled Is this target currently enabled? (read-write) | 126 | enabled Is this target currently enabled? (read-write) |
| 112 | extended Extended mode enabled (read-write) | 127 | extended Extended mode enabled (read-write) |
| 113 | dev_name Local network interface name (read-write) | 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 | remote_ip Remote agent's IP address (read-write) | 132 | remote_ip Remote agent's IP address (read-write) |
| 118 | local_mac Local interface's MAC address (read-only) | 133 | local_mac Local interface's MAC address (read-only) |
| 119 | remote_mac Remote agent's MAC address (read-write) | 134 | remote_mac Remote agent's MAC address (read-write) |
| | 135 | ============== ================================= ============ |
| 120 | | 136 | |
| 121 | The "enabled" attribute is also used to control whether the parameters of | 137 | 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 | 138 | a target can be updated or not -- you can modify the parameters of only |
| 123 | disabled targets (i.e. if "enabled" is 0). | 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 | cat enabled # check if enabled is 1 | 143 | cat enabled # check if enabled is 1 |
| 128 | echo 0 > enabled # disable the target (if required) | 144 | echo 0 > enabled # disable the target (if required) |
| @@ -140,12 +156,12 @@ Extended console: · 11 unmodified lines |
| 140 | | 156 | |
| 141 | If '+' is prefixed to the configuration line or "extended" config file | 157 | If '+' is prefixed to the configuration line or "extended" config file |
| 142 | is set to 1, extended console support is enabled. An example boot | 158 | is set to 1, extended console support is enabled. An example boot |
| 143 | param follows. | 159 | param follows:: |
| 144 | | 160 | |
| 145 | linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc | 161 | linux netconsole=+4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc |
| 146 | | 162 | |
| 147 | Log messages are transmitted with extended metadata header in the | 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 | <level>,<sequnum>,<timestamp>,<contflag>;<message text> | 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 | If a message doesn't fit in certain number of bytes (currently 1000), | 172 | If a message doesn't fit in certain number of bytes (currently 1000), |
| 157 | the message is split into multiple fragments by netconsole. These | 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 | ncfrag=<byte-offset>/<total-bytes> | 176 | ncfrag=<byte-offset>/<total-bytes> |
| 161 | | 177 | |
| 162 | For example, assuming a lot smaller chunk size, a message "the first | 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 | 6,416,1758426,-,ncfrag=0/31;the first chunk, | 181 | 6,416,1758426,-,ncfrag=0/31;the first chunk, |
| 166 | 6,416,1758426,-,ncfrag=16/31; the 2nd chunk. | 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 | Miscellaneous notes: | 184 | Miscellaneous notes: |
| 169 | ==================== | 185 | ==================== |
| 170 | | 186 | |
| 171 | WARNING: the default target ethernet setting uses the broadcast | 187 | .. Warning:: |
| 172 | ethernet address to send packets, which can cause increased load on | 188 | |
| 173 | other systems on the same ethernet segment. | 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 | 205 | .. Tip:: |
| 176 | so it is advised to explicitly specify the remote agents' MAC addresses | | |
| 177 | from the config parameters passed to netconsole. | | |
| 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 | 214 | the network device (eth1 in the above case) can run any kind |
| 184 | the sender, it is suggested to try specifying the MAC address of the | 215 | of other network traffic, netconsole is not intrusive. Netconsole |
| 185 | default gateway (you may use /sbin/route -n to find it out) as the | 216 | might cause slight delays in other traffic if the volume of kernel |
| 186 | remote MAC address instead. | 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 | 219 | .. note:: |
| 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 | | 220 | |
| 193 | NOTE: if you find that the remote logging agent is not receiving or | 221 | 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 | 222 | 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 | 223 | the "console_loglevel" parameter (on the sender) to only send high |
| 196 | priority messages to the console. You can change this at runtime using: | 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 | 228 | 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 | 229 | 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 | 230 | 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. | 231 | dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst |
| | 232 | for details. |
| 204 | | 233 | |
| 205 | Netconsole was designed to be as instantaneous as possible, to | 234 | Netconsole was designed to be as instantaneous as possible, to |
| 206 | enable the logging of even the most critical kernel bugs. It works | 235 | enable the logging of even the most critical kernel bugs. It works |