buildah-run - Run a command inside of the container.
buildah run [
options] [
--]
container command
Launches a container and runs the specified command in that container using the
container's root filesystem as a root filesystem, using configuration settings
inherited from the container's image or as specified using previous calls to
the
buildah config command. To execute
buildah run within an
interactive shell, specify the --tty option.
--add-history
Add an entry to the history which will note what command is being invoked.
Defaults to false.
Note: You can also override the default value of --add-history by setting the
BUILDAH_HISTORY environment variable.
export BUILDAH_HISTORY=true
--cap-add=
CAP_xxx
Add the specified capability to the set of capabilities which will be granted to
the specified command. Certain capabilities are granted by default; this
option can be used to add more beyond the defaults, which may have been
modified by
--cap-add and
--cap-drop options used with the
buildah from invocation which created the container.
--cap-drop=
CAP_xxx
Add the specified capability from the set of capabilities which will be granted
to the specified command. The CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE,
CAP_FOWNER, CAP_FSETID, CAP_KILL, CAP_MKNOD, CAP_NET_BIND_SERVICE,
CAP_SETFCAP, CAP_SETGID, CAP_SETPCAP, CAP_SETUID, and CAP_SYS_CHROOT
capabilities are granted by default; this option can be used to remove them
from the defaults, which may have been modified by
--cap-add and
--cap-drop options used with the
buildah from invocation which
created the container.
If a capability is specified to both the
--cap-add and
--cap-drop
options, it will be dropped, regardless of the order in which the options were
given.
--cgroupns how
Sets the configuration for the cgroup namespaces for the container. The
configured value can be "" (the empty string) or "private"
to indicate that a new cgroup namespace should be created, or it can be
"host" to indicate that the cgroup namespace in which
buildah
itself is being run should be reused.
--contextdir directory
Allows setting context directory for current RUN invocation. Specifying a
context directory causes RUN context to consider context directory as root
directory for specified source in
--mount of type 'bind'.
--env,
-e env=value
Temporarily add a value (e.g. env=
value) to the environment for the
running process. Unlike
buildah config --env, the environment will not
persist to later calls to
buildah run or to the built image. Can be
used multiple times.
--hostname
Set the hostname inside of the running container.
--ipc how
Sets the configuration for the IPC namespaces for the container. The configured
value can be "" (the empty string) or "private" to
indicate that a new IPC namespace should be created, or it can be
"host" to indicate that the IPC namespace in which
buildah
itself is being run should be reused, or it can be the path to an IPC
namespace which is already in use by another process.
--isolation type
Controls what type of isolation is used for running the process. Recognized
types include
oci (OCI-compatible runtime, the default),
rootless (OCI-compatible runtime invoked using a modified
configuration, with
--no-new-keyring added to its
create
invocation, reusing the host's network and UTS namespaces, and creating
private IPC, PID, mount, and user namespaces; the default for unprivileged
users), and
chroot (an internal wrapper that leans more toward
chroot(1) than container technology, reusing the host's control group,
network, IPC, and PID namespaces, and creating private mount and UTS
namespaces, and creating user namespaces only when they're required for ID
mapping).
Note: You can also override the default isolation type by setting the
BUILDAH_ISOLATION environment variable.
export BUILDAH_ISOLATION=oci
--mount=
type=TYPE,TYPE-SPECIFIC-OPTION[,...]
Attach a filesystem mount to the container
Current supported mount TYPES are bind, cache, secret and tmpfs. [1]
⟨#Footnote1⟩
e.g.
type=bind,source=/path/on/host,destination=/path/in/container
type=tmpfs,tmpfs-size=512M,destination=/path/in/container
type=cache,target=/path/in/container
Common Options:
· src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
· dst, destination, target: mount destination spec.
· ro, read-only: true or false (default).
Options specific to bind:
· bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
. bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
· from: stage or image name for the root of the source. Defaults to the build context.
· z: Set shared SELinux label on mounted destination. Use if SELinux is enabled on host machine.
· Z: Set private SELinux label on mounted destination. Use if SELinux is enabled on host machine.
Options specific to tmpfs:
· tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
· tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
· tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
Options specific to secret:
· id: the identifier for the secret passed into the `buildah bud --secret` or `podman build --secret` command.
Options specific to cache:
· id: Create a separate cache directory for a particular id.
· mode: File mode for new cache directory in octal. Default 0755.
· ro, readonly: read only cache if set.
· uid: uid for cache directory.
· gid: gid for cache directory.
· from: stage name for the root of the source. Defaults to host cache directory.
· z: Set shared SELinux label on mounted destination. Enabled by default if SELinux is enabled on the host machine.
· Z: Set private SELinux label on mounted destination. Use if SELinux is enabled on host machine.
--network,
--net=
mode
Sets the configuration for the network namespace for the container.
- •
-
none: no networking;
- •
-
host: use the host network stack. Note: the host
mode gives the container full access to local system services such as
D-bus and is therefore considered insecure;
- •
-
ns:path: path to a network namespace to
join;
- •
-
private: create a new namespace for the container
(default)
--no-hosts
Do not create
/etc/hosts for the container.
By default, Buildah manages
/etc/hosts, adding the container's own IP
address.
--no-hosts disables this, and the image's
/etc/hosts
will be preserved unmodified.
--no-pivot
Do not use pivot root to jail process inside rootfs. This should be used
whenever the rootfs is on top of a ramdisk.
Note: You can make this option the default by setting the BUILDAH_NOPIVOT
environment variable.
export BUILDAH_NOPIVOT=true
--pid how
Sets the configuration for the PID namespace for the container. The configured
value can be "" (the empty string) or "private" to
indicate that a new PID namespace should be created, or it can be
"host" to indicate that the PID namespace in which
buildah
itself is being run should be reused, or it can be the path to a PID namespace
which is already in use by another process.
--runtime path
The
path to an alternate OCI-compatible runtime. Default is
runc,
or
crun when machine is configured to use cgroups V2.
Note: You can also override the default runtime by setting the BUILDAH_RUNTIME
environment variable.
export BUILDAH_RUNTIME=/usr/bin/crun
--runtime-flag flag
Adds global flags for the container runtime. To list the supported flags, please
consult the manpages of the selected container runtime. Note: Do not pass the
leading
-- to the flag. To pass the runc flag
--log-format json
to buildah run, the option given would be
--runtime-flag
log-format=json.
--tty,
--terminal,
-t
By default a pseudo-TTY is allocated only when buildah's standard input is
attached to a pseudo-TTY. Setting the
--tty option to
true will
cause a pseudo-TTY to be allocated inside the container connecting the user's
"terminal" with the stdin and stdout stream of the container.
Setting the
--tty option to
false will prevent the pseudo-TTY
from being allocated.
--user user[:
group]
Set the
user to be used for running the command in the container. The
user can be specified as a user name or UID, optionally followed by a group
name or GID, separated by a colon (':'). If names are used, the container
should include entries for those names in its
/etc/passwd and
/etc/group files.
--uts how
Sets the configuration for the UTS namespace for the container. The configured
value can be "" (the empty string) or "private" to
indicate that a new UTS namespace should be created, or it can be
"host" to indicate that the UTS namespace in which
buildah
itself is being run should be reused, or it can be the path to a UTS namespace
which is already in use by another process.
--volume,
-v source:
destination:
options
Create a bind mount. If you specify,
-v /HOST-DIR:/CONTAINER-DIR, Buildah
bind mounts
/HOST-DIR in the host to
/CONTAINER-DIR in the
Buildah container. The
OPTIONS are a comma delimited list and can be:
[1] ⟨#Footnote1⟩
- •
- [rw|ro]
- •
- [U]
- •
- [z|Z]
- •
- [[r]shared|[r]slave|[r]private]
The
CONTAINER-DIR must be an absolute path such as
/src/docs. The
HOST-DIR must be an absolute path as well. Buildah bind-mounts the
HOST-DIR to the path you specify. For example, if you supply
/foo as the host path, Buildah copies the contents of
/foo to
the container filesystem on the host and bind mounts that into the container.
You can specify multiple
-v options to mount one or more mounts to a
container.
Write Protected Volume Mounts
You can add the
:ro or
:rw suffix to a volume to mount it
read-only or read-write mode, respectively. By default, the volumes are
mounted read-write. See examples.
Chowning Volume Mounts
By default, Buildah does not change the owner and group of source volume
directories mounted into containers. If a container is created in a new user
namespace, the UID and GID in the container may correspond to another UID and
GID on the host.
The
:U suffix tells Buildah to use the correct host UID and GID based on
the UID and GID within the container, to change the owner and group of the
source volume.
Labeling Volume Mounts
Labeling systems like SELinux require that proper labels are placed on volume
content mounted into a container. Without a label, the security system might
prevent the processes running inside the container from using the content. By
default, Buildah does not change the labels set by the OS.
To change a label in the container context, you can add either of two suffixes
:z or
:Z to the volume mount. These suffixes tell Buildah to
relabel file objects on the shared volumes. The
z option tells Buildah
that two containers share the volume content. As a result, Buildah labels the
content with a shared content label. Shared volume labels allow all containers
to read/write content. The
Z option tells Buildah to label the content
with a private unshared label. Only the current container can use a private
volume.
By default bind mounted volumes are
private. That means any mounts done
inside container will not be visible on the host and vice versa. This behavior
can be changed by specifying a volume mount propagation property.
When the mount propagation policy is set to
shared, any mounts completed
inside the container on that volume will be visible to both the host and
container. When the mount propagation policy is set to
slave, one way
mount propagation is enabled and any mounts completed on the host for that
volume will be visible only inside of the container. To control the mount
propagation property of the volume use the
:[r]shared,
:[r]slave
or
:[r]private propagation flag. The propagation property can be
specified only for bind mounted volumes and not for internal volumes or named
volumes. For mount propagation to work on the source mount point (the mount
point where source dir is mounted on) it has to have the right propagation
properties. For shared volumes, the source mount point has to be shared. And
for slave volumes, the source mount has to be either shared or slave. [1]
⟨#Footnote1⟩
Use
df <source-dir> to determine the source mount and then use
findmnt -o TARGET,PROPAGATION <source-mount-dir> to determine
propagation properties of source mount, if
findmnt utility is not
available, the source mount point can be determined by looking at the mount
entry in
/proc/self/mountinfo. Look at
optional fields and see
if any propagation properties are specified.
shared:X means the mount
is
shared,
master:X means the mount is
slave and if
nothing is there that means the mount is
private. [1]
⟨#Footnote1⟩
To change propagation properties of a mount point use the
mount command.
For example, to bind mount the source directory
/foo do
mount
--bind /foo /foo and
mount --make-private --make-shared /foo. This will
convert /foo into a
shared mount point. The propagation properties of
the source mount can be changed directly. For instance if
/ is the
source mount for
/foo, then use
mount --make-shared / to convert
/ into a
shared mount.
--workingdir directory
Temporarily set the working
directory for the running process. Unlike
buildah config --workingdir, the workingdir will not persist to later
calls to
buildah run or the built image.
NOTE: End parsing of options with the
-- option, so that other options
can be passed to the command inside of the container.
buildah run containerID -- ps -auxw
buildah run --hostname myhost containerID -- ps -auxw
buildah run containerID -- sh -c 'echo $PATH'
buildah run --runtime-flag log-format=json containerID /bin/bash
buildah run --runtime-flag debug containerID /bin/bash
buildah run --tty containerID /bin/bash
buildah run --tty=false containerID ls /
buildah run --volume /path/on/host:/path/in/container:ro,z containerID sh
buildah run -v /path/on/host:/path/in/container:z,U containerID sh
buildah run --mount type=bind,src=/tmp/on:host,dst=/in:container,ro containerID
sh
buildah(1),
buildah-from(1),
buildah-config(1),
namespaces(7),
pid_namespaces(7),
crun(1),
runc(8)
1: The Buildah project is committed to inclusivity, a core value of open source.
The
master and
slave mount propagation terminology used here is
problematic and divisive, and should be changed. However, these terms are
currently used within the Linux kernel and must be used as-is at this time.
When the kernel maintainers rectify this usage, Buildah will follow suit
immediately.