blob: 2aa3b9ccc59b79530b4aa169eb2b7e8b900340fa [file] [log] [blame]
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +01001Network console
2===============
wdenk68ceb292004-08-02 21:11:11 +00003
4In U-Boot, we implemented the networked console via the standard
5"devices" mechanism, which means that you can switch between the
6serial and network input/output devices by adjusting the 'stdin' and
7'stdout' environment variables. To switch to the networked console,
8set either of these variables to "nc". Input and output can be
9switched independently.
10
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010011The default buffer size can be overridden by setting
Tom Rini6e7df1d2023-01-10 11:19:45 -050012CFG_NETCONSOLE_BUFFER_SIZE.
Joe Hershberger2c8fe512012-07-31 06:09:17 +000013
wdenkeedcd072004-09-08 22:03:11 +000014We use an environment variable 'ncip' to set the IP address and the
15port of the destination. The format is <ip_addr>:<port>. If <port> is
16omitted, the value of 6666 is used. If the env var doesn't exist, the
17broadcast address and port 6666 are used. If it is set to an IP
18address of 0 (or 0.0.0.0) then no messages are sent to the network.
Joe Hershberger7f518982012-07-31 06:06:41 +000019The source / listening port can be configured separately by setting
20the 'ncinport' environment variable and the destination port can be
21configured by setting the 'ncoutport' environment variable.
wdenkeedcd072004-09-08 22:03:11 +000022
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010023For example, if your server IP is 192.168.1.1, you could use::
wdenkb1bf6f22005-04-03 14:52:59 +000024
25 => setenv nc 'setenv stdout nc;setenv stdin nc'
26 => setenv ncip 192.168.1.1
27 => saveenv
28 => run nc
29
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010030On the host side, please use this script to access the console
wdenkb1bf6f22005-04-03 14:52:59 +000031
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010032.. code-block:: bash
wdenk68ceb292004-08-02 21:11:11 +000033
Mike Frysingerbcb6dd92008-12-09 23:20:31 -050034 tools/netconsole <ip> [port]
wdenk68ceb292004-08-02 21:11:11 +000035
Mike Frysingerbcb6dd92008-12-09 23:20:31 -050036The script uses netcat to talk to the board over UDP. It requires you to
37specify the target IP address (or host name, assuming DNS is working). The
38script can be interrupted by pressing ^T (CTRL-T).
wdenkb1bf6f22005-04-03 14:52:59 +000039
Igor Marnat443feb72007-03-21 09:55:01 +030040Be aware that in some distributives (Fedora Core 5 at least)
41usage of nc has been changed and -l and -p options are considered
42as mutually exclusive. If nc complains about options provided,
43you can just remove the -p option from the script.
44
wdenk25d67122004-12-10 11:40:40 +000045It turns out that 'netcat' cannot be used to listen to broadcast
wdenkeedcd072004-09-08 22:03:11 +000046packets. We developed our own tool 'ncb' (see tools directory) that
47listens to broadcast packets on a given port and dumps them to the
Mike Frysinger1c20e4a2009-09-09 12:20:21 -040048standard output. It will be built when compiling for a board which
49has CONFIG_NETCONSOLE defined. If the netconsole script can find it
50in PATH or in the same directory, it will be used instead.
wdenkb1bf6f22005-04-03 14:52:59 +000051
wdenk68ceb292004-08-02 21:11:11 +000052For Linux, the network-based console needs special configuration.
53Minimally, the host IP address needs to be specified. This can be
54done either via the kernel command line, or by passing parameters
55while loading the netconsole.o module (when used in a loadable module
56configuration). Please refer to Documentation/networking/logging.txt
57file for the original Ingo Molnar's documentation on how to pass
58parameters to the loadable module.
59
60The format of the kernel command line parameter (for the static
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010061configuration) is as follows
wdenk68ceb292004-08-02 21:11:11 +000062
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010063.. code-block:: bash
64
65 netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
wdenk68ceb292004-08-02 21:11:11 +000066
67where
68
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010069src-port
70 source for UDP packets (defaults to 6665)
wdenk68ceb292004-08-02 21:11:11 +000071
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010072src-ip
73 source IP to use (defaults to the interface's address)
74
75dev
76 network interface (defaults to eth0)
77
78tgt-port
79 port for logging agent (defaults to 6666)
80
81tgt-ip
82 IP address for logging agent (this is the required parameter)
83
84tgt-macaddr
85 ethernet MAC address for logging agent (defaults to broadcast)
86
87Examples
88
89.. code-block:: bash
wdenk68ceb292004-08-02 21:11:11 +000090
91 netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc
wdenk68ceb292004-08-02 21:11:11 +000092 netconsole=@/,@192.168.3.1/
93
94Please note that for the Linux networked console to work, the
95ethernet interface has to be up by the time the netconsole driver is
96initialized. This means that in case of static kernel configuration,
97the respective Ethernet interface has to be brought up using the "IP
98Autoconfiguration" kernel feature, which is usually done by defaults
99in the ELDK-NFS-based environment.
100
101To browse the Linux network console output, use the 'netcat' tool invoked
102as follows:
103
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +0100104.. code-block:: bash
105
wdenk68ceb292004-08-02 21:11:11 +0000106 nc -u -l -p 6666
wdenk25d67122004-12-10 11:40:40 +0000107
108Note that unlike the U-Boot implementation the Linux netconsole is
109unidirectional, i. e. you have console output only in Linux.