bilibop-common -------------- OVERVIEW ======== This package mainly provides shell functions that can be called by any user, either manually or from a shell script. One of the main goals of these functions is to easily find the device name of the disk hosting the running system. In the first age of these programs, we assumed that the commands in /usr/bin (awk, cut, tail, and others) could be unavailable, and then were replaced by grep and sed heuristics. Such assumption is not true anymore since modern initramfs provide stuff to mount /usr in this early step, and first level directories /bin, /sbin and /lib necessary to mount /usr from the operating system have started to be replaced by symlinks to /usr subdirectories. dm-crypt/LUKS, LVM, loopback and aufs or overlay root filesystems (and combinations of them) are now _fully_ supported, with the following limitations: these functions are intended to be used on a system hosted by an external and writable device (USB, FireWire, eSATA, MMC and maybe more); this means all filesystems used by the system must be either hosted by the same disk or in RAM. Functions that just output information about devices/filesystems can be called by any unprivileged user. Some of the main functions can be called from the commandline (or from a script) with: $ . /usr/lib/bilibop/common.sh $ underlying_device / $ underlying_partition / $ physical_hard_disk / For the three functions, / can be replaced by any (symlink to a) directory (even if it is not a mount point), regular file or block device. If something goes wrong or gives unexpected result, set DEBUG to true and retry: $ DEBUG=true $ physical_hard_disk [ARG] LIMITATIONS =========== So, the main limitations for _full_ LVM support is that a Volume Group can contain several Logical Volumes, but never more than one Physical Volume: we assume there is no sense to use two partitions of the same disk to create a Volume Group. For the same reason, RAID is not supported at all. The limitations for _full_ aufs or overlay support are the sames than for some of the aufs-tools programs: we assume two branches, the lower being readonly (on disk) and the upper writable (in RAM). With overlay, if several lowerdirs are set for a unique union mount, filesystem should be on the same disk. The piece of code related to the search of the filesystem mounted on the lowerdir is tricky. It may evolve with changes in overlay filesystem code or in live-boot's overlay support. The issue is that there is currently no way to programmatically and safely know from the shell where upperdir and lowerdir are. The option field in /proc/mounts (or whatever file where mount records it) is out-of-sync. When overlay mount is set from the initramfs environment, the lowerdir and upperdir values in /proc/mounts may become unconsistent into the system runtime environment if they are not chosen to be exactly the sames in both initrd and system environments. Note that it is also the case with aufs.brs=0 (aufs.brs=1 being the default). For loop devices, there is a small limitation, concerning the fact that in some cases, some functions cannot be run by any unprivileged user: if the loop device has been associated from into the initramdisk environment, then the filename stored in /sys/block/loop?*/loop/backing_file may be obsolete in the system environment, and a call to losetup is needed to access relevant information about the filesystem the backing file resides on. People who are interested by issues concerning multilayered block devices systems can read: http://wiki.debian.org/AdvancedStartupShutdownWithMultilayeredBlockDevices SHELL COMPATIBILITY =================== The bilibop common shell functions have been tested - and work - with the following shells: - /bin/bash (default login shell on Debian) - /bin/dash (default target of the /bin/sh symlink on Debian) - /bin/busybox sh (alternative shell in the Debian initramdisk) - /usr/lib/klibc/bin/sh.shared (default shell in the Debian initramdisk) And also work with: - /bin/mksh - /bin/mksh-static - /bin/bash-static - /bin/posh - /bin/zsh4 They work conditionally with: - /bin/sash Works when the script begins with #!/bin/sash -f, but not when it begins with #!/bin/sh and /bin/sh is linked to sash. They have been tested and don't work with: - /bin/pdksh (this shell has no 'printf' builtin) - /bin/ksh93 (this shell has no 'local' builtin) - /usr/bin/yash (this shell has no 'local' builtin, and '[' is not implemented when the shell is called as 'sh'; and in all cases, yash being in /usr/bin, it should be considered as unusable for bilibop purposes) NEEDED FILES ============ To run correctly, the bilibop functions need to read information into some virtual files or directories, especially: /dev/* /proc/cmdline /proc/filesystems /proc/mounts /proc/partitions /sys/block/sd?/removable /sys/block/dm-?/slaves /sys/block/loop?*/loop/backing_file (needs linux >= 2.6.37) /sys/class/block/*/dev /sys/class/block/*/holders /sys/module/aufs/parameters/brs /sys/fs/aufs/si_*/br? and maybe others So we assume that /dev, /proc and /sys are mounted. If you have to use the bilibop common functions from into a chrooted environment, you have to do something like that (as root). # mount DEVICE /mnt # mount -t sysfs -o nodev,noexec,nosuid sysfs /mnt/sys # mount -t proc -o nodev,noexec,nosuid proc /mnt/proc # mount -t devtmpfs -o mode=0755 udev /mnt/dev and optionally: # mount -t tmpfs -o nosuid,nodev tmpfs /mnt/tmp # mount -t tmpfs -o nosuid,size=10%,mode=0755 tmpfs /mnt/run # mkdir -p /mnt/dev/pts /mnt/run/lock /mnt/run/shm # mount -t devpts -o noexec,nosuid,gid=5,mode=0620 devpts /mnt/dev/pts # mount -t tmpfs -o noexec,nodev,nosuid,size=10% tmpfs /mnt/run/lock # mount -t tmpfs -o nosuid,nodev tmpfs /mnt/run/shm and finally: # chroot /mnt SCRIPTS ======= Bilibop-common is shipped with three shell scripts: /usr/libexec/bilibop/disk ------------------------- This script is very small; it just outputs the physical disk name that contains the root filesystem (or the disk name containing a file, device or directory given as argument). This is a kind of 'proof of concept'. /usr/libexec/bilibop/test ------------------------- This script tests if the argument (file/directory/device) is on the same physical disk than the root filesystem. If it is the case and -q is not used, then it outputs the value of BILIBOP_COMMON_BASENAME. This is also a kind of 'proof of concept'. /usr/bin/drivemap ----------------- This script is a little bit more complicated; it is fully described in its own manual page: drivemap(1). -- bilibop project Tue, 17 Apr 2012 03:03:52 +0200 -- bilibop project Sat, 14 Jul 2015 12:54:07 +0000