New containers are created from templates. A template is simply a tar archive or a ZFS stream, which is extracted and used as the container's root filesystem. When creating a new container, the user selects the template to be used. Templates can be downloaded from remote repository or the local filesystem.

Templates are described by several parameters:

  • vendor - the template provider, e.g. vpsadminos
  • variant - content description, e.g. minimal
  • arch - x86_64, x86 and so on
  • distribution - debian, ubuntu and so on
  • version - distribution version

To create a new container, osctld needs to know arch, distribution and version. vendor and variant are used just to describe the template, osctld is not using it in any way.

Naming scheme

A template is described either by its parameters, or its name in a special format, which includes all required parameters in it.

The naming format is: <distribution>-<version>-<arch>[-<vendor>[-<variant>]].{dat,tar}.gz

dat.gz is used for ZFS streams, tar.gz for tarballs.

Creating containers

There are several ways to select a template when creating a new container. To download the template from a repository, you can:

  • browse repositories and select the template interactively
  • provide template parameters
  • provide template name

To use template from a local file, the file must either conform to the naming scheme, or the required template parameters have to be provided as options.

Available templates

Templates from remote repositories can be listed with osctl repo templates ls:

[root@vpsadminos:~]# osctl repo templates ls default
vpsadminos   minimal   x86_64   alpine         3.6             -               -      
vpsadminos   minimal   x86_64   alpine         3.7             -               -      
vpsadminos   minimal   x86_64   arch           20180221        -               -      
vpsadminos   minimal   x86_64   centos         7.0             -               -      
vpsadminos   minimal   x86_64   debian         8.0             -               -      
vpsadminos   minimal   x86_64   debian         9.0             latest,stable   -      
vpsadminos   minimal   x86_64   devuan         1.0             -               -      
vpsadminos   minimal   x86_64   gentoo         17.0-20180221   -               -      
vpsadminos   minimal   x86_64   slackware      14.2            -               -      
vpsadminos   minimal   x86_64   ubuntu         14.04           -               -      
vpsadminos   minimal   x86_64   ubuntu         16.04           -               -      
vpsadminos   minimal   x86_64   arch           20180222        latest          -      
vpsadminos   minimal   x86_64   ubuntu         18.04           -               -      
vpsadminos   minimal   x86_64   centos         7.4             stable,latest   -      
vpsadminos   minimal   x86_64   fedora         27              -               -      
vpsadminos   minimal   x86_64   fedora         28              latest,stable   -


When osctl ct new is run without any options, osctl will interactively ask the user to select a template from one of the configured remote repositories:

osctl ct new --user myuser01 myct01

Creating containers from repository templates can be automated by passing the template parameters as command-line options:

osctl ct new --user myuser01 --distribution debian --version 9.0 --arch x86_64 myct01

In this case, vendor and variant have not been specified, thus the default values from the repository will be used. One can also use option --template, which describes the desired template using the naming scheme, with a slightly modified form: <distribution>[-<version>[-<arch>[-<vendor>[-<variant>]]]].

Only distribution is required, version defaults to stable tag, arch to uname -m, vendor and variant to default.

osctl ct new --user myuser01 --template debian-9.0-x86_64 myct01

To use template from a local file, use --from-archive or --from-stream, depending on file type:

osctl ct new --user myuser01 --from-archive debian-9.0-x86_64-vpsadminos-minimal.tar.gz myct01
osctl ct new --user myuser01 --from-stream debian-9.0-x86_64-vpsadminos-minimal.tar.gz myct01

If the file does not follow the naming scheme, specify the required options --distribution, --version and --arch.

Creating templates

vpsAdminOS templates are generated by a collection of scripts at vpsadminos-templates. Read the information in its README file.

Repository management

osctld is downloading pre-built container templates from remote repositories over HTTP. The default repository is https://templates.vpsadminos.org. You can manage active repositories using osctl.

osctl repo ls
osctl repo add myrepo https://repo.domain.tld
osctl repo del myrepo

Note that repositories are configured per-pool. When no pool is specified, the default pool is configured. For example, to add repository to a non-default pool, you could use:

osctl --pool mypool repo add myrepo  https://repo.domain.tld

Creating a repository

vpsAdminOS comes with a tool for creating and maintaining template repositories called osctl-repo. osctl-repo creates a directory structure according to the repository scheme. osctl-repo is not building the templates, it only accepts pre-built templates and places them into the repository, ready to be served to clients by your web server.

osctl-repo is distributed as a Ruby gem:

gem install --source https://rubygems.vpsfree.cz --prerelease osctl-repo libosctl

To create a repository, you have to prepare a directory that is served by a web server. Let's put the repository in /var/www/vpsadminos-repo. Configure your web server to serve this directory, then cd into it and initiate the repository:

cd /var/www/vpsadminos-repo
osctl-repo local init

Templates can then be added using osctl-repo local add:

osctl-repo local add --archive debian.tar.gz --zfs debian.dat.gz vpsadminos minimal x86_64 debian 9.0

Default vendor and variant can be set with:

# Set vendor `vpsadminos` as default
osctl-repo local default vpsadminos

# Set variant `minimal` of vendor `vpsadminos` as default
osctl-repo local default vpsadminos minimal

Accessing repository

osctld is accessing the repository on its own, so you don't have to read this section unless you wish to understand how it works.

osctl-repo is also used to access repositories, i.e. download templates from remote repositories and optionally cache them in a local directory. All client commands work with remote repositories, so you always have to provide the repository's URL as an argument.

To list available templates, use command remote ls:

osctl-repo remote ls https://repo.domain.tld

Templates can be downloaded using command remote get, which will fetch the template and write its contents to standard output:

osctl-repo remote get https://repo.domain.tld \
                      vpsadminos minimal x86_64 debian 9.0 archive \
                      > debian-9.0-x86_64-vpsadminos-minimal.dat.gz

If option --cache <writable directory> is provided, the template will be saved in the cache directory. Subsequent calls of osctl-repo remote get with the same cache directory will use the local version, unless the repository has a newer version.

If you only wish to cache the selected template, use osctl-repo fetch:

osctl-repo remote fetch --cache /var/vpsadminos-templates \
                        https://repo.domain.tld \
                        vpsadminos minimal x86_64 debian 9.0 zfs