From 211393814a8c997d9f1ca27f86367ea8aace7cec Mon Sep 17 00:00:00 2001 From: Matthias Stecher Date: Sun, 5 Jul 2020 20:15:41 +0200 Subject: [PATCH] [__lxc_container] Updated manpage (completly proof-read it) I think it should be fine now .. :-) --- cdist/conf/type/__lxc_container/man.rst | 116 +++++++++++++----------- 1 file changed, 62 insertions(+), 54 deletions(-) diff --git a/cdist/conf/type/__lxc_container/man.rst b/cdist/conf/type/__lxc_container/man.rst index 991c86fb..d0abf2e2 100644 --- a/cdist/conf/type/__lxc_container/man.rst +++ b/cdist/conf/type/__lxc_container/man.rst @@ -14,6 +14,13 @@ with the template or clone parameters if required, whatever is set. These option be ignored if the container is already created, as the template script only runs at creation time. +The container can be `absent`, which means nothing exists. `present` is the opposite and +completely does not care if the container runs or not. Further states imply that the +container exists. There is `running` and `stopped`, which should be self-explainable. +The state `frozen` means all container processes are frozen. If it moves from `stopped` +to `frozen`, the container will be first started to be frozen. From `frozen` to any other +state, the container will be first unfrozen to continue. + REQUIRED PARAMETERS ------------------- None. @@ -23,13 +30,14 @@ OPTIONAL PARAMETERS name String which will used as container name instead of the object id. This should only required - if multiple lxc instances used from different users/directories (in junction with `--lxcpath`). + if multiple lxc instances used from different users/directories (in junction with ``--user`` + and ``--lxcpath``). user - The unix user name in which lxc commands are executed. Each user have a different lxc instance. + The unix user name with all lxc commands are executed. Each user have a different lxc instance. state - The state of the container, if it should exist or not. + The state of the container, if it should exist or not, and running. present The container exist, but it is ignored if the container will run or not **(default)** @@ -41,23 +49,23 @@ state The container exist, but does not run frozen - The container exist and is frozen. If it is stopped before, it will be started and then freezed. + The container exist and all processes are frozen absent The container does not exist lxcpath Set an other directory as lxc container location instead of the program default. This will passed - to all lxc commands who do smth. with containers. + to all lxc commands. config Contains configuration file paths and/or single configuration lines to assemble the lxc container - configuration file. There is no deep dive into files referenced with `lxc.include`. Can be used + configuration file. There is no deep dive into files referenced with ``lxc.include``. Can be used multiple times. config-absent - Contains configuration file paths and/ro single configuration lines which makes the same as the - `--config` parameter execpt all configuration lines will be removed instead of being added, Can + Contains configuration file paths and/or single configuration lines which makes the same as the + ``--config`` parameter execpt all configuration lines will be removed instead of being added. Can be used multiple times. BOOLEAN PARAMETERS @@ -67,63 +75,63 @@ None. CREATE PARAMETERS ----------------- -This parameters will be used with *TEMPLATE PARAMETERS* or *CLONE PARAMETERS* to create the container +This parameters will be used with **TEMPLATE PARAMETERS** or **CLONE PARAMETERS** to create the container if the container is absent. All of these parameters will only used if the container will be created, in all other cases, these parameters will be ignored. -All backingstore parameters (incl. all bdev-* ones) can be read from the manual lxc-create(1) at option -`--bdev` or lxc-copy(1) at option `--backingstore`. The possibilities may differ from creating and cloning. -The bdev-* parameters are only available for some backingstores. If used for other backingstores, the -type aborts. +All backingstore parameters (incl. all `bdev-*` ones) can be read from the manual lxc-create(1) at option +``--bdev`` or lxc-copy(1) at option ``--backingstore``. The possibilities may differ from creating and +cloning. The `bdev-*` parameters are only available for some backingstores. If used for other backingstores, +the type aborts. backingstore - Set the storage for the container root partition. Commonly, there should be at minimum `dir` (or `none`), - `lvm`, `loop`, `btrfs`, `zfs` or `best` be possible. + Set the storage for the container root filesystem. Commonly, there should be at minimum ``dir`` (or ``none``), + ``lvm``, ``loop``, ``btrfs``, ``zfs`` or ``best`` be possible. bdev-dir Specifies an other path for the rootfs directory instead in the lxc configuration directoy. Only - available for the backingstore `dir` or `none`. + available for the backingstore ``dir`` or ``none``. bdev-fstype Specifies the filesystem to be created instead of the default value. Only available for the - backingstore `lvm` and `loop`. + backingstore ``lvm`` and ``loop``. bdev-fssize Specifies the filesystem size to be created instead of the default value. Only available for the - backingstore `lvm` and `loop`. + backingstore ``lvm`` and ``loop``. bdev-lvname The custom LVM logical volume that will be created for the new container. Only availabe for the - backingstore `lvm`. + backingstore ``lvm``. bdev-vgname - The custon LVM volume group in there the logical volume will be created. Only available for the - backingstore `lvm`. + The custon LVM volume group in where the logical volume will be created. Only available for the + backingstore ``lvm``. bdev-thinpool - The custom thinpool the logical volume will created in. Only available for the backingstore `lvm`. + The custom thinpool the logical volume will created in. Only available for the backingstore ``lvm``. 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. +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. Because the templates vary in the possiblities of arguments and unkown arguments causing the abort of the container creation, the type will throw an error if the compatibility is not garanteed to the given template. -The template options are only applied if the container will be created, there are not applied when -the container is already present. +The template options are only applied if the container will be created. There are not applied if the +container is already present. template - The template which is used to create the the container. The name of the template must passed with + The template which is used to create the the container. The name of the template must passed by this argument and should exist on the target host. default-config - 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 + Alternative path for 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 @@ -131,31 +139,31 @@ no-default-config template-opts Raw options which get passed to the template directly. Can be used multiple times. If the argument - contain spaces, it will be interpreted as multiple arguments and must be escaped for an normal posix - shell if this is not wanted. + contain spaces, it will be interpreted as multiple arguments by the target host and must be escaped + for a normal posix shell if this is not wanted. The following parameters are shortcuts for some template options. As templates may support it or not, you should be careful when using them. You can check all available template options with -`lxc-create -t $template -h` (incl. lxc-create help, too) or `/usr/share/lxc/templates/lxc-$template -h`. +``lxc-create -t $template -h`` (incl. lxc-create help, too) or ``/usr/share/lxc/templates/lxc-$template -h``. release - Sets the release for the wanted distribution. Uses the `-r` option. + Sets the release for the wanted distribution. Uses the ``-r`` option. arch - Sets the architecture used for the creating container. Uses the `-a` option. + Sets the architecture used for the creating container. Uses the ``-a`` option. mirror - Sets the mirror to download from. Uses the `--mirror=` option. + Sets the mirror to download from. Uses the ``--mirror=`` option. ssh-key - Sets the ssh key for the root user- Uses the `-S` option. + Sets the ssh key for the root user. Uses the ``-S`` option. 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. +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 @@ -163,8 +171,8 @@ clone the clone will not work. clonepath - The container path for the container to clone. It is like the `--lxcpath` parameter, but for the container - which will be cloned, not the target container. + The container path for the container to clone from. It is like the ``--lxcpath`` parameter, but for the + container from where will be cloned, not the target container (the container given by ``--clone``). MESSAGES -------- @@ -179,27 +187,27 @@ config The container configuration changed. start - Started the container. + Container was started. stop - Stopped the container. + Container was stopped. freeze - Freezed all container processes. The container will be started too if the container is stopped before. + Freezed all container processes. melt - Unfreezed all container processes. Will be done if any other state (except `present`) should be reached. + Unfreezed all container processes. ABORTS ------ Aborts in the following cases: -The type aborts if there are incompatible arguments found. This may be *CLONE* and *TEMPLATE PARAMETERS*, +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. +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 -------- @@ -221,7 +229,7 @@ EXAMPLES # create with some template options __lxc_container special --state stopped --template debian \ - --release stretch --arch amd64 \ + --release buster --arch amd64 \ --template-opts "--packages=foo,bar --flush-cache" # clone a container instead of creating it @@ -235,9 +243,9 @@ EXAMPLES --config "lxc.start.auto = 1" \ # spaces around the equal sign are ignored --config-absent "lxc.group = testing" \ # configuration options can be removed --config - <