[virt-tools-list] [virt-bootstrap] [PATCH v7 26/26] Add man page for virt-bootstrap

[Cedric Bosdonnat]

On Sat, 2017-08-26 at 21:42 +0100, Radostin Stoyanov wrote:
> ---
>  .gitignore             |   1 +
>  MANIFEST.in            |   1 +
>  man/virt-bootstrap.pod | 217 +++++++++++++++++++++++++++++++++++++++++++++++++
>  setup.py               |  27 ++++++
>  4 files changed, 246 insertions(+)
>  create mode 100644 man/virt-bootstrap.pod
> 
> diff --git a/.gitignore b/.gitignore
> index 1dd4028..be03e22 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -4,3 +4,4 @@
>  dist
>  build
>  *.egg-info
> +*.1
> diff --git a/MANIFEST.in b/MANIFEST.in
> index bd0eb08..61bb7fb 100644
> --- a/MANIFEST.in
> +++ b/MANIFEST.in
> @@ -1,2 +1,3 @@
>  include README.md LICENSE
>  recursive-include src *.py
> +recursive-include man *
> diff --git a/man/virt-bootstrap.pod b/man/virt-bootstrap.pod
> new file mode 100644
> index 0000000..c4e3f20
> --- /dev/null
> +++ b/man/virt-bootstrap.pod
> @@ -0,0 +1,217 @@
> +=encoding utf8
> +
> +=head1 NAME
> +
> +virt-bootstrap - Setup root file system for libvirt-based containers
> +
> +=head1 SYNOPSIS
> +
> +B<virt-bootstrap> URI DEST [OPTIONS]
> +
> +=head1 DESCRIPTION
> +
> +B<virt-bootstrap> is a tool providing an easy way to setup the root
> +file system for libvirt-based containers. It allows to use either a
> +tarball containing the file system, an image on a docker registry
> +or virt-builder template and unpacks it either as a folder or in a
> +
> +=head2 Supported sources are:
> +
> +=over 4
> +
> +=item B<file://F</path/to/rootfs.tar>>
> +
> +Tar archive which contains root file system
> +
> +=item B<docker://I<registry>:I<port>/I<image>:I<tag>>
> +
> +Docker registry
> +
> +=item B<virt-builder://I<template>>
> +
> +virt-builder templates
> +
> +=back
> +
> +Docker container images are downloaded and the layers are getting cached.
> +If virt-bootstrap is running with effective UID=0 (root) the layersq
> +are cached in C</var/cache/virt-bootstrap/docker_images>.
> +For unprivileged users the C<~/.cache/virt-bootstrap/docker_images> directory
> +is used. If the environment variable C<XDG_CACHE_HOME> is specified then this
> +directory is used instead of C<~/.cache>.
> +
> +The environment variable C<VIRTBOOTSTRAP_TMPDIR> can be used to specify
> +temporary directory used by virt-bootstrap or default C</tmp> will be used.
> +
> +=head1 OPTIONS
> +
> +=over 4
> +
> +=item B<-f>, B<--format>
> +
> +Output format of the root file system. Possible values are B<dir>
> +(default) and B<qcow2>.
> +
> +=item B<--root-password> ROOT_PASSWORD
> +
> +This argument will generate hash from B<ROOT_PASSWORD> and insert the
> +hashed value into C</etc/shadow> in the created root file system.
> +
> +If the output format is C<qcow2> these modifications are applied in
> +additional qcow2 disk image.
> +
> +Note that the C</etc/shadow> file must already exist in the extracted
> +root file system of the container image and it must have entry for root
> +user.
> +
> +=item B<--no-cache>
> +
> +When this flag is used Docker images will be downloaded in temporary
> +directory and discarded after the root file system is extracted.
> +
> +=item B<--status-only>
> +
> +If this flag is used the log messages will be suppresses and only information
> +about the current progress will be displayed.
> +
> +=item B<-q>, B<--quiet>
> +
> +Show only warning and error messages.
> +
> +=item B<-d>, B<--debug>
> +
> +Show debugging output messages.
> +
> +=item B<-h>, B<--help>
> +
> +Display command line help summary.
> +
> +=item B<--version>
> +
> +Show virt-bootstrap's version number and exit.
> +
> +=back
> +
> +=head2 Authentication options for accessing private Docker registry
> +
> +Note: If B<--username> argument is specified and B<--password> omitted
> +password prompt will be issued. If B<--username> is omitted the B<--password>
> +argument will be ignored.
> +
> +=over 4
> +
> +=item B<-u>, B<--username> USERNAME
> +
> +   This argument takes USERNAME to be used to access Docker source registry.
> +
> +=item B<-p>, B<--password> PASSWORD
> +
> +This argument takes PASSWORD to be used to access Docker source registry.
> +
> +=item B<--not-secure>
> +
> +Don't require HTTPS and verification of certificates when talking to Docker registry.
> +
> +See L<skopeo(1)/"skopeo copy">
> +
> +=back
> +
> +=head2 UID/GID mapping
> +
> +=over 4
> +
> +=item B<--uidmap> I<start>:I<target>:I<count>
> +
> +Shift UIDs of all root file system entries with some offset. This parameter
> +can be specified multiple times.
> +
> +Example: C<--uidmap 0:1000:10 --uidmap 500:1500:10>
> +This will map the UIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509
> +
> +See L<virt-install(1)/"INSTALLATION OPTIONS">
> +
> +=item B<--gidmap> I<start>:I<target>:I<count>
> +
> +Shift GIDs of all root file system entries with some offset. This parameter
> +can be specified multiple times.
> +
> +Example: C<--gidmap 0:1000:10 --gidmap 500:1500:10>
> +This will map the GIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509
> +
> +See L<virt-install(1)/"INSTALLATION OPTIONS">
> +
> +=item B<--idmap> I<start>:I<target>:I<count>
> +
> +Remapping owner and group of all files and directories inside of the
> +root file system. This parameter can be specified multiple times.
> +
> +Example: C<--idmap 0:1000:10 --idmap 500:1500:10>
> +This will map UIDs and GIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509
> +
> +See L<virt-install(1)/"INSTALLATION OPTIONS">
> +
> +=back
> +
> +=head1 USAGE EXAMPLES
> +
> +=over 4
> +
> +=item Create root file system using Ubuntu image docker.io registry:
> +
> +    $ virt-bootstrap docker://ubuntu /tmp/foo
> +
> +=item Create root file system from image stored on private Docker registry:
> +
> +    $ virt-bootstrap docker://localhost:5000/ubuntu /tmp/foo \
> +      --username testuser \
> +      --password testpassoword \
> +      --not-secure
> +
> +=item Apply UIDs/GIDs mapping for root file system entries
> +
> +    $ virt-bootstrap docker://fedora /tmp/foo \
> +      --idmap 0:1000:10
> +
> +This above command will map UIDs/GIDs: B<0>-B<9> to B<1000>-B<1009>
> +
> +The same result can be achieved with:
> +
> +    $ virt-bootstrap docker://fedora /tmp/foo \
> +      --uidmap 0:1000:10 \
> +      --gidmap 0:1000:10
> +
> +=item Multiple mapping values can be specified as follows:
> +
> +    $ virt_bootstrap.py docker://ubuntu /tmp/foo \
> +      --idmap 0:1000:10 \
> +      --idmap 500:1500:10
> +
> +This will map the UID/GIDs:
> +B<0>-B<9> to B<1000>-B<1009> and B<500>-B<509> to B<1500>-B<1509>
> +
> +=item Set root password
> +
> +    $ virt_bootstrap.py docker://opensuse /tmp/foo \
> +      --root-password secret
> +
> +The above command will download the C<opensuse> container image and
> +extract the root file system to C</tmp/foo>. Then it will generate hash
> +of the string C<secret> and insert it into C</tmp/foo/etc/shadow> file.
> +
> +    $ virt_bootstrap.py docker://opensuse /tmp/foo \
> +      --root-password secret \
> +      -f qcow2
> +
> +Similarly for B<qcow2> format the container image will be downloaded and
> +the root file system will be extracted into qcow2 disk images with backing
> +chains. Then additional qcow2 image will be created with backing file set to
> +the last layer and the modification of C<shadow> file will be applied
> +there.
> +
> +=back
> +
> +=head1 AUTHOR
> +
> +Written by Cedric Bosdonnat and  Radostin Stoyanov
> +
> +=cut
> diff --git a/setup.py b/setup.py
> index 0f617e4..bca9955 100755
> --- a/setup.py
> +++ b/setup.py
> @@ -11,6 +11,7 @@ import os
>  import sys
>  import subprocess
>  import setuptools
> +from setuptools.command.install import install
>  
>  # pylint: disable=import-error, wrong-import-position
>  sys.path.insert(0, 'src')  # noqa: E402
> @@ -26,6 +27,27 @@ def read(fname):
>          return fobj.read()
>  
>  
> +class PostInstallCommand(install):
> +    """
> +    Post-installation commands.
> +    """
> +    def run(self):
> +        """
> +        Post install script
> +        """
> +        cmd = [
> +            'pod2man',
> +            '--center=Container bootstrapping tool',
> +            '--name=VIRT-BOOTSTRAP',
> +            '--release=%s' % virtBootstrap.__version__,
> +            'man/virt-bootstrap.pod',
> +            'man/virt-bootstrap.1'
> +        ]
> +        if subprocess.call(cmd) != 0:
> +            raise RuntimeError("Building man pages has failed")
> +        install.run(self)
> +
> +
>  class CheckPylint(setuptools.Command):
>      """
>      Check python source files with pylint and pycodestyle.
> @@ -114,9 +136,14 @@ setuptools.setup(
>  
>      ],
>      cmdclass={
> +        'install': PostInstallCommand,
>          'pylint': CheckPylint
>      },
>  
> +    data_files=[
> +        ("share/man/man1", ['man/virt-bootstrap.1'])
> +    ],
> +
>      tests_require=['mock>=2.0'],
>  
>      extras_require={

Looks much better, ACK
--
Cedric