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

Radostin Stoyanov rstoyanov1 at gmail.com
Sat Aug 19 13:40:25 UTC 2017


>From 3cd1ab707c03b96ab291957d2e8ecaeb3bc82995 Mon Sep 17 00:00:00 2001
From: Radostin Stoyanov <rstoyanov1 at gmail.com>
Date: Wed, 16 Aug 2017 22:00:38 +0100
Subject: [PATCH] Add man page for virt-bootstrap

---
 MANIFEST.in            |   1 +
 man/virt-bootstrap.pod | 201
+++++++++++++++++++++++++++++++++++++++++++++++++
 setup.py               |  27 +++++++
 3 files changed, 229 insertions(+)
 create mode 100644 man/virt-bootstrap.pod

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..aa5edd4
--- /dev/null
+++ b/man/virt-bootstrap.pod
@@ -0,0 +1,201 @@
+=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
+
+=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 L</--username> argument is specified and L</--password> omitted
+password prompt will be issued. If L</--username> is omitted the
L</--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">
+
+=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={
-- 
2.13.5





More information about the virt-tools-list mailing list