Skip to content

Commit

Permalink
Update main userdocs
Browse files Browse the repository at this point in the history
  • Loading branch information
actions-user committed Mar 11, 2024
1 parent f382010 commit a443b59
Show file tree
Hide file tree
Showing 203 changed files with 326 additions and 254 deletions.
82 changes: 60 additions & 22 deletions public/docs/user/main/_sources/bind_paths_and_mounts.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion public/docs/user/main/_sources/cli/apptainer.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -76,4 +76,4 @@ SEE ALSO
* :ref:`apptainer verify <apptainer_verify>` - Verify digital signature(s) within an image
* :ref:`apptainer version <apptainer_version>` - Show the version for Apptainer

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
2 changes: 1 addition & 1 deletion public/docs/user/main/_sources/cli/apptainer_build.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -207,4 +207,4 @@ SEE ALSO
Linux container platform optimized for High Performance Computing (HPC) and
Enterprise Performance Computing (EPC)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
2 changes: 1 addition & 1 deletion public/docs/user/main/_sources/cli/apptainer_cache.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer cache clean <apptainer_cache_clean>` - Clean your local Apptainer cache
* :ref:`apptainer cache list <apptainer_cache_list>` - List your local Apptainer cache

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -48,4 +48,4 @@ SEE ALSO

* :ref:`apptainer cache <apptainer_cache>` - Manage the local cache

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,4 @@ SEE ALSO

* :ref:`apptainer cache <apptainer_cache>` - Manage the local cache

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer capability drop <apptainer_capability_drop>` - Remove capabilities from a user or group (requires root)
* :ref:`apptainer capability list <apptainer_capability_list>` - Show capabilities for a given user or group

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,4 @@ SEE ALSO

* :ref:`apptainer capability <apptainer_capability>` - Manage Linux capabilities for users and groups

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,4 @@ SEE ALSO

* :ref:`apptainer capability <apptainer_capability>` - Manage Linux capabilities for users and groups

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,4 @@ SEE ALSO

* :ref:`apptainer capability <apptainer_capability>` - Manage Linux capabilities for users and groups

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ SEE ALSO

* :ref:`apptainer capability <apptainer_capability>` - Manage Linux capabilities for users and groups

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer checkpoint instance <apptainer_checkpoint_instance>` - Checkpoint the state of a running instance (experimental)
* :ref:`apptainer checkpoint list <apptainer_checkpoint_list>` - List local checkpoints (experimental)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ SEE ALSO

* :ref:`apptainer checkpoint <apptainer_checkpoint>` - Manage container checkpoint state (experimental)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ SEE ALSO

* :ref:`apptainer checkpoint <apptainer_checkpoint>` - Manage container checkpoint state (experimental)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ SEE ALSO

* :ref:`apptainer checkpoint <apptainer_checkpoint>` - Manage container checkpoint state (experimental)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ SEE ALSO

* :ref:`apptainer checkpoint <apptainer_checkpoint>` - Manage container checkpoint state (experimental)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer config fakeroot <apptainer_config_fakeroot>` - Manage fakeroot user mappings entries (root user only)
* :ref:`apptainer config global <apptainer_config_global>` - Edit apptainer.conf from command line (root user only or unprivileged installation)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,4 @@ SEE ALSO

* :ref:`apptainer config <apptainer_config>` - Manage various apptainer configuration (root user only)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@ SEE ALSO

* :ref:`apptainer config <apptainer_config>` - Manage various apptainer configuration (root user only)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ SEE ALSO
Linux container platform optimized for High Performance Computing (HPC) and
Enterprise Performance Computing (EPC)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
2 changes: 1 addition & 1 deletion public/docs/user/main/_sources/cli/apptainer_exec.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -128,4 +128,4 @@ SEE ALSO
Linux container platform optimized for High Performance Computing (HPC) and
Enterprise Performance Computing (EPC)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -100,4 +100,4 @@ SEE ALSO
Linux container platform optimized for High Performance Computing (HPC) and
Enterprise Performance Computing (EPC)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer instance stats <apptainer_instance_stats>` - Get stats for a named instance
* :ref:`apptainer instance stop <apptainer_instance_stop>` - Stop a named instance of a given container image

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@ SEE ALSO

* :ref:`apptainer instance <apptainer_instance>` - Manage containers running as services

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -144,4 +144,4 @@ SEE ALSO

* :ref:`apptainer instance <apptainer_instance>` - Manage containers running as services

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -140,4 +140,4 @@ SEE ALSO

* :ref:`apptainer instance <apptainer_instance>` - Manage containers running as services

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,4 @@ SEE ALSO

* :ref:`apptainer instance <apptainer_instance>` - Manage containers running as services

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -56,4 +56,4 @@ SEE ALSO

* :ref:`apptainer instance <apptainer_instance>` - Manage containers running as services

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
2 changes: 1 addition & 1 deletion public/docs/user/main/_sources/cli/apptainer_key.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer key remove <apptainer_key_remove>` - Remove a local public key from your local or the global keyring
* :ref:`apptainer key search <apptainer_key_search>` - Search for keys on a key server

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -46,4 +46,4 @@ SEE ALSO

* :ref:`apptainer key <apptainer_key>` - Manage OpenPGP keys

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer keyserver logout <apptainer_keyserver_logout>` - Logout from a keyserver
* :ref:`apptainer keyserver remove <apptainer_keyserver_remove>` - Remove a keyserver (root user only)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,4 @@ SEE ALSO

* :ref:`apptainer keyserver <apptainer_keyserver>` - Manage apptainer keyservers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ SEE ALSO

* :ref:`apptainer keyserver <apptainer_keyserver>` - Manage apptainer keyservers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,4 @@ SEE ALSO

* :ref:`apptainer keyserver <apptainer_keyserver>` - Manage apptainer keyservers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ SEE ALSO

* :ref:`apptainer keyserver <apptainer_keyserver>` - Manage apptainer keyservers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ SEE ALSO

* :ref:`apptainer keyserver <apptainer_keyserver>` - Manage apptainer keyservers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
2 changes: 1 addition & 1 deletion public/docs/user/main/_sources/cli/apptainer_oci.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,4 @@ Enterprise Performance Computing (EPC)
* :ref:`apptainer oci umount <apptainer_oci_umount>` - Umount delete bundle (root user only)
* :ref:`apptainer oci update <apptainer_oci_update>` - Update container cgroups resources (root user only)

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ SEE ALSO

* :ref:`apptainer oci <apptainer_oci>` - Manage OCI containers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,4 @@ SEE ALSO

* :ref:`apptainer oci <apptainer_oci>` - Manage OCI containers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ SEE ALSO

* :ref:`apptainer oci <apptainer_oci>` - Manage OCI containers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ SEE ALSO

* :ref:`apptainer oci <apptainer_oci>` - Manage OCI containers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,4 @@ SEE ALSO

* :ref:`apptainer oci <apptainer_oci>` - Manage OCI containers

*Auto generated by spf13/cobra on 8-Mar-2024*
*Auto generated by spf13/cobra on 11-Mar-2024*
Loading

0 comments on commit a443b59

Please sign in to comment.