blob: df27b78342f38acd21281f118e97beb534ec9b06 [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
Fiona Klute7c531822024-05-18 12:47:06 +02006serial and network input/output devices by adjusting the 'stdin',
7'stdout', and 'stderr' environment variables. To switch to the
8networked console, set either of these variables to "nc". Input and
9output can be switched independently.
wdenk68ceb292004-08-02 21:11:11 +000010
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
Fiona Klute5a116722024-05-18 12:47:05 +020021configured by setting the 'ncoutport' environment variable. Note that
22you need to set up the network interface (e.g. using DHCP) before it
23can be used for network console.
wdenkeedcd072004-09-08 22:03:11 +000024
Fiona Klute7c531822024-05-18 12:47:06 +020025For example, if your server IP is 192.168.1.1, you could use:
wdenkb1bf6f22005-04-03 14:52:59 +000026
Fiona Klute7c531822024-05-18 12:47:06 +020027.. prompt:: bash =>
28
29 env set nc 'env set stdout nc; env set stderr nc; env set stdin nc'
30 env set ncip '192.168.1.1'
31 env save
32 run nc
wdenkb1bf6f22005-04-03 14:52:59 +000033
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010034On the host side, please use this script to access the console
wdenkb1bf6f22005-04-03 14:52:59 +000035
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010036.. code-block:: bash
wdenk68ceb292004-08-02 21:11:11 +000037
Mike Frysingerbcb6dd92008-12-09 23:20:31 -050038 tools/netconsole <ip> [port]
wdenk68ceb292004-08-02 21:11:11 +000039
Mike Frysingerbcb6dd92008-12-09 23:20:31 -050040The script uses netcat to talk to the board over UDP. It requires you to
41specify the target IP address (or host name, assuming DNS is working). The
42script can be interrupted by pressing ^T (CTRL-T).
wdenkb1bf6f22005-04-03 14:52:59 +000043
Igor Marnat443feb72007-03-21 09:55:01 +030044Be aware that in some distributives (Fedora Core 5 at least)
45usage of nc has been changed and -l and -p options are considered
46as mutually exclusive. If nc complains about options provided,
47you can just remove the -p option from the script.
48
wdenk25d67122004-12-10 11:40:40 +000049It turns out that 'netcat' cannot be used to listen to broadcast
wdenkeedcd072004-09-08 22:03:11 +000050packets. We developed our own tool 'ncb' (see tools directory) that
51listens to broadcast packets on a given port and dumps them to the
Mike Frysinger1c20e4a2009-09-09 12:20:21 -040052standard output. It will be built when compiling for a board which
53has CONFIG_NETCONSOLE defined. If the netconsole script can find it
54in PATH or in the same directory, it will be used instead.
wdenkb1bf6f22005-04-03 14:52:59 +000055
wdenk68ceb292004-08-02 21:11:11 +000056For Linux, the network-based console needs special configuration.
57Minimally, the host IP address needs to be specified. This can be
58done either via the kernel command line, or by passing parameters
59while loading the netconsole.o module (when used in a loadable module
60configuration). Please refer to Documentation/networking/logging.txt
61file for the original Ingo Molnar's documentation on how to pass
62parameters to the loadable module.
63
64The format of the kernel command line parameter (for the static
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010065configuration) is as follows
wdenk68ceb292004-08-02 21:11:11 +000066
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010067.. code-block:: bash
68
69 netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
wdenk68ceb292004-08-02 21:11:11 +000070
71where
72
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010073src-port
74 source for UDP packets (defaults to 6665)
wdenk68ceb292004-08-02 21:11:11 +000075
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +010076src-ip
77 source IP to use (defaults to the interface's address)
78
79dev
80 network interface (defaults to eth0)
81
82tgt-port
83 port for logging agent (defaults to 6666)
84
85tgt-ip
86 IP address for logging agent (this is the required parameter)
87
88tgt-macaddr
89 ethernet MAC address for logging agent (defaults to broadcast)
90
91Examples
92
93.. code-block:: bash
wdenk68ceb292004-08-02 21:11:11 +000094
95 netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc
wdenk68ceb292004-08-02 21:11:11 +000096 netconsole=@/,@192.168.3.1/
97
98Please note that for the Linux networked console to work, the
99ethernet interface has to be up by the time the netconsole driver is
100initialized. This means that in case of static kernel configuration,
101the respective Ethernet interface has to be brought up using the "IP
102Autoconfiguration" kernel feature, which is usually done by defaults
103in the ELDK-NFS-based environment.
104
105To browse the Linux network console output, use the 'netcat' tool invoked
106as follows:
107
Heinrich Schuchardtd0253f72020-12-12 09:37:47 +0100108.. code-block:: bash
109
wdenk68ceb292004-08-02 21:11:11 +0000110 nc -u -l -p 6666
wdenk25d67122004-12-10 11:40:40 +0000111
112Note that unlike the U-Boot implementation the Linux netconsole is
113unidirectional, i. e. you have console output only in Linux.
Fiona Klute5a116722024-05-18 12:47:05 +0200114
115Setup via environment
116---------------------
117
118If persistent environment is enabled in your U-Boot configuration, you
119can configure the network console using the environment. For example:
120
121.. prompt:: bash =>
122
123 env set autoload no
124 env set hostname "u-boot"
125 env set bootdelay 5
126 env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc'
127 env set ncip '192.168.1.1'
128 env set preboot "${preboot}; run nc;"
129 env save
130 reset
131
132``autoload no`` tells the ``dhcp`` command to configure the network
133interface without trying to load an image. ``hostname "u-boot"`` sets
134the hostname to be sent in DHCP requests, so they are easy to
135recognize in the DHCP server log. The command in ``nc`` calls ``dhcp``
136to make sure the network interface is set up before enabling
137netconsole.
138
139Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole
140before trying to find any boot options, so you can interact with it if
141desired.
142
143``env save`` stores the settings persistently, and ``reset`` then
144triggers a fresh start that will use the changed settings.