[RFC][PATCH -mm take5 7/7] update documentation

From: Keiichi KII
Date: Wed Jun 13 2007 - 06:32:30 EST

From: Keiichi KII <k-keiichi@xxxxxxxxxxxxx>

update Documentation/networking/netconsole.txt
- how to use sysfs for dynamic configurability
- how to use ioctl for dynamic configurability

Signed-off-by: Keiichi KII <k-keiichi@xxxxxxxxxxxxx>
Index: mm/Documentation/networking/netconsole.txt
--- mm.orig/Documentation/networking/netconsole.txt
+++ mm/Documentation/networking/netconsole.txt
@@ -4,6 +4,9 @@ started by Ingo Molnar <mingo@xxxxxxxxxx

Please send bug reports to Matt Mackall <mpm@xxxxxxxxxxx>

+1. Description
This module logs kernel printk messages over UDP allowing debugging of
problem where disk logging fails and serial consoles are impractical.

@@ -13,6 +16,21 @@ the specified interface as soon as possi
capture of early kernel panics, it does capture most of the boot

+This module equips the runtime configurability that can changes
+values(src/tgt IP address and port, tgt MAC address) by using sysfs
+and can add/remove logging agent by using ioctls.
+In order to use the runtime configurability, you have to enable
+CONFIG_NETCONSOLE_DYNCON. If you don't use one, you don't have to enable
+CONFIG_NETCONSOLE_DYNCON. By disabling this option, The kernel module
+size is smaller than the module enabled CONFIG_NETCONSOLE_DYNCON.
+2. Configuration
+2.1 Module Parameter(sender side)
It takes a string configuration parameter "netconsole" in the
following format:

@@ -34,12 +52,21 @@ Examples:

insmod netconsole netconsole=@/,@

+Or it also takes a semi-colon separated configuration parameter.
+In the case, you can send kerenl messages to multiple logging agents.
+ netconsole=<target1>;<target2>;<target3>
+ each target is the above configuration parameter.
+ netconsole="@/,6666@xxxxxxxx/;@/,6666@xxxxxxxx/"
Built-in netconsole starts immediately after the TCP stack is
initialized and attempts to bring up the supplied dev at the supplied

-The remote host can run either 'netcat -u -l -p <port>' or syslogd.
WARNING: the default target ethernet setting uses the broadcast
ethernet address to send packets, which can cause increased load on
other systems on the same ethernet segment.
@@ -55,3 +82,83 @@ from IRQ contexts as well, and does not
sending packets. Due to these unique needs, configuration cannot
be more automatic, and some fundamental limitations will remain:
only IP networks, UDP packets and ethernet devices are supported.
+2.2 Receiver side
+The remote host can run either 'netcat -u -l -p <port>' or syslogd.
+3 Dynamic Configurability
+You can make use of the dynamic configurability if
+CONFIG_NETCONSOLE_DYNCON is enabled. The operations are the following.
+3.1 /sys/class/misc/netconsole
+This entry, "netconsole", has the following attributes related to
+netconsole. You can change configuration of netconsole(writable
+attributes such as IP address, port number and so on) and check
+current configuration of netconsole.
+-+- /sys/class/misc/
+ |-+- netconsole/
+ |-+- port1/
+ | |--- enabled [rw-r--r--] 0:disable 1:enable
+ | |--- id [r--r--r--] unique port id
+ | |--- local_ip [rw-r--r--] source IP to use
+ | |--- local_mac [r--r--r--] source MAC address
+ | |--- local_port [rw-r--r--] source port number for UDP packets
+ | |--- net:<netdev> [r--r--r--] symlink to net_dev: eth0,eth1,...
+ | |--- remote_ip [rw-r--r--] port number for logging agent
+ | |--- remote_mac [rw-r--r--] MAC address for logging agent
+ | +--- remote_port [rw-r--r--] IP address for logging agent
+ |--- port2/
+ |--- port3/
+ ...
+If "enabled" attribute of certain port is '1', this port is used
+and the configurations of this port are uable to change.
+If "enabled" attribute of certain port is '0', this port isn't used
+and the configurations of this port are able to change.
+3.2 ioctls
+1. create device file
+First of all, we would like you to check the entry, "/proc/devices",
+in procfs because of creating device file for netconsole.
+If you can find the entry, "netcon" and that major number, create
+the device file using mknod command.
+2. send commands using ioctl system call
+You can send the following ioctl commands to the above device file.
+- NETCONSOLE_ADD_TARGET ioctl adds netconsole target
+In the case of module parameter,
+ netconsole=6665@xxxxxxxx/eth0,6666@xxxxxxxx/12:34:56:78:9a:bc
+In the case of ioclt command,
+ struct netconsole_request req = {
+ .netdev_name = "eth0",
+ .local_ip = inet_addr(""),
+ .local_port = 6665,
+ .remote_ip = inet_addr(""),
+ .remote_port = 6666,
+ .remote_mac = {0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc},
+ };
+ ioctl(fd, NETCON_ADD_TARGET, &req)
+The above patterns mean the same thing.
+- NETCONSOLE_REMOVE_TARGET ioctl removes netconsole target.
+ ioctl(fd, NETCON_REMOVE_TARGET, &id)
+The above "id" is port number in /sys/class/misc/netconsole.
+For example, The "id" is 1 for /sys/class/misc/netconsole/port1.


To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/