1. Manuals
  2. Tumbleweed
  3. python3-virt-bootstrap
  4. virt-bootstrap(1)

Scroll to navigation

VIRT-BOOTSTRAP(1) Container bootstrapping tool VIRT-BOOTSTRAP(1)

NAME

virt-bootstrap - Setup root file system for libvirt-based containers

SYNOPSIS

virt-bootstrap URI DEST [OPTIONS]

DESCRIPTION

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

Supported sources are:

file:///path/to/rootfs.tar
Tar archive which contains root file system
docker://registry:port/image:tag
Docker registry
builder://template
virt-builder templates

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 "/var/cache/virt-bootstrap/docker_images". For unprivileged users the "~/.cache/virt-bootstrap/docker_images" directory is used. If the environment variable "XDG_CACHE_HOME" is specified then this directory is used instead of "~/.cache".

The environment variable "VIRTBOOTSTRAP_TMPDIR" can be used to specify temporary directory used by virt-bootstrap or default "/tmp" will be used.

OPTIONS

Output format of the root file system. Possible values are dir (default) and qcow2.
This argument will generate hash from ROOT_PASSWORD, gotten from the SELECTOR field, and insert the hashed value into "/etc/shadow" in the created root file system.

Note that SELECTOR can be one of the following: "file:".

If the output format is "qcow2" these modifications are applied in additional qcow2 disk image.

Note that the "/etc/shadow" file must already exist in the extracted root file system of the container image and it must have entry for root user.

When this flag is used Docker images will be downloaded in temporary directory and discarded after the root file system is extracted.
If this flag is used the log messages will be suppresses and only information about the current progress will be displayed.
Show only warning and error messages.
Show debugging output messages.
Display command line help summary.
Show virt-bootstrap's version number and exit.

Authentication options for accessing private Docker registry

Note: If --username argument is specified and --password omitted password prompt will be issued. If --username is omitted the --password argument will be ignored.

   This argument takes USERNAME to be used to access Docker source registry.
This argument takes PASSWORD to be used to access Docker source registry.
Don't require HTTPS and verification of certificates when talking to Docker registry.

See "skopeo copy" in skopeo(1)

UID/GID mapping

Shift UIDs of all root file system entries with some offset. This parameter can be specified multiple times.

Example: "--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 "INSTALLATION OPTIONS" in virt-install(1)

Shift GIDs of all root file system entries with some offset. This parameter can be specified multiple times.

Example: "--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 "INSTALLATION OPTIONS" in virt-install(1)

Remapping owner and group of all files and directories inside of the root file system. This parameter can be specified multiple times.

Example: "--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 "INSTALLATION OPTIONS" in virt-install(1)

USAGE EXAMPLES

    $ virt-bootstrap docker://ubuntu /tmp/foo
    
    $ virt-bootstrap docker://localhost:5000/ubuntu /tmp/foo \
      --username testuser \
      --password testpassoword \
      --not-secure
    
    $ virt-bootstrap docker://fedora /tmp/foo \
      --idmap 0:1000:10

This above command will map UIDs/GIDs: 0-9 to 1000-1009

The same result can be achieved with:

    $ virt-bootstrap docker://fedora /tmp/foo \
      --uidmap 0:1000:10 \
      --gidmap 0:1000:10
    
    $ virt_bootstrap.py docker://ubuntu /tmp/foo \
      --idmap 0:1000:10 \
      --idmap 500:1500:10

This will map the UID/GIDs: 0-9 to 1000-1009 and 500-509 to 1500-1509

    $ virt_bootstrap.py docker://opensuse /tmp/foo \
      --root-password file:/tmp/secret

The above command will download the "opensuse" container image and extract the root file system to "/tmp/foo". Then it will generate hash of the password present in "/tmp/secret" file and insert it into "/tmp/foo/etc/shadow" file.

    $ virt_bootstrap.py docker://opensuse /tmp/foo \
      --root-password file:/tmp/secret \
      -f qcow2

Similarly for 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 "shadow" file will be applied there.

AUTHOR

Written by Cedric Bosdonnat and Radostin Stoyanov

2023-06-19 1.1.1