Merge pull request #21676 from dvdksn/tmpfs-default-mountopts

storage: document opts with --tmpfs

Author: dvdksn

content/manuals/engine/storage/tmpfs.md

@@ -60,10 +60,67 @@ $ docker run --tmpfs <mount-path>
 ```
 
 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).        |
+| `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.                     |
+| `noexec`     | Does not allow the execution of executable binaries in the mounted file system.             |
+| `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`). |
+| `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
@@ -86,10 +143,6 @@ Valid options for `--mount type=tmpfs` include:
 $ 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
@@ -109,6 +162,14 @@ $ docker run -d \
   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`" >}}
 
@@ -120,17 +181,17 @@ $ docker run -d \
   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