Merge "Unify and fix doc of several Debian and Ubuntu elements"
This commit is contained in:
commit
5c1579f0d6
@ -2,77 +2,13 @@
|
|||||||
debian-minimal
|
debian-minimal
|
||||||
==============
|
==============
|
||||||
|
|
||||||
Create a minimal image based on Debian. We default to unstable but
|
The ``debian-minimal`` element uses debootstrap for generating a
|
||||||
``DIB_RELEASE`` can be set to any series of Debian.
|
minimal image. In contrast the ``debian`` element uses the cloud-image
|
||||||
|
as the initial base.
|
||||||
|
|
||||||
There are two ways to configure apt-sources:
|
By default this element creates the latest stable release. The exact
|
||||||
|
setting can be found in the element's ``environment.d`` directory in
|
||||||
1. Using the standard way of defining the default, backports, updates
|
the variable ``DIB_RELEASE``. If a different release of Debian should
|
||||||
and security repositories is the default. In this case you can
|
be created, the variable ``DIB_RELEASE`` can be set appropriately.
|
||||||
overwrite the two environment variables to adapt the behavior:
|
|
||||||
|
|
||||||
* ``DIB_DISTRIBUTION_MIRROR``: the mirror to use (default:
|
|
||||||
`<http://ftp.us.debian.org/debian>`__)
|
|
||||||
* ``DIB_DEBIAN_COMPONENTS``: (default: ``main``) a comma
|
|
||||||
separated list of components. For Debian this can be
|
|
||||||
e.g. ``main,contrib,non-free``.
|
|
||||||
|
|
||||||
Note it is not recommended to use
|
|
||||||
`<http://httpredir.debian.org/>`__ for ``DIB_DISTRIBUTION_MIRROR``
|
|
||||||
due to how unreliable it is. Be sure to select a mirror from the
|
|
||||||
official mirror list at `<https://www.debian.org/mirror/list>`__
|
|
||||||
|
|
||||||
By default only the ``main`` component is used. If
|
|
||||||
``DIB_DEBIAN_COMPONENTS`` (comma separated) from the
|
|
||||||
``debootstrap`` element has been set, that list of components will
|
|
||||||
be used instead.
|
|
||||||
|
|
||||||
Backports, updates and security are included unless ``DIB_RELEASE``
|
|
||||||
is ``unstable``.
|
|
||||||
|
|
||||||
2. Complete configuration given in the variable ``DIB_APT_SOURCES_CONF``.
|
|
||||||
|
|
||||||
Each line contains exactly one entry for the sources.list.d
|
|
||||||
directory. The first word must be the logical name (which is used
|
|
||||||
as file name with ``.list`` automatically appended), followed by a
|
|
||||||
colon ``:``, followed by the complete repository specification.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
|
||||||
|
|
||||||
DIB_APT_SOURCES_CONF=\
|
|
||||||
"default:deb http://10.0.0.10/ stretch main contrib
|
|
||||||
mysecurity:deb http://10.0.0.10/ stretch-security main contrib"
|
|
||||||
|
|
||||||
If necessary, a custom apt keyring and debootstrap script can be
|
|
||||||
supplied to the ``debootstrap`` command via ``DIB_APT_KEYRING`` and
|
|
||||||
``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` respectively. Both options require the
|
|
||||||
use of absolute rather than relative paths.
|
|
||||||
|
|
||||||
Use of this element will also require the tool 'debootstrap' to be
|
|
||||||
available on your system. It should be available on Ubuntu, Debian,
|
|
||||||
and Fedora. It is also recommended that the 'debian-keyring' package
|
|
||||||
be installed.
|
|
||||||
|
|
||||||
The ``DIB_OFFLINE`` or more specific ``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE``
|
|
||||||
variables can be set to prefer the use of a pre-cached root filesystem
|
|
||||||
tarball.
|
|
||||||
|
|
||||||
The ``DIB_DEBOOTSTRAP_EXTRA_ARGS`` environment variable may be used to
|
|
||||||
pass extra arguments to the debootstrap command used to create the
|
|
||||||
base filesystem image. If --keyring is is used in ``DIB_DEBOOTSTRAP_EXTRA_ARGS``,
|
|
||||||
it will override ``DIB_APT_KEYRING`` if that is used as well.
|
|
||||||
|
|
||||||
For further information about ``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` ,
|
|
||||||
``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`` and ``DIB_DEBOOTSTRAP_EXTRA_ARGS``
|
|
||||||
please consult "README.rst" of the debootstrap element.
|
|
||||||
|
|
||||||
-------------------
|
|
||||||
Note on ARM systems
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
Because there is not a one-to-one mapping of ``ARCH`` to a kernel package, if
|
|
||||||
you are building an image for ARM on debian, you need to specify which kernel
|
|
||||||
you want in the environment variable ``DIB_ARM_KERNEL``. For instance, if you want
|
|
||||||
the ``linux-image-mx5`` package installed, set ``DIB_ARM_KERNEL`` to ``mx5``.
|
|
||||||
|
|
||||||
.. element_deps::
|
.. element_deps::
|
||||||
|
@ -2,44 +2,10 @@
|
|||||||
debian
|
debian
|
||||||
======
|
======
|
||||||
|
|
||||||
Create an image based on Debian. We default to unstable but
|
By default this element creates the latest stable release. The exact
|
||||||
``DIB_RELEASE`` is mapped to any series of Debian.
|
setting can be found in the ``debian-minimal/environment.d`` directory
|
||||||
|
in the variable ``DIB_RELEASE``. If a different release of Debian
|
||||||
Note that the default Debian series is `unstable`, and the default
|
should be created, the variable ``DIB_RELEASE`` can be set
|
||||||
mirrors for Debian can be problematic for `unstable`. Because apt does
|
appropriately.
|
||||||
not handle changing Packages files well across multiple out of sync
|
|
||||||
mirrors, it is recommended that you choose a single mirror of debian,
|
|
||||||
and pass it in via `DIB_DISTRIBUTION_MIRROR`.
|
|
||||||
|
|
||||||
If necessary, a custom apt keyring and debootstrap script can be
|
|
||||||
supplied to the `debootstrap` command via `DIB_APT_KEYRING` and
|
|
||||||
`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the
|
|
||||||
use of absolute rather than relative paths.
|
|
||||||
|
|
||||||
Use of this element will also require the tool 'debootstrap' to be
|
|
||||||
available on your system. It should be available on Ubuntu, Debian,
|
|
||||||
and Fedora.
|
|
||||||
|
|
||||||
The `DIB_OFFLINE` or more specific `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`
|
|
||||||
variables can be set to prefer the use of a pre-cached root filesystem
|
|
||||||
tarball.
|
|
||||||
|
|
||||||
The `DIB_DEBOOTSTRAP_EXTRA_ARGS` environment variable may be used to
|
|
||||||
pass extra arguments to the debootstrap command used to create the
|
|
||||||
base filesystem image. If --keyring is is used in `DIB_DEBOOTSTRAP_EXTRA_ARGS`,
|
|
||||||
it will override `DIB_APT_KEYRING` if that is used as well.
|
|
||||||
|
|
||||||
For further information about `DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` ,
|
|
||||||
`DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` and `DIB_DEBOOTSTRAP_EXTRA_ARGS`
|
|
||||||
please consult "README.rst" of the debootstrap element.
|
|
||||||
|
|
||||||
-------------------
|
|
||||||
Note on ARM systems
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
Because there is not a one-to-one mapping of `ARCH` to a kernel package, if
|
|
||||||
you are building an image for ARM on debian, you need to specify which kernel
|
|
||||||
you want in the environment variable `DIB_ARM_KERNEL`. For instance, if you want
|
|
||||||
the `linux-image-mx5` package installed, set `DIB_ARM_KERNEL` to `mx5`.
|
|
||||||
|
|
||||||
.. element_deps::
|
.. element_deps::
|
||||||
|
@ -4,45 +4,77 @@ debootstrap
|
|||||||
|
|
||||||
Base element for creating minimal debian-based images.
|
Base element for creating minimal debian-based images.
|
||||||
|
|
||||||
This element is incomplete by itself, you'll want to use the debian-minimal
|
This element is incomplete by itself, you'll want to use elements like
|
||||||
or ubuntu-minimal elements to get an actual base image.
|
debian-minimal or ubuntu-minimal to get an actual base image.
|
||||||
|
|
||||||
|
There are two ways to configure apt-sources:
|
||||||
|
|
||||||
|
1. Using the standard way of defining the default, backports, updates
|
||||||
|
and security repositories is the default. In this case you can
|
||||||
|
overwrite the two environment variables to adapt the behavior:
|
||||||
|
|
||||||
|
* ``DIB_DISTRIBUTION_MIRROR``: the mirror to use (default:
|
||||||
|
`<http://ftp.us.debian.org/debian>`__)
|
||||||
|
* ``DIB_DEBIAN_COMPONENTS``: (default: ``main``) a comma
|
||||||
|
separated list of components. For Debian this can be
|
||||||
|
e.g. ``main,contrib,non-free``.
|
||||||
|
|
||||||
|
Note it is not recommended to use
|
||||||
|
`<http://httpredir.debian.org/>`__ for ``DIB_DISTRIBUTION_MIRROR``
|
||||||
|
due to how unreliable it is. Be sure to select a mirror from the
|
||||||
|
official mirror list at `<https://www.debian.org/mirror/list>`__
|
||||||
|
|
||||||
|
By default only the ``main`` component is used. If
|
||||||
|
``DIB_DEBIAN_COMPONENTS`` (comma separated) from the
|
||||||
|
``debootstrap`` element has been set, that list of components will
|
||||||
|
be used instead.
|
||||||
|
|
||||||
|
Backports, updates and security are included unless ``DIB_RELEASE``
|
||||||
|
is ``unstable``.
|
||||||
|
|
||||||
|
2. Complete configuration given in the variable ``DIB_APT_SOURCES_CONF``.
|
||||||
|
|
||||||
|
Each line contains exactly one entry for the sources.list.d
|
||||||
|
directory. The first word must be the logical name (which is used
|
||||||
|
as file name with ``.list`` automatically appended), followed by a
|
||||||
|
colon ``:``, followed by the complete repository specification.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
DIB_APT_SOURCES_CONF=\
|
||||||
|
"default:deb http://10.0.0.10/ stretch main contrib
|
||||||
|
mysecurity:deb http://10.0.0.10/ stretch-security main contrib"
|
||||||
|
|
||||||
If necessary, a custom apt keyring and debootstrap script can be
|
If necessary, a custom apt keyring and debootstrap script can be
|
||||||
supplied to the `debootstrap` command via `DIB_APT_KEYRING` and
|
supplied to the ``debootstrap`` command via ``DIB_APT_KEYRING`` and
|
||||||
`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the
|
``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` respectively. Both options require the
|
||||||
use of absolute rather than relative paths.
|
use of absolute rather than relative paths.
|
||||||
|
|
||||||
Use of this element will also require the tool 'debootstrap' to be
|
Use of this element will also require the tool 'debootstrap' to be
|
||||||
available on your system. It should be available on Ubuntu, Debian,
|
available on your system. It should be available on Ubuntu, Debian,
|
||||||
and Fedora.
|
and Fedora. It is also recommended that the 'debian-keyring' package
|
||||||
|
be installed.
|
||||||
|
|
||||||
The `DIB_OFFLINE` or more specific `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`
|
The ``DIB_OFFLINE`` or more specific ``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE``
|
||||||
variables can be set to prefer the use of a pre-cached root filesystem
|
variables can be set to prefer the use of a pre-cached root filesystem
|
||||||
tarball. Setting `DIB_OFFLINE` may cause other element to use cached data,
|
tarball.
|
||||||
while `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` only functions in the debootstrap
|
|
||||||
element.
|
|
||||||
|
|
||||||
The `DIB_DEBOOTSTRAP_EXTRA_ARGS` environment variable may be used to
|
The ``DIB_DEBOOTSTRAP_EXTRA_ARGS`` environment variable may be used to
|
||||||
pass extra arguments to the debootstrap command used to create the
|
pass extra arguments to the debootstrap command used to create the
|
||||||
base filesystem image. If --keyring is is used in `DIB_DEBOOTSTRAP_EXTRA_ARGS`,
|
base filesystem image. If --keyring is is used in ``DIB_DEBOOTSTRAP_EXTRA_ARGS``,
|
||||||
it will override `DIB_APT_KEYRING` if that is used as well.
|
it will override ``DIB_APT_KEYRING`` if that is used as well.
|
||||||
|
|
||||||
The `DIB_DEBOOTSTRAP_CACHE` variable can be used to cache the created root
|
For further information about ``DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`` ,
|
||||||
filesystem. By default this is 0 (disabled) and any other value enables this.
|
``DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`` and ``DIB_DEBOOTSTRAP_EXTRA_ARGS``
|
||||||
If run in offline mode then the most recently cached rootfs is used instead of
|
please consult "README.rst" of the debootstrap element.
|
||||||
being built.
|
|
||||||
|
|
||||||
The `DIB_DEBOOTSTRAP_DEFAULT_LOCALE` environment variable may be used
|
|
||||||
to configure the default locale of the base image. It defaults to
|
|
||||||
C.UTF-8.
|
|
||||||
|
|
||||||
-------------------
|
-------------------
|
||||||
Note on ARM systems
|
Note on ARM systems
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
Because there is not a one-to-one mapping of `ARCH` to a kernel package, if
|
Because there is not a one-to-one mapping of ``ARCH`` to a kernel package, if
|
||||||
you are building an image for ARM on debian, you need to specify which kernel
|
you are building an image for ARM on debian, you need to specify which kernel
|
||||||
you want in the environment variable `DIB_ARM_KERNEL`. For instance, if you want
|
you want in the environment variable ``DIB_ARM_KERNEL``. For instance, if you want
|
||||||
the `linux-image-mx5` package installed, set `DIB_ARM_KERNEL` to `mx5`.
|
the ``linux-image-mx5`` package installed, set ``DIB_ARM_KERNEL`` to ``mx5``.
|
||||||
|
|
||||||
.. element_deps::
|
.. element_deps::
|
||||||
|
@ -2,33 +2,13 @@
|
|||||||
ubuntu-minimal
|
ubuntu-minimal
|
||||||
==============
|
==============
|
||||||
|
|
||||||
Note: The ubuntu element is likely what you want unless you really know
|
The ``ubuntu-minimal`` element uses debootstrap for generating a
|
||||||
you want this one for some reason. The ubuntu element gets a lot more testing
|
minimal image. In contrast the ``ubuntu`` element uses the cloud-image
|
||||||
coverage and use.
|
as the initial base.
|
||||||
|
|
||||||
Create a minimal image based on Ubuntu. We default to xenial but DIB_RELEASE
|
By default this element creates the latest LTS release. The exact
|
||||||
is mapped to any series of Ubuntu.
|
setting can be found in the element's ``environment.d`` directory in
|
||||||
|
the variable ``DIB_RELEASE``. If a different release of Ubuntu should
|
||||||
If necessary, a custom apt keyring and debootstrap script can be
|
be created, the variable ``DIB_RELEASE`` can be set appropriately.
|
||||||
supplied to the `debootstrap` command via `DIB_APT_KEYRING` and
|
|
||||||
`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the
|
|
||||||
use of absolute rather than relative paths.
|
|
||||||
|
|
||||||
Use of this element will also require the tool 'debootstrap' to be
|
|
||||||
available on your system. It should be available on Ubuntu, Debian,
|
|
||||||
and Fedora.
|
|
||||||
|
|
||||||
The `DIB_OFFLINE` or more specific `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`
|
|
||||||
variables can be set to prefer the use of a pre-cached root filesystem
|
|
||||||
tarball.
|
|
||||||
|
|
||||||
The `DIB_DEBOOTSTRAP_EXTRA_ARGS` environment variable may be used to
|
|
||||||
pass extra arguments to the debootstrap command used to create the
|
|
||||||
base filesystem image. If --keyring is is used in `DIB_DEBOOTSTRAP_EXTRA_ARGS`,
|
|
||||||
it will override `DIB_APT_KEYRING` if that is used as well.
|
|
||||||
|
|
||||||
For further information about `DIB_DEBIAN_DEBOOTSTRAP_SCRIPT`,
|
|
||||||
`DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` and `DIB_DEBOOTSTRAP_EXTRA_ARGS`
|
|
||||||
please consult "README.rst" of the debootstrap element.
|
|
||||||
|
|
||||||
.. element_deps::
|
.. element_deps::
|
||||||
|
@ -7,11 +7,9 @@ Use Ubuntu cloud images as the baseline for built disk images.
|
|||||||
Overrides:
|
Overrides:
|
||||||
|
|
||||||
* To use a non-default URL for downloading base Ubuntu cloud images,
|
* To use a non-default URL for downloading base Ubuntu cloud images,
|
||||||
use the environment variable DIB\_CLOUD\_IMAGES
|
use the environment variable ``DIB_CLOUD_IMAGES``
|
||||||
* To download a non-default release of Ubuntu cloud images, use the
|
* To download a non-default release of Ubuntu cloud images, use the
|
||||||
environment variable DIB\_RELEASE. This element will export the DIB_RELEASE
|
environment variable ``DIB_RELEASE``. This element will export the
|
||||||
variable.
|
``DIB_RELEASE`` variable.
|
||||||
* To use different mirrors rather than the default of archive.ubuntu.com and
|
|
||||||
security.ubuntu.com, use the environment variable DIB\_DISTRIBUTION\_MIRROR
|
|
||||||
|
|
||||||
.. element_deps::
|
.. element_deps::
|
||||||
|
Loading…
Reference in New Issue
Block a user