From 1c8eee17499012a1f8b318b502603d37ca01dc13 Mon Sep 17 00:00:00 2001 From: Matthias Stecher Date: Sun, 5 Jul 2020 11:52:34 +0200 Subject: [PATCH] [__lxc_container] Updated manpage (incl. examples, copyright, ..) Should be fine now. --- .../conf/type/__lxc_container/gencode-remote | 2 +- cdist/conf/type/__lxc_container/man.rst | 99 ++++++++++++++++--- 2 files changed, 86 insertions(+), 15 deletions(-) diff --git a/cdist/conf/type/__lxc_container/gencode-remote b/cdist/conf/type/__lxc_container/gencode-remote index 8ee5623b..ef61c66d 100755 --- a/cdist/conf/type/__lxc_container/gencode-remote +++ b/cdist/conf/type/__lxc_container/gencode-remote @@ -105,7 +105,7 @@ USER # check, if the container should be created or cloned if [ -f "$__object/parameter/clone" ]; then copy_from="$(cat "$__object/parameter/clone")" - copypath="$(cat "$__object/parameter/clonepath" || true)" + copypath="$(cat "$__object/parameter/clonepath" 2>/dev/null || true)" # assemble own optional lxc options lxc_opts="" diff --git a/cdist/conf/type/__lxc_container/man.rst b/cdist/conf/type/__lxc_container/man.rst index 547178c5..991c86fb 100644 --- a/cdist/conf/type/__lxc_container/man.rst +++ b/cdist/conf/type/__lxc_container/man.rst @@ -3,16 +3,19 @@ cdist-type__lxc_container(7) NAME ---- -cdist-type__lxc_container - Controls the configuration of a lxc container +cdist-type__lxc_container - Controls the state and configuration of a lxc container DESCRIPTION ----------- -TBA. +This type handles lxc containers. It supports containers from different users and paths. +The state describes if the container exists and is running. The container will be created +with the template or clone parameters if required, whatever is set. These options will +be ignored if the container is already created, as the template script only runs at +creation time. REQUIRED PARAMETERS ------------------- - None. OPTIONAL PARAMETERS @@ -28,17 +31,17 @@ user state The state of the container, if it should exist or not. + present + The container exist, but it is ignored if the container will run or not **(default)** + running - The container exist and is running (default) + The container exist and is running stopped The container exist, but does not run frozen - The container exist and is frozen - - present - The container exist, but it is ignored if the container will run or not + The container exist and is frozen. If it is stopped before, it will be started and then freezed. absent The container does not exist @@ -59,7 +62,6 @@ config-absent BOOLEAN PARAMETERS ------------------ - None. CREATE PARAMETERS @@ -103,6 +105,7 @@ bdev-thinpool TEMPLATE PARAMETERS ------------------- + This or the *CLONE PARAMETERS* are required to create an container and must be present if the container should be created. If the template parameters are choosen, `--template` must be present. Then, none of the *CLONE PARAMETERS* must be present. @@ -119,9 +122,9 @@ template this argument and should exist on the target host. default-config - Alternative path to the user-defined default config. For the root user, this is commonly at - `/etc/lxc/default.conf`. It will be included into the container configuration file at creation - time. + Alternative path to the user-defined default config. This file must exist on the target machine. + For the root user, this is commonly at `/etc/lxc/default.conf`. It will be included into the + container configuration file at creation time. no-default-config **(Boolean value)** This parameter avoids using a default config file by using an empty file instead. @@ -149,13 +152,15 @@ ssh-key CLONE PARAMETERS ---------------- + This or the *TEMPLATE PARAMETERS* are required to create an container and must be present if the container should be created. If the clone parameters are choosen, `--clone` must be present. Then, none of the *TEMPLATE PARAMETERS* must be present. clone Instead of creating a new container with a given template, clone an other container and use him. The - argument takes the container name, which will be cloned. He should exist. + argument takes the container name, which will be cloned. He should exist and must be stopped. Else, + the clone will not work. clonepath The container path for the container to clone. It is like the `--lxcpath` parameter, but for the container @@ -180,7 +185,73 @@ stop Stopped the container. freeze - Freezed all container processes. The container will be started if not yet done to be able to freeze. + Freezed all container processes. The container will be started too if the container is stopped before. melt Unfreezed all container processes. Will be done if any other state (except `present`) should be reached. + +ABORTS +------ +Aborts in the following cases: + +The type aborts if there are incompatible arguments found. This may be *CLONE* and *TEMPLATE PARAMETERS*, +backingstorage parameters for the wrong storage or incompatible template option shortcuts. + +When cloning, it aborts if the container to clone from does not exist or is not stopped with no warning. It +may be possible to clone while the container is running, which requires a backing storage supporting it, but +there is nothing in lxc-copy(1) which indicades something about the container state while cloning. + +EXAMPLES +-------- + +.. code-block:: sh + + # create a container that "just should exist" (does not start the container) + # --template is required if the container needs to be created + __lxc_container foo --template debian + __lxc_container foo --state present --template debian + + # remove the container + __lxc_container bar --state absent + + # container that should definitely running + __lxc_container foobar --state running + # freeze this one + __lxc_container water --state frozen + + # create with some template options + __lxc_container special --state stopped --template debian \ + --release stretch --arch amd64 \ + --template-opts "--packages=foo,bar --flush-cache" + + # clone a container instead of creating it + # foo must be stopped that this will work + __lxc_container foofighters --clone foo --state running + + # handle configuration + __lxc_container peter --state running \ + --config "$__files/lxc/default.conf" \ # content of files are possible + --config "lxc.group = onboot" \ # one lines + --config "lxc.start.auto = 1" \ # spaces around the equal sign are ignored + --config-absent "lxc.group = testing" \ # configuration options can be removed + --config - < + +COPYRIGHT +--------- +Copyright \(C) 2020 Matthias Stecher. 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 3 of the +License, or (at your option) any later version.