Skip to content

storage: document opts with --tmpfs #21676

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 20, 2024
Merged

storage: document opts with --tmpfs #21676

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
72786ec
storage: document how to set mount opts with --tmpfs
dvdksn Dec 20, 2024
dc28d62
storage: use different formatting template when inspecting --tmpfs mount
dvdksn Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 70 additions & 9 deletions content/manuals/engine/storage/tmpfs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,67 @@
```

In general, `--mount` is preferred. The main difference is that the `--mount`
flag is more explicit and supports all the available options.
flag is more explicit. On the other hand, `--tmpfs` is less verbose and gives
you more flexibility as it lets you set more mount options.

The `--tmpfs` flag cannot be used with swarm services. You must use `--mount`.

### Options for --tmpfs

The `--tmpfs` flag consists of two fields, separated by a colon character
(`:`).

```console
$ docker run --tmpfs <mount-path>[:opts]
```

The first field is the container path to mount into a tmpfs. The second field
is optional and lets you set mount options. Valid mount options for `--tmpfs`
include:

| Option | Description |
| ------------ | ------------------------------------------------------------------------------------------- |
| `ro` | Creates a read-only tmpfs mount. |
| `rw` | Creates a read-write tmpfs mount (default behavior). |
| `nosuid` | Prevents `setuid` and `setgid` bits from being honored during execution. |
| `suid` | Allows `setuid` and `setgid` bits to be honored during execution (default behavior). |

Check warning on line 86 in content/manuals/engine/storage/tmpfs.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'lets' instead of 'Allows'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'lets' instead of 'Allows'", "location": {"path": "content/manuals/engine/storage/tmpfs.md", "range": {"start": {"line": 86, "column": 18}}}, "severity": "INFO"}
| `nodev` | Device files can be created but are not functional (access results in an error). |
| `dev` | Device files can be created and are fully functional. |
| `exec` | Allows the execution of executable binaries in the mounted file system. |

Check warning on line 89 in content/manuals/engine/storage/tmpfs.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'lets' instead of 'Allows'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'lets' instead of 'Allows'", "location": {"path": "content/manuals/engine/storage/tmpfs.md", "range": {"start": {"line": 89, "column": 18}}}, "severity": "INFO"}
| `noexec` | Does not allow the execution of executable binaries in the mounted file system. |

Check warning on line 90 in content/manuals/engine/storage/tmpfs.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'let' instead of 'allow'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'let' instead of 'allow'", "location": {"path": "content/manuals/engine/storage/tmpfs.md", "range": {"start": {"line": 90, "column": 27}}}, "severity": "INFO"}
| `sync` | All I/O to the file system is done synchronously. |
| `async` | All I/O to the file system is done asynchronously (default behavior). |
| `dirsync` | Directory updates within the file system are done synchronously. |
| `atime` | Updates file access time each time the file is accessed. |
| `noatime` | Does not update file access times when the file is accessed. |
| `diratime` | Updates directory access times each time the directory is accessed. |
| `nodiratime` | Does not update directory access times when the directory is accessed. |
| `size` | Specifies the size of the tmpfs mount, for example, `size=64m`. |
| `mode` | Specifies the file mode (permissions) for the tmpfs mount (for example, `mode=1777`). |
| `uid` | Specifies the user ID for the owner of the tmpfs mount (for example, `uid=1000`). |
| `gid` | Specifies the group ID for the owner of the tmpfs mount (for example, `gid=1000`). |
| `nr_inodes` | Specifies the maximum number of inodes for the tmpfs mount (for example, `nr_inodes=400k`). |

Check failure on line 102 in content/manuals/engine/storage/tmpfs.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'inodes'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'inodes'?", "location": {"path": "content/manuals/engine/storage/tmpfs.md", "range": {"start": {"line": 102, "column": 50}}}, "severity": "ERROR"}
| `nr_blocks` | Specifies the maximum number of blocks for the tmpfs mount (for example, `nr_blocks=1024`). |

```console {title="Example"}
$ docker run --tmpfs /data:noexec,size=1024,mode=1777
```

Not all tmpfs mount features available in the Linux mount command are supported
with the `--tmpfs` flag. If you require advanced tmpfs options or features, you
may need to use a privileged container or configure the mount outside of
Docker.

> [!CAUTION]
> Running containers with `--privileged` grants elevated permissions and can
> expose the host system to security risks. Use this option only when
> absolutely necessary and in trusted environments.

```console
$ docker run --privileged -it debian sh
/# mount -t tmpfs -o <options> tmpfs /data
```

### Options for --mount

The `--mount` flag consists of multiple key-value pairs, separated by commas
Expand All @@ -86,10 +143,6 @@
$ docker run --mount type=tmpfs,dst=/app,tmpfs-size=21474836480,tmpfs-mode=1770
```

### Options for --tmpfs

The `--tmpfs` flag does not let you specify any options.

## Use a tmpfs mount in a container

To use a `tmpfs` mount in a container, use the `--tmpfs` flag, or use the
Expand All @@ -109,6 +162,14 @@
nginx:latest
```

Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of
the `docker inspect` output:

```console
$ docker inspect tmptest --format '{{ json .Mounts }}'
[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}]
```

{{< /tab >}}
{{< tab name="`--tmpfs`" >}}

Expand All @@ -120,17 +181,17 @@
nginx:latest
```

{{< /tab >}}
{{< /tabs >}}

Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of
the `docker inspect` output:

```console
$ docker inspect tmptest --format '{{ json .Mounts }}'
[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}]
{"/app":""}
```

{{< /tab >}}
{{< /tabs >}}

Stop and remove the container:

```console
Expand Down