1buildah(1)                  General Commands Manual                 buildah(1)
2
3
4

NAME

6       Buildah  -  A command line tool that facilitates building OCI container
7       images.
8
9

SYNOPSIS

11       buildah [OPTIONS] COMMAND [ARG...]
12
13

DESCRIPTION

15       The Buildah package provides a command line tool which can be used to:
16
17
18              * Create a working container, either from scratch or using an image as a starting point.
19              * Mount a working container's root filesystem for manipulation.
20              * Unmount a working container's root filesystem.
21              * Use the updated contents of a container's root filesystem as a filesystem layer to create a new image.
22              * Delete a working container or an image.
23              * Rename a local container.
24
25
26

OPTIONS

28       --cgroup-manager=manager
29
30
31       The CGroup manager to use for container cgroups. Supported  values  are
32       cgroupfs  or  systemd. Default is systemd unless overridden in the con‐
33       tainers.conf file.
34
35
36       Note: Setting this flag can cause certain commands to break when called
37       on  containers  previously  created  by  the other CGroup manager type.
38       Note: CGroup manager is not  supported  in  rootless  mode  when  using
39       CGroups Version V1.
40
41
42       --log-level value
43
44
45       The log level to be used. Either "trace", "debug", "info", "warn", "er‐
46       ror", "fatal", or "panic", defaulting to "warn".
47
48
49       --help, -h
50
51
52       Show help
53
54
55       --registries-conf path
56
57
58       Pathname of the configuration file which specifies which container reg‐
59       istries  should  be  consulted when completing image names which do not
60       include a registry or domain portion.  It is not recommended that  this
61       option  be  used, as the default behavior of using the system-wide con‐
62       figuration (/etc/containers/registries.conf) is most often preferred.
63
64
65       --registries-conf-dir path
66
67
68       Pathname of the directory which contains configuration  snippets  which
69       specify  registries  which  should  be  consulted when completing image
70       names which do not include a registry or domain  portion.   It  is  not
71       recommended  that this option be used, as the default behavior of using
72       the system-wide configuration  (/etc/containers/registries.d)  is  most
73       often preferred.
74
75
76       --root value
77
78
79       Storage  root  dir  (default:  "/var/lib/containers/storage" for UID 0,
80       "$HOME/.local/share/containers/storage" for other users)  Default  root
81       dir is configured in /etc/containers/storage.conf
82
83
84       --runroot value
85
86
87       Storage  state  dir  (default:  "/run/containers/storage"  for  UID  0,
88       "/run/user/$UID" for other users) Default state dir  is  configured  in
89       /etc/containers/storage.conf
90
91
92       --short-name-alias-conf path
93
94
95       Pathname of the file which contains cached mappings between short image
96       names and their corresponding fully-qualified names.  It  is  used  for
97       mapping  from  names  of images specified using short names like "ubi8"
98       which don't include a registry component  and  a  corresponding  fully-
99       specified name which includes a registry and any other components, such
100       as "registry.access.redhat.com/ubi8".  It is not recommended that  this
101       option  be used, as the default behavior of using the system-wide cache
102       (/var/cache/containers/short-name-aliases.conf)   or   per-user   cache
103       ($HOME/.cache/containers/short-name-aliases.conf) to supplement system-
104       wide defaults is most often preferred.
105
106
107       --storage-driver value
108
109
110       Storage driver.  The default storage driver for UID 0 is configured  in
111       /etc/containers/storage.conf  ($HOME/.config/containers/storage.conf in
112       rootless mode), and is vfs for other users.  The  STORAGE_DRIVER  envi‐
113       ronment variable overrides the default.  The --storage-driver specified
114       driver overrides all.
115
116
117       Examples: "overlay", "devicemapper", "vfs"
118
119
120       Overriding this option will cause the storage-opt settings in /etc/con‐
121       tainers/storage.conf  to  be ignored.  The user must specify additional
122       options via the --storage-opt flag.
123
124
125       --storage-opt value
126
127
128       Storage driver option, Default storage driver options are configured in
129       /etc/containers/storage.conf  ($HOME/.config/containers/storage.conf in
130       rootless mode). The STORAGE_OPTS environment variable overrides the de‐
131       fault. The --storage-opt specified options overrides all.
132
133
134       --userns-gid-map mapping
135
136
137       Directly specifies a GID mapping which should be used to set ownership,
138       at the filesystem level, on the working container's contents.  Commands
139       run  when  handling RUN instructions will default to being run in their
140       own user namespaces, configured using the UID and GID maps.
141
142
143       Entries in this map take  the  form  of  one  or  more  colon-separated
144       triples  of a starting in-container GID, a corresponding starting host-
145       level GID, and the number of consecutive IDs which the map entry repre‐
146       sents.
147
148
149       This  option overrides the remap-gids setting in the options section of
150       /etc/containers/storage.conf.
151
152
153       If this option is not specified, but a global --userns-gid-map  setting
154       is supplied, settings from the global option will be used.
155
156
157       If  none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
158       gid-map are specified, but --userns-uid-map is specified, the  GID  map
159       will be set to use the same numeric values as the UID map.
160
161
162       NOTE:  When  this option is specified by a rootless user, the specified
163       mappings are relative to the rootless usernamespace in  the  container,
164       rather than being relative to the host as it would be when run rootful.
165
166
167       --userns-uid-map mapping
168
169
170       Directly specifies a UID mapping which should be used to set ownership,
171       at the filesystem level, on the working container's contents.  Commands
172       run  when  handling RUN instructions will default to being run in their
173       own user namespaces, configured using the UID and GID maps.
174
175
176       Entries in this map take  the  form  of  one  or  more  colon-separated
177       triples  of a starting in-container UID, a corresponding starting host-
178       level UID, and the number of consecutive IDs which the map entry repre‐
179       sents.
180
181
182       This  option overrides the remap-uids setting in the options section of
183       /etc/containers/storage.conf.
184
185
186       If this option is not specified, but a global --userns-uid-map  setting
187       is supplied, settings from the global option will be used.
188
189
190       If  none of --userns-uid-map-user, --userns-gid-map-group, or --userns-
191       uid-map are specified, but --userns-gid-map is specified, the  UID  map
192       will be set to use the same numeric values as the GID map.
193
194
195       NOTE:  When  this option is specified by a rootless user, the specified
196       mappings are relative to the rootless usernamespace in  the  container,
197       rather than being relative to the host as it would be when run rootful.
198
199
200       --version, -v
201
202
203       Print the version
204
205

Environment Variables

207       Buildah can set up environment variables from the env entry in the [en‐
208       gine] table in the containers.conf(5). These variables can be  overrid‐
209       den by passing environment variables before the buildah commands.
210
211

COMMANDS

213       ┌───────────┬───────────────────────┬────────────────────────────────┐
214Command    Man Page              Description                    
215       ├───────────┼───────────────────────┼────────────────────────────────┤
216       │add        │ buildah-add(1)        │ Add  the  contents  of a file, │
217       │           │                       │ URL, or  a  directory  to  the │
218       │           │                       │ container.                     │
219       ├───────────┼───────────────────────┼────────────────────────────────┤
220       │build      │ buildah-build(1)      │ Builds  an OCI image using in‐ │
221       │           │                       │ structions in one or more Con‐ │
222       │           │                       │ tainerfiles.                   │
223       ├───────────┼───────────────────────┼────────────────────────────────┤
224       │commit     │ buildah-commit(1)     │ Create an image from a working │
225       │           │                       │ container.                     │
226       ├───────────┼───────────────────────┼────────────────────────────────┤
227       │config     │ buildah-config(1)     │ Update   image   configuration │
228       │           │                       │ settings.                      │
229       ├───────────┼───────────────────────┼────────────────────────────────┤
230       │containers │ buildah-containers(1) │ List  the  working  containers │
231       │           │                       │ and their base images.         │
232       ├───────────┼───────────────────────┼────────────────────────────────┤
233       │copy       │ buildah-copy(1)       │ Copies the contents of a file, │
234       │           │                       │ URL,  or directory into a con‐ │
235       │           │                       │ tainer's working directory.    │
236       ├───────────┼───────────────────────┼────────────────────────────────┤
237       │from       │ buildah-from(1)       │ Creates  a  new  working  con‐ │
238       │           │                       │ tainer, either from scratch or │
239       │           │                       │ using a specified image  as  a │
240       │           │                       │ starting point.                │
241       ├───────────┼───────────────────────┼────────────────────────────────┤
242       │images     │ buildah-images(1)     │ List images in local storage.  │
243       ├───────────┼───────────────────────┼────────────────────────────────┤
244       │info       │ buildah-info(1)       │ Display  Buildah system infor‐ │
245       │           │                       │ mation.                        │
246       ├───────────┼───────────────────────┼────────────────────────────────┤
247       │inspect    │ buildah-inspect(1)    │ Inspects the configuration  of │
248       │           │                       │ a container or image           │
249       ├───────────┼───────────────────────┼────────────────────────────────┤
250       │login      │ buildah-login(1)      │ Login to a container registry. │
251       ├───────────┼───────────────────────┼────────────────────────────────┤
252       │logout     │ buildah-logout(1)     │ Logout of a container registry │
253       ├───────────┼───────────────────────┼────────────────────────────────┤
254       │manifest   │ buildah-manifest(1)   │ Create and manipulate manifest │
255       │           │                       │ lists and image indexes.       │
256       ├───────────┼───────────────────────┼────────────────────────────────┤
257       │mount      │ buildah-mount(1)      │ Mount the working  container's │
258       │           │                       │ root filesystem.               │
259       ├───────────┼───────────────────────┼────────────────────────────────┤
260       │pull       │ buildah-pull(1)       │ Pull  an image from the speci‐ │
261       │           │                       │ fied location.                 │
262       ├───────────┼───────────────────────┼────────────────────────────────┤
263       │push       │ buildah-push(1)       │ Push an image from local stor‐ │
264       │           │                       │ age to elsewhere.              │
265       ├───────────┼───────────────────────┼────────────────────────────────┤
266       │rename     │ buildah-rename(1)     │ Rename a local container.      │
267       ├───────────┼───────────────────────┼────────────────────────────────┤
268       │rm         │ buildah-rm(1)         │ Removes  one  or  more working │
269       │           │                       │ containers.                    │
270       ├───────────┼───────────────────────┼────────────────────────────────┤
271       │rmi        │ buildah-rmi(1)        │ Removes one or more images.    │
272       ├───────────┼───────────────────────┼────────────────────────────────┤
273       │run        │ buildah-run(1)        │ Run a command  inside  of  the │
274       │           │                       │ container.                     │
275       ├───────────┼───────────────────────┼────────────────────────────────┤
276       │source     │ buildah-source(1)     │ Create,  push, pull and manage │
277       │           │                       │ source images  and  associated │
278       │           │                       │ source artifacts.              │
279       ├───────────┼───────────────────────┼────────────────────────────────┤
280       │tag        │ buildah-tag(1)        │ Add  an  additional  name to a │
281       │           │                       │ local image.                   │
282       ├───────────┼───────────────────────┼────────────────────────────────┤
283       │umount     │ buildah-umount(1)     │ Unmount a working  container's │
284       │           │                       │ root file system.              │
285       ├───────────┼───────────────────────┼────────────────────────────────┤
286       │unshare    │ buildah-unshare(1)    │ Launch  a  command  in  a user │
287       │           │                       │ namespace  with  modified   ID │
288       │           │                       │ mappings.                      │
289       ├───────────┼───────────────────────┼────────────────────────────────┤
290       │version    │ buildah-version(1)    │ Display  the  Buildah  Version │
291       │           │                       │ Information                    │
292       └───────────┴───────────────────────┴────────────────────────────────┘
293

Files

295       storage.conf (/etc/containers/storage.conf)
296
297
298       storage.conf is the storage configuration file for all tools using con‐
299       tainers/storage
300
301
302       The storage configuration file specifies all of the available container
303       storage options for tools using shared container storage.
304
305
306       mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/con‐
307       tainers/mounts.conf)
308
309
310       The  mounts.conf  files  specify volume mount files or directories that
311       are automatically mounted inside containers when executing the  buildah
312       run  or  buildah build commands.  Container processes can then use this
313       content.  The volume mount content does not get committed to the  final
314       image.
315
316
317       Usually  these  directories are used for passing secrets or credentials
318       required by the package software to access remote package repositories.
319
320
321       For  example,  a  mounts.conf  with   the   line   "/usr/share/rhel/se‐
322       crets:/run/secrets",  the  content of /usr/share/rhel/secrets directory
323       is mounted on /run/secrets inside the container.  This  mountpoint  al‐
324       lows  Red  Hat  Enterprise Linux subscriptions from the host to be used
325       within the container.  It is also possible to omit the  destination  if
326       it's  equal  to  the source path.  For example, specifying /var/lib/se‐
327       crets will mount the directory into the same container destination path
328       /var/lib/secrets.
329
330
331       Note  this  is not a volume mount. The content of the volumes is copied
332       into container storage, not bind mounted directly from the host.
333
334
335       registries.conf (/etc/containers/registries.conf)
336
337
338       registries.conf is the configuration file which  specifies  which  con‐
339       tainer registries should be consulted when completing image names which
340       do not include a registry or domain portion.
341
342
343       registries.d (/etc/containers/registries.d)
344
345
346       Directory which contains  configuration  snippets  which  specify  reg‐
347       istries  which should be consulted when completing image names which do
348       not include a registry or domain portion.
349
350

SEE ALSO

352       containers.conf(5),      containers-mounts.conf(5),       newuidmap(1),
353       newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
354
355

HISTORY

357       December  2017,  Originally compiled by Tom Sweeney tsweeney@redhat.com
358       ⟨mailto:tsweeney@redhat.com⟩
359
360
361
362buildah                           March 2017                        buildah(1)
Impressum