Bering-uClibc 7.x - User Guide - Basic Configuration - Booting for the First Time

From bering-uClibc
Revision as of 23:38, 9 October 2020 by Jeanrocco (Talk | contribs) (Successful Boot using the web Browser connection)

Jump to: navigation, search
Basic Configuration - Booting for the First Time
Bering-uClibc 7.x - User Guide Next

Make target connections

Connecting to your target system

LEAF now allows to connect to your target system using a web Browser from an external PC. This is easier than setting up the traditional vga or serial consoles. The caveat here is having to wait patiently for the system to boot without knowing what is happening until it is ready to receive a web connection attempt, usually a couple of minutes. This is where the USB bootable images shine, remember; guaranty to boot.

First make sure there are no connections to all the lan ports on your target system. Then make a connection with an RJ45 lan cable between the external PC network port and the target internal interface network port, in our case eth1 which is pre-configured with IP address The external PC; Linux, Windows or Mac's lan IP address has to be manually preset with for instance.

Important: make no other network connection between your target system and your LAN as we want to be totally isolated from any network until you change the default web Browser 'admin' password, and maybe make some other configuration changes.

Install Media and Boot

Insert the prepared boot media into the system which is to run Bering-uClibc 7.x and power it on.

Successful Boot using the web Browser connection

  • Once the target is booted, you will be able to access it by putting in a Browser URL. You will be greeted with a web page asking for a user name and a password, go ahead and give it user: admin and password: admin. If you don't get a browser response, try all the target rj-45 ports until you get one. If this fails, you will probably have to go to Advanced copy for all other cases.
  • You will be stuck in this page until you change the default 'admin' password. Once changed, you have access to all of Webconf pages.
  • Now is a good time to configure an SSH access to your target. This will give you a CLI (command line interface) console if you prefer that.
    • In the Webconf page, switch to expert, click dropbear and /etc/default/dropbear. At the end of the file add: DB_OPTIONS=" -B ", click save and restart dropbear.
    • From you PC open a SSH session with
ssh root@

    • Login as user "root" (no password required at this point). You will be prompted to set a password for the root account (twice). You will then be presented with the LEAF configuration menu, have a look at the next paragraphe. On Windows use Putty.
    • Just in case, now that the root password is set, comment out the DB_OPTIONS=" -B " in dropbear.
  • When done, if you want to keep all of these changes, run lrcfg on the CLI and hit s) Save configuration, or use Webconf > Save To Disk > Backup Packages.

Successful First Boot for Consoles vga or serial

If everything works properly you should see lots of diagnostic output followed by a login prompt similar to the following:

Linux 4.19.93-x86_64 #1 SMP Mon Jan 13 18:41:53 CET 2020
LEAF Bering-uClibc 7.0.0-alpha1 Rev 1 uClibc 1.0.32  firewall /dev/ttyS0
firewall login: 

Login as user "root" (no password required at this point). You will be prompted to set a password for the root account (twice). You will then be presented with the LEAF configuration menu:

                       LEAF configuration menu

       1) Network configuration

       2) System configuration

       3) Packages configuration

 				s) Save configuration
				m) Backup modules
				f) Find & load modules for hardware

				c) Show configuration changes since last save
				d) Show configuration changes from defaults
				h) Help
 q) quit


In the event of problems it is worth reviewing the Appendix which describes the Bering-uClibc startup logic to assess how far the boot progressed before failing.

Some specific issues, with solutions / workarounds, are listed below.

Hardware Device Driver Issues

Beginning with LEAF Bering-uClibc 6.0 the (most important) hardware modules to access the boot device are build into the Linux kernel. Remaining modules will then be loaded from modules.sqfs, a SquashFS image providing a complete kernel modules tree. It will be unloaded after adding the modules, either detected automatically (most hardware-related modules) or defined in /etc/modules.

There are three main types of problem with hardware device driver kernel Modules failing to load:

  • The necessary kernel Module files might be present in modules.sqfs but are not being loaded automatically.
  • The necessary kernel Module files might be present in modules.sqfs but are not being loaded quickly enough.
  • The necessary kernel Module files might be missing from the default modules.sqfs.

Hardware Auto-Detection Issues

Some older hardware is not fully compatible with the Bering-uClibc 7.x auto-detection logic which loads hardware device driver Modules at boot time. As a result, some required kernel Modules may not be loaded automatically even they are present in the default modules.sqfs.

The solution is to force the necessary module(s) to be loaded and the easiest way to do that is to specify a value for the "KMODULES" kernel command line argument which takes a comma-separated list of modules. To do this edit {iso|pxe|sys}linux.cfg and change the "APPEND" line. For example, to force the "floppy" and "i2c-core" kernel Modules to be loaded change this line to read something like the following:

APPEND reboot=bios KMODULES=floppy,i2c-core

Device Drivers Taking Too Long To Load

On slow hardware, the default 1-second delay in the boot sequence does not allow enough time for the device drivers to load and initialize the hardware before proceeding. Typical symptoms of this are diagnostic messages relating to the successful mounting of devices just after the messages reporting failure to locate leaf.cfg. The solution is to specify a longer delay. Variable "usb_wait" can be used to do this (although the name refers to "USB" it actually applies to any kind of device). For example, to wait for 3 seconds rather than the default of 1, change the "APPEND" line to read something like:

APPEND reboot=bios usb_wait=3

Note: To improve new users experience, 3 seconds are the default entry since LEAF Bering-uClibc 5.1.

Module Files Missing From modules.sqfs

The default modules.sqfs files include all kernel Modules configured for the kernel build, covering the majority of hardware devices. For unusual hardware the required driver may not be included in the kernel build configuration file and so may be missing from modules.sqfs as well. In such cases you should report the problem to the leaf-user mailing list.

DMA Issues

Some drives, especially some Compact Flash drive / adaptor combinations, do not properly support DMA. The symptoms of problems are boot messages like the following, accompanied by delays while the drive access times out and it reverts to non-DMA operation:

[   36.768088] ata1: lost interrupt (Status 0x58)                                                                                        
[   36.769016] ata1: drained 4096 bytes to clear DRQ.                                                                                    
[   36.772872] ata1.00: exception Emask 0x0 SAct 0x0 SErr 0x0 action 0x6 frozen                                                          
[   36.773075] ata1.00: failed command: READ DMA                                                                                         
[   36.773261] ata1.00: cmd c8/00:08:00:00:00/00:00:00:00:00/e0 tag 0 dma 4096 in                                                        
[   36.773273]          res 40/00:00:00:00:00/00:00:00:00:00/00 Emask 0x4 (timeout)                                                      
[   36.773752] ata1.00: status: { DRDY }                                                                                                 
[   36.773970] ata1: soft resetting link                                                                                                 
[   36.931430] ata1.00: configured for MWDMA2                                                                                            
[   36.931597] ata1.00: device reported invalid CHS sector 0                                                                             
[   36.931772] ata1: EH complete

The solution is to disable any attempt to use DMA for the relevant device by setting options for the libata driver. The following is a small extract from linux- (part of the kernel source distribution):

libata.dma=     [LIBATA] DMA control
                libata.dma=0      Disable all PATA and SATA DMA
                libata.dma=1      PATA and SATA Disk DMA only
                libata.dma=2      ATAPI (CDROM) DMA only
                libata.dma=4      Compact Flash DMA only
                Combinations also work, so libata.dma=3 enables DMA
                for disks and CDROMs, but not CFs.

So, assuming the problem affects only Compact Flash devices, these can have DMA disabled by using kernel argument libata.dma=3. This should be specified by editing file syslinux.cfg:

  1. Mount the boot drive: mount /dev/sda1 /mnt
  2. Edit syslinux.cfg: edit /mnt/syslinux/syslinux.cfg
  3. Add libata.dma=3 to the APPEND line so that the complete line reads: APPEND reboot=bios libata.dma=3
  4. Unmount the boot drive: umount /mnt
  5. Reboot

Up Next