Bering-uClibc 7.x - User Guide - Basic Configuration - LEAF Packages
|Basic Configuration - LEAF Packages|
|Prev||Bering-uClibc 7.x - User Guide||Next|
- 1 Adding and Removing Packages
- 2 apkg Primer
Adding and Removing Packages
The configuration is divided into two files:
syslinux.cfg (for SYSLINUX, or the corresponding file for ISOLINUX or PXELINUX) defines the place where
leaf.cfg can be found during boot process. The packages to load and the devices to load from are defined in
leaf.cfg is sourced by
init it is necessary to be aware of linefeed handling. That means you can break
leaf.cfg, if you edit it with a Windows editor like Notepad. A possible solution is to use a decent editor like e3 or to run the DOS2UNIX utility, which strips the <CR> chars. It works under pure DOS as well as under Windows32. It can be downloaded from: https://sourceforge.net/projects/dos2unix
The list of Packages to load is defined in
leaf.cfg so it is necessary to specify where this file is located.
This is done with the LEAFCFG variable which contains an ordered list of locations to search.
This search-list behaviour is particularly important when using a combination of a large read-only device (such as a CD-ROM) in conjuction with a small read-write device (such as a floppy disk), where only configuration changes are stored on the smaller device.
The behaviour is that
leaf.cfg is read from the first location where it is found.
A file in a location at the end of the list is overridden by a file in a location at the start of the list.
The LEAFCFG variable has the following syntax:
Any specified filesystem is tried first.
If no filesystem is specified, or a mount using the specified filesystem fails for any reason, all filesystems currently enabled in the kernel (entries in
/proc/filesystems that do not start with 'nodev') will be used to try to mount the configuration device.
For a hard disk (or flash drive) this could be:
For a CD-ROM something like:
For a CD-ROM with configuration settings saved to a floppy disk it should be:
This last example was used for the
.iso disk Images from Bering-uClibc 4.0 through Bering-uClibc 4.2.
Since floppy disk drives are becoming rare some users prefer to boot from a CD-ROM but then save the configuration settings to a small flash media device, which is typically referenced as
For Bering-uClibc 4.2.1 onwards an extra entry was added to the standard
isolinux.cfg to cater for this possibility:
Any entry which does not reference a valid device is simply ignored.
When changing the value for LEAFCFG a
syslinux.cfg file can usually be edited in-situ, since it is typically stored on read-write media.
isolinux.cfg is more problematic since it is embedded in the
.iso disk Image file. In order to edit this it is necessary to:
- Extract the contents of the
.isodisk Image file
isolinux/isolinux.cfgto specify an alternative entry such as:
- Rebuild the
.isodisk Image file
It will also be necessary to change the setting for PKGPATH within
leaf.cfg as described below.
Set this to the same value as LEAFCFG.
On some systems with multiple disk devices it is not possible to guarantee the order in which these are identified at boot time.
The disk which starts out as
/dev/sda might become
/dev/sdb after a reboot.
As long as
leaf.cfg is only present on a single disk then listing all the possible device names in LEAFCFG should work OK.
For advanced users there is an alternative syntax for LEAFCFG which can reference disks by a persistent block device name - either the file system LABEL or the UUID. This borrows the syntax from other Linux distributions. For example:
would use the disk with the DOS filesystem label "LEAFBUC", or
(since the filesystem type is optional).
Note that this facility is not supported by default since the extra utilities needed to identify devices in this way are not included in the standard
initrd.lrp files, and most users prefer a smaller
However, it is possible to enable this behaviour by following the instructions for Modifying initrd.lrp and adding the following files from
/lib/libblkid.so.1.1.0and its symbolic links
/lib/libuuid.so.1.3.0and its symbolic links
Variables that may be set in
- VERBOSE - (if non-null enables additional output from init)
- LRP - Packages to load
- PKGPATH - Device(s) to load packages from
- syst_size - Size of
/(root) RAM disk
- tmp_size - Size of
- log_size - Size of
- zswap_size - Size of ZRAM swapdisk (or choose 0 for "auto" size or -1 to disable it.)
- CONFIGDB - name of the config database (Default:
ZRAM creates a RAM based block device (named zram) which acts as swap disk. Pages swapped to this disk are compressed and stored in memory itself. Compressing pages and keeping them in RAM virtually increases its capacity. This allows more applications to fit in given amount of memory.
It is enabled by setting the variable zswap_size to 0 (where the size is set automatically as sum of all tmpfs sizes) or choose a fixed size with %d[kMG] (but if set to more than 2GB it will be disabled due to a shell math overflow). Though it can be set to more RAM than available. If too much memory is consumed by an application, this application will be killed due Out Of Memory condition, the used zram swap device becomes free - just like in system w/o swap. By default it's enabled to auto size (0). To disable ZRAM completly, set zswap_size to -1 in
Below an example for a basic image:
LRP="root license dhcpcd keyboard shorwall dnsmasq dropbear mhttpd webconf" PKGPATH="/dev/sda1:vfat" log_size=8M tmp_size=8M zswap_size=0
Spaces, tabs, newlines, or commas may be used to separate entries in the LRP and PKGPATH variables.
Note, that the LRP line is smaller than in previous versions. This due to the fact that Packages that depend on other Packages will automatically load those Packages. For example
root.lrp depends on
modules.lrp, so those will be loaded as well.
Additional capabilities of leaf.cfg
It's still possible to use "LRP" and "PKGPATH" in
syslinux.cfg, they can be extended in
leaf.cfg by doing: LRP="$KCMD_LRP extrapackage" and PKGPATH="$KCMD_PKGPATH,/dev/mydev:newfs".
Variables available for use in the
leaf.cfg script include any kernel command line parameters (prefixed by KCMD_), the mount point of the LEAFCFG device (MNT), and available filesystems (FILESYSTEMS). See the
/init script for full details. Note that the
leaf.cfg file is processed BEFORE any packages are loaded (in fact, before the package path and package list are finalized), so it would be possible, for example, to load any kernel modules or other software directly off the LEAFCFG= device required to read package files from attached devices. It is only necessary to have support for the LEAFCFG= device either compiled into the kernel, or included in the
/boot/ directory of the initial RAM disk.
In addition, the
leaf.cfg file is sourced as a shell script, allowing the potential for extension of the leafcfg scripts without requiring a modification of the physical boot media - i.e.: anything from:
echo "Hi Mom!"
insmod $MNT/MyWeirdDevice.o --with-parameters
mknod /dev/mydevice -b 123 231
What is apkg?
apkg is the current tool for package management and configuration in LEAF's Bering-uClibc branch.
apgk has two modes of operation. The most used mode is interactive, it's the one you see right after logging in. But it can also be used via the shell prompt using switches.
Note: The first time the router boots, there is no
configdb.lrp (unless added by hand). You may see some 'not found' errors; this is an expected behaviour and will disappear once you save the configuration for the first time.
Saving your configuration
LEAF configuration menu" is the first screen you'll see after login. You can always start it from the shell prompt with the lrcfg command.
This menu has some changes in the lower right corner, the available commands are now:
- s) Save configuration
- c) Show configuration changes since last save
- d) Show configuration changes from defaults
s - will save all changed configuration files and directories to
You can change the confirmation question before writing the lrp to your storage media in /etc/config.cfg. Setting CWRT to "off" allows you to save your completely configured box with only two keystrokes ("s" and "m" ).
There are two more commands available regarding configuration changes and saving:
- c) Show configuration changes since last save
This command shows the changes in all your configuration files and directories since you saved your configuration.
- d) Show configuration changes from defaults
This command shows all changes between your setup and the distribution defaults as shipped.
Note: Both commands only work if you saved configurations at least once.
Command line switches
apkg supports the following commands:
- -i [path]<package> install package
- -u [path]<package> upgrade package
- -c [path]<package> list contents of package
- -l [<package>] list installed packages; if <package> given, tell if it is installed
- -h this help
The new package and configuration management alleviate upgrading packages. You can copy a new version of a package to your storage media and with reboot the new version is loaded (from the <package>.lrp) and your previous configuration, cause the configuration files in the package are overwritten by those saved earlier in
You can also use the apkg -u upgrade command. When apkg -u is invoked, the user will be prompted for each changed configuration file - you can keep the old file, install the new file, view a diff or edit a merged version. If a configuration file has not changed between two releases (e.g. no new defaults, no new options etc), the file modified by the user will be kept without asking.
Note: The new package has to be copied to the storage media before the upgrade to survive a reboot and for the same reason the config has to be saved after the upgrade.
More insights for developers and interested users
Every package has a
<package>.local file with files listed which shall be saved. At startup (linuxrc) the sha1sums of everything listed in the
<package>.local file are calculated and saved in
< package>.sha1 files. This part is done with a "find", so also directories can be listed in
<package>.local files. Only use directories, when this directory is unique for the package, otherwise the content is processed multiple times which cost time and processing power. During backup the sha1sums of the files in memory are compared with the saved *.sha1 sums, new files are detected and duplicates are filtered out.
For example: when one package has an etc/ppp directory in
<package>.local and another one an
etc/ppp/dsl-providers file listed, the
dsl-provider file would be found twice and also stored twice in the
configdb. Changed files are saved in
configdb.lrp with a "full" backup, this is dynamic so installing (or removing) a package will also be taken into account.
The first device in the PKGPATH list is used as backup device. The
moddb will always loaded last by linuxrc. This loading is automatic so there is no need to specify
moddb in the packages list. Modules system, a very simple implementation: The complete
/lib/modules directory is backuped to
moddb.lrp and the /lib/modules/'kernel version' is excluded. This also means that the
modules.lrp package now only contains the insmod logic and no modules.
apkg only saves configuration files, declared in <package>.local. It does never save the complete package. It is also not recommended to add binaries to the configdb file.
So, if you want to customize a package, like replacing a file in the LRP or adding new files to the LRP, it is suggested that you build a new package from scratch.
Building a LRP for a few small scripts, that are added on a running system and are not part of any package can surely be overkill. By adding those files to the /var/lib/lrpkg/local.local file, they will be forced to be saved in the config database. The format is simple, just list the full path to the file without a leading slash:
Note: Do not remove the first entry in this file.
Acknowledgments and Thanks
"apkg" was rewritten by Eric Spakman as a replacement for lrpkg. His work was based on David Douthitt, Nathan Angelacos and Natanael Copa's efforts towards a more advanced package management tool. Cedric Schieli and Paul S. Traina added new features and helped to fix and cleanup Eric's work.