__lxc_container: updated todo.txt about type splitting

Because it will get a mess when adding every option to __lxc_container
..

cdist/conf/type/__lxc_container/diff-conf-changes.sh

@@ -0,0 +1,85 @@
+#!/bin/sh -e
+# diff-conf-changes.sh
+
+# This script handles the configuration given to the type. It will be diffed against the existing
+# container options and write the "to be done"-options to a separate file.
+#
+# Output files in "$__object/files/" :
+#  - config-{present,absent}
+#  - config.add
+#  - config.del
+
+
+# Function to read multiple parameter input for configuration and print it to a single file.
+# It will handle file paths as well as the stdin. Instead of the file, the content will be printed.
+#
+# Parameters:
+#  1: parameter name
+#  2: file to print
+write_multi_param() {
+    if ! [ -f "$__object/parameter/$1" ]; then return 0; fi
+
+    while read -r line; do
+        if [ "$line" = "-" ]; then
+            # append stdin
+            cat "$__object/stdin"
+        elif [ -f "$line" ]; then
+            # append file content
+            cat "$line"
+        else
+            # print out content
+            printf "%s\n" "$line"
+        fi
+    done < "$__object/parameter/$1"
+}
+
+# Function to get rid of whitespaces inside of key-value pairs. It will clear all of these.
+#
+# Parameters:
+#  1: the file which should be handled
+trimm_whitespaces() {
+    mv "$1" "$1"~  # backup file to read write back original file
+    grep -E -v "^([[:blank:]]*)(#|$)" "$1"~ \
+        | sed 's/^[[:blank:]]*//; s/[[:blank:]]*=[[:blank:]]*/ = /; s/[[:blank:]]*$//' \
+        > "$1"
+    rm -f "$1"~
+}
+
+
+# save states
+state_should="$(cat "$__object/parameter/state")"
+state_is="$(cat "$__object/explorer/state")"
+
+# Only required if container will not be absent
+# prepare the wanted configuration lines
+if [ "$state_should" != "absent" ]; then
+    # create the files directory
+    mkdir "$__object/files/"
+
+    # Summary of the locally given configuration options
+    # config-present
+    conffile="$__object/files/config-present"
+    write_multi_param config > "$conffile"
+    trimm_whitespaces "$conffile"
+    # config-absent
+    absentfile="$__object/files/config-absent"
+    write_multi_param config-absent > "$absentfile"
+    trimm_whitespaces "$absentfile"
+
+    # Diff the configuration options by removing duplicate config options
+    # config.add
+    grep -v -f "$__object/explorer/config" -f "$__object/files/config-absent" \
+        "$__object/files/config-present" > "$__object/files/config.add" || true
+    # config.del
+    grep -f "$__object/explorer/config" \
+        "$__object/files/config-absent" > "$__object/files/config.del" || true
+
+
+    # fallback: if template parameter exists and container currently absent; try to remove all configs
+    #  If the container is currently absent, nothing will be removed, even it's in the default config
+    #  In this case, it will try to delete every configuration option to be sure
+    # only the cloning configuration is known, but not if the container will be created in an other way
+    if [ "$state_is" = "absent" ] && ! [ -f "$__object/parameter/clone" ]; then
+        cp "$__object/files/config-absent" "$__object/files/config.del"
+    fi
+fi

cdist/conf/type/__lxc_container/explorer/config

@@ -0,0 +1,50 @@
+#!/bin/sh -e
+# explorer/config
+
+# Prints out the current container configuration (if required). This makes
+# it easy to differ changes.
+
+# abort if container will be absent - no config required
+if [ "$(cat "$__object/parameter/state")" = "absent" ]; then
+    exit 0
+fi
+
+
+# read the lxcpath (reusing explorer)
+lxcpath="$( "$__type_explorer/lxcpath" )"
+
+# get name
+name="$__object/parameter/name"
+if [ -f "$name" ]; then
+    name="$(cat "$name")"
+else
+    name="$__object_id"
+fi
+
+
+# if the container will be cloned, use the configuration of the container to clone from
+# else, just use the normal container configuration
+clone="$__object/parameter/clone"
+if [ -f "$clone" ] && [ "$("$__type_explorer/state")" = "absent" ]; then
+    clone="$(cat "$clone")"
+    clonepath="$__object/parameter/clonepath"
+    if [ -f "$clonepath" ]; then
+        clonepath="$(cat "$clonepath")"
+    else
+        clonepath="$lxcpath"
+    fi
+
+    # set the config path of the container to clone from
+    config="$clonepath/$clone/config"
+else
+    # assemble the configuration file of the container
+    config="$lxcpath/$name/config"
+fi
+
+# check if the file exist, else the container is absent
+if [ -r "$config" ]; then
+    # print configuration and strip files to just values
+    #  grep will hide all comments and empty lines - all others must be key-values
+    #  sed will uniform patterns, that no spaces will be problematic (before, in the middle and at end)
+    grep -E -v "^([[:blank:]]*)(#|$)" "$config" | sed 's/^[[:blank:]]*//; s/[[:blank:]]*=[[:blank:]]*/ = /; s/[[:blank:]]*$//'
+fi

cdist/conf/type/__lxc_container/explorer/lxcpath

@@ -0,0 +1,23 @@
+#!/bin/sh -e
+# explorer/lxcpath
+
+# Echos the lxcpath variable for all container instances
+
+# get parameter if exist
+lxcpath="$(cat "$__object/parameter/lxcpath" 2>/dev/null || true)"
+
+
+# lxcpath parameter
+if [ -z "$lxcpath" ]; then
+    user="$(cat "$__object/parameter/user")"
+
+    # gather default value from config
+    if [ "$user" != "$USER" ]; then
+        su -s "$(which -- lxc-config)" -- "$user" lxc.lxcpath
+    else
+        lxc-config lxc.lxcpath
+    fi
+else
+    # output the parameter
+    echo "$lxcpath"
+fi

cdist/conf/type/__lxc_container/explorer/state

@@ -0,0 +1,45 @@
+#!/bin/sh -e
+# explorer/state
+
+# Outputs if the container exist
+#  possible values: present || absent || running || stopped || frozen
+
+# general parameters
+name="$__object/parameter/name"
+if [ -f "$name" ]; then
+    name="$(cat "$name")"
+else
+    name="$__object_id"
+fi
+user="$(cat "$__object/parameter/user")"
+
+# lxcpath
+lxcpath="$(cat "$__object/parameter/lxcpath" 2>/dev/null || true)"
+
+# assemble optional parameters
+LXC_PARAM=""
+if [ "$lxcpath" ]; then
+    # shellcheck disable=SC2089
+    LXC_PARAM="$LXC_PARAM -P \"$lxcpath\""
+fi
+
+
+# function to get information
+lxc_info() {
+    # shellcheck disable=SC2090 disable=SC2086
+    if [ "$user" != "$USER" ]; then
+        su -s "$(which -- lxc-info)" -- "$user" $LXC_PARAM -n "$name" -H "$@"
+    else
+        lxc-info $LXC_PARAM -n "$name" -H "$@"
+    fi
+}
+
+
+# the lxc-info command will exit non-zero if container not exist
+if ! lxc_info -S >/dev/null 2>&1; then
+    # not exist
+    echo "absent"
+else
+    # print state (command output matches to type states)
+    lxc_info -s | tr '[:upper:]' '[:lower:]'
+fi

cdist/conf/type/__lxc_container/gencode-remote

@@ -0,0 +1,371 @@
+#!/bin/sh -e
+# gencode-remote
+
+# Does all common stuff for the container on the host
+#
+# Following stages need to be observed when executing this type
+#  1. Container creation IF $state_is = absent
+#  2. patching container config IF NOT $state_should = absent
+#  3. look after runstates (running,frozen,stopped)
+#  4. Container destruction IF $state_should = absent
+#
+# It is only required if:
+#  - $state_is != $state_should
+#  - config changed (detects if changes are uploaded)
+
+
+# Parameter gathering
+name="$__object/parameter/name"
+if [ -f "$name" ]; then
+    name="$(cat "$name")"
+else
+    name="$__object_id"
+fi
+user="$(cat "$__object/parameter/user")"
+
+# check both states
+state_is="$(cat "$__object/explorer/state")"
+state_should="$(cat "$__object/parameter/state")"
+
+# general lxc things
+lxcpath="$(cat "$__object/parameter/lxcpath" 2>/dev/null || true)"
+
+
+# Summerize common parameter arguments, listed in manual as "COMMON OPTIONS"
+#  will passed raw; must qouted manually
+LXC_PARAM=""
+
+# if lxcpath given
+if [ -n "$lxcpath" ]; then
+    LXC_PARAM="$LXC_PARAM -P \"$lxcpath\""
+fi
+
+
+# shortcut for checking config changes
+# returns success (0) if there are changes
+config_changes() {
+    if [ -s "$__object/files/config.add" ] || [ -s "$__object/files/config.del" ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# shortcut to add bdev parameters if available
+#  $1: $__object parameter name without "bdev-"
+#  $2: target parameter flag (like --foo), else "--$1" will be used
+bdev_add_if_available() {
+    _param_path="$__object/parameter/bdev-$1"
+    if [ -f "$_param_path" ]; then
+        backingstore_opts="$backingstore_opts ${2:---$1} '$(cat "$_param_path")'"
+    fi
+}
+
+# shortcut to add template parameters if available
+#  $1: $__object parameter
+#  $2: target parameter flag (like --foo), else "--$1" will be used
+template_add_if_available() {
+    _param_path="$__object/parameter/$1"
+    if [ -f "$_param_path" ]; then
+        template_opts="$template_opts ${2:---$1} '$(cat "$_param_path")'"
+    fi
+}
+
+
+# Generate configuration diff files
+"$__type"/diff-conf-changes.sh
+
+# Short curcit if nothing changed
+if [ "$state_is" = "$state_should" ] && ( ! config_changes ); then exit; fi
+
+
+# handle if the container should exist or not
+case "$state_should" in
+    # all states where the container should exist
+    present|running|stopped|frozen)
+        # only relevant if the container does not exist before
+        if [ "$state_is" = "absent" ]; then
+            # change privileges (too complex to make exceptions)
+            cat <<USER
+su "$user" - <<SU
+USER
+
+            # backingstore options
+            backingstore_opts=""
+            if [ -f "$__object/parameter/backingstore" ]; then
+                # -B works for both types, they have different long opts
+                backingstore_opts="$backingstore_opts -B '$(cat "$__object/parameter/backingstore")'"
+
+                # add parameters if available
+                bdev_add_if_available dir
+                bdev_add_if_available fstype
+                bdev_add_if_available fssize
+                bdev_add_if_available lvname
+                bdev_add_if_available vgname
+                bdev_add_if_available thinpool
+            fi
+
+            # 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" 2>/dev/null || true)"
+
+                # assemble own optional lxc options
+                lxc_opts=""
+                if [ -n "$copypath" ]; then
+                    # this is set as the default $lxcpath, because it is the origin
+                    lxc_opts="$lxc_opts -P \"$copypath\""
+                fi
+                if [ -n "$lxcpath" ]; then
+                    # this is set as the newpath, because it is the destination
+                    lxc_opts="$lxc_opts -p \"$lxcpath\""
+                fi
+
+                # print lxc-copy code (because of the lxcpath thing, $LXC_PARAM conflicts)
+                cat <<LXC
+lxc-copy $lxc_opts $backingstore_opts -n "$copy_from" --newname "$name"
+LXC
+            else
+                template="$(cat "$__object/parameter/template")"
+
+                # assemble general creation options
+                create_opts=""
+                if [ -f "$__object/parameter/no-default-config" ]; then
+                    # generate a random empty file and append
+                    # maybe work with an nonexistant file - but just be correct
+                    cat <<TMPFILE
+empty_conf="\$(mktemp "\${TMPDIR:-/tmp}/cdist__lxc_container-empty-conf.XXXXXXXXXX")"
+TMPFILE
+                    create_opts="$create_opts -f \"\$empty_conf\""
+
+                elif [ -f "$__object/parameter/default-config" ]; then
+                    # append the configuration
+                    create_opts="$create_opts -f \"$(cat "$__object/parameter/default-config")\""
+                fi
+
+                # assemble template options
+                template_opts=""
+                # add common options (may require different options for different templates)
+                template_add_if_available release -r
+                template_add_if_available arch -a
+                if [ -f "$__object/parameter/mirror" ]; then
+                    template_opts="$template_opts --mirror='$(cat "$__object/parameter/mirror")'"
+                fi
+                template_add_if_available ssh-key -S
+
+                # at last, apply custom options
+                if [ -f "$__object/parameter/template-opts" ]; then
+                    while read -r line; do
+                        template_opts="$template_opts $line"
+                    done < "$__object/parameter/template-opts"
+                fi
+
+                # print lxc-create code
+                cat <<LXC
+lxc-create $LXC_PARAM $backingstore_opts -n "$name" -t "$template" $create_opts -- $template_opts
+LXC
+
+                # remove empty tempfile if it was created
+                if [ -f "$__object/parameter/no-default-config" ]; then
+                    cat <<RM
+rm -f "\$empty_conf"
+RM
+                fi
+            fi
+
+            # end of su here-document
+            echo "SU"
+
+            # write to the message system
+            echo "create" >> "$__messages_out"
+        fi
+        ;;
+
+
+    # list other states to get a correct error message in the wildcard case
+    absent)
+        ;;
+
+    # error handling: invalid state
+    *)
+        printf "Container '%s' in unknown state %s\n" "$name" "$state_should" >&2
+        exit 2
+        ;;
+esac
+
+
+# Check the configurations only if the container exists and there are changes
+if config_changes; then
+    # generate config path
+    container_config="$(cat "$__object/explorer/lxcpath")/$name/config"
+    # create remote tmpfile for config
+    cat <<DONE
+tmpconfig="\$(mktemp "$container_config.XXXXXXXXXX")"
+cp -p "$container_config" "\$tmpconfig"
+DONE
+
+    # check if smth. to be deleted
+    #  must be before adding, because it takes the content of the original file
+    #  because 'cat $file > $file' will not work (> opens before command reads it)
+    # will create a basic regex pattern for grep to ignore malformed spaces
+    if [ -s "$__object/files/config.del" ]; then
+        cat <<DONE
+grep -v -f - <<'ABSENT' "$container_config" > "\$tmpconfig"
+$(awk -v FS=' = ' -v OFS=' = ' -v blank='[[:blank:]]*' '
+function ntostring(n) { ret=""; for(i=n; i<=NF; i++) ret=ret $i (i<NF ? OFS : ""); return ret }
+{ printf "^%s%s%s=%s%s%s$%s", blank, $1, blank, blank, ntostring(2), blank, ORS }
+    ' "$__object/files/config.del" )
+ABSENT
+DONE
+    fi
+
+    # check if smth. to be added
+    if [ -s "$__object/files/config.add" ]; then
+        cat <<DONE
+cat <<'PRESENT' >> "\$tmpconfig"
+$(cat "$__object/files/config.add")
+PRESENT
+DONE
+    fi
+
+
+    # apply all changes
+    cat <<DONE
+rm -f "$container_config"
+mv "\$tmpconfig" "$container_config"
+DONE
+    echo "config" >> "$__messages_out"
+
+
+    # restart container only if it is running
+    #  do not echo messages start/stop or melt/start/stop/freeze; only restart to avoid junk
+    case "$state_is" in
+        running|frozen)
+            # only do it if the container will run again
+            case "$state_should" in
+                present|running|frozen)
+                    # su stuff
+                    cat <<USER
+su "$user" - <<SU
+USER
+
+                    # unfreeze if required
+                    if [ "$state_is" = "frozen" ]; then
+                        cat <<LXC
+lxc-unfreeze $LXC_PARAM -n "$name"
+LXC
+                    fi
+
+                    # stop and start
+                    cat <<LXC
+lxc-stop $LXC_PARAM -n "$name"
+lxc-start $LXC_PARAM -n "$name"
+LXC
+
+                    # freeze it again if it was there before, but be clever
+                    # if $state_is = running but should be frozen, later code will do that
+                    if [ "$state_is" = "frozen" ]; then
+                        if [ "$state_should" = "frozen" ] || [ "$state_should" = "present" ]; then
+                            cat <<LXC
+lxc-freeze $LXC_PARAM -n "$name"
+LXC
+                        else
+                            # correct current state
+                            state_is="running"
+                            echo "melt" >> "$__messages_out"
+                        fi
+                    fi
+
+                    # ending
+                    echo "restart" >> "$__messages_out"
+                    echo "SU"
+                ;;
+            esac
+            ;;
+    esac
+fi
+
+
+# Check if there is a difference within the states
+if [ "$state_is" != "$state_should" ] && [ "$state_should" != "present" ]; then
+    # change privileges (too complex to make exceptions)
+    cat <<USER
+su "$user" - <<SU
+USER
+
+    # unfreeze if nessecary to change state
+    if [ "$state_is" = "frozen" ]; then
+        cat <<LXC
+lxc-unfreeze $LXC_PARAM -n "$name"
+LXC
+        echo "melt" >> "$__messages_out"
+    fi
+
+    # handle if the container should exist or not
+    case "$state_should" in
+        running)
+            # already running if unfreezed
+            if [ "$state_is" != "frozen" ]; then
+                cat <<LXC
+lxc-start $LXC_PARAM -n "$name"
+LXC
+                echo "start" >> "$__messages_out"
+            fi
+            ;;
+
+        # stop the container if it should be removed
+        stopped)
+            cat <<LXC
+lxc-stop $LXC_PARAM -n "$name"
+LXC
+            echo "stop" >> "$__messages_out"
+            ;;
+
+        # container should be stopped if not already done
+        absent)
+            if [ "$state_is" != "stopped" ]; then
+                cat <<LXC
+lxc-stop $LXC_PARAM -n "$name"
+LXC
+            fi
+            ;;
+
+        frozen)
+            # stopped containers can't be frozen; they must be started first
+            if [ "$state_is" = "stopped" ] || [ "$state_is" = "absent" ]; then
+                cat <<LXC
+lxc-start $LXC_PARAM -n "$name"
+LXC
+                echo "start" >> "$__messages_out"
+            fi
+            cat <<LXC
+lxc-freeze $LXC_PARAM -n "$name"
+LXC
+            echo "freeze" >> "$__messages_out"
+            ;;
+
+        *)
+            # must be checked by previous case
+            ;;
+    esac
+
+    # end of su here-document
+    echo "SU"
+fi
+
+
+# Check if the container needs to be removed
+if [ "$state_should" = "absent" ]; then
+    # change privileges (too complex to make exceptions)
+    # then, shutdown and delete the container
+    #  we could force-delete, but better be polite
+    #  snapshots are deleted, too - to keep everything clean. May someone does not want it?
+    cat <<USER
+su "$user" - <<SU
+lxc-destroy $LXC_PARAM --snapshots -n "$name"
+SU
+USER
+
+    # write to the message system
+    echo "destroy" >> "$__messages_out"
+fi

cdist/conf/type/__lxc_container/man.rst

@@ -0,0 +1,269 @@
+cdist-type__lxc_container(7)
+============================
+
+NAME
+----
+cdist-type__lxc_container - Controls the state and configuration of a lxc container
+
+DESCRIPTION
+-----------
+
+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.
+
+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.
+
+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 ``--user``
+    and ``--lxcpath``).
+
+user
+    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, and running.
+
+    present
+        The container exist, but it is ignored if the container will run or not **(default)**
+
+    running
+        The container exist and is running
+
+    stopped
+        The container exist, but does not run
+
+    frozen
+        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.
+
+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
+    multiple times.
+
+config-absent
+    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
+------------------
+
+restart-if-changed
+    Restarts the container if configuration changes. It stop and start the container that new configuration
+    can be applied. If it whould be restarted with ``lxc-stop -n $name --reboot``, configuration changes
+    would be ignored.
+
+CREATE PARAMETERS
+-----------------
+
+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.
+
+backingstore
+    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``.
+
+bdev-fstype
+    Specifies the filesystem to be created instead of the default value. Only available for the
+    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``.
+
+bdev-lvname
+    The custom LVM logical volume that will be created for the new container. Only availabe for the
+    backingstore ``lvm``.
+
+bdev-vgname
+    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``.
+
+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.
+
+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 if the
+container is already present.
+
+template
+    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 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
+    **(Boolean value)** This parameter avoids using a default config file by using an empty file instead.
+
+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 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``.
+
+release
+    Sets the release for the wanted distribution. Uses the ``-r`` option.
+
+arch
+    Sets the architecture used for the creating container. Uses the ``-a`` option.
+
+mirror
+    Sets the mirror to download from. Uses the ``--mirror=`` option.
+
+ssh-key
+    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.
+
+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 and must be stopped. Else,
+    the clone will not work.
+
+clonepath
+    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
+--------
+
+create
+    The container was created by a template or clone.
+
+destroy
+    The container was destroyed.
+
+config
+    The container configuration changed.
+
+start
+    Container was started.
+
+stop
+    Container was stopped.
+
+freeze
+    Freezed all container processes.
+
+melt
+    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**,
+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 buster --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 - <<ABSENT                     # stdin can be read once
+    lxc.group = dev
+    lxc.group = foobar
+    ABSENT
+
+    # some more configuration
+    # configuration lookup does not go deeper to included files
+    __lxc_container dieter --state stopped \
+        --config "lxc.include = /etc/lxc/some-config.conf"
+        --config-absent "lxc.start.auto = 1"
+
+AUTHORS
+-------
+Matthias Stecher <matthiasstecher at gmx.de>
+
+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.

cdist/conf/type/__lxc_container/manifest

@@ -0,0 +1,78 @@
+#!/bin/sh -e
+# manifest
+
+# Manifest; check if everything is valid
+
+# Exit codes:
+#  0: successful or warnings
+#  2: parameters in wrong context given
+
+# basepath of the parameter folder (shortcut)
+param="$__object/parameter/"
+
+
+# ==================== #
+# ==  ERROR CHECKS  == #
+# ==================== #
+
+# valid check if only --template or --clone given
+if [ -f "$param/template" ] && [ -f "$param/clone" ]; then
+    # error and exit
+    >&2 echo "error: can not create and clone a container at once!"
+    >&2 echo "error: --template and --clone can not work together"
+    exit 2
+fi
+
+# no clone option if --template given
+if [ -f "$param/template" ]; then
+    if [ -f "$param/clonepath" ]
+    then
+        >&2 echo "error: container will created by template, no clone options required!"
+        exit 2
+    fi
+fi
+
+# no template options if --clone given
+if [ -f "$param/clone" ]; then
+    if [ -f "$param/template-opts" ] \
+        || [ -f "$param/default-config" ] \
+        || [ -f "$param/no-default-config" ] \
+        || [ -f "$param/release" ] \
+        || [ -f "$param/arch" ]
+    then
+        >&2 echo "error: container will created by clone, no template options required!"
+        exit 2
+    fi
+fi
+
+# check backingstore values
+if [ -f "$param/backingstore" ]; then
+    backingstore="$(cat "$param/backingstore")"
+
+    if [ "$backingstore" != "dir" ] && [ "$backingstore" != "none" ]; then
+        if [ -f "$param/bdev-dir" ]
+        then
+            >&2 echo "error: --bdev-dir is only possible for backingstore 'dir' or 'none'"
+            exit 2
+        fi
+    fi
+
+    if [ "$backingstore" != "lvm" ] && [ "$backingstore" != "loop" ]; then
+        if [ -f "$param/bdev-fstype" ] \
+            || [ -f "$param/bdev-fssize" ]
+        then
+            >&2 echo "error: --bdev-fstype and --bdev-fssize only available for backingstore 'lvm' or 'loop'"
+            exit 2
+        fi
+    fi
+
+    if [ "$backingstore" != "lvm" ]; then
+        if [ -f "$param/bdev-lvname" ] \
+            || [ -f "$param/bdev-vgname" ] \
+            || [ -f "$param/bdev-thinpool" ]
+        then
+            >&2 echo "error: --bdev-{lv,vg}name and --bdev-thinpool only available for backingstore 'lvm'"
+            exit 2
+        fi
+    fi
+fi

cdist/conf/type/__lxc_container/parameter/boolean

@@ -0,0 +1,2 @@
+no-default-config
+restart-if-changed

cdist/conf/type/__lxc_container/parameter/default/state

@@ -0,0 +1 @@
+present

cdist/conf/type/__lxc_container/parameter/default/user

@@ -0,0 +1 @@
+root

cdist/conf/type/__lxc_container/parameter/optional

@@ -0,0 +1,19 @@
+name
+user
+state
+lxcpath
+template
+default-config
+release
+arch
+mirror
+ssh-key
+clone
+clonepath
+backingstore
+bdev-dir
+bdev-fstype
+bdev-fssize
+bdev-lvname
+bdev-vgname
+bdev-thinpool

cdist/conf/type/__lxc_container/parameter/optional_multiple

@@ -0,0 +1,3 @@
+config
+config-absent
+template-opts

cdist/conf/type/__lxc_container/todo.txt

@@ -0,0 +1,34 @@
+# List of all featues that should be implemented
+template (common parameters):
+  - type: a.E. debian, ubuntu -> what on change?
+  - possible root_password?
+  - possible packages?
+  - other options??
+auto.. (lxc autostart):
+  - group
+  - start
+handling networking?
+  - address
+  - bridge? (at default file?)
+
+config:
+  - remove whole sections
+  - keep prettier config files?
+  - own type for config?
+    does it conflict with the current one?
+own __lxc_default type?
+  `lxc-config lxc.default_config`
+  without lxcpath cause singleton?
+
+Splitting up type? (all times the library question :-) )
+  __lxc_container (umbrella; creating,cloning,destroying??)
+  __lxc_container_config (single key-values)
+  __lxc_container_state (only running,freezed,stopped??)
+  __lxc_container_network
+  __lxc_container_mount
+  ...
+All common library files (except explorer things sadly) could be kept under __lxc_container.
+
+
+if multi-valued object ids come to be a thing, following pattern is also used internal at lxc:
+  $lxcpath:$name