summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorNeil Williams <codehelp@debian.org>2015-11-06 12:15:57 +0000
committerNeil Williams <codehelp@debian.org>2015-11-06 12:15:57 +0000
commite27e6e2512f1c59114eac99fc69ac7a952abf521 (patch)
treee8aa2aeb5419c14614531b65d31890018c340688 /doc
parentde7ee920cb2a0b9918ff980f2ad59e83dec5452f (diff)
downloadvmdebootstrap-e27e6e2512f1c59114eac99fc69ac7a952abf521.tar.gz
improve the live helper documentation structure.
Diffstat (limited to 'doc')
-rw-r--r--doc/devel.rst7
-rw-r--r--doc/live.rst229
2 files changed, 138 insertions, 98 deletions
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.