humfsify(1) [debian man page]
HUMFSIFY(1) General Commands Manual HUMFSIFY(1) NAME
humfsify -- convert a directory to the format needed by the UML humfs file system SYNOPSIS
humfsify [user] [group] [size] DESCRIPTION
This manual page documents briefly the humfsify command. This manual page was written for the Debian GNU/Linux distribution because the original program does not have a manual page. Instead, it has documentation in HTML format; see below. humfsify is a Perl script necessary to convert a directory to a format expected by the UML humfs file system. HISTORY
UMLFS was born with the idea to substitute the Hostfs implementation with a proper one for the UML purpose: when you manage files with Hostfs within UML you need to work with two different permission layers (the Host one and the UML one), which have different ideas of own- erships. This becomes evident when you need to create a file as a non-root user on UML: you first need to interact with the UML file system imple- mentation, and then with the host side. The result of a file creation on a mounted hostfs file system is not what you expected: you can see that the file permissions refer to the Host side user rather than the UML creator. The Host side user is to be intended as the UML instance launcher, meanwhile the UML side user is the one you used to log in the UML instance. You can encounter a more-critical problem when creating a device node, operation that usually requires root privileges: you used a common user to launch the UML and, since the operation is done on the Host, it fails, even if you logged in as root. Thus you need a set of tools which requires to bypass the Hostfs permission checks on the Host side: this is done by separating the file permissions and the ownership from the host's files. This is the concept behind the HumFs and its humfsify implementation. ARGUMENTS
user This is the user that needs to 'convert' a directory to the UML file system to use UML. This is the host user who will be using this filesystem from within UML. It may be specified as either a user name or a numeric user id. group This is the group which your UML user belongs to. This may be either a group name or a numeric group id size This is the size of the file system as seen within the UML instance. It must be expressed in Gigabytes ("G"), Megabytes ("M"), or KiloBytes ("K"). EXAMPLES
Create a directory on the host and mount it with humfsify host% mkdir your-humfs-dir host% cd humfs-dir Within this directory create a new one where you would like to have a UML-like hierarchy, i.e. you can loop-mount an UML rootfs host% mkdir dir-to-be-humsified host# mount -o loop rootfs /mnt host% cp -a /mnt dir-to-be-humsified/data host# humfsify user group 512M Then verify it on UML and mount the humfsified directory: UML# mount none /your-uml-host -t humfs -o where '/your-uml-mount-point' is the mount point on UML for the humfsified file system, and .../dir-to-be-humfsified is the humfsified directory in the example above. The '-t' mount option specifies that the file system is to be mounted as 'humfs'. SEE ALSO
The HostFs (link to URL http://user-mode-linux.sourceforge.net/new/hostfs.html) usage explanation within the User-Mode-Linux Web Site AUTHOR
humfsify was written by Jeff Dike. This manual page was written by Stefano Melchior stefano.melchior@openlabs.it for the Debian GNU/Linux system, based on material in the Official User Mode Linux Web Site. HUMFSIFY(1)
Check Out this Related Man Page
rootstrap(1) General Commands Manual rootstrap(1) NAME
rootstrap -- Construct a root filesystem image in a file SYNOPSIS
rootstrap [options ...] imagefile DESCRIPTION
rootstrap is a tool for creating root filesystem images. It was written primarily for use with User-Mode Linux, but may be useful for other purposes as well. Because it uses User-Mode Linux to bootstrap itself, rootstrap can be used without root privileges on the host system, which are normally required for this task in order to use chroot(2) and mount and unmount filesystems. Rootstrap boots UML and uses tools from the host filesystem to perform installation and configuration tasks. Note: since roostrap needs to access the host filesystem it requires an UML kernel with hostfs built-in (CONFIG_HOSTFS=y), not as module. OPTIONS
-s, --image-size Sets the initial size of the image, in megabytes, overriding the initialsize option in rootstrap.conf. -o logfile Log the output of the creation process to logfile instead of to standard output. -u args, --umlargs args Pass additional arguments to user-mode linux when booting to create the image. Supplements the 'umlargs' option in root- strap.conf. Configuration The configuration file consists of sections, starting with a "[section]" header, followed by "option=value" entries. Long values are allowed to span multiple lines if each continued line is indented with whitespace. With the exception of the special section "global", sections are named after a corresponding module. When that module is executed, it receives the option/value pairs in its section as environment variables. All modules inherit global options as environment variables, except where overridden by options within their specific section. At least PATH must be set here, in addition to the required parameters listed below under [global]. Documentation for configurable modules distributed with rootstrap is included below. This section is currently incomplete. Note that the modules shipped with rootstrap have a recommended ordering due to their cooperation in building the guest OS image, equiva- lent modules can be used for each of these tasks: 1. setup guest network (if you need it for OS installation) 2. create the target filesystem 3. mount target filesystem in the guest Linux 4. OS installation 5. UML basic setup (device nodes, kernel modules, etc.) 6. Tweaking (here you should have a fully working OS to play with) 7. unmount the target filesystem Modules [global] Contains configuration options that affect the operation of rootstrap itself, or several modules. fstype The type of filesystem to create (ext2, ext3, reiserfs, etc.) This parameter is mandatory. umlargs Additional arguments to user-mode linux passed when booting to create the image. PATH The PATH environment variable to pass to modules. This parameter is mandatory. initialsize The initial size of the filesystem image (in megabytes). This must be large enough to contain a complete installed system as produced by the selected modules. It will be created sparsely, so additional space is not entirely allocated until it is used. This parameter is mandatory. freespace The amount of free space to leave on the filesystem (in megabytes). The filesystem will be resized, if possible, to adjust the amount of free space to approximately this amount. This parameter is optional. modules The list of modules to invoke, in order. Each module will be searched for in several directories, listed in the FILES section below, and passed environment variables based on the options set in the corresponding section of the configuration file. This parameter is mandatory. debug When set to "true" make rootstrap spawn a shell when a module script fails allowing further debugging actions. The shell will have the same environment as the failing script so you could simply invoke sh -x /path/to/module to see what's going wrong. Moreover the shell exit value will be used to tell rootstrap to: re-evaluate the script when 1 (with exit 1) or continue with the next one when 2 (with exit 2); all other values will make rootstrap fail with an error. This parameter is optional. [network] Network configuration. This module configures virtual networking with the user-mode Linux system used to build the filesystem image. Its presence is not strictly necessary, if the selected modules do not require network access (for example, with a local package mirror) and the network module is not included in the global "modules" list. interface The name of the network interface to configure inside the UML virtual machine, typically "eth0". This parameter is mandatory. host The IP address of the host side of the interface (the host on which rootstrap is run), as visible to the UML virtual machine. This parameter is mandatory. uml The IP address of the UML side of the interface (where the system is being built). The value "dhcp" is also accepted and makes rootstrap try to configure the network interface through DHCP. This parameter is mandatory. transport The type of virtual networking interface to be used. Typically "tuntap". Other available transports are "slirp" and "daemon". This parameter is mandatory. netmask The netmask for the network interface (applies to both sides). This parameter is mandatory. hostname The host name to use for the created UML virtual machine. This parameter is optional. gateway A default gateway to be used by the user-mode Linux system. This parameter is optional. domain The local domain name. nameserver The DNS server to use for domain name resolution inside the UML virtual machine. This parameter is optional, but useful if you do not have a name server running on the host. [mkfs] This module creates the filesystem for the rootfs. It uses the fstype global parameter. [mount] This module mounts the root filesystem where the OS image is going to be created. It uses the fstype global parameter. [umount] This module unmounts the root filesystem and /proc. [uml] Creates /etc/fstab and necessary device nodes, it eventually copies kernel modules into the target image. It uses the fstype global param- eter. kernel_modules How to deal with kernel modules for the guest Linux. It can be one of none, hostfs or copy, defaults to the latter which copies the available modules in the target filesystem. kernel_modules_dir The directory where kernel_modules are located on the host filesystem. It defaults to /usr/lib/uml/modules install_modules This parameter is superseeded by kernel_modules and kernel_modules_dir. It accepts a boolean value (true/false). [debian] Debian installation. This module installs a basic Debian system using debootstrap. dist The distribution to install (e.g., potato, woody, etc.) mirror A URL for a Debian archive containing the base packages. This must be a URL understood by debootstrap, which as of this writing includes URLs understood by wget, and file: URLs. exclude A list of packages which should be excluded (never installed at all). It is quite possible to produce a broken system, or fail to build a system at all, if this option is used improperly. It is useful for excluding packages, such as pcmcia-cs, which are typically not necessary for UML and other applications. Corresponds to debootstrap's --exclude option purge A list of packages which should be removed after installation is complete. Use this for packages which are required during installation, but may be removed afterward. The same warning applies as with the exclude option. Packages are removed with dpkg --purge. include A list of packages which should be included in the initial set of packages to install. Corresponds to debootstrap's --include option. install Extra packages to install via apt after initial debootstrap install. See also the sources option. debconf_preseed_file A file containing a debconf DB to be used as default. Read debconf documentation and see your /var/cache/debconf/config.dat for examples and caveats. sources Sources for target's sources.list. If no value is given the default is the main section of mirror. NOTE: you can provide multi- ple lines if each new line is indented with blank spaces. preferences Preferences for target's apt preferences file (see apt_preferences(5)). NOTE: you can provide multiple lines if each new line is indented with blank spaces. Multiple apt_preferences stanzas are allowed provided that they are separated by a line containing only a dot (".") and obviously indented as specified above. apt_conf Apt configuration for target's apt.conf file (see apt.conf(5)). The file will be created before installing additional packages so it will be already effective then. NOTE: you can provide multiple lines if each new line is indented with blank spaces. apt_force_yes Will make rootstrap use the --force-yes switch to install debian packages. This useful when you need to install packages from sources that don't use a Release.gpg file and thus failing apt key authentication. It can be either true or false and defaults to the former. Be careful anyway as using this option "will cause apt to continue without prompting if it is doing something potentially harm- ful" (from apt-get(8)). This option is provided standalone instead of forcing its inclusion in apt_conf to avoid causing destruc- tive actions later when using apt-get from the UML instance. Custom modules Custom modules can very easily be used by rootstrap, in addition to (or in place of) the supplied modules. See FILES below for locations that are searched for modules. When a module is invoked, the filesystem being created is mounted on $TARGET, /dev, /etc and /tmp are tmpfs filesystems internal to the UML system, while the root filesystem is a hostfs mount of the system where rootstrap is running, to have access to the above shadowed directo- ries the full host filesystem is available on $HOST. /lib/modules is tmpfs too and bind mounted to the host's /usr/lib/uml/modules to let scripts load necessary kernel modules. This means that most software on the host system should be available and work as expected. The working directory where rootstrap is run is available as $WORKDIR. The environment is generated from the configuration file as described above. Be careful about modules ordering (see CONFIGURATION above), you'll mostly want to plug into the tweaking step to perform custom configura- tions. To debug modules enable the debug global parameter, see its description fro more hints. FILES
/etc/rootstrap/rootstrap.conf System-wide default configuration rootstrap.conf Local overrides /usr/lib/rootstrap/modules Modules distributed with rootstrap /etc/rootstrap/modules System-wide overrides and additional modules modules Local overrides and additional modules SEE ALSO
debootstrap(8), apt_preferences(5), apt.conf(5), debconf(7), linux(1); locally installed User-Mode Linux documentation or http://user- mode-linux.sourceforge.net/ (link to URL http://user-mode-linux.sourceforge.net/) AUTHOR
Rootstrap was written by Matt Zimmerman mdz@debian.org rootstrap(1)