1ATOMIC(1) January 2015 ATOMIC(1)
2
6 atomic-install - Execute Image Install Method
7
11 atomic install [-h|--help] [--display] [-n][--name[=NAME]]
12 [--rootfs=ROOTFS] [--set=NAME=VALUE] [--storage]
13 [--system-package=auto|build|yes|no] [--system] IMAGE [ARG...]
14
18 atomic install attempts to read the LABEL INSTALL field in the
19 container IMAGE, if this field does not exist, atomic install will
20 install the IMAGE.
21 If the container image has a LABEL INSTALL instruction like the
24 following:
25 LABEL INSTALL /usr/bin/docker run -t -i --rm \${OPT1} --privileged -v
28 /:/host --net=host --ipc=host --pid=host -e HOST=/host -e NAME=\${NAME}
29 -e IMAGE=\${IMAGE} -e CONFDIR=\/etc/${NAME} -e LOGDIR=/var/log/\${NAME}
30 -e DATADIR=/var/lib/\${NAME} \${IMAGE} \${OPT2} /bin/install.sh
31 \${OPT3}
32 atomic install will set the following environment variables for use in
35 the command:
36 NAME The name specified via the command. NAME will be replaced with
39 IMAGE if it is not specified.
40 IMAGE The name and image specified via the command.
43 OPT1, OPT2, OPT3 Additional options which can be specified via the
46 command.
47 SUDO_UID The SUDO_UID environment variable. This is useful with the
50 docker -u option for user space tools. If the environment variable is
51 not available, the value of /proc/self/loginuid is used.
52 SUDO_GID The SUDO_GID environment variable. This is useful with the
55 docker -u option for user space tools. If the environment variable is
56 not available, the default GID of the value for SUDO_UID is used. If
57 this value is not available, the value of /proc/self/loginuid is used.
58 Any additional arguments will be appended to the command.
61
65 -h --help Print usage statement
66 --display Display the image's install options and environment variables
69 populated into the install command. The install command will not
70 execute if --display is specified. If --display is not specified the
71 install command will execute.
72 -n --name=""
75 Use this name for creating installed content for the container.
76 NAME will default to the IMAGENAME if it is not specified.
77 --rootfs=ROOTFS Specify a ROOTFS folder, which can be an existing,
80 expanded container/image, or a location which contains an existing root
81 filesystem. The existing rootfs will be used as the new system
82 container's rootfs (read only), and thus the new container will only
83 contain config and info files.
84 --runtime=PATH Change the OCI runtime used by the systemd service file
87 for running system containers and user containers. If runtime is not
88 defined, the value runtime in the configuration file is used for system
89 containers. If there is no runtime defined in the configuration file
90 as well, then the default /usr/bin/runc is used.
91 --set=NAME=VALUE Set a value that is going to be used by a system
94 container for its configuration and can be specified multiple times.
95 It is used only by --system. OSTree is required for this feature to be
96 available.
97 --storage Allows you to override the default definition for the storage
100 backend where your image will reside if pulled. If the image is
101 already local, the --storage option will dictate where atomic should
102 look for the image prior to installing. Valid options are docker and
103 ostree.
104 If you are installing a container using docker storage, you may define
107 a label in your image named atomic.has_install_files. This label
108 indicates there are files inside the container image which are meant to
109 be placed on host system. An rpm is created from these files and
110 installed onto host system.
111 --system Install a system container. A system container is a container
114 that is executed out of an systemd unit file early in boot, using runc.
115 The specified IMAGE must be a system image already fetched. If it is
116 not already present, atomic will attempt to fetch it assuming it is an
117 oci image. For more information on how images are fetched, see also
118 atomic-pull(1). Installing a system container consists of checking it
119 the image by default under /var/lib/containers/atomic/ and generating
120 the configuration files for runc and systemd. OSTree and runc are
121 required for this feature to be available.
122 Note: If the image being pulled contains a label of system.type=ostree,
125 atomic will automatically substitute the storage backend to be ostree.
126 This can be overridden with the --storage option.
127 The system container template files support substition of variables.
130 These files in the image are managed as metadata for system containers:
133 /exports/config.json.template The OCI configuration for running the
136 container. The generated file is ultimately used by the OCI runtime
137 for setting up the container.
138 /exports/manifest.json Various settings for the container.
141 /exports/service.template Template for the systemd unit file.
144 /exports/tmpfiles.template Template for systemd-tmpfiles, if the
147 container needs temporary files on the system.
148 In /exports/manifest.json it is possible to setup these settings:
151 defaultValues A dictionary which containers the default values given to
154 variables used by the template files. The user can override these
155 values with -set=VARIABLE=NEWVALUE.
156 installedFilesTemplate List of files that must be preprocessed before
159 being copied to the host.
160 noContainerService Set to True if the container is used only for
163 copying files to the host but has not a systemd service.
164 renameFiles Define the destination name of the files on the host.
167 Variable sobstitution is supported so that it is possible to use
168 variables to compose the final destination path.
169 Every file under /exports/hostfs is copied to the host when the
172 container is installed, and removed once the container is uninstalled.
173 For instance, a file /exports/hostfs/usr/local/bin/foo in the image is
174 copied to the host as /usr/local/bin/foo. The directives
175 installedFilesTemplate and renameFiles from the manifest.json file can
176 be used to modify the content and the final destination of the file.
177 useLinks Specify if files copied to the host under /usr should use hard
180 links when possible. By default it is True.
181 This is the list of the variables that get a value from atomic and
184 cannot be overriden by the user through --set:
185 $DESTDIR Destination on the file system for the checked out container.
188 $EXEC_STARTPRE Command to use for the systemd directive ExecStartPre=.
191 $EXEC_START Command to use for the systemd directive ExecStart=.
194 $EXEC_STOP Command to use for the systemd directive ExecStop=.
197 $EXEC_STOPPOST Command to use for the systemd directive ExecStopPost=.
200 $HOST_UID UID of the user on the system.
203 $HOST_GID GID of the user on the system.
206 $IMAGE_ID ID of the image being installed.
209 $IMAGE_NAME Name of the image being installed.
212 $NAME Name of the container.
215 Some other variables get a value but it is possible to override it
218 through --set:
219 $ALL_PROCESS_CAPABILITIES A list of all the kernel process capabilities
222 available on the system, in the format expected in the OCI
223 configuration file. Privileged containers that keep all capabilities
224 should use this variable instead of hardcoding the list. This
225 simplifies the configuration file as well as improve images portability
226 as the same image can be used on systems with a different set of
227 capabilities.
228 $CONFIG_DIRECTORY Directory where to store configuration files (/etc on
231 the host, /.config/ for user containers).
232 $PIDFILE File where to store the PID of the container main process.
235 $RUN_DIRECTORY Directory where to store runtime files. (/run on the
238 host, $XDG_RUNTIME_DIR for user containers).
239 $STATE_DIRECTORY Directory where to store the state of the container.
242 $UUID UUID generated for this container.
245 $RUNTIME The runtime used to execute the containers.
248 $ATOMIC Path to the atomic executable that is installing the container.
251 --system-package=auto|build|no|yes Control how the container will be
254 installed to the system.
255 auto generates an rpm and install it to the system when the image
258 defines a .spec file. This is the default.
259 build build only the software package, without installing it.
262 no do not generate an rpm package to install the container.
265 yes generate an rpm package and install it to the system.
268 --user If running as non-root, specify to install the image from the
271 current OSTree repository and manage it through systemd and runc.
272 OSTree and runc are required for this feature to be available. The
273 same image format as for --system is supported. Please refer to
274 --system for more information.
275
279 January 2015, Originally compiled by Daniel Walsh (dwalsh at redhat dot
280 com) July 2015, edited by Sally O'Malley (somalley at redhat dot com)
281 October 2017, edited by Giuseppe Scrivano (gscrivan at redhat dot com)
282Dan Walsh Atomic Man Pages ATOMIC(1)