[people/ms/u-boot.git] / doc / README.NetConsole


In U-Boot, we implemented the networked console via the standard
"devices" mechanism, which means that you can switch between the
serial and network input/output devices by adjusting the 'stdin' and
'stdout' environment variables. To switch to the networked console,
set either of these variables to "nc". Input and output can be
switched independently.

We use an environment variable 'ncip' to set the IP address and the
port of the destination. The format is <ip_addr>:<port>. If <port> is
omitted, the value of 6666 is used. If the env var doesn't exist, the
broadcast address and port 6666 are used. If it is set to an IP
address of 0 (or 0.0.0.0) then no messages are sent to the network.

For example, if your server IP is 192.168.1.1, you could use:

	=> setenv nc 'setenv stdout nc;setenv stdin nc'
	=> setenv ncip 192.168.1.1
	=> saveenv
	=> run nc


On the host side, please use this script to access the console:

+++++++++++++++++++++++++++++++++++++++++++
#! /bin/bash

[ $# = 1 ] || { echo "Usage: $0 target_ip" >&2 ; exit 1 ; }
TARGET_IP=$1

stty -icanon -echo intr ^T
nc -u -l -p 6666 < /dev/null &
nc -u ${TARGET_IP} 6666
stty icanon echo intr ^C
+++++++++++++++++++++++++++++++++++++++++++

The script expects exactly one argument, which is interpreted as  the
target IP address (or host name, assuming DNS is working). The script
can be interrupted by pressing ^T (CTRL-T).

Be aware that in some distributives (Fedora Core 5 at least)
usage of nc has been changed and -l and -p options are considered
as mutually exclusive. If nc complains about options provided,
you can just remove the -p option from the script.

It turns out that 'netcat' cannot be used to listen to broadcast
packets. We developed our own tool 'ncb' (see tools directory) that
listens to broadcast packets on a given port and dumps them to the
standard output. use it as follows:

+++++++++++++++++++++++++++++++++++++++++++
#! /bin/bash

[ $# = 1 ] || { echo "Usage: $0 target_ip" >&2 ; exit 1 ; }
TARGET_IP=$1

stty icanon echo intr ^T
./ncb &
nc -u ${TARGET_IP} 6666
stty icanon echo intr ^C
kill 0
+++++++++++++++++++++++++++++++++++++++++++

Again, this script takes exactly one argument, which is interpreted
as the target IP address (or host name, assuming DNS is working). The
script can be interrupted by pressing ^T (CTRL-T).

The 'ncb' tool can be found in the tools directory; it will not be
built by default so you will ither have to adjust the Makefile or
build it manually.


For Linux, the network-based console needs special configuration.
Minimally, the host IP address needs to be specified. This can be
done either via the kernel command line, or by passing parameters
while loading the netconsole.o module (when used in a loadable module
configuration). Please refer to Documentation/networking/logging.txt
file for the original Ingo Molnar's documentation on how to pass
parameters to the loadable module.

The format of the kernel command line parameter (for the static
configuration) is as follows:

  netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]

where

  src-port	source for UDP packets
		(defaults to 6665)
  src-ip	source IP to use
		(defaults to the interface's address)
  dev		network interface
		(defaults to eth0)
  tgt-port	port for logging agent
		(defaults to 6666)
  tgt-ip	IP address for logging agent
		(this is the required parameter)
  tgt-macaddr	ethernet MAC address for logging agent
		(defaults to broadcast)

Examples:

  netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc

or

  netconsole=@/,@192.168.3.1/

Please note that for the Linux networked console to work, the
ethernet interface has to be up by the time the netconsole driver is
initialized. This means that in case of static kernel configuration,
the respective Ethernet interface has to be brought up using the "IP
Autoconfiguration" kernel feature, which is usually done by defaults
in the ELDK-NFS-based environment.

To browse the Linux network console output, use the 'netcat' tool invoked
as follows:

	nc -u -l -p 6666

Note that unlike the U-Boot implementation the Linux netconsole is
unidirectional, i. e. you have console output only in Linux.
Commit	Line	Data
68ceb29e WD	1
	2	In U-Boot, we implemented the networked console via the standard
	3	"devices" mechanism, which means that you can switch between the
	4	serial and network input/output devices by adjusting the 'stdin' and
	5	'stdout' environment variables. To switch to the networked console,
	6	set either of these variables to "nc". Input and output can be
	7	switched independently.
	8
eedcd078 WD	9	We use an environment variable 'ncip' to set the IP address and the
	10	port of the destination. The format is <ip_addr>:<port>. If <port> is
	11	omitted, the value of 6666 is used. If the env var doesn't exist, the
	12	broadcast address and port 6666 are used. If it is set to an IP
	13	address of 0 (or 0.0.0.0) then no messages are sent to the network.
	14
b1bf6f2c WD	15	For example, if your server IP is 192.168.1.1, you could use:
	16
	17	=> setenv nc 'setenv stdout nc;setenv stdin nc'
	18	=> setenv ncip 192.168.1.1
	19	=> saveenv
	20	=> run nc
	21
	22
68ceb29e WD	23	On the host side, please use this script to access the console:
	24
	25	+++++++++++++++++++++++++++++++++++++++++++
	26	#! /bin/bash
	27
b1bf6f2c	28	[ $# = 1 ] \|\| { echo "Usage: $0 target_ip" >&2 ; exit 1 ; }
68ceb29e WD	29	TARGET_IP=$1
	30
	31	stty -icanon -echo intr ^T
	32	nc -u -l -p 6666 < /dev/null &
	33	nc -u ${TARGET_IP} 6666
	34	stty icanon echo intr ^C
	35	+++++++++++++++++++++++++++++++++++++++++++
	36
b1bf6f2c WD	37	The script expects exactly one argument, which is interpreted as the
	38	target IP address (or host name, assuming DNS is working). The script
	39	can be interrupted by pressing ^T (CTRL-T).
	40
443feb74 IM	41	Be aware that in some distributives (Fedora Core 5 at least)
	42	usage of nc has been changed and -l and -p options are considered
	43	as mutually exclusive. If nc complains about options provided,
	44	you can just remove the -p option from the script.
	45
25d6712a	46	It turns out that 'netcat' cannot be used to listen to broadcast
eedcd078 WD	47	packets. We developed our own tool 'ncb' (see tools directory) that
	48	listens to broadcast packets on a given port and dumps them to the
	49	standard output. use it as follows:
	50
	51	+++++++++++++++++++++++++++++++++++++++++++
	52	#! /bin/bash
	53
b1bf6f2c WD	54	[ $# = 1 ] \|\| { echo "Usage: $0 target_ip" >&2 ; exit 1 ; }
	55	TARGET_IP=$1
	56
eedcd078 WD	57	stty icanon echo intr ^T
eedcd078 WD	58	./ncb &
b1bf6f2c	59	nc -u ${TARGET_IP} 6666
eedcd078 WD	60	stty icanon echo intr ^C
	61	kill 0
	62	+++++++++++++++++++++++++++++++++++++++++++
	63
b1bf6f2c WD	64	Again, this script takes exactly one argument, which is interpreted
	65	as the target IP address (or host name, assuming DNS is working). The
	66	script can be interrupted by pressing ^T (CTRL-T).
	67
	68	The 'ncb' tool can be found in the tools directory; it will not be
	69	built by default so you will ither have to adjust the Makefile or
	70	build it manually.
	71
	72
68ceb29e WD	73	For Linux, the network-based console needs special configuration.
	74	Minimally, the host IP address needs to be specified. This can be
	75	done either via the kernel command line, or by passing parameters
	76	while loading the netconsole.o module (when used in a loadable module
	77	configuration). Please refer to Documentation/networking/logging.txt
	78	file for the original Ingo Molnar's documentation on how to pass
	79	parameters to the loadable module.
	80
	81	The format of the kernel command line parameter (for the static
	82	configuration) is as follows:
	83
	84	netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
	85
	86	where
	87
	88	src-port source for UDP packets
	89	(defaults to 6665)
	90	src-ip source IP to use
	91	(defaults to the interface's address)
	92	dev network interface
	93	(defaults to eth0)
	94	tgt-port port for logging agent
	95	(defaults to 6666)
	96	tgt-ip IP address for logging agent
	97	(this is the required parameter)
	98	tgt-macaddr ethernet MAC address for logging agent
	99	(defaults to broadcast)
	100
	101	Examples:
	102
	103	netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc
	104
	105	or
	106
	107	netconsole=@/,@192.168.3.1/
	108
	109	Please note that for the Linux networked console to work, the
	110	ethernet interface has to be up by the time the netconsole driver is
	111	initialized. This means that in case of static kernel configuration,
	112	the respective Ethernet interface has to be brought up using the "IP
	113	Autoconfiguration" kernel feature, which is usually done by defaults
	114	in the ELDK-NFS-based environment.
	115
	116	To browse the Linux network console output, use the 'netcat' tool invoked
	117	as follows:
	118
	119	nc -u -l -p 6666
25d6712a WD	120
	121	Note that unlike the U-Boot implementation the Linux netconsole is
	122	unidirectional, i. e. you have console output only in Linux.