From e27e6e2512f1c59114eac99fc69ac7a952abf521 Mon Sep 17 00:00:00 2001 From: Neil Williams Date: Fri, 6 Nov 2015 12:15:57 +0000 Subject: improve the live helper documentation structure. --- doc/devel.rst | 7 +- doc/live.rst | 229 ++++++++++++++++++++++++++++++++++------------------------ 2 files changed, 138 insertions(+), 98 deletions(-) (limited to 'doc') diff --git a/doc/devel.rst b/doc/devel.rst index 161133c..47d9f5c 100644 --- a/doc/devel.rst +++ b/doc/devel.rst @@ -1,3 +1,5 @@ +.. _customisation_hooks: + Developing live scripts and customisation hooks =============================================== @@ -16,13 +18,14 @@ vmdebootstrap. The 'common' library contains functions and parameters which need to be used in *all* images, including:: - cleanup export_env mount_proc disable_daemons prepare_apt_source - remove_daemon_block + replace_apt_source + remove_daemon_block + cleanup .. _cleanup: diff --git a/doc/live.rst b/doc/live.rst index 99d9346..a1b1b2d 100644 --- a/doc/live.rst +++ b/doc/live.rst @@ -1,8 +1,8 @@ vmdebootstrap for creation of live images -========================================= +######################################### Role of vmdebootstrap ---------------------- +********************* ``vmdebootstrap`` is limited to the role of generating the rootfs for the live image - the architecture-specific part. ``vmdebootstrap`` then @@ -14,99 +14,136 @@ configuration of grub and EFI, addition of other components (like a menu or Debian Installer) and packaging up into a isohybrid image. vmdebootstrap features -====================== - -#. vmdebootstrap has explicit support for foreign architecture - bootstraps using qemu static binformat handling as well as - support for Debian releases from wheezy onwards. - - * This is **not** intended to provide support for all packages - in the Debian archive. Some packages do not install correctly - with binfmt handling and ``vmdebootstrap`` should be run natively - when the package list is to include these packages. - -#. vmdebootstrap can support adding specific packages but a - simpler approach is to use the existing task-* packages and - only add packages manually where explicitly needed for a live - image, using the ``live-support`` package. - -#. debian-cd runs vmdebootstrap inside a VM in a similar manner to - how debian-live currently operates, as both debian-live and - vmdebootstrap need to call debootstrap which involves making - device nodes and needs to run as root. This outer VM is specific - for the release of Debian being built. vmdebootstrap can build - older releases and it may be necessary to use a newer version of - vmdebootstrap than is present in jessie to build jessie and to - use that version to build wheezy. - -#. vmdebootstrap uses a single config file per image type and each - config file can have a single customisation script. The config - file specifies the architecture of the image and the binformat - handler for that architecture (if used), so the customisation hook - script can be architecture-specific. - -#. Customisation hook scripts are shell scripts which will be passed - a single parameter - the directory which represents the root - directory of the final image. These scripts can use standard shell - support to include other common functions or call out to utilities - known to be installed in the outer VM running vmdebootstrap. - -#. Customisation hooks clearly need to live in a VCS - examples will - be carried in the ``examples`` directory of ``vmdebootstrap`` and - in the ``/usr/share/vmdebootstrap/examples`` directory. Working - scripts based on these examples will likely be within the debian-cd - git repo. - -#. Although vmdebootstrap does have architecture support, the deciding - factor is the availability of a working default kernel for the images +********************** + +Architecture support +==================== + +vmdebootstrap has explicit support for foreign architecture +bootstraps using qemu static binformat handling as well as +support for Debian releases from wheezy onwards. + + * This is **not** intended to provide support for all packages + in the Debian archive. Some packages do not install correctly + with binfmt handling and ``vmdebootstrap`` should be run natively + when the package list is to include these packages. + +Whether to use the binfmt_handler or build natively depends on: + +#. the availability of a working default kernel for the images built for that architecture and how to configure the bootloader(s) to provide the relevant dtb where needed. - -#. Unlike standard vmdebootstrap example scripts, the scripts calling - vmdebootstrap itself do not need to use sudo as the call is made inside - the outer VM which already has root. Using sudo will work but will output - a message: sudo: unable to resolve host JESSIE-debian-live-builder - -#. The building of live images doesn't appear to need changes in the - vmdebootstrap package itself. The changes to isolinux to add the menu config, - splash screen and to provide access to the install menus can all be done - after the generation of the squashfs. - -#. Remember to use ``http://cdbuilder.debian.org/debian/`` for the bootstrap - operations (--mirror option) and ``http://httpredir.debian.org/debian`` for - the mirror to be used after the image has booted (--apt-mirror option). - -#. Ensure that a user is created (``--user 'user/live'``) and that ``sudo`` is - added to the set of packages to install and the --sudo option is passed - to vmdebootstrap to ensure that the user is added to the sudo group. The - root user password should also be locked (--lock-root-password). - - * Consider using a blank password and enforcing a password to be set - upon login for those images which can support this. - -#. Installing task packages using debootstrap **omits** ``Recommended`` packages, - resulting in a much smaller image which is not expected for a live image. - Task selection needs to be done in the customisation hook using the chroot - command, at which point the default apt configuration will install the - Recommends as well as the Depends packages. Ensure that the image size is - big enough. - -#. When installing using apt in the customisation script, ensure that the - debconf non-interactive settings are exported to prevent the install - waiting for keyboard interaction. ``DEBIAN_FRONTEND=noninteractive`` - -#. The customisation script needs to mount proc (and possibly other - locations like ``/sys/``, ``/dev/`` and ``/dev/pts/``) before - starting the apt install. - -#. Calls to apt should also not output the progress bar but the actual package - installation steps should be logged. - -#. Move the image apt sources aside and set the cdimage apt source instead. - Use ``http://cdbuilder.debian.org/debian/`` Then, at the end of the - customisation hook, remove that source and replace the original. - -#. ``mksquashfs`` can fail without indication of why and when it does, the image - file can be 4Kb or so of junk. ``vmdebootstrap`` will fail if the - squashfs output is less than 1MB. This can occur if the drive runs - out of space but squashfs does not report an error. +#. the complexity of the package set and compatibility with configuring + those packages using qemu-user. Some packages fail if the emulator + cannot provide threading support or other mechanisms - package sets + with such requirements would need to be built natively. Test with a + smaller package set where possible. + +live-support package +==================== + +vmdebootstrap can support adding specific packages but a +simpler approach is to use the existing task-* packages and +only add packages manually where explicitly needed for a live +image, using the ``live-support`` package. + +Running vmdebootstrap for debian-cd +=================================== + +debian-cd runs vmdebootstrap inside a VM in a similar manner to +how debian-live currently operates, as both debian-live and +vmdebootstrap need to call debootstrap which involves making +device nodes and needs to run as root. This outer VM is specific +for the release of Debian being built. vmdebootstrap can build +older releases and it may be necessary to use a newer version of +vmdebootstrap than is present in jessie to build jessie and to +use that version to build wheezy. + +Remember to use ``http://cdbuilder.debian.org/debian/`` for the bootstrap +operations (--mirror option) and ``http://httpredir.debian.org/debian`` for +the mirror to be used after the image has booted (--apt-mirror option). + +Ensure that a user is created (``--user 'user/live'``) and that ``sudo`` is +added to the set of packages to install and the --sudo option is passed +to vmdebootstrap to ensure that the user is added to the sudo group. The +root user password should also be locked (--lock-root-password). + +* Consider using a blank password and enforcing a password to be set + upon login for those images which can support this. + +``mksquashfs`` can fail without indication of why and when it does, the image +file can be 4Kb or so of junk. ``vmdebootstrap`` will fail if the +squashfs output is less than 1MB. This can occur if the drive runs +out of space but squashfs does not report an error. + +Customisation hooks +=================== + +vmdebootstrap uses a single config file per image type and each +config file can have a single customisation script. The config +file specifies the architecture of the image and the binformat +handler for that architecture (if used), so the customisation hook +script can be architecture-specific. + +Customisation hook scripts are shell scripts which will be passed +a single parameter - the directory which represents the root +directory of the final image. These scripts can use standard shell +support to include other common functions or call out to utilities +known to be installed in the outer VM running vmdebootstrap. + +Customisation hooks clearly need to live in a VCS - examples will +be carried in the ``examples`` directory of ``vmdebootstrap`` and +in the ``/usr/share/vmdebootstrap/examples`` directory. Working +scripts based on these examples will likely be within the debian-cd +git repo. + +Unlike standard vmdebootstrap example scripts, the scripts calling +vmdebootstrap itself do not need to use sudo as the call is made inside +the outer VM which already has root. Using sudo will work but will output +a message: sudo: unable to resolve host JESSIE-debian-live-builder + +The building of live images doesn't appear to need changes in the +vmdebootstrap package itself. The changes to isolinux to add the menu config, +splash screen and to provide access to the install menus can all be done +after the generation of the squashfs. + +Installing task packages using debootstrap **omits** ``Recommended`` packages, +resulting in a much smaller image which is not expected for a live image. +Task selection needs to be done in the customisation hook using the chroot +command, at which point the default apt configuration will install the +Recommends as well as the Depends packages. Ensure that the image size is +big enough. + +Use the helpers +--------------- + +:file:`vmdebootstrap` provides helpers for customisation hooks - typically +you call a series at the start, do your customisations and call a parallel +set before the customisation script finishes. See :ref:`customisation_hooks`. + +* :ref:`export_env` - When installing using apt in the customisation + script, ensure that the debconf non-interactive settings are exported + to prevent the install waiting for keyboard interaction:: + + ``DEBIAN_FRONTEND=noninteractive`` + +* :ref:`mount_proc` - The customisation script needs to mount proc (and + possibly other locations like ``/sys/``, ``/dev/`` and ``/dev/pts/``) + before starting the apt install. + +* :ref:`cleanup` - cleanup mountpoints at the end of the script. + +* Calls to apt should also not output the progress bar but the actual package + installation steps should be logged. + +* :ref:`prepare_apt_source` - Move the image apt sources aside and set + the cdimage apt source instead. Use ``http://cdbuilder.debian.org/debian/``. + +* :ref:`replace_apt_source` - At the end of the customisation hook, + remove that source and replace the original. + +* :ref:`disable_daemons` - any daemons installed into the system need to + know that the daemon should not be started until boot. + +* :ref:`remove_daemon_block` - allow installed daemons to start, once + all package installations are complete. -- cgit v1.2.1