Difference between revisions of "Bering-uClibc 4.x - User Guide - Basic Configuration - LEAF Packages"

From bering-uClibc
Jump to: navigation, search
(remove syst_size, cleanup)
(Added syst_size variable and formatting cleaup)
Line 10: Line 10:
  
 
==Adding and Removing Packages==
 
==Adding and Removing Packages==
 
 
===Introduction===
 
===Introduction===
 
The configuration is divided into two files: <code class="filename">syslinux.cfg</code> defines the place where <code class="filename">leaf.cfg</code> can be found during boot process. The packages to load and the devices to load from are defined in <code class="filename">leaf.cfg</code>.
 
The configuration is divided into two files: <code class="filename">syslinux.cfg</code> defines the place where <code class="filename">leaf.cfg</code> can be found during boot process. The packages to load and the devices to load from are defined in <code class="filename">leaf.cfg</code>.
Line 20: Line 19:
  
 
This variable has the following syntax:
 
This variable has the following syntax:
  LEAFCFG=/dev/device[:filesystem]
+
  LEAFCFG=/dev/''device''[:''filesystem''][,/dev/''device''[:''filesystem'']]
  
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.
+
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 <code class="filename">/proc/filesystems</code> that do not start with '<tt>nodev</tt>') will be used to try to mount the configuration device.
  
For a floppy it could be <tt>LEAFCFG=/dev/fd0u1680:msdos</tt> for a harddisk something like <tt>LEAFCFG=/dev/sda1:vfat</tt> for a CD-ROM it could be <tt>LEAFCFG=/dev/cdrom:iso9660</tt>
+
For a floppy disk it could be:
 +
LEAFCFG=/dev/fd0:vfat
 +
For a harddisk (or CF card) something like:
 +
LEAFCFG=/dev/sda1:vfat
 +
For a CD-ROM it could be:
 +
LEAFCFG=/dev/sr0:iso9660
 +
For a CD-ROM with configuration settings saved to a floppy disk it could be:
 +
LEAFCFG=/dev/fd0:vfat,/dev/sr0:iso9660
  
===Configuring leaf.cfg===
+
===Configuring <code class="filename">leaf.cfg</code>===
 
Variables that may be set in <code class="filename">leaf.cfg</code> include:
 
Variables that may be set in <code class="filename">leaf.cfg</code> include:
 +
* <tt>VERBOSE</tt> - (if non-null enables additional output from init)
 +
* <tt>LRP</tt> - Packages to load
 +
* <tt>PKGPATH</tt> - Device(s) to load packages from
 +
* <tt>syst_size</tt> - Size of <code class="filename">/</code> (root) RAM disk
 +
* <tt>tmp_size</tt> - Size of <code class=="filename">/tmp</code> RAM disk
 +
* <tt>log_size</tt> - Size of <code class="filename">/var/log</code> RAM disk
 +
* <tt>CONFIGDB</tt> - name of the config database (Default: <code class="filename">configdb.lrp</code>)
 +
* <tt>MODDB</tt> - name of the modules database (Default: <code class="filename">moddb.lrp</code>)
  
VERBOSE - (if non-null enables additional output from init)
+
Note that spaces, tabs, newlines, or commas may be used to separate entries in the <tt>LRP</tt> and <tt>PKGPATH</tt> variables.
 
+
LRP - Packages to load
+
 
+
PKGPATH - Device(s) to load packages from
+
 
+
tmp_size - Size of /tmp ramdisk
+
 
+
log_size - Size of /var/log ramdisk
+
 
+
CONFIGDB - name of the config database (Default: configdb.lrp)
+
 
+
MODDB - name of the modules database (Default: moddb.lrp)
+
 
+
Note that spaces, tabs, newlines, or commas may be used to separate entries in the LRP and PKGPATH variables.
+
  
 
Below an example for a basic image:
 
Below an example for a basic image:
  LRP="root config etc local modules iptables dhcpcd keyboard shorwall dnscache dropbear"
+
  LRP="root config etc modules mawk iptables dhcpcd keyboard libm perl shorwall dnsmasq dropbear mhttpd webconf"
 
  PKGPATH="/dev/sda1:vfat"
 
  PKGPATH="/dev/sda1:vfat"
tmp_size=25M
 
 
  log_size=8M
 
  log_size=8M
 +
tmp_size=8M
  
 
===Additional capabilities of leaf.cfg===
 
===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".
+
It's still possible to use "<tt>LRP</tt>" and "<tt>PKGPATH</tt>" in <code class="filename">syslinux.cfg</code>, they can be extended in <code class="filename">leaf.cfg</code> by doing: <tt>LRP="$KCMD_LRP extrapackage"</tt> and <tt>PKGPATH="$KCMD_PKGPATH,/dev/mydev:newfs"</tt>.
  
 
Variables available for use in the <code class="filename">leaf.cfg</code> script include any kernel command line parameters (prefixed by KCMD_), the mount point of the LEAFCFG device (MNT), and available filesystems (FILESYSTEMS). See the linuxrc 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 off of 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 ramdisk.
 
Variables available for use in the <code class="filename">leaf.cfg</code> script include any kernel command line parameters (prefixed by KCMD_), the mount point of the LEAFCFG device (MNT), and available filesystems (FILESYSTEMS). See the linuxrc 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 off of 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 ramdisk.

Revision as of 10:50, 20 February 2011

Basic Configuration - LEAF Packages
Prev Bering-uClibc 4.x - User Guide Next


Adding and Removing Packages

Introduction

The configuration is divided into two files: syslinux.cfg 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.

Warning: Because 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

Configuring syslinux.cfg

As with Bering-uClibc 3.x there must be neither packages nor devices defined in syslinux.cfg. You have to configure the LEAFCFG variable instead.

This variable has the following syntax:

LEAFCFG=/dev/device[:filesystem][,/dev/device[:filesystem]]

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 floppy disk it could be:

LEAFCFG=/dev/fd0:vfat

For a harddisk (or CF card) something like:

LEAFCFG=/dev/sda1:vfat

For a CD-ROM it could be:

LEAFCFG=/dev/sr0:iso9660

For a CD-ROM with configuration settings saved to a floppy disk it could be:

LEAFCFG=/dev/fd0:vfat,/dev/sr0:iso9660

Configuring leaf.cfg

Variables that may be set in leaf.cfg include:

  • 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 /tmp RAM disk
  • log_size - Size of /var/log RAM disk
  • CONFIGDB - name of the config database (Default: configdb.lrp)
  • MODDB - name of the modules database (Default: moddb.lrp)

Note that spaces, tabs, newlines, or commas may be used to separate entries in the LRP and PKGPATH variables.

Below an example for a basic image:

LRP="root config etc modules mawk iptables dhcpcd keyboard libm perl shorwall dnsmasq dropbear mhttpd webconf"
PKGPATH="/dev/sda1:vfat"
log_size=8M
tmp_size=8M

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 linuxrc 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 off of 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 ramdisk.

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!"

to:

insmod $MNT/MyWeirdDevice.o --with-parameters
insmod $MNT/NewFileSystem.o
mknod /dev/mydevice -b 123 231
PKGPATH="$KCMD_PKGPATH,/dev/mydev:newfs"


apkg Primer

What is apkg?

apkg is the current tool for package management and configuration in LEAF's Bering-uClibc branch.

It was first introduced with Bering-uClibc 3.0 and replaced the aged lrpkg scripts.

Why is apkg better than lrpkg?

apkg simplifies configuration saving, is extensible and eases package updates.

The difference from the old lrpkg package management scripts is that, from now on the .lrp packages become effectively read-only, while the changes to the various configuration files are saved in a new package called configdb.lrp. As for the kernel modules (i.e.: the files in /lib/modules), they are now stored in another new package called moddb.lrp.

This approach improves not only the way packages are handled, by saving only the information that has changed, but also provides new options for preparing special base installations (such as a simple fileset for WRAP boards), while providing easy package upgrades.

Using apkg

apgk has two modes of operation, just like lrpkg. 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

Interactive mode

The "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
  • m) Backup modules
  • c) Show configuration changes since last save
  • d) Show configuration changes from defaults

s - will save all changed configuration files and directories to configdb.lrp.

m -backs up the modules directory /lib/modules to moddb.lrp.

Note: The file /etc/modules will be saved in configdb.lrp. If you only changed the entries in this file, "Save config" is enough. But if you add a new module and changed /etc/modules you have to save both - the configuration and the modules.

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 completly 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

Upgrading packages

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 configdb.lrp.

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 configdb and moddb will always loaded last by linuxrc. This loading is automatic so there is no need to specify configdb and 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.

Customizing packages

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: etc/init.d/example.sh

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.



Prev Up Next