diff --git a/bind_paths_and_mounts.rst b/bind_paths_and_mounts.rst index 052eba87..58f8ccee 100755 --- a/bind_paths_and_mounts.rst +++ b/bind_paths_and_mounts.rst @@ -27,15 +27,27 @@ system-defined bind paths and user-defined bind paths. System-defined bind paths ************************* -The system administrator has the ability to define what bind paths will -be included automatically inside each container. Some bind paths are -automatically derived (e.g. a user's home directory) and some are -statically defined (e.g. bind paths in the {Project} configuration -file). In the default configuration, the system default bind points are -``$HOME`` , ``/sys:/sys`` , ``/proc:/proc``, ``/tmp:/tmp``, -``/var/tmp:/var/tmp``, ``/etc/resolv.conf:/etc/resolv.conf``, -``/etc/passwd:/etc/passwd``, and ``$PWD``. Where the first path before -``:`` is the path from the host and the second path is the path in the +The system administrator has the ability to define which bind paths will be +included automatically inside each container. Some bind paths are derived (e.g. +a user's home directory), and some are statically defined with a ``bind path`` +entry in the {Project} configuration. + +In the default configuration, the default bind mounts are: + +- The user's home directory (``$HOME``) +- The current working directory (``CWD``), unless its path contains symlinks + resolving to different locations on the host vs inside the container. +- ``/dev`` +- ``/etc/hosts`` +- ``/etc/localtime`` +- ``/proc`` +- ``/sys`` +- ``/tmp`` +- ``/var/tmp`` + +Additionally, customized system configuration files ``/etc/resolv.conf``, +``/etc/group``, and ``/etc/passwd`` are mounted into the container. These are +adapted at container startup to match the requested configuration of the container. Disabling System Binds @@ -249,32 +261,58 @@ Using ``--no-home`` and ``--containall`` flags ``--no-home`` ------------- -When shelling into your container image, {Project} allows you to -mount your current working directory (``CWD``) without mounting your -host ``$HOME`` directory with the ``--no-home`` flag. +When starting a container, {Project} allows you to mount your current +working directory (``CWD``) without mounting your host ``$HOME`` directory by +using the ``--no-home`` flag. This is equivalent to ``--no-mount home``: .. code:: $ {command} shell --no-home my_container.sif + -or- + + $ {command} shell --no-mount home my_container.sif + +Disabling the mount of ``$HOME`` may be useful if your container image has files +at ``$HOME``, which would otherwise be hidden by the bind mount from the host. + .. note:: - Beware that if it is the case that your ``CWD`` is your ``$HOME`` - directory, it will still mount your ``$HOME`` directory. + If your current working directory is under ``$HOME``, and you do not want to + mount it, you will need to disable both ``cwd`` and ``home`` mounts: + + .. code:: + + $ {command} shell --no-mount home,cwd my_container.sif + +``--contain`` / ``--containall`` +-------------------------------- -``--containall`` ----------------- +When using the ``--contain`` / ``--containall`` (or ``-c`` / ``-C`` for short) +flags, ``$HOME`` from the host is not mounted, and an in-memory temporary +directory is created at the ``$HOME`` point inside the container instead. An +in-memory temporary directory is also used for ``/tmp`` and ``/var/tmp`` inside +the container. - Using the ``--containall`` (or ``-C`` for short) flag, ``$HOME`` is - not mounted and a dummy bind mount is created at the ``$HOME`` point. - You cannot use ``-B``` (or ``--bind``) to bind your ``$HOME`` - directory because it creates an empty mount. So if you have files - located in the image at ``/home/user``, the ``--containall`` flag - will hide them all. +If the container image includes files within ``$HOME``, the mounted temporary +directory will hide them unless you also specify ``--no-home`` or ``--no-mount +home``: .. code:: $ {command} shell --containall my_container.sif + {Project}> ls -lah $HOME + total 4K + drwxr-xr-x 2 user group 60 Sep 1 11:45 . + drwxr-xr-x 1 user group 60 Sep 1 11:44 .. + + $ {command} shell --containall --no-home my_container.sif + {Project}> ls -lah $HOME + total 52K + drwxr-xr-x 2 user group 60 Sep 1 11:45 . + drwxr-xr-x 1 user group 60 Sep 1 11:44 .. + drwxr-xr-x 1 user group 38672 Sep 1 11:44 mydata.csv + drwxr-xr-x 1 user group 14235 Sep 1 11:44 myimage.jpg *********** FUSE mounts diff --git a/quick_start.rst b/quick_start.rst index f137049e..f653b291 100644 --- a/quick_start.rst +++ b/quick_start.rst @@ -416,9 +416,10 @@ Files on the host are reachable from within the container: Hello from inside the container -This example works because ``hostfile.txt`` exists in the user's home -directory. By default, {Project} bind mounts ``/home/$USER``, -``/tmp``, and ``$PWD`` into your container at runtime. +This example works because ``hostfile.txt`` exists in the user's home directory +(``$HOME``). By default, {Project} bind mounts ``$HOME``, the current +working directory, and additional system locations from the host into the +container. You can specify additional directories to bind mount into your container with the ``--bind`` option. In this example, the ``data`` directory on