[elbe-devel] [PATCH 2/9] docs: check in reST files
Thomas Weißschuh
thomas.weissschuh at linutronix.de
Mon Apr 8 15:08:37 CEST 2024
These files have been generated by the existing Makefile.
docs/article-elbe-schema-reference.rst is skipped as it would create a
lot of code churn and is generated anyways.
Signed-off-by: Thomas Weißschuh <thomas.weissschuh at linutronix.de>
---
.gitignore | 2 -
docs/article-elbeoverview-en.rst | 987 +++++++++++++++++++++++++++++++++++++++
docs/article-quickstart.rst | 562 ++++++++++++++++++++++
docs/elbe-add.rst | 55 +++
docs/elbe-buildchroot.rst | 111 +++++
docs/elbe-buildsdk.rst | 49 ++
docs/elbe-buildsysroot.rst | 76 +++
docs/elbe-check_updates.rst | 86 ++++
docs/elbe-chg_archive.rst | 80 ++++
docs/elbe-chroot.rst | 91 ++++
docs/elbe-control.rst | 252 ++++++++++
docs/elbe-daemon.rst | 48 ++
docs/elbe-db.rst | 151 ++++++
docs/elbe-debianize.rst | 79 ++++
docs/elbe-diff.rst | 48 ++
docs/elbe-fetch_initvm_pkgs.rst | 85 ++++
docs/elbe-gen_update.rst | 86 ++++
docs/elbe-genlicence.rst | 73 +++
docs/elbe-get_archive.rst | 56 +++
docs/elbe-hdimg.rst | 75 +++
docs/elbe-init.rst | 97 ++++
docs/elbe-initvm.rst | 174 +++++++
docs/elbe-mkcdrom.rst | 104 +++++
docs/elbe-parselicence.rst | 380 +++++++++++++++
docs/elbe-pbuilder.rst | 171 +++++++
docs/elbe-pkgdiff.rst | 50 ++
docs/elbe-preprocess.rst | 55 +++
docs/elbe-prjrepo.rst | 89 ++++
docs/elbe-remove_sign.rst | 56 +++
docs/elbe-repodir.rst | 87 ++++
docs/elbe-setsel.rst | 77 +++
docs/elbe-show.rst | 59 +++
docs/elbe-sign.rst | 62 +++
docs/elbe-toolchainextract.rst | 104 +++++
docs/elbe-updated.rst | 87 ++++
docs/elbe-validate.rst | 52 +++
docs/elbe-xsdtoasciidoc.rst | 57 +++
docs/elbe.rst | 121 +++++
38 files changed, 4932 insertions(+), 2 deletions(-)
diff --git a/.gitignore b/.gitignore
index 6edf0e1f3d73..f1f0bed2555e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,8 +28,6 @@ docs/*.1
docs/*.html
docs/*.png
docs/*.xml
-docs/elbe*.rst
-docs/article-*.rst
docs/manpage-base-url.xsl
docs/elbe-schema-reference.txt
debian/.control.swp
diff --git a/docs/article-elbeoverview-en.rst b/docs/article-elbeoverview-en.rst
new file mode 100644
index 000000000000..b7019202b175
--- /dev/null
+++ b/docs/article-elbeoverview-en.rst
@@ -0,0 +1,987 @@
+************************
+ELBE Overview
+************************
+
+Debian-based system to generate root filesystems for embedded devices.
+
+.. _`_general_notes`:
+
+General Notes
+=============
+
+Generally, root filesystem creation faces the following requirements:
+
+- Creation of root filesystem for a specific architecture.
+
+- Generation of a development environment for the specific
+ architecture.
+
+Trying to solve this via cross-compilation of the required packages, we
+face the following problems:
+
+- Many packages are not designed and tested for cross-compilation.
+
+- Big projects consume a significant amount of time to cross-compile.
+
+- Dependencies are not resolved automatically. The developer is
+ required to manually find out which package versions of dependencies
+ are required.
+
+- Changes and patches to the packages need to be updated for newer
+ versions. This process makes an update a very time-consuming process.
+
+- One must make sure that the same toolchain is used in the development
+ environment and in the root filesystem.
+
+Elbe takes a different approach to solve these problems:
+
+- Standard packages are not self-compiled. Elbe uses binary packages
+ from their respective Debian distributions.
+
+- Own applications are not cross-compiled. They are built natively on
+ the target architecture in a chroot environment using qemu.
+
+- The root filesystem is a subset of the Debian system inside the
+ chroot environment. This implicitly ensures that the same toolchain
+ is used on the development machine and on the target.
+
+- Updating, adding, or removing a package is done via Debian’s
+ package-management (apt) which also resolves package dependencies.
+
+.. _`_overview`:
+
+Overview
+========
+
+The Elbe system consists of the program ``elbe`` which is implemented in
+Python. Similar to git, it can be called with several sub commands. For
+example:
+
+::
+
+ elbe <command>
+ elbe initvm create --directory /scratch/example example.xml
+ elbe chg_archive example.xml archive.tar.bz2
+
+An Elbe project consists of an XML file that describes the project.
+
+This xml File is processed inside a virtual machine because we need root
+privileges to create the Rootfilesystem. This virtual machine is called
+*initvm* in the following text.
+
+When an xml File is now submitted into the initvm, the following
+happens:
+
+- Debian’s *debootstrap* utility is used to setup a Debian base system.
+
+- The packages specified in the package list of the XML file are
+ installed in the base system. The result of this is called the build
+ environment.
+
+- A copy of the environment is used as the target system. There is a
+ set of different modes for this copy.
+
+- If the XML file contains an archive, it will be unpacked into the
+ target, so the fine-tuning commands can use the content of the
+ archive, too.
+
+- Inside a chroot environment, the fine-tuning commands are applied to
+ the target.
+
+- The archive from the XML file is unpacked again. This is to ensure
+ the target filesystem contains all files from the archive, even if
+ some of them have been deleted by a fine-tuning command.
+
+- According to what is specified in the XML file, the target filesystem
+ is then baked into a tar archive and/or a filesystem image.
+
+This diagram illustrates the complete process:
+
+.. figure:: elbe-process.png
+ :alt: elbe-process.png
+
+The following figure shows the steps performed inside the build VM
+during the build process of the target. The highlighted steps are
+performed inside a chroot environment:
+
+.. figure:: elbeoverview-en__1.png
+ :alt: elbeoverview-en\__1.png
+
+On regular Debian installations, init scripts installed by packages are
+started automatically during the post-installation step. Please note
+that Elbe **will not start any services during package installation**.
+
+As a consequence, packages that require a specific service to be running
+will cause problems during installation. This typically includes
+database application packages, which set up a database in their postinst
+script and rely on the database server to be already running.
+
+.. _`_create_initvm_and_build_a_first_xml_file_from_the_examples`:
+
+Create initvm and build a first xml file from the examples
+==========================================================
+
+In order to use elbe, a user needs to be member of the ``libvirt``
+system group.
+
+To create an initvm and make that initvm build a first Rootfilesystem,
+use the following command:
+
+::
+
+ elbe initvm create --directory ~/elbe-initvm /usr/share/doc/elbe-doc/examples/x86_32-pc-hdimg-minimal-grub-buster.xml
+
+This will take quite a while.
+
+Only one initvm may run on a single computer. If an initvm is already
+running in the background, this command will exit with a failure notice.
+
+The initvm will keep on running, after this command. Further xml Files
+may be built using
+
+::
+
+ elbe initvm submit --directory ~/elbe-initvm /usr/share/doc/elbe-doc/examples/x86_32-pc-hdimg-minimal-grub-buster.xml
+
+The initvm will not be restarted upon a reboot of the machine.
+
+If you need to start the initvm again, use
+
+::
+
+ elbe initvm start --directory ~/elbe-initvm
+
+.. _`_example_xml_files`:
+
+Example XML Files
+-----------------
+
+A root-filesystem-project is described with a XML file.
+
+Elbe ships with a set of example XML files.
+
+The following XML file describes a simple system in the default full
+copy mode. The root filesystem is essentially identical to the build
+environment and it will be saved as ``nfsroot.tar.gz``
+
+.. container:: formalpara-title
+
+ **example.xml**
+
+.. code:: xml
+
+ <ns0:RootFileSystem xmlns:ns0="https://www.linutronix.de/projects/Elbe"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ created="2009-05-20T08:50:56" revision="6"
+ xsi:schemaLocation="https://www.linutronix.de/projects/Elbe dbsfed.xsd">
+ <project>
+ <name>ARMexample</name>
+ <version>08.15</version>
+ <description>full featured debian system</description>
+ <buildtype>armel</buildtype>
+ <mirror>
+ <primary_host>debian.tu-bs.de</primary_host>
+ <primary_path>/debian</primary_path>
+ <primary_proto>http</primary_proto>
+ <options>
+ <option>trusted=yes</option>
+ </options>
+ </mirror>
+ <suite>buster</suite>
+ </project>
+ <target>
+ <hostname>myARM</hostname>
+ <domain>tec.linutronix.de</domain>
+ <passwd>foo</passwd>
+ <console>ttyS0,115200</console>
+ <package>
+ <tar>
+ <name>nfsroot.tar.gz</name>
+ </tar>
+ </package>
+ <finetuning>
+ </finetuning>
+ <pkg-list>
+ <pkg>bash</pkg>
+ <pkg>openssh-server</pkg>
+ </pkg-list>
+ </target>
+ </ns0:RootFileSystem>
+
+To generate the project directory from the XML file the following
+command is used:
+
+::
+
+ elbe initvm submit --directory ~/elbe-initvm example.xml
+
+The directory ``~/elbe-initvm`` must contain a running initvm. If an
+initvm has not been created yet, use:
+
+::
+
+ elbe initvm create --directory ~/elbe-initvm example.xml
+
+.. _`_passwords_in_xml`:
+
+Passwords in XML
+----------------
+
+Using plain-text passwords in XML has advantages and disadvantages. The
+main advantage is the documentation of the login credentials for the
+generated systems. But storing plain-text passwords on a system is a
+significant weakening of system security. For that reason, all XML
+files, which are generated by Elbe during the build process
+(``/etc/elbe_base.xml`` and ``source.xml``) contain only hashed
+passwords.
+
+If a plain-text password for root or a user is specified in the input
+XML, it is converted into a hashed password during the XML
+preprocessing. The preprocessed XML only contains the hashed password,
+the plain-text password will be removed. The XML preprocessing only
+supports the hashing method ``sha512crypt`` at the moment, which is the
+default in most of the supported Debian releases.
+
+Hashed passwords can be used right from the start and directly placed
+into the input XML. A plain-text password can be hashed with the tool
+``mkpasswd`` or with various hashing libraries like crypt (C/C++) or
+passlib (Python). If the hashed passwords are generated manually, all
+hashing methods can be used, which are supported by the PAM
+configuration on the target system. If unsure, ``sha512crypt`` should be
+used.
+
+The following example uses the tool ``mkpasswd`` to hash the password.
+The tool will ask for a plain-text password (in this example "foo").
+
+::
+
+ mkpasswd --method=sha512crypt --rounds=656000
+ Password:
+ $6$rounds=656000$b.Wh.guGMquBcUeA$T7zTO/icEQarZ8mOvhjok4eR2X3ERazvMW2b07n52w.C.BERGYgOyKT0wZehikY97ISAP41ihPk9C0EVxp3n70
+
+The generated line contains the hashing parameters and the hashed
+password and has to be copied completely to the XML, either as
+``passwd_hashed`` node for the root password or as ``passwd_hashed``
+attribute for other users in ``adduser`` nodes.
+
+.. code:: xml
+
+ <target>
+ <!-- hashed password for root -->
+ <passwd_hashed>$6$rounds=656000$b.Wh.guGMquBcUeA$T7zTO/icEQarZ8mOvhjok4eR2X3ERazvMW2b07n52w.C.BERGYgOyKT0wZehikY97ISAP41ihPk9C0EVxp3n70</passwd_hashed>
+ </target>
+
+.. code:: xml
+
+ <finetuning>
+ <!-- hashed password for user elbe -->
+ <adduser passwd_hashed="$6$rounds=656000$b.Wh.guGMquBcUeA$T7zTO/icEQarZ8mOvhjok4eR2X3ERazvMW2b07n52w.C.BERGYgOyKT0wZehikY97ISAP41ihPk9C0EVxp3n70" shell="/bin/bash">elbe</adduser>
+ </finetuning>
+
+If the XML contains an action ``login``, the password for the root login
+must be given in plain-text. This plain-text password will not be
+removed by the preprocessing and will stay also in the generated XML
+files ``/etc/elbe_base.xml`` and ``source.xml``.
+
+.. _`_changing_the_subset_that_is_extracted_as_the_root_filesystem`:
+
+Changing the subset that is extracted as the root filesystem
+============================================================
+
+Elbe has several methods to select the subset that is packaged as the
+root-filesystem.
+
+- The finetuning section allows to remove, copy or move files before
+ the archive will be extracted and the target image is generated.
+
+- The *install-recommends* tag.
+
+- The initial copy has several modes, which allow to extract very small
+ subsets.
+
+- The embedded archive.
+
+.. _`_finetuning`:
+
+Finetuning
+----------
+
+The finetuning section allows to copy, move and delete files in the
+root-filesystem. Additionally it is possible to run commands. Here is an
+example finetuning section:
+
+.. code:: xml
+
+ <finetuning>
+ <rm>/usr/share/doc</rm>
+ <mkdir>/mydir</mkdir>
+ <mknod opts="c 1 5">/dev/zero</mknod>
+ <buildenv_mkdir>/mydir</buildenv_mkdir>
+ <cp path="/copy/me">/my/destination</cp>
+ <buildenv_cp path="/copy/me">/my/destination</buildenv_cp>
+ <b2t_cp path="/copy/me">/my/name/on/target</b2t_cp>
+ <t2b_cp path="/copy/me">/my/name/on/buildenv</b2t_cp>
+ <mv path="/var">/var_ro</mv>
+ <buildenv_mv path="/var">/var_ro</buildenv_mv>
+ <command>echo "T0:23:respawn:/sbin/getty -L ttyO0 115200 vt102" >> /etc/inittab</command>
+ <buildenv_command>some_command</buildenv_command>
+ <purge>apt</purge>
+ <addgroup>mygroup</addgroup>
+ <adduser groups='mygroup,audio' passwd='huhu' shell='/bin/zsh'>manut</adduser>
+ <adduser passwd='test' shell='/bin/bash'>test</adduser>
+ </finetuning>
+
+- Remove the directory */usr/share/doc* from the target.
+
+- Create the directory */mydir* on the target.
+
+- Create the character device */dev/zero* with major number 1 and minor
+ number 5 on the target.
+
+- Create the directory */mydir* in the build environment.
+
+- Copy */copy/me* on the target to */my/destination*.
+
+- Copy */copy/me* in the build environment to */my/destination*.
+
+- Copy */copy/me* from the build environment to */my/name/on/target* on
+ the target.
+
+- Copy */copy/me* from the target to */my/name/on/buildenv* in the
+ build environment.
+
+- Move */var* to */var/ro* in the target root filesystem.
+
+- Move */var* to */var/ro* in the build environment.
+
+- Execute the given command in the target root filesystem. In this
+ example a line is added to */etc/inittab* in order to permit logins
+ via the serial console.
+
+- Execute *some_command* in the build environment.
+
+- Remove the *apt* package from the target root filesystem using *dpkg
+ --purge*.
+
+- A group with the name *mygroup* is created.
+
+- Adds the user *manut* with */bin/zsh* as default shell. A group with
+ the same name as the user is always created and is the default group.
+ manut is additionally added to the groups *mygroup* and *audio*.
+ manuts login password is *huhu*. The *groups* attribute is optional,
+ *passwd* and *shell* are mandatory.
+
+The copy, mv, and rm commands operate on full directories.
+
+.. _`_useful_directories_to_trim_with_finetuning`:
+
+Useful directories to trim with finetuning
+------------------------------------------
+
+This section provides some useful directories that can be safely removed
+to get a smaller target image.
+
+.. code:: xml
+
+ <finetuning>
+ <rm>/usr/share/doc</rm>
+ <rm>var/cache/apt/archives/*</rm>
+ <rm>var/cache/apt/pkgcache.bin</rm>
+ <rm>var/cache/apt/srcpkgcache.bin</rm>
+ <rm>var/lib/apt/lists/*_Release</rm>
+ <rm>var/lib/apt/lists/*_Packages</rm>
+ <rm>var/lib/apt/lists/*_Sources</rm>
+
+ <rm>boot</rm>
+
+ <rm>lib/modules/2.6.32-5-versatile/</rm>
+ <rm>var/cache/man/*</rm>
+ <rm>var/cache/elbe</rm>
+ <rm>var/cache/debconf/*</rm>
+ </finetuning>
+
+- The doc files are not necessary on an embedded target.
+
+- The apt cache can be downloaded again if necessary.
+
+- The boot directory contains the kernel used for the VM. On embedded
+ targets the kernel is normally loaded by the bootloader.
+
+- The kernel modules for the standard Debian kernel.
+
+- The man page cache
+
+- The full copy mode will also copy elbe onto the root-filesystem.
+
+- debconf cache is also not necessary
+
+.. _`_archive`:
+
+Archive
+-------
+
+It’s also possible to include an archive into the XML file, that is
+unpacked into the target root-filesystem after the finetuning step. This
+archive must be a bzip2 compressed tar (.tar.bz2) and the following
+command can be used to embed the archive into the XML file:
+
+::
+
+ elbe chg_archive <xmlfile> archive.tar.bz2
+
+This feature is useful to place custom configuration-files into the
+final image.
+
+.. _`_slimming_the_root_filesystem_with_the_different_modes`:
+
+Slimming the root filesystem with the different modes
+=====================================================
+
+The copying process has several modes. The mode is configured in the
+*target* tag. It needs to be the tag before *finetuning*.
+
+The following commented example illustrates where the mode is
+configured.
+
+.. code:: xml
+
+ <target>
+ <hostname>example</hostname>
+ <domain>example.com</domain>
+ <passwd>foo</passwd>
+ <package>
+ <tar>nfsroot.tar.gz</tar>
+ </package>
+
+ <diet /> <!-- The mode is configured at this place.
+ Leaving it out enables the default mode. -->
+
+ <install-recommends />
+
+ <finetuning />
+ <pkg-list>
+ <pkg>bash</pkg>
+ </pkg-list>
+
+ </target>
+
+.. _`_install_recommends`:
+
+install-recommends
+------------------
+
+*install-recommends* enables installation of recommended packages. This
+can make the root-filesystem a lot bigger. With the default setting,
+installed programs will still work, but some functionality requiring
+external programs might be disabled.
+
+This is not strictly a mode as described in the following paragraphs. It
+can be combined with any of them, and the following modes are mutually
+exclusive.
+
+.. _`_default`:
+
+default
+-------
+
+The default mode generates a full copy of the build image. This mode is
+the easiest to use, but its not possible to generate images which have
+the Debian package management removed.
+
+.. _`_setsel`:
+
+setsel
+------
+
+The setsel mode can be used to generate images which only contain
+*dpkg*, and offers a more fine-grained control on which packages are
+installed.
+
+The recommended usage is as follows:
+
+- Generate an image in the default mode.
+
+- Run the image and use aptitude to purge unwanted packages.
+
+- Maybe even use dpkg to remove apt and aptitude.
+
+- Then generate the list of selected Packages using
+ ``dpkg --get-selections > selections.list``
+
+- Transfer this file to the host System.
+
+- Use ``elbe setsel <xmlfile> selections.list`` to import the pkg-list
+ into the XML file.
+
+- Rebuild using setsel mode.
+
+The setsel mode works by feeding the pkg list to
+``dpkg --set-selections`` in the target image copy. It has the advantage
+that there is no need to cope with some unregistered configuration
+files.
+
+.. _`_diet`:
+
+diet
+----
+
+Diet Mode only copies the files that are referenced in the Package
+management. It resolves the dependencies so that one does not need to
+reference library packages.
+
+Some packages rely on files generated in the post-inst scripts, which
+are not tracked by the package management. Work is in progress to
+execute the post-inst scripts in the target copy, but there are still
+some problems with corner-cases, when dependencies of these scripts get
+removed in the *finetuning*.
+
+These Errors are hard to find. And slow down development of an RFS. Diet
+Mode is intended to build small root-filesystems. E.g. to add some
+packages, like openssh-server, to a busybox based system.
+
+Do not use this for normal filesystems.
+
+This also holds for the *tighten* mode.
+
+.. _`_tighten`:
+
+tighten
+-------
+
+Tighten mode only extracts the files referenced by the packages in
+*pkg-list*. No dependencies are resolved. This mode is intended for
+compatibility with old XML files, do not use in new elbe projects.
+
+.. _`_cdrom_functionality`:
+
+CDROM Functionality
+===================
+
+Elbe creates a CDROM iso image with all the installed packages. It is
+created in the build directory, and its filename is ``install.iso`` This
+can also serve as an installation source.
+
+.. code:: xml
+
+ <mirror>
+ <cdrom>/home/user/elbe-example/install.iso</cdrom>
+ </mirror>
+
+.. _`_install_reports`:
+
+Install Reports
+===============
+
+The build process also creates a report file in asciidoc format:
+``elbe-report.txt`` can be converted to html using the following
+command:
+
+::
+
+ asciidoc elbe-report.txt
+
+This report lists all files in the root-file-system, including the
+origin Debian package.
+
+.. _`_validation`:
+
+Validation
+==========
+
+After a build the ``source.xml`` file includes information about all
+installed packages and versions. If this information is already present
+in a file used with ``elbe create`` the installed package versions and
+md5 hashes are validated and a report is printed and saved to
+``validation.txt``. This file is also in asciidoc format.
+
+.. _`_xml_reference`:
+
+XML Reference
+=============
+
+This section is a step by step explanation of the ARM example.
+
+The XML file starts with the following header, which should always be
+the same:
+
+.. code:: XML
+
+ <ns0:RootFileSystem xmlns:ns0="https://www.linutronix.de/projects/Elbe"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ created="2009-05-20T08:50:56" revision="6"
+ xsi:schemaLocation="https://www.linutronix.de/projects/Elbe dbsfed.xsd">
+
+After this header follows the project description.
+
+.. code:: xml
+
+ <project>
+ <name>ARMexample</name>
+ <version>08.15</version>
+ <mirror>
+ <primary_host>debian.tu-bs.de</primary_host>
+ <primary_path>/debian</primary_path>
+ <primary_proto>http</primary_proto>
+ <options>
+ <option>trusted=yes</option>
+ <option>check-valid-until=no</option>
+ </options>
+ <url-list>
+ <url>
+ <binary>http://debian.linutronix.de/elbe buster main</binary>
+ <source>http://debian.linutronix.de/elbe buster main</source>
+ <options>
+ <option>trusted=yes</option>
+ </options>
+ </url>
+ </url-list>
+
+ </mirror>
+ <suite>buster</suite>
+
+- The *mirror* tag contains *primary_host*, *primary_path*,
+ *primary_proto* and *host* *host* is optional, used in case of a
+ primary mirror different for the sdk architecture. It describes the
+ Debian mirror used.
+
+- The *options* tags can be used to set a list of *option* tag. Each
+ 'option tag can contain an option of the form NAME=VALUE.
+
+- The *url-list* can contain additional package sources.
+
+- The *suite* selects the distribution codename used from the primary
+ mirror.
+
+the *project* tag isn’t closed yet.
+
+The following section describes the virtual machine in which the
+debian-installer is executed and custom packages can be built.
+
+.. code:: xml
+
+ <buildimage>
+ <arch>armel</arch>
+ <size>20G</size>
+ <mem>256</mem>
+ <interpreter>qemu-system-arm</interpreter>
+ <console>ttyAMA0,115200n1</console>
+ <machine>versatilepb</machine>
+ <NIC>
+ <model>smc91c111</model>
+ <MAC>de:ad:be:ef:be:05</MAC>
+ </NIC>
+ <portforwarding>
+ <forward>
+ <proto>tcp</proto>
+ <buildenv>22</buildenv>
+ <host>5022</host>
+ </forward>
+ </portforwarding>
+ <pkg-list>
+ <pkg>buildd</pkg>
+ </pkg-list>
+ </buildimage>
+ </project>
+
+- *arch* is the Debian architecture of the target. (optional)
+
+- *size* is the size of the hard-disk image. (optional)
+
+- *mem* controls the amount of RAM that is allocated to the virtual
+ machine. (optional)
+
+- The *interpreter* is either *qemu-system-<arch>* or *qemu-kvm*. Usage
+ of kvm is usually only possible, when the target is *x86*. (optional)
+
+- The *console* line needs special attention because it is different on
+ different emulation targets. (optional)
+
+- The *machine* tag contains the *-machine* parameter, that is provided
+ to qemu. (optional)
+
+- *portforwarding* of network server ports from the virtual machine to
+ the host. This example forwards the ssh port to port 5022 on the
+ host. (optional)
+
+- This is the list of packages that are only installed to the
+ buildimage. (The packages listed in the target sections pkg-list are
+ installed to the target image and the buildimage.) It can be used for
+ example to install the debian build server into the buildenvironment.
+ (optional)
+
+The optional parameters are normally set to defaults by the buildtype
+tag. The tags can be used for advanced use of elbe; to override the
+defaults.
+
+If the optional parameters are not set, the buildtype can even be
+overridden by the flag --buildtype at *elbe create* to build the same
+configuration for a different architecture
+
+.. code:: xml
+
+ <target>
+ <hostname>myARM</hostname>
+ <domain>tec.linutronix.de</domain>
+ <passwd>foo</passwd>
+ <console>ttyS0,115200</console>
+ <package>
+ <tar>
+ <name>nfsroot.tar.gz</name>
+ </tar>
+ </package>
+ <finetuning>
+ </finetuning>
+ <pkg-list>
+ <pkg>build-essential</pkg>
+ <pkg>bash</pkg>
+ <pkg>less</pkg>
+ <pkg>git</pkg>
+ <pkg>debhelper</pkg>
+ <pkg>nfs-common</pkg>
+ <pkg>openssh-server</pkg>
+ </pkg-list>
+ </target>
+
+- The hostname
+
+- and domainname
+
+- This is the plain-text root password of the machine. It will be
+ converted into a hashed password by the XML preprocessing.
+
+- This describes, that the resulting rootfilesystem, shall be generated
+ as *nfsroot.tar.gz*
+
+- finetuning section can be empty. If you need finetuning it can be
+ defined here. The format of this tag is explained above.
+
+- The package list resides here.
+
+.. _`_building_ubi_images`:
+
+Building ubi images
+-------------------
+
+Elbe also has the ability to generate ubi images, including different
+partitions and mountpoints. Lets look at an example *target* section.
+
+.. code:: xml
+
+ <target>
+ <hostname>myARM</hostname>
+ <domain>tec.linutronix.de</domain>
+ <passwd>foo</passwd>
+ <console>ttyS0,115200</console>
+
+ <images>
+ <mtd>
+ <name>linux.img</name>
+ <nr>0</nr>
+ <size>60MB</size>
+ <ubivg>
+ <label>nand</label>
+ <miniosize>2048</miniosize>
+ <maxlogicaleraseblockcount>1533</maxlogicaleraseblockcount>
+ <logicaleraseblocksize>126976</logicaleraseblocksize>
+ <physicaleraseblocksize>128KiB</physicaleraseblocksize>
+ <ubi>
+ <type>static</type>
+ <label>kernel</label>
+ <id>0</id>
+ <size>4MiB</size>
+ <binary>/boot/vmlinuz-2.6.33.9-rt31</binary>
+ </ubi>
+ <ubi>
+ <type>dynamic</type>
+ <label>rfs</label>
+ <id>1</id>
+ <size>26MiB</size>
+ </ubi>
+ <ubi>
+ <type>dynamic</type>
+ <label>data</label>
+ <id>2</id>
+ <size>30MiB</size>
+ </ubi>
+ </ubivg>
+ </mtd>
+ </images>
+
+ <fstab>
+ <bylabel>
+ <label>data</label>
+ <mountpoint>/opt</mountpoint>
+ <fs>
+ <type>ubifs</type>
+ <mkfs>-x lzo</mkfs>
+ </fs>
+ <options>rw</options>
+ </bylabel>
+ <bylabel>
+ <label>rfs</label>
+ <mountpoint>/</mountpoint>
+ <fs>
+ <type>ubifs</type>
+ <mkfs>-x lzo</mkfs>
+ </fs>
+ <options>ro</options>
+ </bylabel>
+ <bydev>
+ <source>proc</source>
+ <mountpoint>/proc</mountpoint>
+ <fs>
+ <type>proc</type>
+ </fs>
+ </bydev>
+ <bydev>
+ <source>sysfs</source>
+ <mountpoint>/sys</mountpoint>
+ <fs>
+ <type>sysfs</type>
+ </fs>
+ </bydev>
+ <bydev>
+ <source>tmpfs</source>
+ <mountpoint>/tmp</mountpoint>
+ <fs>
+ <type>tmpfs</type>
+ </fs>
+ <options>size=2M</options>
+ </bydev>
+ <bydev>
+ <source>tmpfs</source>
+ <mountpoint>/var/log</mountpoint>
+ <fs>
+ <type>tmpfs</type>
+ </fs>
+ <options>size=4M</options>
+ </bydev>
+ <bydev>
+ <source>tmpfs</source>
+ <mountpoint>/var/run</mountpoint>
+ <fs>
+ <type>tmpfs</type>
+ </fs>
+ <options>size=2M</options>
+ </bydev>
+ </fstab>
+
+ <finetuning>
+ </finetuning>
+ <pkg-list>
+ <pkg>dash</pkg>
+ </pkg-list>
+ </target>
+
+- This specifies an mtd image with 60MB size whose filename is
+ linux.img
+
+- Parameters for the ubi tools, describing the NAND geometry.
+
+- Specification of ubi volumes.
+
+- specifies the fstab, so that everything can be copied to the right
+ image.
+
+- Normal partition entries are by label.
+
+- The target /etc/fstab file is created with the entries defined in
+ this section. Entries for */proc*, */sys* etc. can be generated with
+ *bydev* nodes.
+
+.. _`_building_harddisk_sdcard_images`:
+
+Building harddisk / sdcard images
+---------------------------------
+
+Elbe also has the ability to generate ubi images, including different
+partitions and mountpoints. Lets look at an example *target* section.
+
+.. code:: xml
+
+ <images>
+ <hd>
+ <name>sda.img</name>
+ <size>1900</size>
+ <partitions>
+ <primary>
+ <part>1</part>
+ <size>remain</size>
+ <label>rfs</label>
+ <parttype>linux</parttype>
+ </primary>
+ </partitions>
+ </hd>
+ <hd>
+ <name>sdb.img</name>
+ <size>400</size>
+ <partitions>
+ <primary>
+ <part>1</part>
+ <size>remain</size>
+ <label>config</label>
+ <parttype>linux</parttype>
+ </primary>
+ </partitions>
+ </hd>
+ </images>
+ <fstab>
+ <bylabel>
+ <label>rfs</label>
+ <mountpoint>/</mountpoint>
+ <fs>
+ <type>ext4</type>
+ </fs>
+ </bylabel>
+ <bylabel>
+ <label>config</label>
+ <mountpoint>/mnt/config</mountpoint>
+ <fs>
+ <type>ext4</type>
+ </fs>
+ <options>ro</options>
+ </bylabel>
+ <bydev>
+ <source>none</source>
+ <mountpoint>/sys/kernel/debug</mountpoint>
+ <fs>
+ <type>debug</type>
+ </fs>
+ </bydev>
+ </fstab>
+
+- this specifies an hd image
+
+- size of a hd image
+
+- Specification of ubi volumes.
+
+- labels are used to assign mountpoints to partitions
+
+- The target /etc/fstab file is created with the entries defined in
+ this section. Entries for */proc*, */sys* etc. can be generated with
+ *bydev* nodes.
+
+A complete reference that is automatically generated from the schema
+file is also available.
+
+.. _`_elbe_init_detailed_explanation`:
+
+Elbe init (detailed Explanation)
+================================
+
+``elbe init`` is now considered a low-level command for advanced Users.
+Under normal circumstances ``elbe initvm`` should be used. This
+paragraph is kept for reference.
+
+The *elbe init* command generates a project directory, which contains a
+hard disk image for a virtual build machine and a *Makefile* to install
+the build VM and to work with it.
+
+During this process, *elbe init* will download a linux kernel and
+initrd.gz from the debian mirror. In case of a local mirror, be sure,
+that ``dists/<codename>/main/installer-amd64/`` is also mirrored.
+
+After *elbe init* has generated the project directory, change to the
+project directory and run *make*. This will start the installation of
+the build VM.
diff --git a/docs/article-quickstart.rst b/docs/article-quickstart.rst
new file mode 100644
index 000000000000..b895b5b2bcdc
--- /dev/null
+++ b/docs/article-quickstart.rst
@@ -0,0 +1,562 @@
+************************
+ELBE Quickstart
+************************
+
+You have probably received a root filesystem, which has been built with
+ELBE. Additionally, you should have an XML file describing the root
+filesystem.
+
+This quickstart guide describes the steps necessary to rebuild the
+root-filesystem from the XML file and to simple modifications.
+
+.. _`_steps_necessary`:
+
+Steps necessary
+===============
+
+1. install Debian 10 (buster) or later on your Host. The latest version
+ of elbe should be compatible with this system.
+
+2. install ELBE on Host Linux
+
+3. generate the ``initvm`` running the build environment
+
+4. build the root filesystem inside the initvm
+
+Steps 1,2 and 3 need only be performed once.
+
+.. note::
+
+ When Debian is running inside a VM (vmware etc), you need to make
+ sure, that nested KVM is working.
+
+.. _`_customization_of_the_build`:
+
+Customization of the build
+==========================
+
+The ELBE XML can contain an archive, which can contain configuration
+files, and additional software. This archive is extracted onto the
+target-image during the buildprocess. It allows you to override any
+file, which needs to be different from the default Debian Install.
+
+This guide also explains how the archive can be extracted from the XML
+file, and vice versa.
+
+ELBE allows manipulating the generated root filesystem through a set of
+``<finetuning>`` rules. We also describe, how these can be used to add a
+user, change directory permissions, and remove files from the root
+filesystem.
+
+.. _`_installing_elbe`:
+
+Installing ELBE
+===============
+
+There are several possibilities to install ELBE. The simplest method is
+by installing prebuilt binary packages via Linutronix package repository
+on a Debian 10 (Buster) system.
+
+But ELBE can also be installed from git.
+
+.. _`_binary_debian_packages`:
+
+Binary Debian packages
+----------------------
+
+The latest packages for elbe reside in the following repository
+
+::
+
+ http://debian.linutronix.de/elbe
+
+Install the repository key to a known place (as root):
+
+::
+
+ # apt install elbe-archive-keyring || wget -O /usr/share/keyrings/elbe-archive-keyring.gpg http://debian.linutronix.de/elbe/elbe-repo.pub.gpg
+
+Add the following content to the file ``/etc/apt/sources.list``
+
+::
+
+ # echo "deb [signed-by=/usr/share/keyrings/elbe-archive-keyring.gpg] http://debian.linutronix.de/elbe buster main" >> /etc/apt/sources.list
+
+Then run (as root):
+
+::
+
+ # apt update
+ # apt install elbe
+
+.. _`_create_initvm_and_submit_xml_files`:
+
+Create initvm and submit XML files
+==================================
+
+The first thing you need to do is set up a virtual-machine for
+generating root-filesystems.
+
+This virtual-machine is referred to as ``initvm``. You will want your
+initvm to be the same architecture as your workstation. This allows
+using hardware accelerated virtualization implemented by kvm.
+
+To work with virtual machines as a regular user, the user needs to be
+added to kvm and libvirt groups:
+
+::
+
+ # adduser <youruser> kvm
+ # adduser <youruser> libvirt
+
+Now create an ``initvm`` subdirectory and builds the initvm inside this
+directory.
+
+::
+
+ $ elbe initvm create
+ Import debian-archive-buster-automatic.gpg:
+ gpg: key DC30D7C23CBBABEE: 4 Beglaubigungen wegen fehlender Schlüssel nicht geprüft
+ gpg: Schlüssel DC30D7C23CBBABEE: Öffentlicher Schlüssel "Debian Archive Automatic Signing Key (10/buster) <ftpmaster at debian.org>" importiert
+ gpg: Anzahl insgesamt bearbeiteter Schlüssel: 1
+ gpg: importiert: 1
+ ...
+
+ Installing the base system ... 17%... 20%... 30%... 40%... 50%... 60%... 70%... 83%... 91%
+ ... 100%
+ Configuring apt ... 14%... 21%... 35%... 40%... 50%... 64%... 71%... 85%... 92%... 100%
+ Select and install software
+ ... 10%... 20%... 30%... 40%... 50%... 61%... 71%... 81%... 78%... 80%... 90%
+ ... 100%
+ Installing GRUB boot loader ... 16%... 33%... 50%... 66%... 83%... 100%
+ The system is going down NOW!.. 12%... 20%... 33%... 41%... 50%... 62%... 70%... 83%... 91%
+ Sent SIGKILL to all processes
+ Requesting system reboot
+ [ 656.391904] reboot: Restarting system
+ mkdir -p .stamps
+ touch .stamps/stamp-install-initial-image
+ *****
+
+.. _`_submitting_an_xml_file`:
+
+Submitting an XML file
+======================
+
+Submitting an XML file triggers an image build inside the initvm. Once
+the initvm has been created and is running, you can submit XML files
+using
+
+::
+
+ $ elbe initvm submit examples/x86_64-pc-rescue-busybox-dyn-cpio.xml
+ Build started, waiting till it finishes
+ [INFO] Build started
+ [INFO] ELBE Report for Project x86_64-rescue-image
+ Report timestamp: 20191001-135512
+ [CMD] reprepro --basedir "/var/cache/elbe/63e09968-c9e7-45d8-8dd2-82c1a8f54f8d/repo" export stretch
+ [CMD] mkdir -p "/var/cache/elbe/63e09968-c9e7-45d8-8dd2-82c1a8f54f8d/chroot"
+ [INFO] Debootstrap log
+ [CMD] dpkg --print-architecture
+ [CMD] debootstrap --include="gnupg" --arch=amd64 "stretch" "/var/cache/elbe/63e09968-c9e7-45d8-8dd2-82c1a8f54f8d/chroot" "http://ftp.de.debian.org//debian"
+ I: Retrieving InRelease
+ I: Retrieving Release
+ I: Retrieving Release.gpg
+ I: Checking Release signature
+ I: Valid Release signature (key id 067E3C456BAE240ACEE88F6FEF0F382A1A7B6500)
+ I: Retrieving Packages
+ I: Validating Packages
+ I: Resolving dependencies of required packages...
+ I: Resolving dependencies of base packages...
+ I: Checking component main on http://ftp.de.debian.org//debian...
+ I: Retrieving libacl1 2.2.52-3+b1
+ I: Validating libacl1 2.2.52-3+b1
+
+ ...
+ 79.05% done, estimate finish Mon Aug 1 09:53:26 2022
+ 81.77% done, estimate finish Mon Aug 1 09:53:26 2022
+ 84.49% done, estimate finish Mon Aug 1 09:53:26 2022
+ 87.22% done, estimate finish Mon Aug 1 09:53:26 2022
+ 89.95% done, estimate finish Mon Aug 1 09:53:26 2022
+ 92.67% done, estimate finish Mon Aug 1 09:53:27 2022
+ 95.39% done, estimate finish Mon Aug 1 09:53:27 2022
+ 98.12% done, estimate finish Mon Aug 1 09:53:27 2022
+ Total translation table size: 0
+ Total rockridge attributes bytes: 73534
+ Total directory bytes: 355120
+ Path table size(bytes): 2354
+ Max brk space used bd000
+ 183454 extents written (358 MB)
+ [INFO] Build finished successfully
+
+ Build finished !
+
+ ELBE Package validation
+ =======================
+
+ Package List validation
+ -----------------------
+
+ No Errors found
+ Binary CD
+ Source CD
+
+ Getting generated Files
+
+ Saving generated Files to elbe-build-20220801-095330
+ source.xml (Current source.xml of the project)
+ rescue.cpio (Image)
+ licence-chroot.txt (License file)
+ licence-chroot.xml (xml License file)
+ licence-target.txt (License file)
+ licence-target.xml (xml License file)
+ validation.txt (Package list validation result)
+ elbe-report.txt (Report)
+ log.txt (Log file)
+ bin-cdrom.iso (Repository IsoImage)
+ src-cdrom-target.iso (Repository IsoImage)
+ src-cdrom-main.iso (Repository IsoImage)
+ src-cdrom-added.iso (Repository IsoImage)
+
+The result of the build is stored in elbe-build-<TIMESTAMP> below your
+current working directory.
+
+.. _`_ports_opened_by_initvm`:
+
+Ports opened by initvm
+======================
+
+The initvm will open port 7587 on localhost. This is used by the elbe
+tools on your host to communicate with the initvm.
+
+.. _`_advanced_usage`:
+
+Advanced usage
+==============
+
+.. _`_elbe_archive`:
+
+ELBE Archive
+------------
+
+The ELBE XML file can contain an archivedir which is copied into the
+root-filesystem during the image generation phase.
+
+It is done with the following XML node:
+
+.. code:: xml
+
+ <archivedir>foo</archivedir>
+
+.. _`_archivedir`:
+
+archivedir
+----------
+
+The new XML element ‘archivedir’ points to a local directory and adds
+the content into a newly created archive. ‘archivedir’ can be specified
+more than once. The content of the directories is copied in order of
+appearance. Existing files are overwritten by the later ones.
+
+Example snippet to use ‘archivedir’:
+
+.. code:: xml
+
+ <archivedir>foo</archivedir>
+ <archivedir variant="production">bar</archivedir>
+
+.. _`_adding_packages_to_the_list_of_packages_to_install`:
+
+Adding packages to the "list of packages to install"
+----------------------------------------------------
+
+The XML file contains a *list of packages to install* ``<pkg-list>`` in
+the ``<target>`` XML node. Inserting a line containing
+
+.. code:: xml
+
+ <pkg>util-linux</pkg>
+
+will add the ``util-linux`` package to the target-rfs.
+
+.. _`_using_the_finetuning_rules`:
+
+Using the finetuning rules
+--------------------------
+
+An ELBE XML file can contain a set of finetuning rules. Finetuning is
+used to customize the target-rfs, e.g. remove man-pages. Here is an
+example finetuning from
+``/usr/share/doc/elbe-doc/examples/elbe-desktop.xml``:
+
+.. code:: xml
+
+ <finetuning>
+ <rm>var/cache/apt/archives/*.deb</rm>
+ <adduser passwd="elbe" shell="/bin/bash">elbe</adduser>
+ </finetuning>
+
+.. _`_rm`:
+
+rm
+~~
+
+The ``<rm>`` node removes files from the target-rfs.
+
+.. _`_adduser`:
+
+adduser
+~~~~~~~
+
+The adduser node allows to create a user. The following example creates
+the user ``elbe`` with the password ``foo``.
+
+It is also possible to specify groups the new user should be part of:
+
+.. code:: xml
+
+ <adduser passwd="foo" shell="/bin/bash" groups="audio,video,dialout">elbe</adduser>
+
+Instead of specifying a plain-text password, it is also possible to use
+hashed passwords in the XML. Hashed passwords can be either converted by
+the Elbe preprocessing (``elbe preprocess <xml>``), with the tool
+``mkpasswd`` or with various hashing libraries like crypt (C/C++) or
+passlib (Python).
+
+In this example, the command ``mkpasswd`` is used to hash the plain-text
+password ``elbe``. If the salt is not specified, ``mkpasswd`` will use a
+random salt.
+
+::
+
+ mkpasswd --method=sha512crypt --rounds=656000 --salt=7vWuOPVX0YKaISh5 "elbe"
+
+The generated line contains the hashing parameters and the hashed
+password and has to be copied completely to the ``passwd_hashed``
+attribute in the XML.
+
+.. code:: xml
+
+ <adduser passwd_hashed="$6$rounds=656000$7vWuOPVX0YKaISh5$cJhevq/z7kJ215n18dnksv/zOeUf6uPoLgICwLeTSu/2xoLHkyYQABaM7a99sQmpilCV.SlK9jfHZz3m7/s2a." shell="/bin/bash">elbe</adduser>
+
+.. _`_changing_ownership_of_directories_or_files`:
+
+Changing ownership of directories or files
+------------------------------------------
+
+There is currently no special finetuning node for ``chmod`` and
+``chown``. These commands needs to be specified via the command tag,
+which allows running any command that is available in the target-rfs.
+
+.. code:: xml
+
+ <command>chown elbe:elbe /mnt</command>
+ <command>chmod 777 /mnt</command>
+
+.. _`_further_example`:
+
+Further Example
+~~~~~~~~~~~~~~~
+
+A more complete example can be found in the ELBE overview document that
+is installed at ``/usr/share/doc/elbe-doc/elbeoverview-en.html``
+
+.. _`_using_the_elbe_pbuilder_feature`:
+
+Using the Elbe Pbuilder Feature
+===============================
+
+Since Version 1.9.2, elbe is able to create a pbuilder Environment. You
+can create a pbuilder for a specific xml File inside the initvm.
+
+The repositories and architecture specified in the xml File will be used
+to satisfy build dependencies. It is possible to crosscompile packages
+for a foreign architecture. To do so use the *elbe pbuilder create*
+command with the --cross option. This will setup the right environment
+for crosscompiling. To use this environment you have to use the --cross
+option with the build command. (If the environment was created with the
+--cross option, the build command must be used with --cross too.
+Otherwise it will throw an error.) By creating an environment the
+compiler cache ``ccache`` gets installed by default to speed up
+recompilations. It is possible to change the size or to deactivate it if
+it is not needed. Pbuilder will only build debianised Software.
+
+A pbuilder instance is always associated with a project inside the
+initvm. The ``pbuilder create`` command will write the project uuid to a
+file, if instructed to do so.
+
+``pbuilder build`` works like ``pdebuild``, in that it uploads the
+current working directory into the initvm pbuilder project, and then
+builds it using the pbuilder instance created earlier.
+
+Here is an example:
+
+::
+
+ $ elbe pbuilder create --xmlfile examples/x86_64-pc-rescue-busybox-dyn-cpio.xml --writeproject ../pbuilder.prj
+ $ git clone https://github.com/Linutronix/libgpio.git
+ $ cd libgpio/
+ $ elbe pbuilder build --project `cat ~/repos/elbe/pbuilder.prj` --out ../out/
+
+With these steps, elbe builds the libgpio project inside the initvm and
+stores the built packages in an internal repository. Every package,
+built in this manner, will also be stored in that repository. This
+repository can be used for later RFS builds.
+
+List contents of the repository with the following command:
+
+::
+
+ $ elbe prjrepo list_packages `cat ~/repos/elbe/pbuilder.prj`
+ libgpio-dev_3.0.0_amd64.deb
+ libgpio1_3.0.0_amd64.deb
+ libgpio1-dbgsym_3.0.0_amd64.deb
+
+To use this repository for further RFS builds download the repo with:
+
+::
+
+ $ elbe prjrepo download `cat ~/repos/elbe/pbuilder.prj`
+
+The repository is download as elbe-projectrepo-20191002-114244.tar.gz.
+This should be unpacked in the DocumentRoot of your webserver and
+customized with your key as explained in the next chapter.
+
+Here is an example for crosscompiling a linux kernel with debian
+profiles:
+
+::
+
+ $ elbe pbuilder --cross create --xmlfile examples/armhf-ti-beaglebone-black.xml --writeproject pbuilder.prj
+ $ apt source linux
+ $ cd linux*/
+ $ ../elbe pbuilder --cross --origfile ../linux*.orig.tar.xz --profile nodoc,nopython build --project `cat ../pbuilder.prj`
+
+.. _`_custom_repository`:
+
+Custom Repository
+=================
+
+You might have your own packages which should be installed into your
+image. This can be done with a custom repository. You can use
+`reprepro <https://mirrorer.alioth.debian.org/>`__ to create your own
+repository or the above mentioned pbuilder feature.
+
+.. _`_repository_key`:
+
+Repository Key
+--------------
+
+Because the repository needs to be signed using ``gpg``, a key needs to
+be generated.
+
+::
+
+ -> gpg --default-new-key-algo rsa4096 --gen-key
+ gpg (GnuPG) 2.1.18; Copyright (C) 2017 Free Software Foundation, Inc.
+ This is free software: you are free to change and redistribute it.
+ There is NO WARRANTY, to the extent permitted by law.
+
+ Note: Use "gpg --full-generate-key" for a full featured key generation dialog.
+
+ GnuPG needs to construct a user ID to identify your key.
+
+ Real name: Torben Hohn
+ Email address: torben.hohn at linutronix.de
+ You selected this USER-ID:
+ "Torben Hohn <torben.hohn at linutronix.de>"
+
+ Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
+ We need to generate a lot of random bytes. It is a good idea to perform
+ some other action (type on the keyboard, move the mouse, utilize the
+ disks) during the prime generation; this gives the random number
+ generator a better chance to gain enough entropy.
+ gpg: key 68E68615BB6CB47C marked as ultimately trusted
+ gpg: directory '/home/torbenh/.gnupg/openpgp-revocs.d' created
+ gpg: revocation certificate stored as '/home/torbenh/.gnupg/openpgp-revocs.d/CF837F1AAAC35E084062AE4468E68615BB6CB47C.rev'
+ public and secret key created and signed.
+
+ Note that this key cannot be used for encryption. You may want to use
+ the command "--edit-key" to generate a subkey for this purpose.
+ pub rsa4096 2018-10-08 [SC] [expires: 2020-10-07]
+ CF837F1AAAC35E084062AE4468E68615BB6CB47C
+ CF837F1AAAC35E084062AE4468E68615BB6CB47C
+ uid Torben Hohn <torben.hohn at linutronix.de>
+
+Please note the keyname (here
+``CF837F1AAAC35E084062AE4468E68615BB6CB47C``). This keyname can then be
+used to export the public key into a repo.pub file.
+
+::
+
+ gpg --export --armor CF837F1AAAC35E084062AE4468E68615BB6CB47C > repo.pub
+
+.. _`_reprepro_configuration`:
+
+reprepro configuration
+----------------------
+
+To create your own repository with reprepro or the elbe pbuilder feature
+you need only the ``distributions`` configuration file. For an ``amd64``
+and ``source`` repository for Debian ``stretch`` it might look as
+follows:
+
+::
+
+ Origin: mylocal
+ Label: mylocal
+ Suite: stable
+ Codename: stretch
+ Architectures: amd64 source
+ Components: main
+ Description: my local repo
+ SignWith: CF837F1AAAC35E084062AE4468E68615BB6CB47C
+
+.. note::
+
+ the ``SignWith:`` field needs to be the key of the previously
+ generated key.
+
+Now place the ``distributions`` file in a ``conf`` named directory. also
+put ``repo.pub`` into your ``repo`` directory.
+
+::
+
+ repo/
+ ├── conf
+ │ └── distributions
+ └── repo.pub
+
+.. _`_insert_pkgs_into_repo`:
+
+insert pkgs into repo
+---------------------
+
+To include packages in your repository you might use the following
+command from inside the ``repo`` directory:
+
+::
+
+ $ reprepro include stretch ../path/to/your/*.changes
+
+To use this repository from ELBE you need a webserver. Simply place the
+repository inside the document root of your webserver.
+
+If the webserver is running on the same machine as the initvm you can
+use the following to access the repository:
+
+.. code:: xml
+
+ <url-list>
+ <url>
+ <binary>http://LOCALMACHINE/repo/ buster main</binary>
+ <source>http://LOCALMACHINE/repo/ buster main</source>
+ <key>http://LOCALMACHINE/repo/repo.pub</key>
+ </url>
+ </url-list>
+
+ELBE replaces the string ``LOCALMACHINE`` with the ip address of your
+machine. If you use an external machine as webserver you need to replace
+``LOCALMACHINE`` with the name or the ip of it.
+
+Now you can install packages from your custom repository the same way
+you can install from any other repository.
diff --git a/docs/elbe-add.rst b/docs/elbe-add.rst
new file mode 100644
index 000000000000..ac8362db75a0
--- /dev/null
+++ b/docs/elbe-add.rst
@@ -0,0 +1,55 @@
+************************
+elbe-add
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-add - Insert new package(s) into the target package list.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe add [options] <xmlfile> <package name> [<package name>]*
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command adds an entry to the target pkg-list of the given XML file.
+If more than one package name was given, all the packages are added to
+the list. If a package already exists in the list, the package isn’t
+added twice.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<xmlfile>
+ The xmlfile to be modified.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Add *vim-nox* and *mc* into *mybsp.xml*
+
+ ::
+
+ $ elbe add mybsp.xml vim-nox mc
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-buildchroot.rst b/docs/elbe-buildchroot.rst
new file mode 100644
index 000000000000..a52508c72d02
--- /dev/null
+++ b/docs/elbe-buildchroot.rst
@@ -0,0 +1,111 @@
+************************
+elbe-buildchroot
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-buildchroot - Build a root filesystem.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe buildchroot [ OPTIONS ] <xmlfile>
+
+<xmlfile>
+ The XML describing the Elbe project.
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe buildchroot* builds a root filesystem using the settings specified
+in the given XML file. This command has to be run as root **inside the
+Elbe build VM**.
+
+By default, also an ISO image for a binary CD-ROM will be generated,
+which will contain all packages installed into the root filesystem. It
+can also be used as an installation source. For details, please refer to
+``elbe-mkcdrom(1)``. Optionally, a source CD-ROM image can be generated,
+too.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+-t, --target <targetdir>
+ Target directory for the build. The directory must not exist before
+ calling this command. Defaults to *./build*
+
+-o, --output <logfile>
+ Name of the file to write the build report to. If not specified, the
+ report is written to stdout.
+
+-n, --name <projectname>
+ Override the name of the project (used in the build report),
+
+--build-bin
+ Build Debian binary cdrom. All binaries used are built onto the
+ cdrom. And this iso image can later be used to reproduce the images.
+
+--build-sources
+ Build a Debian source CD-ROM image, containing the source packages
+ used by the project.
+
+--debug
+ Enables a few features that allow for better debugging of the build
+ process.
+
+--buildtype <buildtype>
+ Override the build type specified in the XML file. (Not recommended)
+
+--cdrom-size <N> ISO Cdrom size, after which a new volume is generated.
+
+--skip-validation
+ Skip the validation of the XML file. (Not recommended)
+
+--skip-debootstrap
+ Skip debootstrap.
+
+--skip-pkglist
+ Ignore changes to the pkglist, and don’t rebuild the buildimage. (Not
+ recommended)
+
+--skip-cdrom
+ Obsolete option, from the time, before --build-bin and
+ --build-sources existed.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build a root filesystem from *myarm.xml* in */root/myarm*. Log to
+ *myarm.txt*. Do not build any ISO-Images.
+
+ ::
+
+ # elbe buildchroot --output myarm.txt --target /root/myarm myarm.xml
+
+- Build a root filesystem from *myarm.xml* in */root/myarm*. Log to
+ *myarm.txt*. Also build source and binary ISO-Images.
+
+ ::
+
+ # elbe buildchroot --output myarm.txt --target /root/myarm \
+ --build-sources --build-bin myarm.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-buildsdk.rst b/docs/elbe-buildsdk.rst
new file mode 100644
index 000000000000..a45991e99d35
--- /dev/null
+++ b/docs/elbe-buildsdk.rst
@@ -0,0 +1,49 @@
+************************
+elbe-buildsdk
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-buildsdk - Build a yocto style sdk.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe buildsdk <directory>
+
+<directory>
+ directory containing the elbe project.
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+creates a yocto style SDK
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build a root filesystem from *myarm.xml* in */root/myarm*. Log to
+ *myarm.txt*. Then create a SDK for this RFS.
+
+ ::
+
+ # elbe buildchroot --output myarm.txt --target /root/myarm myarm.xml
+ # elbe buildsdk /root/myarm
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-buildsysroot.rst b/docs/elbe-buildsysroot.rst
new file mode 100644
index 000000000000..d813db364767
--- /dev/null
+++ b/docs/elbe-buildsysroot.rst
@@ -0,0 +1,76 @@
+************************
+elbe-buildsysroot
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-buildsysroot - Build a sysroot archive.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe buildsysroot \
+ [ --buildtype <type> ] \
+ [ --skip-validation ] \
+ <builddir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe buildsysroot* builds a sysroot tar archive from the given build
+directory (built with ``elbe-buildchroot(1)`` before), containing the
+libraries and header files of the root filesystem. This can be used for
+cross-compiling. For example, if a Linaro 2014.02 toolchain is used, the
+archive can be unpacked into
+*gcc-linaro-arm-linux-gnueabihf-\*/arm-linux-gnueabihf/libc* to set up a
+cross-toolchain for the given root filesystem.
+
+The archive will be created as *sysroot.tar.xz* in the build directory.
+
+This command has to be run as root **inside the Elbe build VM**.
+
+Please note that the package *symlinks* has to be included in the
+package list of the project for this to work, as well as the relevant
+development packages. The XML file of the project also needs a *triplet*
+definition.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--buildtype <buildtype>
+ Override the build type specified in the XML file.
+
+--skip-validation
+ Skip the validation of the XML file. (Not recommended)
+
+<builddir>
+ The build directory to generate the sysroot archive from.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build a sysroot archive from the project located at */root/myarm*
+
+ ::
+
+ # elbe buildsysroot /root/myarm
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-check_updates.rst b/docs/elbe-check_updates.rst
new file mode 100644
index 000000000000..37d8b9c8b230
--- /dev/null
+++ b/docs/elbe-check_updates.rst
@@ -0,0 +1,86 @@
+************************
+elbe-check_updates
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-check_updates - Check whether package updates are available for an
+Elbe project.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe check_updates \
+ [ --script <script> ] \
+ [ --skip-validation ] \
+ <source-xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe check_updates* checks if package updates are available for a given
+Elbe project. The command will also detect package names that are
+specified in the package list of the project but missing in the package
+repositories.
+
+Optionally the command can run a script if some packages are missing or
+have updates available. If at least one package is missing, the script
+will be invoked with the following command line:
+
+ ::
+
+ <script> ERRORS <source-xmlfile>
+
+Otherwise, if at least one package can be updated, the script will be
+started like this:
+
+ ::
+
+ <script> UPDATE <source-xmlfile>
+
+If none of the above is true, the script will not be started.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--script <script>
+ File name of a script to run, if an update is required or packages
+ are missing.
+
+--skip-validation
+ Skip the validation of the XML file. (Not recommended)
+
+<source-xmlfile>
+ Path to the *source.xml* file of the project.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Check the project in */scratch/example* for available updates and
+ missing packages. Run the script */scratch/fixpackages.sh*, if
+ necessary.
+
+ ::
+
+ $ elbe check_updates --script /scratch/fixpackages.sh \
+ /scratch/example/source.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-chg_archive.rst b/docs/elbe-chg_archive.rst
new file mode 100644
index 000000000000..8d872f32cbc9
--- /dev/null
+++ b/docs/elbe-chg_archive.rst
@@ -0,0 +1,80 @@
+************************
+elbe-chg_archive
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-chg_archive - Insert a new config archive (.tbz) into a XML file.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe chg_archive [options] <xmlfile> [<archive.tar.bz2> | <directory>]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command exchanges the archive file inside the xml file with the one
+specified.
+
+The archive tbz is used to insert configuration files into the
+root-filesystem.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--keep-attributes
+ This is only parsed, if the specified input is a <directory>. If
+ specified the local owners and groups will be stored inside the
+ archive. If not all files and directories will belong to user root
+ and group root.
+
+<xmlfile>
+ The xmlfile to be modified.
+
+<archive.tar.bz2>
+ The archive which must be a tar.bz2. The archive is uuencoded and
+ swapped with the archive in the xml file. If no archive exists, the
+ archive xmlnode will be created.
+
+<directory>
+ A local directory that will be used as archive. The content of the
+ directory will be archived in a tar.bz2 format and then stored
+ uuencoded in the <archive> tag of the specified <xmlfile>.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Insert *myarch.tar.bz2* into *mybsp.xml*
+
+ ::
+
+ $ elbe chg_archive mybsp.xml myarch.tar.bz2
+
+- Insert *my-rfs-overlay* into *mybsp.xml*
+
+ ::
+
+ $ mkdir -p my-rfs-overlay/etc
+ $ echo 'my-very-special-config' > my-rfs-overlay/etc/my.cfg
+ $ elbe chg_archive mybsp.xml my-rfs-overlay
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-chroot.rst b/docs/elbe-chroot.rst
new file mode 100644
index 000000000000..4dc691e2c8f9
--- /dev/null
+++ b/docs/elbe-chroot.rst
@@ -0,0 +1,91 @@
+************************
+elbe-chroot
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-chroot - Enter an Elbe root filesystem using chroot.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe chroot [--skip-validation] [--buildtype=TYPE] [--target] <builddir> \
+ ["command"]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Enters buildenv of a previously built Elbe root filesystem using chroot.
+The command has to be run as root **inside the Elbe build VM** (created
+with ``elbe-init(1)``).
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--skip-validation
+ Do not validate the source.xml file in <builddir> against the XML
+ schema. (Not recommended.)
+
+--buildtype=TYPE
+ Override the buildtype specified in the source.xml file.
+
+--target
+ chroot into target rfs instead of buildenv
+
+<builddir>
+ The build directory of the root filesystem to work with.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Work with the root filesystem built in */root/testrfs_arm*
+
+ ::
+
+ # elbe chroot /root/testrfs_arm "ls -lh /"
+ work on existing rfs
+ running cmd +chroot /root/testrfs_arm/chroot debconf-set-selections < /root/testrfs_arm/chroot/var/cache/elbe/preseed.txt+
+ total 64K
+ -rw-r--r-- 1 root root 0 Jun 3 09:31 aptcache.log
+ drwxr-xr-x 2 root root 4.0K Jun 3 09:28 bin
+ drwxr-xr-x 2 root root 4.0K Jun 3 09:29 boot
+ drwxr-xr-x 13 root root 3.0K Jun 23 12:38 dev
+ drwxr-xr-x 51 root root 4.0K Jun 3 12:10 etc
+ drwxr-xr-x 2 root root 4.0K Apr 20 03:33 home
+ drwxr-xr-x 11 root root 4.0K Jun 3 09:26 lib
+ drwxr-xr-x 2 root root 4.0K Jun 3 09:23 media
+ drwxr-xr-x 2 root root 4.0K Apr 20 03:33 mnt
+ drwxr-xr-x 2 root root 4.0K Jun 3 09:23 opt
+ dr-xr-xr-x 69 root root 0 Jun 23 12:38 proc
+ drwx------ 2 root root 4.0K Jun 3 12:10 root
+ drwxr-xr-x 6 root root 4.0K Jun 3 09:27 run
+ drwxr-xr-x 2 root root 4.0K Jun 3 09:28 sbin
+ drwxr-xr-x 2 root root 4.0K Jun 10 2012 selinux
+ drwxr-xr-x 2 root root 4.0K Jun 3 09:23 srv
+ drwxr-xr-x 13 root root 0 Jun 23 12:38 sys
+ drwxrwxrwt 2 root root 4.0K Jun 3 09:28 tmp
+ drwxr-xr-x 10 root root 4.0K Jun 3 09:23 usr
+ drwxr-xr-x 11 root root 4.0K Jun 3 09:23 var
+
+ # elbe chroot /root/testrfs_arm
+ (chroot) #
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-control.rst b/docs/elbe-control.rst
new file mode 100644
index 000000000000..e539f1e45378
--- /dev/null
+++ b/docs/elbe-control.rst
@@ -0,0 +1,252 @@
+************************
+elbe-control
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-control - Low level interface to elbe Soap Daemon running in initvm
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe control [options] list_projects
+ elbe control [options] create_project
+ elbe control [options] build_sysroot <build-dir>
+ elbe control [options] build_cdroms <build-dir>
+ elbe control [options] set_pdebuild <project-dir> <pdebuild file>
+ elbe control [options] get_files <build-dir>
+ elbe control [options] build_chroot_tarball <build-dir>
+ elbe control [options] build_sdk <build-dir>
+ elbe control [options] set_orig <build-dir>
+ elbe control [options] set_cdrom <build-dir> <iso-img>
+ elbe control [options] reset_project <build-dir>
+ elbe control [options] list_users
+ elbe control [options] wait_busy <build-dir>
+ elbe control [options] set_xml <build-dir> <xmlfile>
+ elbe control [options] del_project <build-dir>
+ elbe control [options] build_pbuilder <build-dir>
+ elbe control [options] build <build-dir>
+ elbe control [options] rm_log <build-dir>
+ elbe control [options] get_file <build-dir> <filename>
+ elbe control [options] dump_file <build-dir> <filename>
+ elbe control [options] shutdown_initvm
+ elbe control [options] install_elbe_version <version>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Low Level interface to control an elbe daemon running inside an initvm.
+It allows one to submit xml files etc.
+
+For the high level interface, see *elbe initvm*
+
+Please take notice, that a single user can only have a single project
+opened inside the soap server. So it is not possible to have a single
+user build 2 projects at once.
+
+You can only wait on the project, that you are currently building.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--host <hostname>
+ ip or hostname of the elbe-deamon (defaults to localhost, which is
+ the default, where an initvm would be listening).
+
+--port <N>
+ Port of the soap interface on the elbe-daemon.
+
+--user <username>
+ Username to use for login (defaults to root).
+
+--pass <password>
+ Password for login (defaults to *foo*).
+
+--retries <N>
+ How many times to retry the connection to the server before giving up
+ (default is 10 times, yielding 10 seconds).
+
+--build-bin
+ Build binary repository CDROM, for exact reproduction.
+
+--build-sources
+ Build source CDROM.
+
+--output <directory>
+ Output downloaded files to <directory>.
+
+--pbuilder-only
+ Only list/download pbuilder files.
+
+--profile
+ Specify pbuilder profile(s) to build. Provide multiple profiles as a
+ comma separated list.
+
+.. _`_commands`:
+
+COMMANDS
+========
+
+*list_projects*
+ List projects available on the elbe daemon.
+
+*create_project*
+ Create a new project on soap server. a new build-dir is created.
+
+ The name of the created <build-dir> is printed to stdout, for further
+ reference in subsequent commands.
+
+*build_sysroot* <build-dir>
+ Build a sysroot for the specified project.
+
+The sysroot can be used with a toolchain for cross-compiles.
+
+*build_cdroms* <build-dir>
+ Build ISO images containing the Debian binary or source packages used
+ by the given build-dir. Either --build-bin or --build-sources or both
+ needs to be specified.
+
+*set_pdebuild* <build-dir> <pdebuild file>
+
+Build a Debian Project using a pbuilder.
+
+The pdebuild file needs to be a .tar.gz archive of a project containing
+a ./debian folder with a valid debianization.
+
++ The generated debian packages are stored inside the initvm.
+
++ Use get_files to retrieve them.
+
+*get_files* <build-dir>
+ Get list of files in the <build-dir>.
+
+ If the --output option is specified, the files are downloaded to the
+ directory specified in the option. If the --matches option is
+ specified only files matching the wildcard expression are
+ shown/downloaded. Note that you have to put the wildcard expression
+ in quotation marks.
+
+*build_chroot_tarball* <build-dir>
+ Creates a tarball of the chroot environment in <build_dir>.
+
+*build_sdk* <build-dir>
+ Creates a yocto-style SDK.
+
+*set_orig* <build-dir> <orig-file>
+ Uploads a quilt orig-file to the initvm.
+
+ This command shall be run before building a Debian package with
+ ``elbe pbuilder build`` if the package is given in the quilt source
+ format.
+
+*set_cdrom* <build-dir> <iso-img>
+ Set the cdrom iso image. The <iso-img> is uploaded into the intivm.
+ And the source.xml in the <build-dir> is modified, that it builds
+ from the cdrom mirror now.
+
+*reset_project* <build-dir>
+ Reset project database status for <build-dir>.
+
+ When the database becomes inconsistent, this allows us to access an
+ otherwise blocked project again.
+
+ Use with care.
+
+*list_users*
+ List configured users. Only admins may use this command.
+
+*add_user* <name> <fullname> <password> <email>
+ Create a user inside the initvm. The user is not an Admin user. When
+ the user already exists, nothing is done. Only admins may use this
+ command.
+
+*wait_busy* <build-dir>
+ Wait, while <build-dir> is busy.
+
+*set_xml* <build-dir> <xmlfile>
+ Upload a new xml File into the given <build-dir>. This is most likely
+ going to change the status of the project to *needs_rebuild*.
+
+*del_project* <build-dir>
+ Delete project in <build-dir>
+
+*build_pbuilder* <build-dir>
+ Build a pbuilder environment for the given project <build-dir>.
+
+*build* <build-dir>
+ Trigger building the project. Status will change to busy.
+
+*rm_log* <build-dir>
+ Deletes log file for the given project <build-dir>
+
+*get_file* <build-dir> <filename>
+ Download a single file from the project.
+
+*dump_file* <build-dir> <filename>
+ Dump a single File from the project to stdout.
+
+*shutdown_initvm*
+ Make the initvm shutdown.
+
+*install_elbe_version* [version]
+ Make the initvm install a specific elbe version. Defaults to the
+ version of the elbe executable. This requires, that the initvm has
+ package sources configured properly.
+
+.. _`_examples`:
+
+Examples
+========
+
+- List current Projects
+
+ ::
+
+ $ elbe control list_projects
+ /var/cache/elbe/982d64de-e69f-48c7-8942-66d8d480f3dc rescue image 1.0 build_done 2015-06-08 15:29:29.613620
+ /var/cache/elbe/dd37a03e-31bd-45db-afd4-fc51d51fa90a rescue image 1.0 build_done 2015-06-09 08:53:26.658500
+ /var/cache/elbe/8d62928f-4e75-47cf-aec9-d2365ca59003 rescue image 1.0 build_done 2015-06-09 09:14:15.371456
+
+- Create a new Project, trigger build, and wait till it finishes.
+
+ ::
+
+ $ elbe control create_project examples/rescue.xml
+ /var/cache/elbe/f310dcbc-f5fc-423e-99e4-fb72d7b9dd5f
+ $ elbe control build /var/cache/elbe/f310dcbc-f5fc-423e-99e4-fb72d7b9dd5f
+ $ elbe control wait_busy /var/cache/elbe/f310dcbc-f5fc-423e-99e4-fb72d7b9dd5f
+ project still busy, waiting
+ project still busy, waiting
+ ...
+ project still busy, waiting
+ $ elbe control get_files /var/cache/elbe/f310dcbc-f5fc-423e-99e4-fb72d7b9dd5f
+ source.xml (Current source.xml of the project)
+ rescue.cpio (Image)
+ validation.txt (Package list validation result)
+ elbe-report.txt (Report)
+ log.txt (Log file)
+
+.. _`_see_also`:
+
+SEE ALSO
+========
+
+``elbe-initvm(1)`` ``git-daemon(1)``
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-daemon.rst b/docs/elbe-daemon.rst
new file mode 100644
index 000000000000..46883f7db212
--- /dev/null
+++ b/docs/elbe-daemon.rst
@@ -0,0 +1,48 @@
+************************
+elbe-daemon
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-daemon - control the ELBE daemon.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe daemon [options]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command controls the ELBE daemon and is run inside the inivm.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--host <hostname>
+ ip or hostname of the elbe-deamon (defaults to localhost, which is
+ the default, where an initvm would be listening).
+
+--port <N>
+ Port of the soap interface on the elbe-daemon.
+
+--<daemon>
+ Enable <daemon>.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-db.rst b/docs/elbe-db.rst
new file mode 100644
index 000000000000..bf5a4caf86bd
--- /dev/null
+++ b/docs/elbe-db.rst
@@ -0,0 +1,151 @@
+************************
+elbe-db
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-db - interface to the ELBE db. Must be run inside the initvm.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe db [options] list_projects
+ elbe db [options] create_project <project_dir>
+ elbe db [options] get_files <project_dir>
+ elbe db [options] reset_project <project_dir>
+ elbe db [options] list_users
+ elbe db [options] save_version <project_dir>
+ elbe db [options] set_xml <project_dir> <xml_file>
+ elbe db [options] del_project <project_dir>
+ elbe db [options] print_version_xml <project_dir> <version>
+ elbe db [options] init
+ elbe db [options] del_user <userid>
+ elbe db [options] set_project_version <project_dir> <version>
+ elbe db [options] add_user <username>
+ elbe db [options] list_versions <project_dir>
+ elbe db [options] del_versions <project_dir> <version>
+ elbe db [options] build <project_dir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command controls the ELBE daemon and is run inside the initvm.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+-h, --help
+ Displays help.
+
+--name
+ Sets the name of the new user.
+
+--fullname
+ Sets the full name of the new user.
+
+--password
+ Sets the password of the new user.
+
+--email
+ Sets the email address of the new user.
+
+--noadmin
+ TODO!! MACHT MEINER MEINUNG NACH DAS GLEICHE WIE ADMIN.
+
+--admin
+ Gives the new user admin privileges. (Boolean variable,
+ default=False).
+
+--delete-projects
+ Delete all projects owned by the user.
+
+--quiet
+ TODO
+
+--user
+ User name of the project owner.
+
+--clean
+ Deletes the target and chroot directory in <project-dir>.
+
+--description
+ Description of the project version which shall be stored in the
+ database.
+
+.. _`_commands`:
+
+COMMANDS
+========
+
+*init*
+ Creates a new ELBE database and adds one new user. Options:
+ name[=root], fullname[=Admin], password[=foo],
+ email[=\ root at localhost], noadmin[=True].
+
+*add_user* <username>
+ Adds a new user. Options: fullname, password, email, admin=[False].
+
+*del_user* <userid>
+ Deletes user <userid>. Options: delete-projects[=False],
+ quiet=[False].
+
+*list_projects*
+ Lists all projects stored in the database.
+
+*list_users*
+ Lists all users registered in the ELBE database.
+
+*create_project* <project_dir>
+ Creates a new project in directory <project_dir>. Options: user.
+
+*del_project* <project_dir>
+ Removes project in <project_dir> from ELBE database.
+
+*set_xml* <project_dir> <xml_file>
+ Assigns the file <xml_file> as ELBE recipe to the project in
+ <project_dir>.
+
+*build* <project_dir>
+ Builds the project in <project_dir>.
+
+*get_files* <project_dir>
+ Returns a list of all files and directories in <project_dir>
+
+*reset_project* <project_dir>
+ Resets the project state in the database. Can be useful if a build
+ has been aborted and the project is set ``busy`` in in the database
+ obstructing future actions on this project. Options: clean[=False].
+
+*set_project_version* <project_dir> <version>
+ Sets the project version of project <project_dir> to <version>.
+
+*list_versions* <project_dir>
+ Lists all versions of project <project_dir>.
+
+*save_version* <project_dir>
+ Saves current state of project <project_dir> as version. Options:
+ description.
+
+*del_versions* <project_dir> <version>
+ Deletes the version <version> of project <project_dir>.
+
+*print_version_xml* <project_dir> <version>
+ Prints ELBE xml file in <project_dir> of version <version>.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-debianize.rst b/docs/elbe-debianize.rst
new file mode 100644
index 000000000000..9688a9b16b1d
--- /dev/null
+++ b/docs/elbe-debianize.rst
@@ -0,0 +1,79 @@
+************************
+elbe-debianize
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-debianize - How to debianize software
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe debianize* used to be a command that generated a *debian*
+directory inside a source tree of the Linux kernel, U-Boot, or Barebox.
+The templates that the command used for that directory do not follow
+Debian’s best practices and broke for Linux >= 5.16. Therefore, *elbe
+debianize* was removed and is no longer supported.
+
+In order to package U-Boot, please use the u-boot source package from
+the Debian archive. Modifying it for your target architecture or a
+vendor source tree should be straight-forward.
+
+For Barebox, there is no alternative currently. However, Debian bug
+#900958 asks for a barebox package. When that is resolved, please refer
+to that package.
+
+Linux has a built-in deb-pkg make target for a long time. The problem
+with using it as *elbe debianize* alternative is that it builds the
+source and binary packages directly after inserting the debian directory
+into the source. To build only the source package, one must set the make
+variable DPKG_FLAGS=-S on the deb-pkg call. Just be sure to configure
+the kernel so that a .config file is available, and to set the variables
+that are evaluated by the script. See this man page’s EXAMPLES section.
+After the source package is built, there is one generated file that does
+not belong to an unbuilt debian directory: debian/files.
+
+Instead of specifying a specific defconfig the .config will end up being
+used. There is no compiler prefix embedded in debian/rules for cross
+compilation, so you need to specify it while building the package.
+
+This will only generate the source package format that is specified in
+the Linux tree, which is 1.0 for versions < 6.3. The resulting kernel
+image format will be the default for the build architecture and the
+uImage load address is not included in the debian directory but it
+should be derived from some defconfig value if needed.
+
+Several Linux versions will not generate all the Build-Depends that are
+needed to build in a clean environment and you will probably need to fix
+them manually.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+In order to debianize and build a stable kernel for an arm64 system use
+the following commands. Most of the environment and make variables are
+optional but demonstrate the replacements for the *elbe debianize*
+fields.
+
++
+
+::
+
+ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
+ $ cd linux-stable
+ $ export CROSS_COMPILE=aarch64-linux-gnu-
+ $ export DEBEMAIL="`git config user.name` <`git config user.email`>"
+ $ export KDEB_CHANGELOG_DIST=unstable
+ $ make ARCH=arm64 defconfig
+ $ make ARCH=arm64 DPKG_FLAGS=-S KERNELRELEASE=6.2-elbe deb-pkg
+ $ rm debian/files
+ $ git add -f debian
+ $ git commit -sm 'add the deb-pkg generated debianization'
+ $ CC=aarch64-linux-gnu-gcc dpkg-buildpackage -b -aarm64
diff --git a/docs/elbe-diff.rst b/docs/elbe-diff.rst
new file mode 100644
index 000000000000..6cf1d36ee7d1
--- /dev/null
+++ b/docs/elbe-diff.rst
@@ -0,0 +1,48 @@
+************************
+elbe-diff
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-diff - Looks at 2 directories and makes Suggestions to modify the
+xml file.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe diff <generated_dir> <fixed_dir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command is useful, when the initially generated RootFS needs some
+tweaks. It is supplied with the generated and the fixed rootfs, and will
+suggest a finetuning section and a commandline to generate an archive
+file.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<generated_dir>
+ This should point to the originally generated directory.
+
+<fixed_dir>
+ This should point to the fixed directory.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-fetch_initvm_pkgs.rst b/docs/elbe-fetch_initvm_pkgs.rst
new file mode 100644
index 000000000000..57c88b5a282a
--- /dev/null
+++ b/docs/elbe-fetch_initvm_pkgs.rst
@@ -0,0 +1,85 @@
+************************
+elbe-fetch_initvm_pkgs
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-fetch_initvm_pkgs - Download initvm binary and source Packages
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe fetch_initvm_pkgs [--binrepo <dir> ] \
+ [--srcrepo <dir>] \
+ [--skip-validation] \
+ [--cdrom-mount-path <path>] \
+ [--cdrom-device <dev>] \
+ [--apt-archive <dir>] \
+ [--src-archive <dir>] \
+ [--skip-build-source] \
+ [--skip-build-bin] \
+ <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe fetch_initvm_pkgs* downloads source and binary packages of
+software installed into the initvm. These packages are installed into
+debian repositories.
+
+Later on in the target build process, these Repositories are used to
+generate the initvm related repositories.
+
+This command is used by elbe internally during the creation of the
+initvm. It is currently not supposed to be called by users.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--binrepo <dir>
+ directory where the bin repo should reside
+
+--srcrepo <dir>
+ directory where the src repo should reside
+
+--skip-validation
+ Skip xml schema validation
+
+--cdrom-mount-path <path>
+ path where cdrom is mounted
+
+--cdrom-device <device>
+ cdrom device, in case it has to be mounted
+
+--apt-archive <dir>
+ path where binary packages are downloaded to.
+
+--src-archive <dir>
+ path where src packages are downloaded to.
+
+--skip-build-sources
+ skip downloading Source Packages
+
+--skip-build-bin
+ skip downloading binary packages
+
+<xmlfile>
+ the XML file to use.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-gen_update.rst b/docs/elbe-gen_update.rst
new file mode 100644
index 000000000000..5fc949259eda
--- /dev/null
+++ b/docs/elbe-gen_update.rst
@@ -0,0 +1,86 @@
+************************
+elbe-gen_update
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-gen_update - Generate an update archive to be used by elbe-updated.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe gen_update --target <targetdir> --output <outputfile> \
+ [ --buildtype <type> ] \
+ [ --debug ] \
+ [ --name <name> ] \
+ [ --skip-validation ] \
+ <base_sourcexml>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe gen_update* creates an update archive by comparing the packages
+installed in the given target project against the packages listed in the
+given base XML file. The resulting update archive will contain all new
+and all updated packages and can be used to update the target system
+with ``elbe-updated(1)``.
+
+This command has to be run as root **inside the Elbe build VM**.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--target <targetdir>
+ The project directory to generate the update for.
+
+--output <outputfile>
+ Name of the update archive to generate.
+
+--buildtype <type>
+ Override the build type specified in the XML file.
+
+--debug
+ Enable a few debug features.
+
+--name <name>
+ Override the name of the project.
+
+--skip-validation
+ Skip validation of the passed XML file and of the *source.xml* file
+ in the target directory (Not recommended).
+
+<base_sourcexml>
+ The *source.xml* file of the base version of the project.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Create an update package for *myproject* including all packages
+ installed or updated via *apt-get* since the project has been built
+ with *v0.1.xml*. Write the update archive to *v0.1-v0.2.upd*.
+
+ ::
+
+ # elbe gen_update --target /root/myproject \
+ --output /root/v0.1-v0.2.upd \
+ /root/v0.1.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-genlicence.rst b/docs/elbe-genlicence.rst
new file mode 100644
index 000000000000..7027b52174ec
--- /dev/null
+++ b/docs/elbe-genlicence.rst
@@ -0,0 +1,73 @@
+************************
+elbe-genlicence
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-genlicence - Generate a file containing the licences of the
+packages included in a project.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe genlicence \
+ [ --output <filename> ] \
+ [ --xml <xmlfilename> ] \
+ <project-dir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe-genlicence* creates a file which will contain the licences of the
+packages included in a project, generated from the *copyright* files in
+the */usr/share/doc/\** directories of the root filesystem.
+
+This command has to be run **inside the Elbe build VM**.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--output <filename>
+ Write the result to <filename> instead of *licence.txt*.
+
+--xml <xmlfilename>
+ Write an xml file with all the licenses to <xmlfilename>.
+
+--buildtype <buildtype>
+ Override the buildtype.
+
+--skip-validation
+ Skip xml schema validation.
+
+<project>
+ The build directory of the project to process.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Generate a licence file for the project in */var/cache/elbe/<uuid>*
+ and name the result *myproject-licences.txt*.
+
+ ::
+
+ # elbe genlicence --output myproject-licences.txt /var/cache/elbe/<uuid>
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-get_archive.rst b/docs/elbe-get_archive.rst
new file mode 100644
index 000000000000..c175c3b78122
--- /dev/null
+++ b/docs/elbe-get_archive.rst
@@ -0,0 +1,56 @@
+************************
+elbe-get_archive
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-get_archive - Extract the archive from an xmlfile.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe get_archive <xmlfile> <archive>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command extracts the archive from an xml file. It will not
+overwrite anything.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<xmlfile>
+ The xml file to use.
+
+<archive>
+ Name of the extracted archive file. The archive must be a tar.bz2.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Extract the archive in *project.xml* to *archive.tar.bz2*
+
+ ::
+
+ $ elbe get_archive project.xml archive.tar.bz2
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-hdimg.rst b/docs/elbe-hdimg.rst
new file mode 100644
index 000000000000..6687d39271a2
--- /dev/null
+++ b/docs/elbe-hdimg.rst
@@ -0,0 +1,75 @@
+************************
+elbe-hdimg
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-hdimg - Create hard disk and flash images from the given XML file.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe hdimg --target <dir> --output <out> \
+ [ --buildtype <type> ] \
+ [ --skip-validation ] \
+ [ --skip-grub ] \
+ <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe hdimg* creates hard disk and flash images from the *images*
+section in the given XML file. The command has to be run as root
+**inside the Elbe build VM**.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--target <dir>
+ Operate on the given project directory.
+
+--output <out>
+ Name of the log file.
+
+--buildtype <type>
+ Override the build type specified in the XML file.
+
+--skip-validation
+ Do not validate the XML file against the Elbe XML schema (Not
+ recommended).
+
+--skip-grub
+ Skip GRUB installation.
+
+<xmlfile>
+ The XML file to use.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build images for the project in */root/myproject*
+
+ ::
+
+ elbe hdimg --target /root/myproject --output /root/hdimg.log \
+ /root/myproject/source.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-init.rst b/docs/elbe-init.rst
new file mode 100644
index 000000000000..bf2b84d80414
--- /dev/null
+++ b/docs/elbe-init.rst
@@ -0,0 +1,97 @@
+************************
+elbe-init
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-init - create a project for an Elbe build virtual machine
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe init \
+ [ --build-source ] \
+ [ --buildtype <buildtype> ] \
+ [ --debug ] \
+ [ --directory <directory> ] \
+ [ --skip-cds ] \
+ [ --skip-validation ] \
+ <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command generates a project directory for an Elbe build virtual
+machine.
+
+When *make* is executed in that directory, a VM is started, which
+installs Debian and the Elbe build environment. If the XML file contains
+a *target* section, then the target root filesystem will be built inside
+the virtual machine using ``elbe-buildchroot(1)``.
+
+The build VM can be started by executing *make run* (or *make run-con*,
+if a serial console is enough). After that, the virtual machine can be
+used to work inside the generated root filesystem. To do so, please use
+the ``elbe-chroot(1)`` command **inside the VM**.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--build-source
+ Build a Debian source CD-ROM image, containing the source packages
+ used by the project.
+
+--buildtype <buildtype>
+ Override the build type specified in the XML file.
+
+--debug
+ Enables a few features that allow for better debugging of the build
+ process.
+
+--directory <dir>
+ The location of the project directory. If this option isn’t given, a
+ directory *build* is created in the current working directory. The
+ directory must not exist.
+
+--skip-cds
+ Skip the generation of Debian binary cdroms. This makes the build
+ faster. Otherwise all used binary packages are stored on an ISO cdrom
+ image.
+
+--skip-validation
+ Skip the validation of the XML file. (Not recommended)
+
+<xmlfile>
+ The XML describing the Elbe project.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Generate a build VM directory for the project specified in
+ *project.xml* and build the target root filesystem.
+
+ ::
+
+ $ elbe init --directory=/scratch/example project.xml
+ $ cd /scratch/example
+ $ make
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-initvm.rst b/docs/elbe-initvm.rst
new file mode 100644
index 000000000000..0950799fc54b
--- /dev/null
+++ b/docs/elbe-initvm.rst
@@ -0,0 +1,174 @@
+************************
+elbe-initvm
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-initvm - High Level Interface to the ELBE System. Allows one to
+create an initvm and directly build Rootfilesystems using ELBE.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe initvm [options] attach
+ elbe initvm [options] create [<xmlfile> | <isoimage>]
+ elbe initvm [options] submit [<xmlfile> | <isoimage>]
+ elbe initvm [options] start
+ elbe initvm [options] stop
+ elbe initvm [options] ensure
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command allows one to build and manage an initvm.
+
+Initvms are managed via libvirt, and it’s necessary that a user is a
+member of the libvirt group.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--directory <dir>
+ Directory where the initvm resides, or is supposed to reside.
+ (Defaults to *./initvm*)
+
+--cdrom <CDROM>
+ ISO image of Binary cdrom.
+
+--devel
+ Install elbe Version from the current working into initvm.
+
+--skip-download
+ After the build has finished, the generated Files are downloaded from
+ the initvm to the host. This step is skipped, when this option is
+ specified.
+
+--output <dir>
+ Directoryname where the generated and downloaded Files should be
+ saved. The default is to generate a directory with a timestamp in the
+ current working directory.
+
+--skip-build-bin
+ Skip building binary repository CDROM, for exact reproduction.
+
+--skip-build-sources
+ Skip building source CDROM.
+
+--output <directory>
+ Output downloaded files to <directory>.
+
+--keep-files
+ Don’t delete elbe project files after a build in the initvm use *elbe
+ control list_projects* to get a list of available projects
+
+--writeproject <file>
+ Write project name to <file>.
+
+--nesting
+ Allow initvm to support nested kvm. This makes /proc/cpuinfo inside
+ initvm differ per host.
+
+--build-sdk
+ Also make *initvm submit* build an SDK.
+
+--qemu
+ Use QEMU directly instead of libvirt.
+
+.. _`_xml_options`:
+
+XML OPTIONS
+===========
+
+--variant <variant>
+ comma separated list of variants
+
+--proxy <proxy>
+ add proxy to mirrors
+
+.. _`_commands`:
+
+COMMANDS
+========
+
+*attach*
+ Attach to the initvm console, which is accessed via virsh.
+
+ User *root*, password *root*.
+
+*create* [ <xmlfile> \| <isoimage> ]
+ This command triggers a complete rebuild of the Elbe XML File. It
+ also includes rebuilding the initvm.
+
+ If an initvm is already available, you should use the *submit*
+ command, to build a project in an existing initvm.
+
+ Note that only a single initvm can be running on your host.
+
+ When an iso Image with the binaries has been built earlier, it can
+ also be used to recreate the original image. The source.xml from the
+ iso will be used, and all the binary packages available also.
+
+*submit* [ <xmlfile> \| <isoimage> ]
+ This command triggers a complete rebuild of the Elbe XML File. It
+ will however use an existing initvm.
+
+ When an iso Image with the binaries has been built earlier, it can
+ also be used to recreate the original image. The source.xml from the
+ iso will be used, and all the binary packages available also.
+
+*start*
+ Start initvm in the Background.
+
+*stop*
+ Shutdown running initvm.
+
+*sync*
+ Upload elbe Version from the current working into initvm using rsync.
+ Before using this command, you’ll have to add your client SSH key to
+ */root/.ssh/authorized_keys* in initvm manually.
+
+*ensure*
+ Make sure an initvm is running in the Background.
+
+.. _`_examples`:
+
+Examples
+========
+
+- Build an initvm and on that build an elbe example:
+
+ ::
+
+ $ elbe initvm create /usr/share/doc/elbe-doc/examples/rescue.xml
+
+- Reuse the initvm built in the previous Step to build another example
+ xml
+
+ ::
+
+ $ elbe initvm submit /usr/share/doc/elbe-doc/examples/elbe-desktop.xml
+
+.. _`_see_also`:
+
+SEE ALSO
+========
+
+``elbe-control(1)``
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-mkcdrom.rst b/docs/elbe-mkcdrom.rst
new file mode 100644
index 000000000000..3d8e7406813d
--- /dev/null
+++ b/docs/elbe-mkcdrom.rst
@@ -0,0 +1,104 @@
+************************
+elbe-mkcdrom
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-mkcdrom - Create an ISO image containing binary and/or source
+packages used in the given project.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe mkcdrom \
+ [ --arch <arch> ] \
+ [ --binary ] \
+ [ --buildtype <type> ] \
+ [ --codename <codename> ] \
+ [ --log <logfile> ] \
+ [ --skip-validation ] \
+ [ --source ] \
+ [ --rfs-only ] \
+ <builddir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe mkcdrom* creates an ISO image containing the binary and/or source
+packages used in the given project. This command has to be run as root
+**inside the Elbe build VM**.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--arch <arch>
+ Override the architecture.
+
+--binary
+ Build an ISO file for a binary CD-ROM. It will contain all installed
+ packages, including those pulled in by debootstrap (except if
+ *--rfs-only* is used, see down below) and those installed from
+ additional sources. It can also be used as an installation source,
+ see ``elbe-setcdrom(1)``.
+
+--buildtype <type>
+ Override the build type specified in the XML file.
+
+--codename <codename>
+ Override the Debian code name.
+
+--log <logfile>
+ Write a log file.
+
+--skip-validation
+ Do not validate the *source.xml* file in <builddir> against the XML
+ schema (Not recommended).
+
+--source
+ Build an ISO image for a source CD-ROM.
+
+--rfs-only
+ <builddir> is not a build directory, but the path to a root
+ filesystem. In that case, the packages pulled in only by debootstrap
+ will not be included in the ISO image for binary CD-ROM.
+
+<builddir>
+ The path to the Elbe build directory to create the ISO image for. It
+ is also possible to specify the path to the root filesystem instead
+ of the build directory. In that case the *--rfs-only* option has to
+ be given.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build a binary CD-ROM image for the project in foo/myproject
+
+ ::
+
+ # elbe mkcdrom --binary foo/myproject
+
+- Build a source CD-ROM image for the project in foo/myproject
+
+ ::
+
+ # elbe mkcdrom --source foo/myproject
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-parselicence.rst b/docs/elbe-parselicence.rst
new file mode 100644
index 000000000000..e3a78a710e97
--- /dev/null
+++ b/docs/elbe-parselicence.rst
@@ -0,0 +1,380 @@
+************************
+elbe-parselicence
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-parselicence - Generate a file containing the licences of the
+packages included in a project.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe parselicence \
+ --mapping <filename> \
+ [ --output <filename> \
+ [ --tvout <filename> \
+ [ --use-nomos ] \
+ [ --errors-only ] \
+ <licence.xml filename>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe-parselicence* parses an xml file with licence information. This
+xml file is generated during an elbe build. SPDX Licenses information is
+generated using mappings and overrides found in the mapping file.
+
+This information is written to an output xml file, and to a tagvalue
+based SPDX File.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--mapping <filename>
+ Use <filename> to aid with packages which contain
+ non-machine-readable or incomplete Licence infos. The format is
+ explained in the chapter MAPPING FILE.
+
+--output <filename>
+ Write the xml result to <filename>.
+
+--tvout <filename>
+ Write the tagvalue result to <filename>.
+
+--use-nomos
+ Also pipe licence text through nomos, and add this info to xml
+ Datastructures.
+
+--errors-only
+ Only Output Packages with errors. This is useful during the Phase
+ where the mapping file is setup.
+
+<licence.xml filename>
+ licence.xml File generated during elbe build.
+
+.. _`_workflow`:
+
+WORKFLOW
+========
+
+Elbe generates a ``license.xml`` File. This file is then parsed using
+
+::
+
+ elbe parselicence --mapping my_mapping.xml /path/to/license.xml --errors-only --output out.xml
+
+.. note::
+
+ an example mapping is still missing. Maybe you can use some text from
+ this man page.
+
+The previous step will only output nodes into out.xml where an error
+happened. The errors need to be fixed by expanding ``my_mapping.xml``
+
+.. note::
+
+ ``my_mapping.xml`` is describe in it own chapter.
+
+When no more errors happen, one can remove the option ``--errors-only``
+and use the out.xml or generate tag-value output using option
+``--tvout <filename>``
+
+::
+
+ elbe parselicence --mapping my_mapping.xml /path/to/license.xml --tvout spdx_licenses.tagvalue
+
+.. _`_license_xml_file`:
+
+LICENSE.XML FILE
+================
+
+When elbe builds an image, it will look at all
+``/usr/share/doc/*/copyright`` Files, and concatenate them into
+``license.txt``. Elbe will also generate ``license.xml``, which also
+contains meta-data extracted from machine-readable copyright files, or
+generated via heuristics.
+
+There are 3 possibitlities per Package:
+
+.. _`_copyright_file_is_machine_readable`:
+
+Copyright File is machine-readable
+----------------------------------
+
+The debian Licenses and all per file information is put into the xml
+file if the copyright file is machine-readable.
+
+The ``<pkglicense>`` tag will contain a ``<machinereadable />`` tag, and
+also ``<debian_licenses>`` and a ``<detailed>`` tag.
+
+Example:
+
+.. code:: xml
+
+ <pkglicense name="liblogging-stdlog0"><text>Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+ Upstream-Name: liblogging
+ Source: http://www.liblogging.org/
+
+ Files: *
+ Copyright: 2002-2014 Rainer Gerhards and Adiscon GmbH.
+ License: BSD-2-Clause
+
+ License: BSD-2-Clause
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+ .
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE HOLDERS OR
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ </text>
+ <machinereadable />
+ <debian_licenses><license>BSD-2-Clause</license>
+ </debian_licenses>
+ <detailed><files><glob>*</glob>
+ <license>BSD-2-Clause</license>
+ <copyright>2002-2014 Rainer Gerhards and Adiscon GmbH.</copyright>
+ </files>
+ </detailed>
+ </pkglicense>
+
+.. _`_some_information_can_be_extracted_via_heuristics`:
+
+Some information can be extracted via heuristics
+------------------------------------------------
+
+There are quite a few copyright files which almost adopted the new
+machine readable Format. But the parser does not accept it.
+
+The heuristic will look for lines containing ``License: *`` and will
+extract that info into a ``<debian_licenses>`` tag.
+
+Example:
+
+.. code:: xml
+
+ <pkglicense name="libapt-pkg4.12"><text>Apt is copyright 1997, 1998, 1999 Jason Gunthorpe and others.
+ Apt is currently developed by APT Development Team <deity at lists.debian.org>.
+
+ License: GPLv2+
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
+
+ See /usr/share/common-licenses/GPL-2, or
+ <http://www.gnu.org/copyleft/gpl.txt> for the terms of the latest version
+ of the GNU General Public License.
+
+ </text>
+ <heuristics />
+ <debian_licenses><license>GPLv2+</license>
+ </debian_licenses>
+ </pkglicense>
+
+.. _`_no_information_can_be_extracted_automatically`:
+
+No information can be extracted automatically
+---------------------------------------------
+
+Only the text will be put into the xml File.
+
+Example:
+
+.. code:: xml
+
+ <pkglicense name="bsd-mailx"><text>This package was debianized by Loic Prylli <lprylli at graville.fdn.fr> on
+ Mon, 23 Dec 1996 00:13:13 +0100.
+ The package is currently maintained by Robert Luberda <robert at debian.org>
+
+ It is now based on OpenBSD in directory src/usr.bin/mail on a lot of major
+ ftp sites.
+ See the README.Debian (and changelog.Debian) for the complicated history
+ of the Debian package.
+
+ Copyright (c) 1980, 1993 The Regents of the University of California.
+
+
+
+ This software is licensed under the BSD License. The complete text of
+ the license is included below:
+
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+ 3. Neither the name of the University nor the names of its contributors
+ may be used to endorse or promote products derived from this software
+ without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
+ </text>
+ </pkglicense>
+
+.. _`_mapping_file`:
+
+MAPPING FILE
+============
+
+In order to help ``elbe parselicence`` with decisions, which it can not
+make automatically, a mapping file is needed.
+
+It defines the following items:
+
+- global mappings from Debian License to SPDX License Identifier in
+ node ``<global>``
+
+- per package mappings ``<perpackage> <package> <mapping>``
+
+- per package override definitions
+
+Here is an example mapping.xml:
+
+.. code:: xml
+
+ <?xml version='1.0' encoding='utf-8'?>
+ <license_map>
+ <global>
+ <mapping name='GPL-1+'>GPL-1.0+</mapping>
+ <mapping name='GPL-2'>GPL-2.0</mapping>
+ <mapping name='GPL-2.0'>GPL-2.0</mapping>
+ <mapping name='GPL-2+'>GPL-2.0+</mapping>
+ <mapping name='GPLv2+'>GPL-2.0+</mapping>
+ <mapping name='GPL-2.0+'>GPL-2.0+</mapping>
+ <mapping name='GPL-2.1+'>GPL-2.1+</mapping>
+ <mapping name='GPL-3+'>GPL-3.0+</mapping>
+ <mapping name='GPLv3+'>GPL-3.0+</mapping>
+ <mapping name='GPL-3.0+'>GPL-3.0+</mapping>
+
+ <mapping name='LGPL-2'>LGPL-2.0</mapping>
+ <mapping name='LGPL-2.0'>LGPL-2.0</mapping>
+ <mapping name='LGPL-2+'>LGPL-2.0+</mapping>
+ <mapping name='LGPL2.1'>LGPL-2.1</mapping>
+ <mapping name='LGPL-2.1'>LGPL-2.1</mapping>
+ <mapping name='LGPL-2.1+'>LGPL-2.1+</mapping>
+ <mapping name='LGPL-3+'>LGPL-3.0+</mapping>
+ <mapping name='LGPL-3.0+'>LGPL-3.0+</mapping>
+ <mapping name='LGPL'>LGPL-3.0+</mapping>
+
+ <mapping name='GFDL-1.2'>GFDL-1.2</mapping>
+ <mapping name='GFDL-1.2+'>GFDL-1.2+</mapping>
+ <mapping name='GFDL-1.3'>GFDL-1.3</mapping>
+ <mapping name='GFDL-1.3+'>GFDL-1.3+</mapping>
+
+ <mapping name='BSD-2-clause'>BSD-2-Clause</mapping>
+ <mapping name='BSD-2-Clause'>BSD-2-Clause</mapping>
+ <mapping name='BSD-3-clause'>BSD-3-Clause</mapping>
+ <mapping name='BSD-3-Clause'>BSD-3-Clause</mapping>
+ <mapping name='BSD-4-clause'>BSD-4-Clause</mapping>
+ <mapping name='BSD-4-Clause'>BSD-4-Clause</mapping>
+ <mapping name='MIT'>MIT</mapping>
+ <mapping name='CC-BY-SA-3.0'>CC-BY-SA-3.0</mapping>
+
+ <mapping name='ZLIB'>Zlib</mapping>
+ <mapping name='MPL-2.0'>MPL-2.0</mapping>
+ <mapping name='Apache-2.0'>Apache-2.0</mapping>
+ <mapping name='GPL-3.0-with-GCC-exception'>GPL-3.0 WITH GCC-exception-3.1</mapping>
+ <mapping name='GPL-3+ with GCC-Runtime-3.1 exception'>GPL-3.0+ WITH GCC-exception-3.1</mapping>
+ <mapping name='Artistic'>Artistic-1.0</mapping>
+ <mapping name='Artistic-2'>Artistic-2.0</mapping>
+ <mapping name='GPL-3+ with OpenSSL exception'>GPL-3.0+ WITH openvpn-openssl-exception</mapping>
+ <mapping name='FTL'>FTL</mapping>
+ <mapping name='ISC'>ISC</mapping>
+ <mapping name='Gzip'>Zlib</mapping>
+
+ <mapping name='X-Consortium'>X11</mapping>
+
+ <mapping name='Expat'>MIT</mapping>
+ <mapping name='public-domain'>CC-0</mapping>
+ </global>
+
+ <perpackage>
+ <package name='grub-common'>
+ <!-- heuristics override, because of error in machine read-->
+ <license>GPL-3.0+</license>
+ <license>MIT</license>
+ <license>CC-BY-SA-3.0</license>
+ </package>
+ <package name='init-system-helpers'>
+ <mapping name='BSD'>BSD-3-Clause</mapping>
+ </package>
+
+ <package name='liblzo2-2'>
+ <license>GPL-2.0+</license>
+ </package>
+ <package name='logrotate'>
+ <license>GPL-2.0+</license>
+ </package>
+ </perpackage>
+ </license_map>
+
+As you can see, it is also necessary to add identity mappings, like
+``<mapping name='GPL-2.0'>GPL-2.0</mapping>``
+
+Its not allowed to mix ``<license>`` and ``<mapping>`` in a single
+<package> node.
+
+.. _`_nomos`:
+
+NOMOS
+=====
+
+Nomos is part of fossology. See https://www.fossology.org/get-started/
+to find out, how to install the nomos executable.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-pbuilder.rst b/docs/elbe-pbuilder.rst
new file mode 100644
index 000000000000..f7da74396854
--- /dev/null
+++ b/docs/elbe-pbuilder.rst
@@ -0,0 +1,171 @@
+************************
+elbe-pbuilder
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-pbuilder - High Level Interface to the ELBE Package Build System.
+Allows one to create a package builder for a project and to build Debian
+packages.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe pbuilder build [--project <project> | --xmlfile <xmlfile>]
+ elbe pbuilder create [--project <project> | --xmlfile <xmlfile>] [--writeproject <filename>]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Creates a pbuilder for a specified project and builds the Debian package
+like pbuilder, but for the configured ELBE project.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--project <dir>
+ *key* (/var/cache/elbe/<uuid> for the project inside the initvm to
+ use. Use *elbe control list_projects* to get a list of the available
+ projects. Another option would be to use the --writeproject option,
+ when the pbuilder is created.
+
+--xmlfile <xmlfile>
+ This file is used to create a new ELBE project including the pbuilder
+ environment.
+
+--cpuset <int>
+ When this value is not -1 (the default), the pbuilder is run using
+ *taskset <cpuset>* which allows one to limit the number of cpus used
+ for the build. This is useful when multithreading and qemu-user yield
+ problem with e.g. java.
+
+--profile string
+ Specify the build profile(s) to build. (dpkg-buildpackage
+ -P<profile>) Provide multiple profiles as a comma separated list.
+
+--cross
+ Combined with the create command it creates a chroot environment to
+ make crossbuilding possible. Combined with the build command it will
+ use this environment for crossbuilding.
+
+--no-ccache
+ The compiler cache *ccache* is activated by default. Use this option
+ with the *create* command to deactivate it.
+
+--ccache-size <string>
+ Use this option to configure the limit of the compiler cache. Should
+ be a number followed by an optional suffix: k, M, G, T. Use 0 for no
+ limit.
+
+.. _`_xml_options`:
+
+XML OPTIONS
+===========
+
+--variant <variant>
+ comma separated list of variants
+
+--proxy <proxy>
+ add proxy to mirrors
+
+.. _`_commands`:
+
+COMMANDS
+========
+
+*create*
+ A pbuilder environment for the given project or xml File will be
+ created. If --cross is given the pbuilder environment will be created
+ to crossbuild packages. (If --cross is given with the create command
+ you have to use --cross with the build command also.) The compiler
+ cache ``ccache`` gets installed by default to speed up
+ recompilations. To deactivate use ``--no-ccache`` with the create
+ command. It is possible to change the size with
+ ``--ccache-size <string>`` where string should be a number followed
+ by an optional suffix: k, M, G, T. For no limit use 0.
+
+*build*
+ Build the *Debianized Project* in the current working directory. (A
+ valid ./debian directory needs to exist.) If --project was specified,
+ the specified build environment will be used. If --xmlfile is
+ specified, a new build environment will be created for the given ELBE
+ XML File, and the *Debianized Project* in the current working
+ directory will be built. The result of the package build is stored in
+ ../ like pbuilder does.
+
+.. _`_notes`:
+
+NOTES
+=====
+
+In this benchmark all opportunitys for creating a pbuilder environment
+and building a package with it were tested. All environments were
+created with the *armhf-ti-beaglebone-black.xml* example and with cross,
+ccache, no-cross or no-ccache in all possible variations. The build
+command was tested with the zlib package. All times are real-time
+captures. The build command with ccache was tested twice to see the
+impact of ccache.
+
+pbuilder no-ccache create 6m35,003s pbuilder no-ccache build 7m19,467s
+
+pbuilder no-ccache cross create 4m2,553s pbuilder no-ccache build
+2m39,151s
+
+pbuilder ccache create 6m44,117s pbuilder ccache build 1. 7m36,130s 2.
+4m47,050s
+
+pbuilder ccache cross create 4m4,190s pbuilder ccache cross build 1.
+2m40,159s 2. 2m32,650s
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build a pbuilder for *myarm.xml*. Save project name into myarm.prj
+
+ ::
+
+ # elbe pbuilder create --xmlfile myarm.xml --writeproject myarm.prj
+
+- Use the pbuilder we have built, to build *program*, using the prj
+ File generated in parent directory
+
+ ::
+
+ # cd program
+ # elbe pbuilder build --project `cat ../myarm.prj`
+
+- Use the pbuilder we have built, to build *program*, using the prj
+ File generated in parent directory. And don’t use more than one CPU
+ as a workaround for qemu-user and java problems.
+
+ ::
+
+ # cd program
+ # elbe pbuilder build --project `cat ../myarm.prj` --cpuset 1
+
+.. _`_see_also`:
+
+SEE ALSO
+========
+
+``elbe-control(1)`` ``elbe-initvm(1)`` ``pdebuild(1)``
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-pkgdiff.rst b/docs/elbe-pkgdiff.rst
new file mode 100644
index 000000000000..8a08c76be07b
--- /dev/null
+++ b/docs/elbe-pkgdiff.rst
@@ -0,0 +1,50 @@
+************************
+elbe-pkgdiff
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-pkgdiff - Compare two directories for differing packages and
+suggest how to modify the Elbe XML file.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe pkgdiff <generated_dir> <fixed_dir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command is useful if new packages have been installed to a root
+filesystem or if some packages have been removed from it after it was
+created. It suggests changes to the pkg-list section to include the
+added packages and to exclude the removed ones. The command is supplied
+with the path to the originally generated directory and the path to the
+directory with the modified root filesystem.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<generated_dir>
+ This should point to the originally generated directory.
+
+<fixed_dir>
+ This should point to the fixed directory.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-preprocess.rst b/docs/elbe-preprocess.rst
new file mode 100644
index 000000000000..98df3d5cdb72
--- /dev/null
+++ b/docs/elbe-preprocess.rst
@@ -0,0 +1,55 @@
+************************
+elbe-preprocess
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-preprocess - resolves xinclude, external resources and resolves
+variants
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ 'elbe preprocess [options] <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Typically elbe preprocess is used to generate an elbe XML file from a
+XML file that uses Xincludes, or other XML features. It can be also used
+for variant management with the *variant=* attribute.
+
+If e.g. a variant="audio,video" attribute is added to any XML tag, the
+tag will only be used if *elbe preprocess* is called with
+--variant=audio or --variant=video or --variant=audio,video. If no
+--variant is given, the tag will be dropped.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--variant <variant>
+ comma separated list of variants
+
+--proxy <proxy>
+ add proxy to mirrors
+
+--output <filename>
+ preprocessed output file, defaults to preprocess.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-prjrepo.rst b/docs/elbe-prjrepo.rst
new file mode 100644
index 000000000000..f819da7d216d
--- /dev/null
+++ b/docs/elbe-prjrepo.rst
@@ -0,0 +1,89 @@
+************************
+elbe-prjrepo
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-prjrepo - Provides access to the Debian repositories in each
+project folder.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe prjrepo download <project_dir>
+ elbe prjrepo upload_pkg <project_dir> [<debfile> | <dscfile> | <changesfile>]
+ elbe prjrepo list_packages <project_dir>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Whenever ELBE pbuilder builds a Debian package, it is added to a local
+Debian repository which is located in the project folder inside the
+initvm. Packages in this repository can then be installed into a root
+file system. The ``elbe-prjrepo`` command allows the user to interact
+with this repository, i.e. list, upload and download packages.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--user <username>
+ Username to use for login (defaults to root).
+
+--pass <password>
+ Password for login (defaults to *foo*).
+
+--retries <N>
+ How many times to retry the connection to the server before giving up
+ (default is 10 times, yielding 10 seconds).
+
+.. _`_commands`:
+
+COMMANDS
+========
+
+*download* <project_dir>
+ Downloads the Debian repository of the project located in
+ <project_dir> to the host machine.
+
+*upload_pkg* <project_dir> [<debfile> \| <dscfile> \| <changesfile>]
+ Loads a Debian package into the Debian repository of an existing Elbe
+ project in the initvm. Both binary and source packages are supported.
+ In order to upload a source package you need to specify the dsc-file
+ in the command as shown above. The actual source files which are
+ required for the source package need to be located in the same
+ directory as the dsc-file. The same is true for a changes file. The
+ actual files defined in the changes file need to reside in the same
+ directory.
+
+*list_packages* <project_dir>
+ Lists all packages available in the Debian repository of the project.
+
+.. _`_example`:
+
+Example
+=======
+
+- List the packages available in the project
+ 38599ce2-4cad-4578-bfe1-06fa793b883a:
+
+ ::
+
+ $ elbe prjrepo list_packages "/var/cache/elbe/38599ce2-4cad-4578-bfe1-06fa793b883a"
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-remove_sign.rst b/docs/elbe-remove_sign.rst
new file mode 100644
index 000000000000..22603d048e3c
--- /dev/null
+++ b/docs/elbe-remove_sign.rst
@@ -0,0 +1,56 @@
+************************
+elbe-remove_sign
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-remove_sign - Verify a signed file and remove the signature.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe remove_sign <filename>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command checks the validity of a file signed with ``elbe-sign(1)``
+or *gpg --sign*. It uses the GPG keyring of the current user, so for
+this to work the public key of the signer has to be added to the
+keyring. Note that to get *VALID (Trusted)*, the key has to have
+ultimate trust.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<filename>
+ The name of the file to sign.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- check validity of *rfs.tar.bz2.gpg* and remove the signature
+
+ ::
+
+ elbe remove_sign rfs.tar.bz2.gpg
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-repodir.rst b/docs/elbe-repodir.rst
new file mode 100644
index 000000000000..39d962a1d0fb
--- /dev/null
+++ b/docs/elbe-repodir.rst
@@ -0,0 +1,87 @@
+************************
+elbe-repodir
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-repodir - preprocesses and hosts repodirs on an Elbe client
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ 'elbe repodir [options] <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+elbe repodir preprocesses an XML file to convert <repodir> tags to valid
+<url> tags. It runs a web server on a random TCP port with the root set
+to a repodir’s PATH, which can be a relative path to the XML file or an
+absolute filesystem path.
+
+The repository is not considered to be signed unless the repodir
+contains a signed-by attribute, which will then copy the given
+ascii-armored OpenPGP keyring file as <raw-key> to the <url> node. The
+key file must be a relative path to repodir’s PATH.
+
+After the output file is written, the started webserver(s) will log
+their accessed files.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--output <filename>
+ preprocessed output file, defaults to repodir.xml. If this exists it
+ will be overridden.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+The source …
+
+.. code:: xml
+
+ <repodir>PATH1 bullseye main contrib</repodir>
+ <repodir signed-by="relative-path.asc">PATH2 buster main</repodir>
+
+i. is preprocessed to:
+
+.. code:: xml
+
+ <url>
+ <binary>http://LOCALMACHINE:36071 bullseye main contrib</binary>
+ <source>http://LOCALMACHINE:36071 bullseye main contrib</source>
+ <options>
+ <option>trusted=yes</option>
+ </options>
+ </url>
+ <url>
+ <binary>http://LOCALMACHINE:33187 buster main</binary>
+ <source>http://LOCALMACHINE:33187 buster main</source>
+ <raw-key>
+ CONTENT OF KEYRING FILE "PATH2/relative-path.asc"
+ </raw-key>
+ </url>
+
+i. with randomly chosen TCP port 36071 serving PATH1 and port 33187
+ serving PATH2.
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-setsel.rst b/docs/elbe-setsel.rst
new file mode 100644
index 000000000000..eb200672c268
--- /dev/null
+++ b/docs/elbe-setsel.rst
@@ -0,0 +1,77 @@
+************************
+elbe-setsel
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-setsel - Replace the package list of an Elbe XML file by a list
+obtained from *dpkg-getselections*.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe setsel <xmlfile> <pkglist>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe setsel* replaces the package list of an Elbe XML file by a package
+list obtained from *dpkg --get-selections*. Together with the setsel
+mode of Elbe, this offers a more fine-grained control on which packages
+are installed (even apt and aptitude can be excluded from the root
+filesystem). The recommended usage is as follows:
+
+1. Generate an image using the default mode of Elbe.
+
+2. Run the image and use *apt-get* to purge unwanted packages.
+
+3. Maybe even use *dpkg* to remove apt and aptitude.
+
+4. Generate the list of selected packages using *dpkg --get-selections >
+ selections.list*
+
+5. Transfer this file to the host system.
+
+6. Use *elbe setsel <xmlfile> selections.list* to import the package
+ list into the XML file.
+
+7. Rebuild using the setsel mode of Elbe.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<xmlfile>
+ The XML file to modify.
+
+<pkglist>
+ The package list from *dpkg --get-selections*.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Replace the package list of myproject.xml with the packages listed by
+ *dpkg --get-selections > myproject.pkgs*.
+
+ ::
+
+ $ elbe setsel myproject.xml myproject.pkgs
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-show.rst b/docs/elbe-show.rst
new file mode 100644
index 000000000000..3d05f21027d8
--- /dev/null
+++ b/docs/elbe-show.rst
@@ -0,0 +1,59 @@
+************************
+elbe-show
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-show - Get a human readable representation of a ELBE XML file.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe show [--verbose] <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command generates a human readable overview of a given ELBE XML
+file.
+
+It’s useful to get an idea what a specific XML file was designed for.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--verbose
+ Give more information, e.g. the package list of the target
+ root-filesystem.
+
+<xmlfile>
+ The xmlfile to be shown.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- get a human readable representation of *project.xml*
+
+ ::
+
+ $ elbe show project.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-sign.rst b/docs/elbe-sign.rst
new file mode 100644
index 000000000000..920dfed3d976
--- /dev/null
+++ b/docs/elbe-sign.rst
@@ -0,0 +1,62 @@
+************************
+elbe-sign
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-sign - Add a signature to the given file
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe sign <filename> <fingerprint>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Sign the given file with the GPG key having the specified fingerprint.
+The resulting file will contain both the compressed data and the
+signature (the same format *gpg --sign* uses if no other arguments are
+specified), and it will get a *.gpg* extension.
+
+The person receiving the file can use *gpg --decrypt* or
+``elbe-remove_sign(1)`` to verify the file and to get the original
+content.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<filename>
+ The name of the file to sign.
+
+<fingerprint>
+ The fingerprint of the private GPG key to use for signing the file.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- sign *rfs.tar.bz2* with the key having the fingerprint *FEE1DEAD*
+
+ ::
+
+ elbe sign rfs.tar.bz2 FEE1DEAD
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-toolchainextract.rst b/docs/elbe-toolchainextract.rst
new file mode 100644
index 000000000000..05a45f878b15
--- /dev/null
+++ b/docs/elbe-toolchainextract.rst
@@ -0,0 +1,104 @@
+************************
+elbe-toolchainextract
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-toolchainextract - extract libraries from a cross-toolchain
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe toolchainextract \
+ [ --path <path to toolchain> ] \
+ [ --output <output repository path> ]
+ [ --codename <distro codename for repository> ]
+ [ --buildtype <shortname for the toolchain type> ]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe toolchainextract* builds a debian repository containing debian
+packages that have been generated from a given cross-toolchain.
+
+This command has to be run as root **inside the Elbe build VM**.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--path <path to toolchain>
+ basepath to the toolchain that is used to extract the debian
+ packages.
+
+--output <output repository path>
+ path were the debian repo will be generated.
+
+--codename <distro codename for repository>
+ codename of the debian suite for which the repo should be built for.
+
+--buildtype <shortname of the toolchain type>
+ currently armhf-linaro48 or armel-linaro48 can be used.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Build a repo containing the lib packages from a Linaro armhf
+ toolchain.
+
+ ::
+
+ # elbe initvm attach
+
+ login: root # (password root)
+
+ # elbe toolchainextract \
+ -p /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_linux \
+ -o /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo \
+ -c stretch \
+ -b armhf-linaro48
+
+ # ls /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/*/*
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/liba/libasan0:
+ libasan0_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/liba/libatomic1:
+ libatomic1_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/libg/libgcc1:
+ libgcc1_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/libg/libgfortran3:
+ libgfortran3_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/libg/libgomp1:
+ libgomp1_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/libm/libmudflap0:
+ libmudflap0_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/libs/libssp0:
+ libssp0_4.8.3_armhf.deb
+
+ /opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_repo/pool/main/libs/libstdc++6:
+ libstdc++6_4.8.3_armhf.deb
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-updated.rst b/docs/elbe-updated.rst
new file mode 100644
index 000000000000..8f6e2bda33e5
--- /dev/null
+++ b/docs/elbe-updated.rst
@@ -0,0 +1,87 @@
+************************
+elbe-updated
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-updated - Elbe update daemon.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe updated \
+ [ --directory <update_dir> ] \
+ [ --host <host> ] \
+ [ --nosign ] \
+ [ --port <port> ] \
+ [ --usb ]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+*elbe updated* is the Elbe update daemon, which runs on the target
+system. It watches a directory for incoming update packages (which have
+been created with ``elbe-gen_update(1)`` in the build VM) and applies
+them to the system. By default, only signed update packages are allowed.
+To sign an update package, please use ``elbe-sign(1)``. It is also
+possible to monitor the USB bus and to install updates located on an USB
+drive.
+
+*elbe updated* also has a built in SOAP interface which can be used to
+monitor the status of the update daemon and to initiate downgrades.
+
+This command has to be run as root **on the target system**. Please note
+that *elbe updated* is usually started by the init script of its
+package, so in most cases there should be no need to start it by
+invoking this command directly.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--directory <update_dir>
+ Monitor the given directory for incoming update packages. Default is:
+ */var/cache/elbe/updates*
+
+--host <host>
+ Bind address for the SOAP interface. Default is to bind to all
+ network interfaces.
+
+--nosign
+ Accept update packages without signatures.
+
+--port <port>
+ Port for the SOAP interface. Default is 8088.
+
+--usb
+ Enable the USB monitor. This option requires pyudev module and an
+ automount system for the usb drives (e.g. usbmount).
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Start the update daemon, watch */updates* for updates and accept
+ update packages without a signature.
+
+ ::
+
+ # elbe updated --directory /updates --nosign
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-validate.rst b/docs/elbe-validate.rst
new file mode 100644
index 000000000000..f6a09995e54a
--- /dev/null
+++ b/docs/elbe-validate.rst
@@ -0,0 +1,52 @@
+************************
+elbe-validate
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-validate - validate xml file.
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe validate <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command validates the xmlfile provided, and prints out errors.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+<xmlfile>
+ The xml file to validate.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- Validate *project.xml*
+
+ ::
+
+ $ elbe validate project.xml
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe-xsdtoasciidoc.rst b/docs/elbe-xsdtoasciidoc.rst
new file mode 100644
index 000000000000..9f68bd16446b
--- /dev/null
+++ b/docs/elbe-xsdtoasciidoc.rst
@@ -0,0 +1,57 @@
+************************
+elbe-xsdtoasciidoc
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe-xsdtoasciidoc - Create an asciidoc documentation from an annotated
+XML Schema file (xsd).
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe xsdtoasciidoc [options] <xmlfile>
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+This command generates documentation for the format of any ELBE XML
+file. It parses the ELBE schema file and creates an asciidoc
+documentation out of the annotations in the xsd file.
+
+.. _`_options`:
+
+OPTIONS
+=======
+
+--output=FILE specify output filename
+
+<xsdfile>
+ The xsdfile to be used.
+
+.. _`_examples`:
+
+EXAMPLES
+========
+
+- get the documentation of the elbe xml format
+
+ ::
+
+ $ elbe xsdtoasciidoc /usr/share/elbe/dbsfed.xsd
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
diff --git a/docs/elbe.rst b/docs/elbe.rst
new file mode 100644
index 000000000000..f5b8ddb02d3b
--- /dev/null
+++ b/docs/elbe.rst
@@ -0,0 +1,121 @@
+************************
+elbe
+************************
+
+.. _`_name`:
+
+NAME
+====
+
+elbe - Embedded Linux Build Environment
+
+.. _`_synopsis`:
+
+SYNOPSIS
+========
+
+ ::
+
+ elbe <command> [<args>]
+
+.. _`_description`:
+
+DESCRIPTION
+===========
+
+Elbe is a system to build Rootfilesystems from XML description files. It
+also includes tools to modify xml files.
+
+The *<command>* is a name of an Elbe command (see below).
+
+.. _`_elbe_commands`:
+
+Elbe COMMANDS
+=============
+
+``elbe-initvm(1)``
+ build and manage initvm. Also allows one to submit xml Files into the
+ initvm
+
+``elbe-control(1)``
+ low-level interface to projects inside the initvm.
+
+``elbe-buildchroot(1)``
+ build a root filesystem.
+
+``elbe-buildsysroot(1)``
+ build a sysroot archive.
+
+``elbe-check_updates(1)``
+ check whether package updates are available for a given project.
+
+``elbe-chg_archive(1)``
+ insert a new config archive (.tbz) into a XML file.
+
+``elbe-chroot(1)``
+ enter a root filesystem with chroot.
+
+``elbe-diff(1)``
+ compare two root file systems for differing files.
+
+``elbe-gen_update(1)``
+ generate an update archive for elbe-updated.
+
+``elbe-genlicence(1)``
+ generate a file containing the licences of all packages included in a
+ project.
+
+``elbe-get_archive(1)``
+ extract a config archive (.tbz) from a XML file.
+
+``elbe-hdimg(1)``
+ create a hard disk image from the given XML file.
+
+``elbe-init(1)``
+ create a project for an Elbe build virtual machine.
+
+``elbe-mkcdrom(1)``
+ create an ISO image containing all binary or source packages used in
+ the given project.
+
+``elbe-pbuilder(1)``
+ generate a pbuilder environment and build packages within it
+
+``elbe-pkgdiff(1)``
+ compare two root filesystems for differing packages.
+
+``elbe-remove_sign(1)``
+ verify a signed file and remove the signature.
+
+``elbe-setsel(1)``
+ update the packagelist from the output of dpkg-getselections.
+
+``elbe-show(1)``
+ show a textual information about the given XML file.
+
+``elbe-sign(1)``
+ add a signature to the given file.
+
+``elbe-updated(1)``
+ start the Elbe update daemon.
+
+``elbe-validate(1)``
+ validate the given XML file against the Elbe XML Schema.
+
+``elbe-xsdtoasciidoc(1)``
+ create an asciidoc documentation from an annotated XML Schema file
+ (xsd).
+
+.. _`_see_also`:
+
+SEE ALSO
+========
+
+``elbe(1)``
+
+.. _`_elbe`:
+
+ELBE
+====
+
+Part of the ``elbe(1)`` suite
--
2.44.0
More information about the elbe-devel
mailing list