# salt.modules.nspawn

Manage nspawn containers

Added in version 2015.8.0.

systemd-nspawn(1) is a tool used to manage lightweight namespace containers. This execution module provides several functions to help manage these containers.

Minions running systemd >= 219 will place new containers in `/var/lib/machines`, while those running systemd < 219 will place them in `/var/lib/container`.

salt.modules.nspawn.bootstrap_container(name, dist=None, version=None)

  Bootstrap a container from package servers, if dist is None the os the minion is running as will be created, otherwise the needed bootstrapping tools will need to be available on the host.

  CLI Example:

      salt myminion nspawn.bootstrap_container <name>

salt.modules.nspawn.bootstrap_salt(name, config=None, approve_key=True, install=True, pub_key=None, priv_key=None, bootstrap_url=None, force_install=False, unconditional_install=False, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None)

  Bootstrap a container from package servers, if dist is None the os the minion is running as will be created, otherwise the needed bootstrapping tools will need to be available on the host.

  CLI Example:

      salt '*' nspawn.bootstrap_salt arch1

salt.modules.nspawn.copy_to(name, source, dest, overwrite=False, makedirs=False)

  Copy a file from the host into a container

  name

    Container name

  source

    File to be copied to the container

  dest

    Destination on the container. Must be an absolute path.

  overwriteFalse

    Unless this option is set to `True`, then if a file exists at the location specified by the `dest` argument, an error will be raised.

  makedirs : False

  > Create the parent directory on the container if it does not already exist.

  CLI Example:

      salt 'minion' nspawn.copy_to /tmp/foo /root/foo

salt.modules.nspawn.cp(name, source, dest, overwrite=False, makedirs=False)

  This function is an alias of `copy_to`.

  Copy a file from the host into a container

  name

    Container name

  source

    File to be copied to the container

  dest

    Destination on the container. Must be an absolute path.

  overwriteFalse

    Unless this option is set to `True`, then if a file exists at the location specified by the `dest` argument, an error will be raised.

  makedirs : False

  > Create the parent directory on the container if it does not already exist.

  CLI Example:

      salt 'minion' nspawn.copy_to /tmp/foo /root/foo

salt.modules.nspawn.destroy(name, stop=False)

  This function is an alias of `remove`.

  Remove the named container

  Warning

  This function will remove all data associated with the container. It will not, however, remove the btrfs subvolumes created by pulling container images (`nspawn.pull_raw`, `nspawn.pull_tar`, `nspawn.pull_dkr`).

  stopFalse

    If `True`, the container will be destroyed even if it is running/frozen.

  CLI Examples:

      salt '*' nspawn.remove foo
      salt '*' nspawn.remove foo stop=True

salt.modules.nspawn.disable(name)

  Set the named container to not be launched at boot

  CLI Example:

      salt myminion nspawn.enable <name>

salt.modules.nspawn.enable(name)

  Set the named container to be launched at boot

  CLI Example:

      salt myminion nspawn.enable <name>

salt.modules.nspawn.exists(name)

  Returns true if the named container exists

  CLI Example:

      salt myminion nspawn.exists <name>

salt.modules.nspawn.info(name, **kwargs)

  Return info about a container

  Note

  The container must be running for `machinectl` to gather information about it. If the container is stopped, then this function will start it.

  startFalse

    If `True`, then the container will be started to retrieve the info. A `Started` key will be in the return data if the container was started.

  CLI Example:

      salt myminion nspawn.info arch1
      salt myminion nspawn.info arch1 force_start=False

salt.modules.nspawn.list_()

  This function is an alias of `list_running`.

  Lists running nspawn containers

  Note

  `nspawn.list` also works to list running containers

  CLI Example:

      salt myminion nspawn.list_running
      salt myminion nspawn.list

salt.modules.nspawn.list_all()

  Lists all nspawn containers

  CLI Example:

      salt myminion nspawn.list_all

salt.modules.nspawn.list_running()

  Lists running nspawn containers

  Note

  `nspawn.list` also works to list running containers

  CLI Example:

      salt myminion nspawn.list_running
      salt myminion nspawn.list

salt.modules.nspawn.list_stopped()

  Lists stopped nspawn containers

  CLI Example:

      salt myminion nspawn.list_stopped

salt.modules.nspawn.pid(name)

  Returns the PID of a container

  name

    Container name

  CLI Example:

      salt myminion nspawn.pid arch1

salt.modules.nspawn.poweroff(name)

  Issue a clean shutdown to the container. Equivalent to running `machinectl poweroff` on the named container.

  For convenience, running `nspawn.stop``(as shown in the CLI examples below) is equivalent to running ``nspawn.poweroff`.

  Note

  `machinectl poweroff` is only supported in systemd >= 219. On earlier systemd versions, running this function will simply issue a clean shutdown via `systemctl`.

  CLI Examples:

      salt myminion nspawn.poweroff arch1
      salt myminion nspawn.stop arch1

salt.modules.nspawn.pull_dkr(url, name, index)

  Execute a `machinectl pull-dkr` to download a docker image and add it to /var/lib/machines as a new container.

  Note

  Requires systemd >= 219

  url

    URL from which to download the container

  name

    Name for the new container

  index

    URL of the Docker index server from which to pull (must be an `http://` or `https://` URL).

  CLI Examples:

      salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com
      salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com

salt.modules.nspawn.pull_docker(url, name, index)

  This function is an alias of `pull_dkr`.

  Execute a `machinectl pull-dkr` to download a docker image and add it to /var/lib/machines as a new container.

  Note

  Requires systemd >= 219

  url

    URL from which to download the container

  name

    Name for the new container

  index

    URL of the Docker index server from which to pull (must be an `http://` or `https://` URL).

  CLI Examples:

      salt myminion nspawn.pull_dkr centos/centos6 cent6 index=https://get.docker.com
      salt myminion nspawn.pull_docker centos/centos6 cent6 index=https://get.docker.com

salt.modules.nspawn.pull_raw(url, name, verify=False)

  Execute a `machinectl pull-raw` to download a .qcow2 or raw disk image, and add it to /var/lib/machines as a new container.

  Note

  Requires systemd >= 219

  url

    URL from which to download the container

  name

    Name for the new container

  verifyFalse

    Perform signature or checksum verification on the container. See the `machinectl(1)` man page (section titled "Image Transfer Commands") for more information on requirements for image verification. To perform signature verification, use `verify=signature`. For checksum verification, use `verify=checksum`. By default, no verification will be performed.

  CLI Examples:

      salt myminion nspawn.pull_raw http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz fedora21

salt.modules.nspawn.pull_tar(url, name, verify=False)

  Execute a `machinectl pull-raw` to download a .tar container image, and add it to /var/lib/machines as a new container.

  Note

  Requires systemd >= 219

  url

    URL from which to download the container

  name

    Name for the new container

  verifyFalse

    Perform signature or checksum verification on the container. See the `machinectl(1)` man page (section titled "Image Transfer Commands") for more information on requirements for image verification. To perform signature verification, use `verify=signature`. For checksum verification, use `verify=checksum`. By default, no verification will be performed.

  CLI Examples:

      salt myminion nspawn.pull_tar http://foo.domain.tld/containers/archlinux-2015.02.01.tar.gz arch2

salt.modules.nspawn.reboot(name, kill=False)

  Reboot the container by sending a SIGINT to its init process. Equivalent to running `machinectl reboot` on the named container.

  For convenience, running `nspawn.restart` (as shown in the CLI examples below) is equivalent to running `nspawn.reboot`.

  Note

  `machinectl reboot` is only supported in systemd >= 219. On earlier systemd versions, running this function will instead restart the container via `systemctl`.

  CLI Examples:

      salt myminion nspawn.reboot arch1
      salt myminion nspawn.restart arch1

salt.modules.nspawn.remove(name, stop=False)

  Remove the named container

  Warning

  This function will remove all data associated with the container. It will not, however, remove the btrfs subvolumes created by pulling container images (`nspawn.pull_raw`, `nspawn.pull_tar`, `nspawn.pull_dkr`).

  stopFalse

    If `True`, the container will be destroyed even if it is running/frozen.

  CLI Examples:

      salt '*' nspawn.remove foo
      salt '*' nspawn.remove foo stop=True

salt.modules.nspawn.restart(name)

  This is a compatibility function which simply calls nspawn.reboot.

salt.modules.nspawn.retcode(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

  Run `cmd.retcode` within a container

  name

    Name of the container in which to run the command

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console. Assumes `output=all`.

  keep_envNone

    If not passed, only a sane default PATH environment variable will be set. If `True`, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.

  CLI Example:

      salt myminion nspawn.retcode mycontainer 'ip addr show'

salt.modules.nspawn.run(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

  Run `cmd.run` within a container

  name

    Name of the container in which to run the command

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console.

  keep_envNone

    If not passed, only a sane default PATH environment variable will be set. If `True`, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.

  CLI Example:

      salt myminion nspawn.run mycontainer 'ip addr show'

salt.modules.nspawn.run_all(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

  Run `cmd.run_all` within a container

  Note

  While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container.

  name

    Name of the container in which to run the command

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console. Assumes `output=all`.

  keep_envNone

    If not passed, only a sane default PATH environment variable will be set. If `True`, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.

  CLI Example:

      salt myminion nspawn.run_all mycontainer 'ip addr show'

salt.modules.nspawn.run_stderr(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

  Run `cmd.run_stderr` within a container

  name

    Name of the container in which to run the command

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console. Assumes `output=all`.

  keep_envNone

    If not passed, only a sane default PATH environment variable will be set. If `True`, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.

  CLI Example:

      salt myminion nspawn.run_stderr mycontainer 'ip addr show'

salt.modules.nspawn.run_stdout(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, ignore_retcode=False, keep_env=None)

  Run `cmd.run_stdout` within a container

  name

    Name of the container in which to run the command

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console. Assumes `output=all`.

  keep_envNone

    If not passed, only a sane default PATH environment variable will be set. If `True`, all environment variables from the container's host will be kept. Otherwise, a comma-separated list (or Python list) of environment variable names can be passed, and those environment variables will be kept.

  CLI Example:

      salt myminion nspawn.run_stdout mycontainer 'ip addr show'

salt.modules.nspawn.start(name)

  Start the named container

  CLI Example:

      salt myminion nspawn.start <name>

salt.modules.nspawn.state(name)

  Return state of container (running or stopped)

  CLI Example:

      salt myminion nspawn.state <name>

salt.modules.nspawn.stop(name, kill=False)

  This is a compatibility function which provides the logic for nspawn.poweroff and nspawn.terminate.

salt.modules.nspawn.terminate(name)

  Kill all processes in the container without issuing a clean shutdown. Equivalent to running `machinectl terminate` on the named container.

  For convenience, running `nspawn.stop` and passing `kill=True` (as shown in the CLI examples below) is equivalent to running `nspawn.terminate`.

  Note

  `machinectl terminate` is only supported in systemd >= 219. On earlier systemd versions, running this function will simply issue a clean shutdown via `systemctl`.

  CLI Examples:

      salt myminion nspawn.terminate arch1
      salt myminion nspawn.stop arch1 kill=True