atomic/docs/atomic-run.1.md

% ATOMIC(1) Atomic Man Pages
% Dan Walsh
% January 2015
# NAME
atomic-run - Execute container image run method

# SYNOPSIS
**atomic run**
[**-h**|**--help**]
[**--display**]
[**-n**][**--name**[=*NAME*]]
[**-r**, **--replace**]
[**--spc**]
[**--storage**]
[**--set**=*NAME*=*VALUE*]
[**--quiet**]
IMAGE [COMMAND] [ARG...]

# DESCRIPTION
**atomic run** attempts to start an existing container or run a container
from an image,  first reading the `LABEL RUN` field in the container IMAGE.


If the container image has a LABEL RUN instruction like the following:

`LABEL RUN /usr/bin/docker run -t -i --rm \${OPT1} --cap-add=SYS_ADMIN --net=host -v \${LOGDIR}:/var/log -v \${DATADIR}:/var/lib --name \${NAME} \${IMAGE} \${OPT2} run.sh \${OPT3}`

`atomic run` will run the following:

`/usr/bin/docker run -t -i --rm --cap-add=SYS_ADMIN --net=host -v ${LOGDIR}:/var/log -v ${DATADIR}:/var/lib --name ${NAME} ${IMAGE} run.sh`

If this field does not exist, `atomic run` defaults to the following:

`/usr/bin/docker run -t -i --rm -v ${LOGDIR}:/var/log -v ${DATADIR}:/var/lib --name ${NAME} ${IMAGE}`

These defaults are suggested values for your container images.

`atomic run` will set the following environment variables for use in the command:

**NAME**
  The name specified via the command.  NAME will be replaced with IMAGE if it is not specified.

**IMAGE**
  The name and image specified via the command.

**OPT1, OPT2, OPT3**
  Additional options which can be specified via the command.

**SUDO_UID**
  The `SUDO_UID` environment variable.  This is useful with the docker `-u` option for user space tools.  If the environment variable is not available, the value of `/proc/self/loginuid` is used.

**SUDO_GID**
  The `SUDO_GID` environment variable.  This is useful with the docker `-u` option for user space tools.  If the environment variable is not available, the default GID of the value for `SUDO_UID` is used.  If this value is not available, the value of `/proc/self/loginuid` is used.

**RUN_OPTS**
  Content of file specified by `LABEL RUN_OPTS_FILE`.  During `atomic install`, the `install.sh` can populate the file with any additional options that need to be passed to `docker run`, for example `--hostname=www.example.test` or `--net host`. The file name undergoes environment variable expansion, so for example `LABEL RUN_OPTS_FILE '/var/lib/${NAME}/docker-run-opts'` can be used to store per-container configuration.

Custom environment variables can be provided to the container through the LABEL RUN instruction as follows:

`LABEL RUN /usr/bin/docker run -t -i --rm -e FOO="\${FOO:-bar}" -v \${LOGDIR}:/var/log -v \${DATADIR}:/var/lib --name \${NAME} \${IMAGE}`

`atomic run` will run the following:

`/usr/bin/docker run -t -i --rm -e FOO="${FOO:-bar}"  -v ${LOGDIR}:/var/log -v ${DATADIR}:/var/lib --name ${NAME} ${IMAGE}`

The value of `FOO` can be set explicitly via `FOO=baz atomic run`.

# OPTIONS:
**-h** **--help**
  Print usage statement

**--display**
  Display the image's run options and environment variables populated into the run command.
The run command will not execute if --display is specified.
If --display is not specified the run command will execute.

**--n** **--name**=""
   Use this name for creating run content for the container.
NAME will default to the IMAGENAME if it is not specified.

**-r** **--replace**
   Replaces an existing container by the same name if it exists prior to running.

**--runtime=PATH**
   Change the OCI runtime used by the systemd service file for running
   system containers and user containers.  If runtime is not defined, the
   value **runtime** in the configuration file is used for system
   containers.  If there is no runtime defined in the configuration file
   as well, then the default **/usr/bin/runc** is used.
   
**--spc**
  Run container in super privileged container mode.  The image will run with the following command:

`/usr/bin/docker run -t -i --rm --privileged -v /:/host -v /run:/run --net=host --ipc=host --pid=host -e HOST=/host -e NAME=${NAME} -e IMAGE=${IMAGE} --name ${NAME} ${IMAGE}`

**--storage**
   Allows you to override the default definition for the storage backend where your image will reside if pulled.  If the image is already local,
the --storage option will dictate where atomic should look for the image prior to running. Valid options are `docker` and `ostree`.

**--set=NAME=VALUE**
Set a value that is going to be used by a system container for its
configuration and can be specified multiple times.  It is used only
by --system.  OSTree is required for this feature to be available.


**--quiet**
  Run without verbose messaging (i.e. security warnings).

# HISTORY
January 2015, Originally compiled by Daniel Walsh (dwalsh at redhat dot com)
July 2015, edited by Sally O'Malley (somalley at redhat dot com)