diff --git a/doc/source/index.rst b/doc/source/index.rst index 7d277349c..c683ab654 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,7 +8,7 @@ It includes support for building images based on many major distributions and can produce cloud-images in all common formats (``qcow2``, ``vhd``, ``raw``, etc), bare metal file-system images and ram-disk images. These images are composed from the many included -`elements`; ``diskimage-builder`` acts as a framework to easily add +``elements``; ``diskimage-builder`` acts as a framework to easily add your own elements for even further customization. ``diskimage-builder`` is used extensively by the `TripleO project @@ -35,15 +35,15 @@ Issues Issues are tracked on launchpad at: - * `https://bugs.launchpad.net/diskimage-builder/+bugs` - + * ``__ Communication ------------- Communication among the diskimage-builder developers happens on IRC in -#openstack-dib on freenode and on the openstack-dev mailing list (openstack-dev@lists.openstack.org). +``#openstack-dib`` on freenode and on the ``openstack-dev`` mailing list +(``openstack-dev@lists.openstack.org``). Table of Contents @@ -55,3 +55,4 @@ Table of Contents user_guide/index developer/index elements + specs/README diff --git a/doc/source/specs/README.rst b/doc/source/specs/README.rst index 2840b9b6a..8f9f5e33c 100644 --- a/doc/source/specs/README.rst +++ b/doc/source/specs/README.rst @@ -1,10 +1,9 @@ -======= -README -======= - +================================ diskimage-builder Specifications ================================ +Overview +======== This directory is used to hold approved design specifications for changes to the diskimage-builder project. Reviews of the specs are done in gerrit, using a @@ -46,7 +45,7 @@ given release should only refer to the ``implemented`` directory. Example specifications ---------------------- -You can find an example spec in ``specs/template.rst``. +You can find an example spec in :doc:`v1/approved/v1-template` Backlog specifications ---------------------- @@ -80,3 +79,11 @@ change any of our public APIs are sometimes not required to provide a specification. The decision of whether something is trivial or not is a judgement made by the author or by consensus of the project cores, generally trying to err on the side of spec creation. + +Approved Specifications +======================= + +.. toctree:: + :glob: + + v1/approved/* diff --git a/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst b/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst index ec17e9eb7..81b96ffe2 100644 --- a/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst +++ b/doc/source/specs/v1/approved/block-device-lvl1-partitioning.rst @@ -20,7 +20,9 @@ The implementation for this proposed changed already exists, was discussed and is currently waiting for reviews [1]. To have a complete overview over the block device setup, this document is provided. + The dependencies are not implemented as they should be, because + * the spec process is currently in the phase of discussion and not finalized [2], * the implementation was finished and reviewed before the spec process @@ -137,14 +139,15 @@ size Example: -:: - ["partitioning", - {"rootdisk": { - "label": "mbr", - "partitions": - [{"name": "part-01", - "flags": ["boot"], - "size": "100%"}]}}] +.. code-block:: yaml + + ["partitioning", + {"rootdisk": { + "label": "mbr", + "partitions": + [{"name": "part-01", + "flags": ["boot"], + "size": "100%"}]}}] Security impact --------------- diff --git a/doc/source/specs/v1/approved/block-device-overview.rst b/doc/source/specs/v1/approved/block-device-overview.rst index 105d413b5..3f10cc8ee 100644 --- a/doc/source/specs/v1/approved/block-device-overview.rst +++ b/doc/source/specs/v1/approved/block-device-overview.rst @@ -123,6 +123,7 @@ level or module needs it's own spec. A first step is to reimplement the existing functionality, this contains: + #. Level 0: Local Loop module Use loop device on local image file (This is already implemented: [1]) @@ -133,6 +134,7 @@ contains: #. Level 3: Mounting As a second step the following functionality can be added: + * Level 1: LVM module * Level 2: Create File System (swap) diff --git a/elements/cloud-init/README.rst b/elements/cloud-init/README.rst index 707823e48..2f51545af 100644 --- a/elements/cloud-init/README.rst +++ b/elements/cloud-init/README.rst @@ -1,6 +1,6 @@ -======== +========== cloud-init -======== +========== Install's and enables cloud-init for systems that don't come with it pre-installed diff --git a/elements/debian-minimal/README.rst b/elements/debian-minimal/README.rst index 66f017218..7a4bd11df 100644 --- a/elements/debian-minimal/README.rst +++ b/elements/debian-minimal/README.rst @@ -2,48 +2,51 @@ debian-minimal ============== -Create a minimal image based on Debian. We default to unstable but `DIB_RELEASE` -can be set to any series of Debian. +Create a minimal image based on Debian. We default to unstable but +``DIB_RELEASE`` can be set to any series of Debian. 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: + * ``DIB_DISTRIBUTION_MIRROR``: the mirror to use (default: + ``__) - https://www.debian.org/mirror/list + * ``DIB_DEBIAN_COMPONENTS``: (default: ``main``) a comma + separated list of components. For Debian this can be + e.g. ``main,contrib,non-free``. - By default only `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. + Note it is not recommended to use + ``__ for ``DIB_DISTRIBUTION_MIRROR`` + due to how unreliable it is. Be sure to select a mirror from the + official mirror list at ``__ - Backports, updates and security are included unless `DIB_RELEASE` - is `unstable`. + 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``. -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. - Example: - 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" + 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 @@ -51,24 +54,24 @@ 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` +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 +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. -For further information about `DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` , -`DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` and `DIB_DEBOOTSTRAP_EXTRA_ARGS` +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``. diff --git a/elements/partitioning-sfdisk/README.rst b/elements/partitioning-sfdisk/README.rst index 8528e04d1..a3471e32d 100644 --- a/elements/partitioning-sfdisk/README.rst +++ b/elements/partitioning-sfdisk/README.rst @@ -5,15 +5,27 @@ Sets up a partitioned disk using sfdisk, according to user needs. Environment Variables --------------------- -DIB_PARTITIONING_SFDISK_SCHEMA - : Required: Yes - : Default: 2048,,L * - 0 0; - 0 0; - 0 0; - : Description: A multi-line string specifying a disk schema in sectors. - : Example: ``DIB_PARTITIONING_SFDISK_SCHEMA=" - 2048,10000,L * - 10248,,L - 0 0; - " will create two partitions on disk, first one will be bootable. + +``DIB_PARTITIONING_SFDISK_SCHEMA`` + +:Required: + Yes +:Default: + :: + + 2048,,L * + 0 0; + 0 0; + 0 0; +:Description: + A multi-line string specifying a disk schema in sectors. +:Example: + + .. code-block:: bash + + DIB_PARTITIONING_SFDISK_SCHEMA=" + 2048,10000,L * + 10248,,L + 0 0;" + + will create two partitions on disk, first one will be bootable. diff --git a/elements/python-brickclient/README.rst b/elements/python-brickclient/README.rst index 24612815d..aa1850860 100644 --- a/elements/python-brickclient/README.rst +++ b/elements/python-brickclient/README.rst @@ -1,34 +1,48 @@ python-brickclient ================== -* This element is aimed for providing cinder local attach/detach functionality. +* This element is aimed for providing cinder local attach/detach + functionality. + * Currently the feature has a dependency on a known bug - "https://launchpad.net/bugs/1623549", which has been resolved and will be part - of the upstream with the next release of python-brick-cinderclient-ext. - Note: Current version of python-brick-cinderclient-ext i.e. 0.2.0 requires and update - to be made in Line32 fo below script. - /usr/share/python-brickclient/venv/lib/python2.7/site-packages/brick_cinderclient_ext/__init__.py - update "brick-python-cinderclient-ext" to "python-brick-cinderclient-ext". + ``__, which has been resolved + and will be part of the upstream with the next release of + ``python-brick-cinderclient-ext``. Note: Current version of + ``python-brick-cinderclient-ext`` i.e. 0.2.0 requires and update to + be made in Line32 for + ``/usr/share/python-brickclient/venv/lib/python2.7/site-packages/brick_cinderclient_ext/__init__.py``: + update ``brick-python-cinderclient-ext`` to + ``python-brick-cinderclient-ext``. -* Usage: - Pass the below shell script to parameter 'user-data' and set 'config-drive=true' - at the time of provisioning the node via nova-boot to make cinder local - attach/detach commands talk to your cloud controller. - [Example of Config Drive Script] - #!/bin/bash - FILE="/etc/bash.bashrc" - [ ! -f "$FILE" ] && touch "$FILE" - echo 'export OS_AUTH_URL="http://:5000/v2.0"' >> "$FILE" - echo 'export OS_PASSWORD="password"' >> "$FILE" - echo 'export OS_USERNAME="demo"' >> "$FILE" - echo 'export OS_TENANT_NAME="demo"' >> "$FILE" - echo 'export OS_PROJECT_NAME="demo"' >> "$FILE" - exec bash - To attach: /usr/share/python-brickclient/venv/bin/cinder local-attach - To detach: /usr/share/python-brickclient/venv/bin/cinder local-detach +Usage +----- -* Alternatively, the same action can be completed manually at the node which does - not require setting up of config drive such as: - /usr/share/python-brickclient/venv/bin/cinder --os-username demo --os-password \ - password --os-tenant-name demo --os-project-name demo \ - --os-auth-url=http://:5000/v2.0 local-attach +Pass the below shell script to parameter ``user-data`` and set +``config-drive=true`` at the time of provisioning the node via +nova-boot to make cinder local attach/detach commands talk to your +cloud controller. + +.. code-block:: bash + + #!/bin/bash + FILE="/etc/bash.bashrc" + [ ! -f "$FILE" ] && touch "$FILE" + echo 'export OS_AUTH_URL="http://:5000/v2.0"' >> "$FILE" + echo 'export OS_PASSWORD="password"' >> "$FILE" + echo 'export OS_USERNAME="demo"' >> "$FILE" + echo 'export OS_TENANT_NAME="demo"' >> "$FILE" + echo 'export OS_PROJECT_NAME="demo"' >> "$FILE" + exec bash + + To attach: ``/usr/share/python-brickclient/venv/bin/cinder local-attach `` + To detach: ``/usr/share/python-brickclient/venv/bin/cinder local-detach `` + +Alternatively, the same action can be completed manually at the node +which does not require setting up of config drive such as: + +.. code-block:: bash + + /usr/share/python-brickclient/venv/bin/cinder \ + --os-username demo --os-password password \ + --os-tenant-name demo --os-project-name demo \ + --os-auth-url=http://:5000/v2.0 local-attach diff --git a/elements/rhel7/README.rst b/elements/rhel7/README.rst index 11536af01..f387b006e 100644 --- a/elements/rhel7/README.rst +++ b/elements/rhel7/README.rst @@ -13,7 +13,10 @@ https://access.redhat.com/downloads/content/69/ver=/rhel---7/7.1/x86_64/product- Then before running the image build, define DIB_LOCAL_IMAGE (replace the file name with the one downloaded, if it differs from the example):: - export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2 + +.. code-block:: bash + + export DIB_LOCAL_IMAGE=rhel-guest-image-7.1-20150224.0.x86_64.qcow2 The downloaded file will then be used as the basis for any subsequent image builds.