Merge "Unify and fix doc of several Debian and Ubuntu elements"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
5c1579f0d6
@ -2,77 +2,13 @@
|
||||
debian-minimal
|
||||
==============
|
||||
|
||||
Create a minimal image based on Debian. We default to unstable but
|
||||
``DIB_RELEASE`` can be set to any series of Debian.
|
||||
The ``debian-minimal`` element uses debootstrap for generating a
|
||||
minimal image. In contrast the ``debian`` element uses the cloud-image
|
||||
as the initial base.
|
||||
|
||||
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
|
||||
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``.
|
||||
By default this element creates the latest stable release. The exact
|
||||
setting can be found in the element's ``environment.d`` directory in
|
||||
the variable ``DIB_RELEASE``. If a different release of Debian should
|
||||
be created, the variable ``DIB_RELEASE`` can be set appropriately.
|
||||
|
||||
.. element_deps::
|
||||
|
||||
@ -2,44 +2,10 @@
|
||||
debian
|
||||
======
|
||||
|
||||
Create an image based on Debian. We default to unstable but
|
||||
``DIB_RELEASE`` is mapped to any series of Debian.
|
||||
|
||||
Note that the default Debian series is `unstable`, and the default
|
||||
mirrors for Debian can be problematic for `unstable`. Because apt does
|
||||
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`.
|
||||
By default this element creates the latest stable release. The exact
|
||||
setting can be found in the ``debian-minimal/environment.d`` directory
|
||||
in the variable ``DIB_RELEASE``. If a different release of Debian
|
||||
should be created, the variable ``DIB_RELEASE`` can be set
|
||||
appropriately.
|
||||
|
||||
.. element_deps::
|
||||
|
||||
@ -4,45 +4,77 @@ debootstrap
|
||||
|
||||
Base element for creating minimal debian-based images.
|
||||
|
||||
This element is incomplete by itself, you'll want to use the debian-minimal
|
||||
or ubuntu-minimal elements to get an actual base image.
|
||||
This element is incomplete by itself, you'll want to use elements like
|
||||
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
|
||||
supplied to the `debootstrap` command via `DIB_APT_KEYRING` and
|
||||
`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the
|
||||
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.
|
||||
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
|
||||
tarball. Setting `DIB_OFFLINE` may cause other element to use cached data,
|
||||
while `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` only functions in the debootstrap
|
||||
element.
|
||||
tarball.
|
||||
|
||||
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
|
||||
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.
|
||||
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.
|
||||
|
||||
The `DIB_DEBOOTSTRAP_CACHE` variable can be used to cache the created root
|
||||
filesystem. By default this is 0 (disabled) and any other value enables this.
|
||||
If run in offline mode then the most recently cached rootfs is used instead of
|
||||
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.
|
||||
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
|
||||
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`.
|
||||
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::
|
||||
|
||||
@ -2,33 +2,13 @@
|
||||
ubuntu-minimal
|
||||
==============
|
||||
|
||||
Note: The ubuntu element is likely what you want unless you really know
|
||||
you want this one for some reason. The ubuntu element gets a lot more testing
|
||||
coverage and use.
|
||||
The ``ubuntu-minimal`` element uses debootstrap for generating a
|
||||
minimal image. In contrast the ``ubuntu`` element uses the cloud-image
|
||||
as the initial base.
|
||||
|
||||
Create a minimal image based on Ubuntu. We default to xenial but DIB_RELEASE
|
||||
is mapped to any series of Ubuntu.
|
||||
|
||||
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.
|
||||
By default this element creates the latest LTS release. The exact
|
||||
setting can be found in the element's ``environment.d`` directory in
|
||||
the variable ``DIB_RELEASE``. If a different release of Ubuntu should
|
||||
be created, the variable ``DIB_RELEASE`` can be set appropriately.
|
||||
|
||||
.. element_deps::
|
||||
|
||||
@ -7,11 +7,9 @@ Use Ubuntu cloud images as the baseline for built disk images.
|
||||
Overrides:
|
||||
|
||||
* 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
|
||||
environment variable DIB\_RELEASE. This element will export the 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
|
||||
environment variable ``DIB_RELEASE``. This element will export the
|
||||
``DIB_RELEASE`` variable.
|
||||
|
||||
.. element_deps::
|
||||
|
||||
Loading…
Reference in New Issue
Block a user