[v2,1/2] doc: Detailed example for netconsole setup

This adds details that I would have liked to have readily available,
in particular how to activate the network interface before enabling
netconsole, and how to integrate netconsole so you can use the U-Boot
prompt.

Signed-off-by: Fiona Klute <fiona.klute@gmx.de>
---
Changes in v2:
* Include stderr redirection
* Use 4 spaces instead of tabs for code block to avoid overflowing
  lines

 doc/usage/netconsole.rst | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

--
2.43.0

Hi Fiona,

On Thu, May 16, 2024 at 3:43 AM Fiona Klute <fiona.klute@gmx.de> wrote:
>
> This adds details that I would have liked to have readily available,
> in particular how to activate the network interface before enabling
> netconsole, and how to integrate netconsole so you can use the U-Boot
> prompt.
>
> Signed-off-by: Fiona Klute <fiona.klute@gmx.de>
> ---
> Changes in v2:
> * Include stderr redirection
> * Use 4 spaces instead of tabs for code block to avoid overflowing
>   lines
>
>  doc/usage/netconsole.rst | 33 ++++++++++++++++++++++++++++++++-
>  1 file changed, 32 insertions(+), 1 deletion(-)
>
> diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst
> index 2aa3b9ccc5..647f0c220b 100644
> --- a/doc/usage/netconsole.rst
> +++ b/doc/usage/netconsole.rst
> @@ -18,7 +18,9 @@ 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.
>  The source / listening port can be configured separately by setting
>  the 'ncinport' environment variable and the destination port can be
> -configured by setting the 'ncoutport' environment variable.
> +configured by setting the 'ncoutport' environment variable. Note that
> +you need to set up the network interface (e.g. using DHCP) before it
> +can be used for network console.
>
>  For example, if your server IP is 192.168.1.1, you could use::
>
> @@ -107,3 +109,32 @@ as follows:
>
>  Note that unlike the U-Boot implementation the Linux netconsole is
>  unidirectional, i. e. you have console output only in Linux.
> +
> +Setup via environment
> +---------------------
> +
> +If persistent environment is enabled in your U-Boot configuration, you
> +can configure the network console using the environment. For example::
> +
> +    => env set autoload no
> +    => env set hostname "u-boot"
> +    => env set bootdelay 5
> +    => env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc'
> +    => env set ncip 192.168.1.1
> +    => env set preboot "${preboot}; run nc;"
> +    => env save
> +    => reset
> +
> +``autoload no`` tells the ``dhcp`` command to configure the network
> +interface without trying to load an image. ``hostname "u-boot"`` sets
> +the hostname to be sent in DHCP requests, so they are easy to
> +recognize in the DHCP server log. The command in ``nc`` calls ``dhcp``
> +to make sure the network interface is set up before enabling
> +netconsole.
> +
> +Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole
> +before trying to find any boot options, so you can interact with it if
> +desired.
> +
> +``env save`` stores the settings persistently, and ``reset`` then
> +triggers a fresh start that will use the changed settings.
> --
> 2.43.0
>

Just for information, if the board uses static IP then the example
would be slightly different. I usually use static IP and ping the
netconsole server to make sure it is up. However, I think this DHCP
example is good enough to show how to prepare and activate netconsole.

Reviewed-by: Tony Dinh <mibodhi@gmail.com>

All the best,
Tony

Hi Tony!

Am 16.05.24 um 21:28 schrieb Tony Dinh:
> On Thu, May 16, 2024 at 3:43 AM Fiona Klute <fiona.klute@gmx.de> wrote:
>>
>> This adds details that I would have liked to have readily available,
>> in particular how to activate the network interface before enabling
>> netconsole, and how to integrate netconsole so you can use the U-Boot
>> prompt.
>>
>> Signed-off-by: Fiona Klute <fiona.klute@gmx.de>
>> ---
>> Changes in v2:
>> * Include stderr redirection
>> * Use 4 spaces instead of tabs for code block to avoid overflowing
>>    lines
>>
>>   doc/usage/netconsole.rst | 33 ++++++++++++++++++++++++++++++++-
>>   1 file changed, 32 insertions(+), 1 deletion(-)
>>
>> diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst
>> index 2aa3b9ccc5..647f0c220b 100644
>> --- a/doc/usage/netconsole.rst
>> +++ b/doc/usage/netconsole.rst
>> @@ -18,7 +18,9 @@ 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.
>>   The source / listening port can be configured separately by setting
>>   the 'ncinport' environment variable and the destination port can be
>> -configured by setting the 'ncoutport' environment variable.
>> +configured by setting the 'ncoutport' environment variable. Note that
>> +you need to set up the network interface (e.g. using DHCP) before it
>> +can be used for network console.
>>
>>   For example, if your server IP is 192.168.1.1, you could use::
>>
>> @@ -107,3 +109,32 @@ as follows:
>>
>>   Note that unlike the U-Boot implementation the Linux netconsole is
>>   unidirectional, i. e. you have console output only in Linux.
>> +
>> +Setup via environment
>> +---------------------
>> +
>> +If persistent environment is enabled in your U-Boot configuration, you
>> +can configure the network console using the environment. For example::
>> +
>> +    => env set autoload no
>> +    => env set hostname "u-boot"
>> +    => env set bootdelay 5
>> +    => env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc'
>> +    => env set ncip 192.168.1.1
>> +    => env set preboot "${preboot}; run nc;"
>> +    => env save
>> +    => reset
>> +
>> +``autoload no`` tells the ``dhcp`` command to configure the network
>> +interface without trying to load an image. ``hostname "u-boot"`` sets
>> +the hostname to be sent in DHCP requests, so they are easy to
>> +recognize in the DHCP server log. The command in ``nc`` calls ``dhcp``
>> +to make sure the network interface is set up before enabling
>> +netconsole.
>> +
>> +Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole
>> +before trying to find any boot options, so you can interact with it if
>> +desired.
>> +
>> +``env save`` stores the settings persistently, and ``reset`` then
>> +triggers a fresh start that will use the changed settings.
>> --
>> 2.43.0
>>
>
> Just for information, if the board uses static IP then the example
> would be slightly different. I usually use static IP and ping the
> netconsole server to make sure it is up. However, I think this DHCP
> example is good enough to show how to prepare and activate netconsole.

Maybe it'd make sense to link to a general network setup section for
alternatives? The problem is I can't find any in the existing docs, the
closest I see is the "Automatically updated variables" list:
https://docs.u-boot.org/en/latest/usage/environment.html#automatically-updated-variables

As far as I understand you can also set the environment variables
mentioned there manually to configure networking, but I'm not sure if
that applies to all of them.

Is my understanding correct? If yes, I could send a separate patch to
add that information, and maybe rename the section to "Network
configuration variables".

Best regards,
Fiona

> Reviewed-by: Tony Dinh <mibodhi@gmail.com>
>
> All the best,
> Tony

Hi Fiona,

Added Heinrich to CC list.

On Sat, May 18, 2024 at 4:05 AM Fiona Klute <fiona.klute@gmx.de> wrote:
>
> Hi Tony!
>
> Am 16.05.24 um 21:28 schrieb Tony Dinh:
> > On Thu, May 16, 2024 at 3:43 AM Fiona Klute <fiona.klute@gmx.de> wrote:
> >>
> >> This adds details that I would have liked to have readily available,
> >> in particular how to activate the network interface before enabling
> >> netconsole, and how to integrate netconsole so you can use the U-Boot
> >> prompt.
> >>
> >> Signed-off-by: Fiona Klute <fiona.klute@gmx.de>
> >> ---
> >> Changes in v2:
> >> * Include stderr redirection
> >> * Use 4 spaces instead of tabs for code block to avoid overflowing
> >>    lines
> >>
> >>   doc/usage/netconsole.rst | 33 ++++++++++++++++++++++++++++++++-
> >>   1 file changed, 32 insertions(+), 1 deletion(-)
> >>
> >> diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst
> >> index 2aa3b9ccc5..647f0c220b 100644
> >> --- a/doc/usage/netconsole.rst
> >> +++ b/doc/usage/netconsole.rst
> >> @@ -18,7 +18,9 @@ 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.
> >>   The source / listening port can be configured separately by setting
> >>   the 'ncinport' environment variable and the destination port can be
> >> -configured by setting the 'ncoutport' environment variable.
> >> +configured by setting the 'ncoutport' environment variable. Note that
> >> +you need to set up the network interface (e.g. using DHCP) before it
> >> +can be used for network console.
> >>
> >>   For example, if your server IP is 192.168.1.1, you could use::
> >>
> >> @@ -107,3 +109,32 @@ as follows:
> >>
> >>   Note that unlike the U-Boot implementation the Linux netconsole is
> >>   unidirectional, i. e. you have console output only in Linux.
> >> +
> >> +Setup via environment
> >> +---------------------
> >> +
> >> +If persistent environment is enabled in your U-Boot configuration, you
> >> +can configure the network console using the environment. For example::
> >> +
> >> +    => env set autoload no
> >> +    => env set hostname "u-boot"
> >> +    => env set bootdelay 5
> >> +    => env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc'
> >> +    => env set ncip 192.168.1.1
> >> +    => env set preboot "${preboot}; run nc;"
> >> +    => env save
> >> +    => reset
> >> +
> >> +``autoload no`` tells the ``dhcp`` command to configure the network
> >> +interface without trying to load an image. ``hostname "u-boot"`` sets
> >> +the hostname to be sent in DHCP requests, so they are easy to
> >> +recognize in the DHCP server log. The command in ``nc`` calls ``dhcp``
> >> +to make sure the network interface is set up before enabling
> >> +netconsole.
> >> +
> >> +Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole
> >> +before trying to find any boot options, so you can interact with it if
> >> +desired.
> >> +
> >> +``env save`` stores the settings persistently, and ``reset`` then
> >> +triggers a fresh start that will use the changed settings.
> >> --
> >> 2.43.0
> >>
> >
> > Just for information, if the board uses static IP then the example
> > would be slightly different. I usually use static IP and ping the
> > netconsole server to make sure it is up. However, I think this DHCP
> > example is good enough to show how to prepare and activate netconsole.
>
> Maybe it'd make sense to link to a general network setup section for
> alternatives? The problem is I can't find any in the existing docs, the
> closest I see is the "Automatically updated variables" list:
> https://docs.u-boot.org/en/latest/usage/environment.html#automatically-updated-variables
>
> As far as I understand you can also set the environment variables
> mentioned there manually to configure networking, but I'm not sure if
> that applies to all of them.
>
> Is my understanding correct? If yes, I could send a separate patch to
> add that information, and maybe rename the section to "Network
> configuration variables".

Currently, there is no documentation for using static IP in netconsole
that I'm aware of. I think it would be great if you send a separate
patch after this. Basically, the current u-boot network driver model
will automatically bring up the network when we try to use it, e.g.
pinging a server, or dhcp.

So the difference is instead of dhcp in your example, we could also do this:

env set ipaddr 192.168.1.100
env set nc 'if ping ${ncip}; then env set stdout nc; env set stderr
nc; env set stdin nc; fi'

Note that the board ipaddr needed to be set before the ping.

All the best,
Tony

>
> Best regards,
> Fiona
>
> > Reviewed-by: Tony Dinh <mibodhi@gmail.com>
> >
> > All the best,
> > Tony
>