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       --log-level value
29
30
31       The log level to be used. Either "trace", "debug", "info", "warn", "er‐
32       ror", "fatal", or "panic", defaulting to "warn".
33
34
35       --help, -h
36
37
38       Show help
39
40
41       --registries-conf path
42
43
44       Pathname of the configuration file which specifies which container reg‐
45       istries should be consulted when completing image names  which  do  not
46       include  a registry or domain portion.  It is not recommended that this
47       option be used, as the default behavior of using the  system-wide  con‐
48       figuration (/etc/containers/registries.conf) is most often preferred.
49
50
51       --registries-conf-dir path
52
53
54       Pathname  of  the directory which contains configuration snippets which
55       specify registries which should  be  consulted  when  completing  image
56       names  which  do  not  include a registry or domain portion.  It is not
57       recommended that this option be used, as the default behavior of  using
58       the  system-wide  configuration  (/etc/containers/registries.d) is most
59       often preferred.
60
61
62       --root value
63
64
65       Storage root dir (default:  "/var/lib/containers/storage"  for  UID  0,
66       "$HOME/.local/share/containers/storage"  for  other users) Default root
67       dir is configured in /etc/containers/storage.conf
68
69
70       --runroot value
71
72
73       Storage  state  dir  (default:  "/run/containers/storage"  for  UID  0,
74       "/run/user/$UID"  for  other  users) Default state dir is configured in
75       /etc/containers/storage.conf
76
77
78       --storage-driver value
79
80
81       Storage driver.  The default storage driver for UID 0 is configured  in
82       /etc/containers/storage.conf  ($HOME/.config/containers/storage.conf in
83       rootless mode), and is vfs for other users.  The  STORAGE_DRIVER  envi‐
84       ronment variable overrides the default.  The --storage-driver specified
85       driver overrides all.
86
87
88       Examples: "overlay", "devicemapper", "vfs"
89
90
91       Overriding this option will cause the storage-opt settings in /etc/con‐
92       tainers/storage.conf  to  be ignored.  The user must specify additional
93       options via the --storage-opt flag.
94
95
96       --storage-opt value
97
98
99       Storage driver option, Default storage driver options are configured in
100       /etc/containers/storage.conf  ($HOME/.config/containers/storage.conf in
101       rootless mode). The STORAGE_OPTS environment variable overrides the de‐
102       fault. The --storage-opt specified options overrides all.
103
104
105       --userns-uid-map mapping
106
107
108       Directly specifies a UID mapping which should be used to set ownership,
109       at the filesystem level, on the working container's contents.  Commands
110       run  when  handling RUN instructions will default to being run in their
111       own user namespaces, configured using the UID and GID maps.
112
113
114       Entries in this map take  the  form  of  one  or  more  colon-separated
115       triples  of  a  starting  in-container  UID,  a  corresponding starting
116       host-level UID, and the number of consecutive IDs which the  map  entry
117       represents.
118
119
120       This  option overrides the remap-uids setting in the options section of
121       /etc/containers/storage.conf.
122
123
124       If this option is not specified, but a global --userns-uid-map  setting
125       is supplied, settings from the global option will be used.
126
127
128       If    none   of   --userns-uid-map-user,   --userns-gid-map-group,   or
129       --userns-uid-map are specified, but --userns-gid-map is specified,  the
130       UID map will be set to use the same numeric values as the GID map.
131
132
133       NOTE:  When  this option is specified by a rootless user, the specified
134       mappings are relative to the rootless usernamespace in  the  container,
135       rather than being relative to the host as it would be when run rootful.
136
137
138       --userns-gid-map mapping
139
140
141       Directly specifies a GID mapping which should be used to set ownership,
142       at the filesystem level, on the working container's contents.  Commands
143       run  when  handling RUN instructions will default to being run in their
144       own user namespaces, configured using the UID and GID maps.
145
146
147       Entries in this map take  the  form  of  one  or  more  colon-separated
148       triples  of  a  starting  in-container  GID,  a  corresponding starting
149       host-level GID, and the number of consecutive IDs which the  map  entry
150       represents.
151
152
153       This  option overrides the remap-gids setting in the options section of
154       /etc/containers/storage.conf.
155
156
157       If this option is not specified, but a global --userns-gid-map  setting
158       is supplied, settings from the global option will be used.
159
160
161       If    none   of   --userns-uid-map-user,   --userns-gid-map-group,   or
162       --userns-gid-map are specified, but --userns-uid-map is specified,  the
163       GID map will be set to use the same numeric values as the UID map.
164
165
166       NOTE:  When  this option is specified by a rootless user, the specified
167       mappings are relative to the rootless usernamespace in  the  container,
168       rather than being relative to the host as it would be when run rootful.
169
170
171       --version, -v
172
173
174       Print the version
175
176

Environment Variables

178       Buildah can set up environment variables from the env entry in the [en‐
179       gine] table in the containers.conf(5). These variables can be  overrid‐
180       den by passing environment variables before the buildah commands.
181
182

COMMANDS

184       ┌──────────────────────┬────────────────────────────────┐
185Command               Description                    
186       ├──────────────────────┼────────────────────────────────┤
187buildah-add(1)        │ Add  the  contents  of a file, │
188       │                      │ URL, or  a  directory  to  the │
189       │                      │ container.                     │
190       ├──────────────────────┼────────────────────────────────┤
191buildah-bud(1)        │ Build  an image using instruc‐ │
192       │                      │ tions from Dockerfiles.        │
193       ├──────────────────────┼────────────────────────────────┤
194buildah-commit(1)     │ Create an image from a working │
195       │                      │ container.                     │
196       ├──────────────────────┼────────────────────────────────┤
197buildah-config(1)     │ Update   image   configuration │
198       │                      │ settings.                      │
199       ├──────────────────────┼────────────────────────────────┤
200buildah-containers(1) │ List  the  working  containers │
201       │                      │ and their base images.         │
202       ├──────────────────────┼────────────────────────────────┤
203buildah-copy(1)       │ Copies the contents of a file, │
204       │                      │ URL, or directory into a  con‐ │
205       │                      │ tainer's working directory.    │
206       ├──────────────────────┼────────────────────────────────┤
207buildah-from(1)       │ Creates  a  new  working  con‐ │
208       │                      │ tainer, either from scratch or │
209       │                      │ using  a  specified image as a │
210       │                      │ starting point.                │
211       ├──────────────────────┼────────────────────────────────┤
212buildah-images(1)     │ List images in local storage.  │
213       ├──────────────────────┼────────────────────────────────┤
214buildah-info(1)       │ Display Buildah system  infor‐ │
215       │                      │ mation.                        │
216       ├──────────────────────┼────────────────────────────────┤
217buildah-inspect(1)    │ Inspects  the configuration of │
218       │                      │ a container or image           │
219       ├──────────────────────┼────────────────────────────────┤
220buildah-login(1)      │ Login to a container registry. │
221       ├──────────────────────┼────────────────────────────────┤
222buildah-logout(1)     │ Logout of a container registry │
223       ├──────────────────────┼────────────────────────────────┤
224buildah-manifest(1)   │ Create and manipulate manifest │
225       │                      │ lists and image indexes.       │
226       ├──────────────────────┼────────────────────────────────┤
227buildah-mount(1)      │ Mount  the working container's │
228       │                      │ root filesystem.               │
229       ├──────────────────────┼────────────────────────────────┤
230buildah-pull(1)       │ Pull an image from the  speci‐ │
231       │                      │ fied location.                 │
232       ├──────────────────────┼────────────────────────────────┤
233buildah-push(1)       │ Push an image from local stor‐ │
234       │                      │ age to elsewhere.              │
235       ├──────────────────────┼────────────────────────────────┤
236buildah-rename(1)     │ Rename a local container.      │
237       ├──────────────────────┼────────────────────────────────┤
238buildah-rm(1)         │ Removes one  or  more  working │
239       │                      │ containers.                    │
240       ├──────────────────────┼────────────────────────────────┤
241buildah-rmi(1)        │ Removes one or more images.    │
242       ├──────────────────────┼────────────────────────────────┤
243buildah-run(1)        │ Run  a  command  inside of the │
244       │                      │ container.                     │
245       ├──────────────────────┼────────────────────────────────┤
246buildah-tag(1)        │ Add an additional  name  to  a │
247       │                      │ local image.                   │
248       ├──────────────────────┼────────────────────────────────┤
249buildah-umount(1)     │ Unmount  a working container's │
250       │                      │ root file system.              │
251       ├──────────────────────┼────────────────────────────────┤
252buildah-unshare(1)    │ Launch a  command  in  a  user │
253       │                      │ namespace   with  modified  ID │
254       │                      │ mappings.                      │
255       ├──────────────────────┼────────────────────────────────┤
256buildah-version(1)    │ Display  the  Buildah  Version │
257       │                      │ Information                    │
258       ├──────────────────────┼────────────────────────────────┤
259       │                      │                                │
260       └──────────────────────┴────────────────────────────────┘
261

Files

263       storage.conf (/etc/containers/storage.conf)
264
265
266       storage.conf is the storage configuration file for all tools using con‐
267       tainers/storage
268
269
270       The storage configuration file specifies all of the available container
271       storage options for tools using shared container storage.
272
273
274       mounts.conf (/usr/share/containers/mounts.conf and optionally /etc/con‐
275       tainers/mounts.conf)
276
277
278       The mounts.conf files specify volume mount files  or  directories  that
279       are  automatically mounted inside containers when executing the buildah
280       run or buildah build-using-dockerfile  commands.   Container  processes
281       can  then use this content.  The volume mount content does not get com‐
282       mitted to the final image.
283
284
285       Usually these directories are used for passing secrets  or  credentials
286       required by the package software to access remote package repositories.
287
288
289       For   example,   a   mounts.conf  with  the  line  "/usr/share/rhel/se‐
290       crets:/run/secrets", the content of  /usr/share/rhel/secrets  directory
291       is  mounted  on /run/secrets inside the container.  This mountpoint al‐
292       lows Red Hat Enterprise Linux subscriptions from the host  to  be  used
293       within  the  container.  It is also possible to omit the destination if
294       it's equal to the source path.  For  example,  specifying  /var/lib/se‐
295       crets will mount the directory into the same container destination path
296       /var/lib/secrets.
297
298
299       Note this is not a volume mount. The content of the volumes  is  copied
300       into container storage, not bind mounted directly from the host.
301
302
303       registries.conf (/etc/containers/registries.conf)
304
305
306       registries.conf  is  the  configuration file which specifies which con‐
307       tainer registries should be consulted when completing image names which
308       do not include a registry or domain portion.
309
310
311       registries.d (/etc/containers/registries.d)
312
313
314       Directory  which  contains  configuration  snippets  which specify reg‐
315       istries which should be consulted when completing image names which  do
316       not include a registry or domain portion.
317
318

SEE ALSO

320       containers.conf(5),       containers-mounts.conf(5),      newuidmap(1),
321       newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
322
323

HISTORY

325       December 2017, Originally compiled by Tom  Sweeney  tsweeney@redhat.com
326       ⟨mailto:tsweeney@redhat.com⟩
327
328
329
330buildah                           March 2017                        buildah(1)
Impressum