1ATOMIC(1)                        January 2015                        ATOMIC(1)
2
3
4

NAME

6       atomic-install - Execute Image Install Method
7
8
9

SYNOPSIS

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
15
16

DESCRIPTION

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
22
23       If the container image has a LABEL INSTALL instruction like the
24       following:
25
26
27       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
33
34       atomic install will set the following environment variables for use in
35       the command:
36
37
38       NAME The name specified via the command.  NAME will be replaced with
39       IMAGE if it is not specified.
40
41
42       IMAGE The name and image specified via the command.
43
44
45       OPT1, OPT2, OPT3 Additional options which can be specified via the
46       command.
47
48
49       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
53
54       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
59
60       Any additional arguments will be appended to the command.
61
62
63

OPTIONS:

65       -h --help Print usage statement
66
67
68       --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
73
74       -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
78
79       --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
85
86       --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
92
93       --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
98
99       --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
105
106       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
112
113       --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
123
124       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
128
129       The system container template files support substition of variables.
130
131
132       These files in the image are managed as metadata for system containers:
133
134
135       /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
139
140       /exports/manifest.json Various settings for the container.
141
142
143       /exports/service.template Template for the systemd unit file.
144
145
146       /exports/tmpfiles.template Template for systemd-tmpfiles, if the
147       container needs temporary files on the system.
148
149
150       In /exports/manifest.json it is possible to setup these settings:
151
152
153       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
157
158       installedFilesTemplate List of files that must be preprocessed before
159       being copied to the host.
160
161
162       noContainerService Set to True if the container is used only for
163       copying files to the host but has not a systemd service.
164
165
166       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
170
171       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
178
179       useLinks Specify if files copied to the host under /usr should use hard
180       links when possible.  By default it is True.
181
182
183       This is the list of the variables that get a value from atomic and
184       cannot be overriden by the user through --set:
185
186
187       $DESTDIR Destination on the file system for the checked out container.
188
189
190       $EXEC_STARTPRE Command to use for the systemd directive ExecStartPre=.
191
192
193       $EXEC_START Command to use for the systemd directive ExecStart=.
194
195
196       $EXEC_STOP Command to use for the systemd directive ExecStop=.
197
198
199       $EXEC_STOPPOST Command to use for the systemd directive ExecStopPost=.
200
201
202       $HOST_UID UID of the user on the system.
203
204
205       $HOST_GID GID of the user on the system.
206
207
208       $IMAGE_ID ID of the image being installed.
209
210
211       $IMAGE_NAME Name of the image being installed.
212
213
214       $NAME Name of the container.
215
216
217       Some other variables get a value but it is possible to override it
218       through --set:
219
220
221       $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
229
230       $CONFIG_DIRECTORY Directory where to store configuration files (/etc on
231       the host,  /.config/ for user containers).
232
233
234       $PIDFILE File where to store the PID of the container main process.
235
236
237       $RUN_DIRECTORY Directory where to store runtime files. (/run on the
238       host, $XDG_RUNTIME_DIR for user containers).
239
240
241       $STATE_DIRECTORY Directory where to store the state of the container.
242
243
244       $UUID UUID generated for this container.
245
246
247       $RUNTIME The runtime used to execute the containers.
248
249
250       $ATOMIC Path to the atomic executable that is installing the container.
251
252
253       --system-package=auto|build|no|yes Control how the container will be
254       installed to the system.
255
256
257       auto generates an rpm and install it to the system when the image
258       defines a .spec file.  This is the default.
259
260
261       build build only the software package, without installing it.
262
263
264       no do not generate an rpm package to install the container.
265
266
267       yes generate an rpm package and install it to the system.
268
269
270       --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
276
277

HISTORY

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)
282
283
284
285Dan Walsh                       Atomic Man Pages                     ATOMIC(1)
Impressum