kevinheyer/bootstrap-vz
1
0
Fork 0
mirror of https://github.com/kevingruesser/bootstrap-vz.git synced 2025-08-24 15:36:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Better formatting for manifests readme

Browse source
This commit is contained in:
Anders Ingemann 2015-04-19 17:06:17 +02:00
parent fe68d20829
commit 134e283748
1 changed files with 77 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
manifests/README.rst
View file

@ -1,9 +1,7 @@
Manifest Manifest
======== ========
The manifest file is the primary way to interact with bootstrap-vz.
| The manifest file is the primary way to interact with bootstrap-vz. Every configuration and customization of a Debian installation is specified in this file.
| Every configuration and customization of a Debian installation is
specified in this file.
The manifest format is YAML or JSON. It is near impossible to run the The manifest format is YAML or JSON. It is near impossible to run the
bootstrapper with an invalid configuration, since every part of the bootstrapper with an invalid configuration, since every part of the
@ -23,7 +21,7 @@ bootstrapper (e.g. all python date formatting variables are available).
Any reference uses dots to specify a path to the desired manifest Any reference uses dots to specify a path to the desired manifest
setting. Not all settings support this though, to see whether embedding setting. Not all settings support this though, to see whether embedding
a manifest variable in a setting is possible, look for the a manifest variable in a setting is possible, look for the
*``manifest vars``* label. ``manifest vars`` label.
Sections Sections
-------- --------
@ -36,8 +34,8 @@ Provider
The provider section contains all provider specific settings and the The provider section contains all provider specific settings and the
name of the provider itself. name of the provider itself.
- **``name``**: target virtualization platform of the installation - ``name``: target virtualization platform of the installation
*``required``* ``required``
Consult the `providers <../bootstrapvz/providers>`__ section of the documentation Consult the `providers <../bootstrapvz/providers>`__ section of the documentation
for a list of valid values. for a list of valid values.
@ -48,10 +46,10 @@ Bootstrapper
This section concerns the bootstrapper itself and its behavior. There This section concerns the bootstrapper itself and its behavior. There
are 4 possible settings: are 4 possible settings:
- **``workspace``**: Path to where the bootstrapper should place images - ``workspace``: Path to where the bootstrapper should place images
and intermediate files. Any volumes will be mounted under that path. and intermediate files. Any volumes will be mounted under that path.
*``required``* ``required``
- **``tarball``**: debootstrap has the option to download all the - ``tarball``: debootstrap has the option to download all the
software and pack it up in a tarball. When starting the actual software and pack it up in a tarball. When starting the actual
bootstrapping process, debootstrap can then be pointed at that bootstrapping process, debootstrap can then be pointed at that
tarball and use it instead of downloading anything from the internet. tarball and use it instead of downloading anything from the internet.
@ -60,26 +58,26 @@ are 4 possible settings:
whether it should create a new tarball or not. It will search for and whether it should create a new tarball or not. It will search for and
use an available tarball if it already exists, regardless of this use an available tarball if it already exists, regardless of this
setting. setting.
*``optional``* ``optional``
Valid values: ``true, false`` Valid values: ``true, false``
Default: ``false`` Default: ``false``
- **``mirror``**: The mirror debootstrap should download software from. - ``mirror``: The mirror debootstrap should download software from.
It is advisable to specify a mirror close to your location (or the It is advisable to specify a mirror close to your location (or the
location of the host you are bootstrapping on), to decrease latency location of the host you are bootstrapping on), to decrease latency
and improve bandwidth. If not specified, `the configured aptitude and improve bandwidth. If not specified, `the configured aptitude
mirror URL <#packages>`__ is used. mirror URL <#packages>`__ is used.
*``optional``* ``optional``
- **``include_packages``**: Extra packages to be installed during - ``include_packages``: Extra packages to be installed during
bootstrap. Accepts a list of package names. bootstrap. Accepts a list of package names.
*``optional``* ``optional``
- **``exclude_packages``**: Packages to exclude during bootstrap phase. - ``exclude_packages``: Packages to exclude during bootstrap phase.
Accepts a list of package names. Accepts a list of package names.
*``optional``* ``optional``
- **``guest_additions``**: This setting is only relevant for the - ``guest_additions``: This setting is only relevant for the
`virtualbox provider <../bootstrapvz/providers/virtualbox.html>`__. `virtualbox provider <../bootstrapvz/providers/virtualbox.html>`__.
It specifies the path to the VirtualBox Guest Additions ISO, which, when specified, It specifies the path to the VirtualBox Guest Additions ISO, which, when specified,
will be mounted and used to install the VirtualBox Guest Additions. will be mounted and used to install the VirtualBox Guest Additions.
*``optional``* ``optional``
Image Image
~~~~~ ~~~~~
@ -87,23 +85,23 @@ Image
The image section configures anything pertaining directly to the image The image section configures anything pertaining directly to the image
that will be created. that will be created.
- **``name``**: The name of the resulting image. - ``name``: The name of the resulting image.
When bootstrapping cloud images, this would be the name visible in When bootstrapping cloud images, this would be the name visible in
the interface when booting up new instances. the interface when booting up new instances.
When bootstrapping for VirtualBox or kvm, it's the filename of the When bootstrapping for VirtualBox or kvm, it's the filename of the
image. image.
*``required``* ``required``
*``manifest vars``* ``manifest vars``
- **``description``**: Description of the image. Where this setting is - ``description``: Description of the image. Where this setting is
used depends highly on which provider is set. At the moment it is used depends highly on which provider is set. At the moment it is
only used for AWS images. only used for AWS images.
**``required for ec2 provider``** ``required for ec2 provider``
*``manifest vars``* ``manifest vars``
- **``bucket``**: When bootstrapping an S3 backed image for AWS, this - ``bucket``: When bootstrapping an S3 backed image for AWS, this
will be the bucket where the image is uploaded to. will be the bucket where the image is uploaded to.
**``required for S3 backing``** ``required for S3 backing``
- **``region``**: Region in which the AMI should be registered. - ``region``: Region in which the AMI should be registered.
**``required for S3 backing``** ``required for S3 backing``
System System
~~~~~~ ~~~~~~
@ -111,30 +109,30 @@ System
This section defines anything that pertains directly to the bootstrapped This section defines anything that pertains directly to the bootstrapped
system and does not fit under any other section. system and does not fit under any other section.
- **``architecture``**: The architecture of the system. - ``architecture``: The architecture of the system.
Valid values: ``i386, amd64`` Valid values: ``i386, amd64``
*``required``* ``required``
- **``bootloader``**: The bootloader for the system. Depending on the - ``bootloader``: The bootloader for the system. Depending on the
bootmethod of the virtualization platform, the options may be bootmethod of the virtualization platform, the options may be
restricted. restricted.
Valid values: ``grub, extlinux, pv-grub`` Valid values: ``grub, extlinux, pv-grub``
*``required``* ``required``
- **``charmap``**: The default charmap of the system. - ``charmap``: The default charmap of the system.
Valid values: Any valid charmap like ``UTF-8``, ``ISO-8859-*`` or Valid values: Any valid charmap like ``UTF-8``, ``ISO-8859-`` or
``GBK``. ``GBK``.
*``required``* ``required``
- **``hostname``**: hostname to preconfigure the system with. - ``hostname``: hostname to preconfigure the system with.
*``optional``* ``optional``
- **``locale``**: The default locale of the system. - ``locale``: The default locale of the system.
Valid values: Any locale mentioned in ``/etc/locale.gen`` Valid values: Any locale mentioned in ``/etc/locale.gen``
*``required``* ``required``
- **``release``**: Defines which debian release should be bootstrapped. - ``release``: Defines which debian release should be bootstrapped.
Valid values: ``squeeze``, ``wheezy``, ``jessie``, ``sid``, Valid values: ``squeeze``, ``wheezy``, ``jessie``, ``sid``,
``oldstable``, ``stable``, ``testing``, ``unstable`` ``oldstable``, ``stable``, ``testing``, ``unstable``
*``required``* ``required``
- **``timezone``**: Timezone of the system. - ``timezone``: Timezone of the system.
Valid values: Any filename from ``/usr/share/zoneinfo`` Valid values: Any filename from ``/usr/share/zoneinfo``
*``required``* ``required``
Packages Packages
~~~~~~~~ ~~~~~~~~
@ -142,10 +140,10 @@ Packages
The packages section allows you to install custom packages from a The packages section allows you to install custom packages from a
variety of sources. variety of sources.
- **``install``**: A list of strings that specify which packages should - ``install``: A list of strings that specify which packages should
be installed. Valid values: package names optionally followed by a be installed. Valid values: package names optionally followed by a
``/target`` or paths to local ``.deb`` files. ``/target`` or paths to local ``.deb`` files.
- **``install_standard``**: Defines if the packages of the - ``install_standard``: Defines if the packages of the
``"Standard System Utilities"`` option of the Debian installer, ``"Standard System Utilities"`` option of the Debian installer,
provided by `tasksel <https://wiki.debian.org/tasksel>`__, should be provided by `tasksel <https://wiki.debian.org/tasksel>`__, should be
installed or not. The problem is that with just ``debootstrap``, the installed or not. The problem is that with just ``debootstrap``, the
@ -153,36 +151,36 @@ variety of sources.
machine that will not be used interactively, but otherwise it is nice machine that will not be used interactively, but otherwise it is nice
to have at hand tools like ``bash-completion``, ``less``, ``locate``, to have at hand tools like ``bash-completion``, ``less``, ``locate``,
etc. etc.
*``optional``* ``optional``
Valid values: ``true``, ``false`` Valid values: ``true``, ``false``
Default: ``false`` Default: ``false``
- **``mirror``**: The default aptitude mirror. - ``mirror``: The default aptitude mirror.
*``optional``* ``optional``
Default: ``http://http.debian.net/debian`` Default: ``http://http.debian.net/debian``
- **``sources``**: A map of additional sources that should be added to - ``sources``: A map of additional sources that should be added to
the aptitude sources list. The key becomes the filename in the aptitude sources list. The key becomes the filename in
``/etc/apt/sources.list.d/`` (with ``.list`` appended to it), while ``/etc/apt/sources.list.d/`` (with ``.list`` appended to it), while
the value is an array with each entry being a line. the value is an array with each entry being a line.
*``optional``* ``optional``
- **``components``**: A list of components that should be added to the - ``components``: A list of components that should be added to the
default apt sources. For example ``contrib`` or ``non-free`` default apt sources. For example ``contrib`` or ``non-free``
*``optional``* ``optional``
Default: ``['main']`` Default: ``['main']``
- **``trusted-keys``**: List of paths to ``.gpg`` keyrings that should - ``trusted-keys``: List of paths to ``.gpg`` keyrings that should
be added to the aptitude keyring of trusted signatures for be added to the aptitude keyring of trusted signatures for
repositories. repositories.
*``optional``* ``optional``
- **``preferences``**: Allows you to pin packages through `apt - ``preferences``: Allows you to pin packages through `apt
preferences <https://wiki.debian.org/AptPreferences>`__. The setting preferences <https://wiki.debian.org/AptPreferences>`__. The setting
is an object where the key is the preference filename in is an object where the key is the preference filename in
``/etc/apt/preferences.d/``. The key ``main`` is special and refers ``/etc/apt/preferences.d/``. The key ``main`` is special and refers
to the file ``/etc/apt/preferences``, which will be overwritten if to the file ``/etc/apt/preferences``, which will be overwritten if
specified. specified.
*``optional``* ``optional``
The values are objects with three keys: The values are objects with three keys:
- **``package``**: The package to pin (wildcards allowed) - ``package``: The package to pin (wildcards allowed)
- **``pin``**: The release to pin the package to. - ``pin``: The release to pin the package to.
- **``pin-priority``**: The priority of this pin. - ``pin-priority``: The priority of this pin.
Volume Volume
~~~~~~ ~~~~~~
@ -193,45 +191,45 @@ volumes using either the gpt or msdos scheme. At most, there are only
three partitions with predefined roles configurable though. They are three partitions with predefined roles configurable though. They are
boot, root and swap. boot, root and swap.
- **``backing``**: Specifies the volume backing. This setting is very - ``backing``: Specifies the volume backing. This setting is very
provider specific. provider specific.
Valid values: ``ebs``, ``s3``, ``vmdk``, ``vdi``, ``raw`` Valid values: ``ebs``, ``s3``, ``vmdk``, ``vdi``, ``raw``
*``required``* ``required``
- **``partitions``**: A map of the partitions that should be created on - ``partitions``: A map of the partitions that should be created on
the volume. the volume.
- **``type``**: The partitioning scheme to use. When using ``none``, - ``type``: The partitioning scheme to use. When using ``none``,
only root can be specified as a partition. only root can be specified as a partition.
Valid values: ``none``, ``gpt``, ``msdos`` Valid values: ``none``, ``gpt``, ``msdos``
*``required``* ``required``
- **``root``**: Configuration of the root partition. *``required``* - ``root``: Configuration of the root partition. ``required``
- **``size``**: The size of the partition. Valid values: Any - ``size``: The size of the partition. Valid values: Any
datasize specification up to TB (e.g. 5KiB, 1MB, 6TB). datasize specification up to TB (e.g. 5KiB, 1MB, 6TB).
*``required``* ``required``
- **``filesystem``**: The filesystem of the partition. When choosing - ``filesystem``: The filesystem of the partition. When choosing
``xfs``, the ``xfsprogs`` package will need to be installed. ``xfs``, the ``xfsprogs`` package will need to be installed.
Valid values: ``ext2``, ``ext3``, ``ext4``, ``xfs`` Valid values: ``ext2``, ``ext3``, ``ext4``, ``xfs``
*``required``* ``required``
- **``format_command``**: Command to format the partition with. This - ``format_command``: Command to format the partition with. This
optional setting overrides the command bootstrap-vz would normally optional setting overrides the command bootstrap-vz would normally
use to format the partition. The command is specified as a string use to format the partition. The command is specified as a string
array where each option/argument is an item in that array (much array where each option/argument is an item in that array (much
like the `image\_commands <../bootstrapvz/plugins/image_commands.html>`__ plugin). like the `image\_commands <../bootstrapvz/plugins/image_commands.html>`__ plugin).
*``optional``* The following variables are available: ``optional`` The following variables are available:
- **``{fs}``**: The filesystem of the partition. - ``{fs}``: The filesystem of the partition.
- **``{device_path}``**: The device path of the partition. - ``{device_path}``: The device path of the partition.
- **``{size}``**: The size of the partition. - ``{size}``: The size of the partition.
The default command used by boostrap-vz is The default command used by boostrap-vz is
``['mkfs.{fs}', '{device_path}']``. ``['mkfs.{fs}', '{device_path}']``.
- **``boot``**: Configuration of the boot partition. The three - ``boot``: Configuration of the boot partition. The three
settings equal those of the root partition. settings equal those of the root partition.
*``optional``* ``optional``
- **``swap``**: Configuration of the swap partition. Since the swap - ``swap``: Configuration of the swap partition. Since the swap
partition has its own filesystem you can only specify the size for partition has its own filesystem you can only specify the size for
this partition. this partition.
*``optional``* ``optional``
Plugins Plugins
~~~~~~~ ~~~~~~~