Overview of Balsa on a Linux Host
This page tells you how a Balsa Prototype is set up on a Linux system. It contains information for a someone in a technical support role.
There is a separate page with instructions for setting up a machine to run Balsa.
The Working Balsa System
Once the Balsa system is booted (#The Balsa Boot Process is described below), the Balsa device is the main system device.
Files and Directories that Balsa sets up on a Linux Host
Files created by Balsa Set-up
- Balsa sets a Balsa entry at the top of the grub menu on the host machine.
- It creates an entry /etc/grub.d/06_balsa. You can rename this to put the Balsa entry in a different place in the grub menu, e.g. 39_balsa puts it at the end. Run the update-grub command to recreate the grub menu.
- It stores customized boot files into /boot/balsa & subsequently /boot/balsa.old on the host machine.
Data Files Created by Balsa
Balsa stores the Balsa data files in a directory named /balsafiles on the same partition as /home on the host machine. Within the host Linux system these files are in /balsafiles/ (unless it has a separate home partition).
Within the Balsa system these are available in /run/balsahost/balsafiles. The directory /run/balsahost/balsafiles/home/ is mounted on /home.
The first time that Balsa is run it copies /usr/share/balsa/skel/ to /home/ (/run/balsahost/balsafiles/home). This initializes the Balsa system with the default data files. Some of these files may be modified by the upgrade and downgrade scripts in /usr/share/balsa/initscripts/.
Balsa also creates and uses some addional control files in /run/balsahost/balsafiles/:
- /balsafiles/etc/passwd contains a copy of /etc/passwd from the last time that the Balsa was shut down.
- /balsafiles/usr/share/balsa/version contains the version of the last Balsa device that was run on the host. This file gets compared with the version on the Balsa device to tell whether to upgrade or downgrade when Balsa boots.
- /balsafiles/uuid is a unique number identifying this host to the balsa system. It is used in the rsync-backup to identify a backup set.
- Balsa creates a swap file of 512 Mbytes in the same partition as /balsafiles. The swap file is named balsaswap.img.
The Balsa Boot Cycle on a Linux Host
The Balsa boot entry boots to the customized host vmlinuz/initrd which are located on the host machine at /boot/balsa. It then reboots using kexec to the Balsa device.
- Boot using /boot/balsa/vmlinuz & /boot/balsa/initrd.img. The following boot parameters are passed on the kernel line:
- The BalsaRoot partition is specified by its partition label.
- The location of the /balsafiles defaults to the same partition as the host Linux system's /home directory.
- A panic=20 parameter tells the boot process to reboot after 20 seconds if the boot process is aborted. This usually happens because the Balsa SD card is not present, so the BalsaRoot partition isn't found.
- /boot/balsa/vmlinuz & /boot/balsainitrd.img will transfer control to the vmlinuz-... & initrd.img-... files in the /boot directory of the BalsaRoot partition on the SD card. The kernel line parameters are passed on. The boot process from this point on is a Ubuntu boot using the SD card as the system device.
- Mount the host partition containing the /balsafiles directory to /run/balsahost.
- Bind mount /run/balsahost/balsafiles/home to /home, making the files in /balsafiles/home the home directory.
- Create a swap file /run/balsahost/balsaswap.img (512 Mbytes) in the directory mounted on /run/balsahost.
- Do other hardware specific configuration, based on screen size and machine architecture.
- Display the Balsa log-in screen and log into either the Balsa User account or Advisor account.
- Execute the programs in the ~/.autoexec directory.
Modifying the Boot Process
Other Advanced Configurations
More information is available on the page Other Advanced Balsa Configurations