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       --short-name-alias-conf path
79
80
81       Pathname of the file which contains cached mappings between short image
82       names  and  their  corresponding fully-qualified names.  It is used for
83       mapping from names of images specified using short names  like  "hello-
84       world"  which  don't  include  a registry component and a corresponding
85       fully-specified name which includes a registry  and  any  other  compo‐
86       nents,  such as "docker.io/library/hello-world".  It is not recommended
87       that this option be used, as the default behavior of using the  system-
88       wide  cache (/var/cache/containers/short-name-aliases.conf) or per-user
89       cache ($HOME/.cache/containers/short-name-aliases.conf)  to  supplement
90       system-wide defaults is most often preferred.
91
92
93       --storage-driver value
94
95
96       Storage  driver.  The default storage driver for UID 0 is configured in
97       /etc/containers/storage.conf ($HOME/.config/containers/storage.conf  in
98       rootless  mode),  and is vfs for other users.  The STORAGE_DRIVER envi‐
99       ronment variable overrides the default.  The --storage-driver specified
100       driver overrides all.
101
102
103       Examples: "overlay", "devicemapper", "vfs"
104
105
106       Overriding this option will cause the storage-opt settings in /etc/con‐
107       tainers/storage.conf to be ignored.  The user must  specify  additional
108       options via the --storage-opt flag.
109
110
111       --storage-opt value
112
113
114       Storage driver option, Default storage driver options are configured in
115       /etc/containers/storage.conf ($HOME/.config/containers/storage.conf  in
116       rootless mode). The STORAGE_OPTS environment variable overrides the de‐
117       fault. The --storage-opt specified options overrides all.
118
119
120       --userns-uid-map mapping
121
122
123       Directly specifies a UID mapping which should be used to set ownership,
124       at the filesystem level, on the working container's contents.  Commands
125       run when handling RUN instructions will default to being run  in  their
126       own user namespaces, configured using the UID and GID maps.
127
128
129       Entries  in  this  map  take  the  form  of one or more colon-separated
130       triples of a starting in-container UID, a corresponding starting  host-
131       level UID, and the number of consecutive IDs which the map entry repre‐
132       sents.
133
134
135       This option overrides the remap-uids setting in the options section  of
136       /etc/containers/storage.conf.
137
138
139       If  this option is not specified, but a global --userns-uid-map setting
140       is supplied, settings from the global option will be used.
141
142
143       If none of --userns-uid-map-user, --userns-gid-map-group, or  --userns-
144       uid-map  are  specified, but --userns-gid-map is specified, the UID map
145       will be set to use the same numeric values as the GID map.
146
147
148       NOTE: When this option is specified by a rootless user,  the  specified
149       mappings  are  relative to the rootless usernamespace in the container,
150       rather than being relative to the host as it would be when run rootful.
151
152
153       --userns-gid-map mapping
154
155
156       Directly specifies a GID mapping which should be used to set ownership,
157       at the filesystem level, on the working container's contents.  Commands
158       run when handling RUN instructions will default to being run  in  their
159       own user namespaces, configured using the UID and GID maps.
160
161
162       Entries  in  this  map  take  the  form  of one or more colon-separated
163       triples of a starting in-container GID, a corresponding starting  host-
164       level GID, and the number of consecutive IDs which the map entry repre‐
165       sents.
166
167
168       This option overrides the remap-gids setting in the options section  of
169       /etc/containers/storage.conf.
170
171
172       If  this option is not specified, but a global --userns-gid-map setting
173       is supplied, settings from the global option will be used.
174
175
176       If none of --userns-uid-map-user, --userns-gid-map-group, or  --userns-
177       gid-map  are  specified, but --userns-uid-map is specified, the GID map
178       will be set to use the same numeric values as the UID map.
179
180
181       NOTE: When this option is specified by a rootless user,  the  specified
182       mappings  are  relative to the rootless usernamespace in the container,
183       rather than being relative to the host as it would be when run rootful.
184
185
186       --version, -v
187
188
189       Print the version
190
191

Environment Variables

193       Buildah can set up environment variables from the env entry in the [en‐
194       gine]  table in the containers.conf(5). These variables can be overrid‐
195       den by passing environment variables before the buildah commands.
196
197

COMMANDS

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

Files

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

SEE ALSO

337       containers.conf(5),      containers-mounts.conf(5),       newuidmap(1),
338       newgidmap(1), containers-registries.conf(5), containers-storage.conf(5)
339
340

HISTORY

342       December  2017,  Originally compiled by Tom Sweeney tsweeney@redhat.com
343       ⟨mailto:tsweeney@redhat.com⟩
344
345
346
347buildah                           March 2017                        buildah(1)
Impressum