Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs freshness updates 

Signed-off-by: Chris Chinchilla <chris.ward@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit e693e7f3b4)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Chris Chinchilla 2023-03-31 11:56:40 +02:00 committed by Sebastiaan van Stijn
parent 776388cc19
commit 6c0f9022c8
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 134 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

242
docs/reference/commandline/run.md
View File

@ -91,7 +91,7 @@ Create and run a new container from an image
| `-P`, `--publish-all` | | | Publish all exposed ports to random ports |
| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) |
| `-q`, `--quiet` | | | Suppress the pull output |
| `--read-only` | | | Mount the container's root filesystem as read only |
| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only |
| [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits |
| `--rm` | | | Automatically remove the container when it exits |
| `--runtime` | `string` | | Runtime to use for this container |
@ -118,14 +118,11 @@ Create and run a new container from an image
## Description
The `docker run` command first `creates` a writeable container layer over the
specified image, and then `starts` it using the specified command. That is,
`docker run` is equivalent to the API `/containers/create` then
`/containers/(id)/start`. A stopped container can be restarted with all its
previous changes intact using `docker start`. See `docker ps -a` to view a list
of all containers.
The `docker run` command runs a command in a new container, pulling the image if needed and starting the container.
You can restart a stopped container with all its previous changes intact using `docker start`.
Use `docker ps -a` to view a list of all containers, including those that are stopped.
For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/).
## Examples
@ -144,9 +141,9 @@ d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago
This example runs a container named `test` using the `debian:latest`
image. The `-it` instructs Docker to allocate a pseudo-TTY connected to
the container's stdin; creating an interactive `bash` shell in the container.
In the example, the `bash` shell is quit by entering
`exit 13`. This exit code is passed on to the caller of
`docker run`, and is recorded in the `test` container's metadata.
The example quits the `bash` shell by entering
`exit 13`, passing the exit code on to the caller of
`docker run`, and recording it in the `test` container's metadata.
### <a name="cidfile"></a> Capture container ID (--cidfile)
@ -154,9 +151,9 @@ In the example, the `bash` shell is quit by entering
$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
```
This will create a container and print `test` to the console. The `cidfile`
This creates a container and prints `test` to the console. The `cidfile`
flag makes Docker attempt to create a new file and write the container ID to it.
If the file exists already, Docker will return an error. Docker will close this
If the file exists already, Docker returns an error. Docker closes this
file when `docker run` exits.
### <a name="privileged"></a> Full container capabilities (--privileged)
@ -167,9 +164,9 @@ root@bc338942ef20:/# mount -t tmpfs none /mnt
mount: permission denied
```
This will *not* work, because by default, most potentially dangerous kernel
capabilities are dropped; including `cap_sys_admin` (which is required to mount
filesystems). However, the `--privileged` flag will allow it to run:
This *doesn't* work, because by default, Docker drops most potentially dangerous kernel
capabilities, including `CAP_SYS_ADMIN ` (which is required to mount
filesystems). However, the `--privileged` flag allows it to run:
```console
$ docker run -t -i --privileged ubuntu bash
@ -190,8 +187,8 @@ flag exists to allow special use-cases, like running Docker within Docker.
$ docker run -w /path/to/dir/ -i -t ubuntu pwd
```
The `-w` lets the command being executed inside directory given, here
`/path/to/dir/`. If the path does not exist it is created inside the container.
The `-w` option runs the command executed inside the directory specified, in this example,
`/path/to/dir/`. If the path does not exist, Docker creates it inside the container.
### <a name="storage-opt"></a> Set storage driver options per container (--storage-opt)
@ -199,14 +196,17 @@ The `-w` lets the command being executed inside directory given, here
$ docker run -it --storage-opt size=120G fedora /bin/bash
```
This (size) will allow to set the container filesystem size to 120G at creation time.
This (size) constraints the container filesystem size to 120G at creation time.
This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
`windowsfilter` and `zfs` graph drivers.
For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers,
user cannot pass a size less than the Default BaseFS Size.
`windowsfilter` and `zfs` storage drivers.
For the `overlay2` storage driver, the size option is only available if the
backing filesystem is `xfs` and mounted with the `pquota` mount option.
Under these conditions, user can pass any size less than the backing filesystem size.
Under these conditions, you can pass any size less than the backing filesystem size.
For the `windowsfilter`, `devicemapper`, `btrfs`, and `zfs` storage drivers,
you cannot pass a size less than the Default BaseFS Size.
### <a name="tmpfs"></a> Mount tmpfs (--tmpfs)
@ -217,32 +217,41 @@ $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`,
`noexec`, `nosuid`, `size=65536k` options.
### <a name="volume"></a> Mount volume (-v, --read-only)
### <a name="volume"></a> Mount volume (-v)
```console
$ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd
$ docker run -v $(pwd):$(pwd) -w $(pwd) -i -t ubuntu pwd
```
The `-v` flag mounts the current working directory into the container. The `-w`
lets the command being executed inside the current working directory, by
changing into the directory to the value returned by `pwd`. So this
combination executes the command using the container, but inside the
current working directory.
The example above mounts the current directory into the container at the same path
using the `-v` flag, sets it as the working directory, and then runs the `pwd` command inside the container.
As of Docker Engine version 23, you can use relative paths on the host.
```console
$ docker run -v ./content:/content -w /content -i -t ubuntu pwd
```
The example above mounts the `content` directory in the current directory into the container at the
`/content` path using the `-v` flag, sets it as the working directory, and then
runs the `pwd` command inside the container.
```console
$ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
```
When the host directory of a bind-mounted volume doesn't exist, Docker
will automatically create this directory on the host for you. In the
example above, Docker will create the `/doesnt/exist`
automatically creates this directory on the host for you. In the
example above, Docker creates the `/doesnt/exist`
folder before starting your container.
### <a name="read-only"></a> Mount volume read-only (--read-only)
```console
$ docker run --read-only -v /icanwrite busybox touch /icanwrite/here
```
Volumes can be used in combination with `--read-only` to control where
You can use volumes in combination with the `--read-only` flag to control where
a container writes files. The `--read-only` flag mounts the container's root
filesystem as read only prohibiting writes to locations other than the
specified volumes for the container.
@ -256,7 +265,7 @@ binary (refer to [get the Linux binary](https://docs.docker.com/engine/install/b
you give the container the full access to create and manipulate the host's
Docker daemon.
On Windows, the paths must be specified using Windows-style semantics.
On Windows, you must specify the paths using Windows-style path semantics.
```powershell
PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt
@ -266,9 +275,9 @@ PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.
Contents of file
```
The following examples will fail when using Windows-based containers, as the
The following examples fails when using Windows-based containers, as the
destination of a volume or bind mount inside the container must be one of:
a non-existing or empty directory; or a drive other than C:. Further, the source
a non-existing or empty directory; or a drive other than `C:`. Further, the source
of a bind mount must be a local directory, not a file.
```powershell
@ -282,13 +291,12 @@ docker run -v c:\foo:c:\existing-directory-with-contents ...
For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/)
### <a name="mount"></a> Add bind mounts or volumes using the --mount flag
The `--mount` flag allows you to mount volumes, host-directories and `tmpfs`
The `--mount` flag allows you to mount volumes, host-directories, and `tmpfs`
mounts in a container.
The `--mount` flag supports most options that are supported by the `-v` or the
The `--mount` flag supports most options supported by the `-v` or the
`--volume` flag, but uses a different syntax. For in-depth information on the
`--mount` flag, and a comparison between `--volume` and `--mount`, refer to
[Bind mounts](https://docs.docker.com/storage/bind-mounts/).
@ -314,10 +322,10 @@ $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash
This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host
machine. You can also specify `udp` and `sctp` ports.
The [Docker User Guide](https://docs.docker.com/network/links/)
explains in detail how to manipulate ports in Docker.
explains in detail how to use ports in Docker.
Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
`-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if
`-p 127.0.0.1:80:80`) are externally accessible. This also applies if
you configured UFW to block this specific port, as Docker manages its
own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
@ -345,7 +353,7 @@ When creating (and running) a container from an image, the daemon checks if the
image exists in the local image cache. If the image is missing, an error is
returned to the CLI, allowing it to initiate a pull.
The default (`missing`) is to only pull the image if it is not present in the
The default (`missing`) is to only pull the image if it's not present in the
daemon's image cache. This default allows you to run images that only exist
locally (for example, images you built from a Dockerfile, but that have not
been pushed to a registry), and reduces networking.
@ -378,7 +386,7 @@ $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array)
environment variables in the container you're running, or overwrite variables
that are defined in the Dockerfile of the image you're running.
defined in the Dockerfile of the image you're running.
You can define the variable and its value when running the container:
@ -388,7 +396,7 @@ VAR1=value1
VAR2=value2
```
You can also use variables that you've exported to your local environment:
You can also use variables exported to your local environment:
```console
export VAR1=value1
@ -402,7 +410,7 @@ VAR2=value2
When running the command, the Docker CLI client checks the value the variable
has in your local environment and passes it to the container.
If no `=` is provided and that variable is not exported in your local
environment, the variable won't be set in the container.
environment, the variable isn't set in the container.
You can also load the environment variables from a file. This file should use
the syntax `<variable>=value` (which sets the variable to the given value) or
@ -446,7 +454,7 @@ $ docker run --label-file ./labels ubuntu bash
The label-file format is similar to the format for loading environment
variables. (Unlike environment variables, labels are not visible to processes
running inside a container.) The following example illustrates a label-file
running inside a container.) The following example shows a label-file
format:
```console
@ -465,8 +473,9 @@ the Docker User Guide.
### <a name="network"></a> Connect a container to a network (--network)
When you start a container use the `--network` flag to connect it to a network.
The following commands create a network named `my-net`, and adds a `busybox` container
To start a container and connect it to a network, use the `--network` option.
The following commands create a network named `my-net` and adds a `busybox` container
to the `my-net` network.
```console
@ -484,7 +493,7 @@ $ docker run -itd --network=my-net --ip=10.10.9.75 busybox
If you want to add a running container to a network use the `docker network connect` subcommand.
You can connect multiple containers to the same network. Once connected, the
containers can communicate easily using only another container's IP address
containers can communicate using only another container's IP address
or name. For `overlay` networks or custom plugins that support multi-host
connectivity, containers connected to the same multi-host network but launched
from different Engines can also communicate in this way.
@ -498,6 +507,8 @@ from different Engines can also communicate in this way.
You can disconnect a container from a network using the `docker network
disconnect` command.
For more information on connecting a container to a network when using the `run` command, see the ["*Docker network overview*"](https://docs.docker.com/network/).
### <a name="volumes-from"></a> Mount volumes from container (--volumes-from)
```console
@ -505,13 +516,13 @@ $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ub
```
The `--volumes-from` flag mounts all the defined volumes from the referenced
containers. Containers can be specified by repetitions of the `--volumes-from`
containers. You can specify more than one container by repetitions of the `--volumes-from`
argument. The container ID may be optionally suffixed with `:ro` or `:rw` to
mount the volumes in read-only or read-write mode, respectively. By default,
the volumes are mounted in the same mode (read write or read only) as
Docker mounts the volumes in the same mode (read write or read only) as
the reference container.
Labeling systems like SELinux require that proper labels are placed on volume
Labeling systems like SELinux require placing proper labels 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, Docker does not change the labels set by the OS.
@ -541,17 +552,17 @@ only to the container's `STDIN`.
$ docker run -a stderr ubuntu echo test
```
This isn't going to print anything unless there's an error because we've
only attached to the `STDERR` of the container. The container's logs
still store what's been written to `STDERR` and `STDOUT`.
This isn't going to print anything to the console unless there's an error because output
is only attached to the `STDERR` of the container. The container's logs
still store what's written to `STDERR` and `STDOUT`.
```console
$ cat somefile | docker run -i -a stdin mybuilder dobuild
```
This is a way of using `--attach` to pipe a build file into a container.
The container's ID will be printed after the build is done and the build
logs could be retrieved using `docker logs`. This is
This example shows a way of using `--attach` to pipe a file into a container.
The command prints the container's ID after the build completes and you can retrieve
the build logs using `docker logs`. This is
useful if you need to pipe a file or something else into a container and
retrieve the container's ID once the container has finished running.
@ -571,15 +582,15 @@ brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd
crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/foobar
```
It is often necessary to directly expose devices to a container. The `--device`
option enables that. For example, a specific block storage device or loop
device or audio device can be added to an otherwise unprivileged container
It's often necessary to directly expose devices to a container. The `--device`
option enables that. For example, adding a specific block storage device or loop
device or audio device to an otherwise unprivileged container
(without the `--privileged` flag) and have the application directly access it.
By default, the container will be able to `read`, `write` and `mknod` these devices.
By default, the container is able to `read`, `write` and `mknod` these devices.
This can be overridden using a third `:rwm` set of options to each `--device`
flag. If the container is running in privileged mode, then the permissions specified
will be ignored.
flag. If the container is running in privileged mode, then Docker ignores the
specified permissions.
```console
$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc
@ -600,8 +611,8 @@ fdisk: unable to open /dev/xvdc: Operation not permitted
> **Note**
>
> The `--device` option cannot be safely used with ephemeral devices. Block devices
> that may be removed should not be added to untrusted containers with `--device`.
> The `--device` option cannot be safely used with ephemeral devices. You shouldn't
> add block devices that may be removed to untrusted containers with `--device`.
For Windows, the format of the string passed to the `--device` option is in
the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019
@ -612,8 +623,8 @@ Refer to the table defined in the [Windows container
docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers)
for a list of container-supported device interface class GUIDs.
If this option is specified for a process-isolated Windows container, _all_
devices that implement the requested device interface class GUID are made
If you specify this option for a process-isolated Windows container, Docker makes
_all_ devices that implement the requested device interface class GUID
available in the container. For example, the command below makes all COM
ports on the host visible in the container.
@ -628,16 +639,16 @@ PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.micro
### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule)
Devices available to a container are assigned at creation time. The
assigned devices will both be added to the cgroup.allow file and
created into the container once it is run. This poses a problem when
a new device needs to be added to running container.
Docker assigns devices available to a container at creation time. The
assigned devices are added to the cgroup.allow file and
created into the container when it runs. This poses a problem when
you need to add a new device to running container.
One of the solutions is to add a more permissive rule to a container
One solution is to add a more permissive rule to a container
allowing it access to a wider range of devices. For example, supposing
our container needs access to a character device with major `42` and
any number of minor number (added as new devices appear), the
following rule would be added:
the container needs access to a character device with major `42` and
any number of minor numbers (added as new devices appear), add the
following rule:
```console
$ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
@ -646,18 +657,19 @@ $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
the required device when it is added.
> **Note**: initially present devices still need to be explicitly added to the
> **Note**: You still need to explicitly add initially present devices to the
> `docker run` / `docker create` command.
### <a name="gpus"></a> Access an NVIDIA GPU
The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
Read [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
for more information.
To use `--gpus`, specify which GPUs (or all) to use. If no value is provided, all
available GPUs are used. The example below exposes all available GPUs.
To use `--gpus`, specify which GPUs (or all) to use. If you provide no value, Docker uses all
available GPUs. The example below exposes all available GPUs.
```console
$ docker run -it --rm --gpus all ubuntu nvidia-smi
@ -678,7 +690,7 @@ $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi
### <a name="restart"></a> Restart policies (--restart)
Use Docker's `--restart` to specify a container's *restart policy*. A restart
Use the `--restart` flag to specify a container's *restart policy*. A restart
policy controls whether the Docker daemon restarts a container after exit.
Docker supports the following restart policies:
@ -686,17 +698,17 @@ Docker supports the following restart policies:
|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `no` | Do not automatically restart the container when it exits. This is the default. |
| `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. |
| `unless-stopped` | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. |
| `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. |
| `unless-stopped` | Restart the container unless it's explicitly stopped or Docker itself is stopped or restarted. |
| `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon tries to restart the container indefinitely. The container always starts on daemon startup, regardless of the current state of the container. |
```console
$ docker run --restart=always redis
```
This will run the `redis` container with a restart policy of **always**
so that if the container exits, Docker will restart it.
so that if the container exits, Docker restarts it.
More detailed information on restart policies can be found in the
You can find more detailed information on restart policies in the
[Restart Policies (--restart)](../run.md#restart-policies---restart)
section of the Docker run reference page.
@ -742,8 +754,8 @@ for the bridge device).
Since setting `ulimit` settings in a container requires extra privileges not
available in the default container, you can set these using the `--ulimit` flag.
`--ulimit` is specified with a soft and hard limit as such:
`<type>=<soft limit>[:<hard limit>]`, for example:
Specify `--ulimit` with a soft and hard limit in the format
`<type>=<soft limit>[:<hard limit>]`. For example:
```console
$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
@ -752,21 +764,25 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
> **Note**
>
> If you do not provide a `hard limit`, the `soft limit` is used
> for both values. If no `ulimits` are set, they are inherited from
> the default `ulimits` set on the daemon. The `as` option is disabled now.
> If you don't provide a hard limit value, Docker uses the soft limit value
> for both values. If you don't provide any values, they are inherited from
> the default `ulimits` set on the daemon.
> **Note**
>
> The `as` option is deprecated.
> In other words, the following script is not supported:
>
> ```console
> $ docker run -it --ulimit as=1024 fedora /bin/bash
> ```
The values are sent to the appropriate `syscall` as they are set.
Docker doesn't perform any byte conversion. Take this into account when setting the values.
Docker sends the values to the appropriate OS `syscall` and doesn't perform any byte conversion.
Take this into account when setting the values.
#### For `nproc` usage
Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the
Be careful setting `nproc` with the `ulimit` flag as Linux uses `nproc` to set the
maximum number of processes available to a user, not to a container. For example, start four
containers with `daemon` user:
@ -780,36 +796,36 @@ $ docker run -d -u daemon --ulimit nproc=3 busybox top
$ docker run -d -u daemon --ulimit nproc=3 busybox top
```
The 4th container fails and reports "[8] System error: resource temporarily unavailable" error.
The 4th container fails and reports a "[8] System error: resource temporarily unavailable" error.
This fails because the caller set `nproc=3` resulting in the first three containers using up
the three processes quota set for the `daemon` user.
### <a name="stop-signal"></a> Stop container with signal (--stop-signal)
The `--stop-signal` flag sets the system call signal that will be sent to the
The `--stop-signal` flag sends the system call signal to the
container to exit. This signal can be a signal name in the format `SIG<NAME>`,
for instance `SIGKILL`, or an unsigned number that matches a position in the
kernel's syscall table, for instance `9`.
The default is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal)
The default value is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal)
in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined.
### <a name="security-opt"></a> Optional security options (--security-opt)
On Windows, this flag can be used to specify the `credentialspec` option.
On Windows, you can use this flag to specify the `credentialspec` option.
The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`.
### <a name="stop-timeout"></a> Stop container with timeout (--stop-timeout)
The `--stop-timeout` flag sets the number of seconds to wait for the container
to stop after sending the pre-defined (see `--stop-signal`) system call signal.
If the container does not exit after the timeout elapses, it is forcibly killed
If the container does not exit after the timeout elapses, it's forcibly killed
with a `SIGKILL` signal.
If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will
wait indefinitely for the container to exit.
If you set `--stop-timeout` to `-1`, no timeout is applied, and the daemon
waits indefinitely for the container to exit.
The default is determined by the daemon, and is 10 seconds for Linux containers,
The Daemon determines the default, and is 10 seconds for Linux containers,
and 30 seconds for Windows containers.
### <a name="isolation"></a> Specify isolation technology for container (--isolation)
@ -857,12 +873,12 @@ PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hy
### <a name="memory"></a> Specify hard limits on memory available to containers (-m, --memory)
These parameters always set an upper limit on the memory available to the container. On Linux, this
is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`.
These parameters always set an upper limit on the memory available to the container. Linux sets this
on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`.
On Windows, this will affect containers differently depending on what type of isolation is used.
On Windows, this affects containers differently depending on what type of isolation you use.
- With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container
- With `process` isolation, Windows reports the full memory of the host system, not the limit to applications running inside the container
```powershell
PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory*
@ -877,7 +893,7 @@ On Windows, this will affect containers differently depending on what type of is
OsMaxProcessMemorySize : 137438953344
```
- With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory."
- With `hyperv` isolation, Windows creates a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory."
```powershell
PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory*
@ -892,7 +908,6 @@ On Windows, this will affect containers differently depending on what type of is
OsMaxProcessMemorySize : 137438953344
```
### <a name="sysctl"></a> Configure namespaced kernel parameters (sysctls) at runtime (--sysctl)
The `--sysctl` sets namespaced kernel parameters (sysctls) in the
@ -909,6 +924,7 @@ $ docker run --sysctl net.ipv4.ip_forward=1 someimage
> inside of a container that also modify the host system. As the kernel
> evolves we expect to see more sysctls become namespaced.
#### Currently supported sysctls
IPC Namespace:
@ -922,3 +938,13 @@ Network Namespace:
- Sysctls beginning with `net.*`
- If you use the `--network=host` option using these sysctls are not allowed.
## Command internals
The `docker run` command is equivalent to the following API calls:
- `/<API version>/containers/create`
- If that call returns a 404 (image not found), and depending on the `--pull` option ("always", "missing", "never") the call can trigger a `docker pull <image>`.
- `/containers/create` again after pulling the image.
- `/containers/(id)/start` to start the container.
- `/containers/(id)/attach` to attach to the container when starting with the `-it` flags for interactive containers.