From a8d76b496c849a6d10c676be53ce904304bd3311 Mon Sep 17 00:00:00 2001 From: preminger Date: Tue, 14 Mar 2023 21:37:00 -0400 Subject: [PATCH] updated heading style Signed-off-by: Edita Kizinevic --- Makefile | 2 +- appendix.rst | 20 +++++------ bind_paths_and_mounts.rst | 38 ++++++++++----------- build_a_container.rst | 62 +++++++++++++++++------------------ build_env.rst | 44 ++++++++++++------------- cgroups.rst | 52 ++++++++++++++--------------- checkpoint.rst | 12 +++---- cli.rst | 6 ++-- contributing.rst | 32 +++++++++--------- definition_files.rst | 42 ++++++++++++------------ docker_and_oci.rst | 62 +++++++++++++++++------------------ encryption.rst | 24 +++++++------- endpoint.rst | 32 +++++++++--------- environment_and_metadata.rst | 60 ++++++++++++++++----------------- fakeroot.rst | 32 +++++++++--------- gpu.rst | 34 +++++++++---------- index.rst | 56 +++++++++++++++---------------- introduction.rst | 24 +++++++------- key_commands.rst | 30 ++++++++--------- library_api.rst | 36 ++++++++++---------- license.rst | 18 +++++----- mpi.rst | 42 ++++++++++++------------ networking.rst | 36 ++++++++++---------- oci_runtime.rst | 32 +++++++++--------- persistent_overlays.rst | 30 ++++++++--------- plugins.rst | 36 ++++++++++---------- quick_start.rst | 42 ++++++++++++------------ running_services.rst | 36 ++++++++++---------- security.rst | 52 ++++++++++++++--------------- security_options.rst | 24 +++++++------- signNverify.rst | 22 ++++++------- singularity_compatibility.rst | 30 ++++++++--------- 32 files changed, 550 insertions(+), 550 deletions(-) diff --git a/Makefile b/Makefile index 71fa4023..8208710e 100755 --- a/Makefile +++ b/Makefile @@ -61,7 +61,7 @@ apptainer_source/builddir/apptainer: cli/apptainer.rst: apptainer_source/builddir/apptainer cd apptainer_source &&\ - go run -tags "$(GO_BUILD_TAGS)" ./cmd/docs rst --dir ../cli + go run -tags "$(GO_BUILD_TAGS)" ./cmd/docs rst --dir ../cli endif diff --git a/appendix.rst b/appendix.rst index 25be229d..a833db4c 100755 --- a/appendix.rst +++ b/appendix.rst @@ -1,17 +1,17 @@ .. _appendix: -########## - Appendix -########## +######## +Appendix +######## .. TODO oci & oci-archive along with http & https .. _{command}-environment-variables: -*************************************** - {Project}'s environment variables -*************************************** +************************************* +{Project}'s environment variables +************************************* {Project} comes with some environment variables you can set or modify depending on your needs. You can see them listed alphabetically @@ -391,9 +391,9 @@ below with their respective functionality. .. _buildmodules: -*************** - Build Modules -*************** +************* +Build Modules +************* .. _build-library-module: @@ -978,7 +978,7 @@ The ``{ENVPREFIX}_DOCKER_HOST`` or ``DOCKER_HOST`` environment variables may be set to instruct {{Project}} to pull images from a Docker daemon that is not running at the default location. For example, when using a virtualized Docker you may be instructed to set ``DOCKER_HOST`` e.g. -.. code:: +.. code:: To connect the Docker client to the Docker daemon, please set export DOCKER_HOST=tcp://192.168.59.103:2375 diff --git a/bind_paths_and_mounts.rst b/bind_paths_and_mounts.rst index 6b9d353b..5a7dd9e7 100755 --- a/bind_paths_and_mounts.rst +++ b/bind_paths_and_mounts.rst @@ -1,8 +1,8 @@ .. _bind-paths-and-mounts: -####################### - Bind Paths and Mounts -####################### +##################### +Bind Paths and Mounts +##################### .. _sec:bindpaths: @@ -12,9 +12,9 @@ Unless `disabled by the system administrator directories within your container using bind mounts. This allows you to read and write data on the host system with ease. -********** - Overview -********** +******** +Overview +******** When {Project} 'swaps' the host operating system for the one inside your container, the host file systems becomes inaccessible. However, you @@ -23,9 +23,9 @@ container. To enable this functionality, {Project} will bind directories back into the container via two primary methods: system-defined bind paths and user-defined bind paths. -*************************** - System-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 @@ -82,9 +82,9 @@ To disable all ``bind path`` entries set in ``{command}.conf``, use .. _user-defined-bind-paths: -************************* - User-defined bind paths -************************* +*********************** +User-defined bind paths +*********************** Unless the system administrator has `disabled user control of binds <{admindocs}/configfiles.html#bind-mount-management>`_, @@ -267,9 +267,9 @@ host ``$HOME`` directory with the ``--no-home`` flag. $ {command} shell --containall my_container.sif -************* - FUSE mounts -************* +*********** +FUSE mounts +*********** Filesystem in Userspace (FUSE) is an interface to allow filesystems to be mounted using code that runs in userspace, rather than in the Linux @@ -301,7 +301,7 @@ into the container. If you are using an older distribution that provides FUSE commands such as ``sshfs`` based on FUSE 2 then you can install FUSE 3 versions of the commands you need inside your container. EL7 distributions can install a -compatible version of FUSE 3 from the EPEL repository. +compatible version of FUSE 3 from the EPEL repository. FUSE mount definitions ====================== @@ -366,9 +366,9 @@ added to your container, you can use the ``container`` mount type: {Project}> cat /server/etc/hostname server -************** - Image Mounts -************** +************ +Image Mounts +************ In {Project} you can mount a directory contained in an image file into a container. This may be useful if you want to diff --git a/build_a_container.rst b/build_a_container.rst index a4caf5be..7779518b 100755 --- a/build_a_container.rst +++ b/build_a_container.rst @@ -1,8 +1,8 @@ .. _build-a-container: -################### - Build a Container -################### +################# +Build a Container +################# .. _sec:build_a_container: @@ -14,9 +14,9 @@ You can use it to convert containers between the formats supported by ` file to create a container from scratch and customized it to fit your needs. -********** - Overview -********** +******** +Overview +******** The ``build`` command accepts a target as input and produces a container as output. @@ -44,9 +44,9 @@ Because ``build`` can accept an existing container as a target and create a container in either supported format you can convert existing containers from one format to another. -*************************************************** - Downloading an existing container from Docker Hub -*************************************************** +************************************************* +Downloading an existing container from Docker Hub +************************************************* You can use ``build`` to download layers from Docker Hub and assemble them into {Project} containers. @@ -55,9 +55,9 @@ them into {Project} containers. $ {command} build alpine.sif docker://alpine -*************************************************************** - Downloading an existing container from a Library API Registry -*************************************************************** +************************************************************* +Downloading an existing container from a Library API Registry +************************************************************* If you have set up a library remote endpoint as described in :ref:`Managing Remote Endpoints `, @@ -76,9 +76,9 @@ container in a writable format use the ``--sandbox`` option. .. _create_a_writable_container: -********************************************* - Creating writable ``--sandbox`` directories -********************************************* +******************************************* +Creating writable ``--sandbox`` directories +******************************************* If you wanted to create a container within a writable directory (called a sandbox) you can do so with the ``--sandbox`` option. @@ -95,9 +95,9 @@ invoke your container. $ {command} shell --writable alpine/ -************************************************** - Converting containers from one format to another -************************************************** +************************************************ +Converting containers from one format to another +************************************************ If you already have a container saved locally, you can use it as a target to build a new container. This allows you convert containers from @@ -116,9 +116,9 @@ rendering your container non-reproducible. It is a best practice to build your immutable production containers directly from {aProject} definition file instead. -********************************************************* - Building containers from {Project} definition files -********************************************************* +******************************************************* +Building containers from {Project} definition files +******************************************************* Of course, {Project} definition files can be used as the target when building a container. For detailed information on writing {Project} @@ -158,20 +158,20 @@ You can do so with the following command. trying to run that image on a node where the only compressor available is ``gzip``. -******************************* - Building encrypted containers -******************************* +***************************** +Building encrypted containers +***************************** With {aProject} setuid installation it is possible to build and run -encrypted containers. +encrypted containers. Encrypted containers are decrypted at runtime entirely in kernel space, meaning that no intermediate decrypted data is ever present on disk. See :ref:`encrypted containers ` for more details. -*************** - Build options -*************** +************* +Build options +************* ``--encrypt`` ============= @@ -336,9 +336,9 @@ tmpfs overlay filesystem in place. This allows the tests to create files, which will be discarded at the end of the build. Other portions of the build do not use this temporary filesystem. -******************* - More Build topics -******************* +***************** +More Build topics +***************** - If you want to **customize the cache location** (where Docker layers are downloaded on your system), specify Docker credentials, or any diff --git a/build_env.rst b/build_env.rst index 89f548ac..4e88329d 100644 --- a/build_env.rst +++ b/build_env.rst @@ -1,14 +1,14 @@ .. _build-environment: -################### - Build Environment -################### +################# +Build Environment +################# .. _sec:buildenv: -********** - Overview -********** +******** +Overview +******** You may wish to customize your build environment by doing things such as specifying a custom cache directory for images or sending your Docker @@ -17,9 +17,9 @@ other topics related to the build environment. .. _sec:cache: -*************** - Cache Folders -*************** +************* +Cache Folders +************* {Project} will cache SIF container images generated from remote sources, and any OCI/docker layers used to create them. The cache is @@ -102,9 +102,9 @@ file: rm ~/.local/share/containers/cache/blob-info-cache-v1.boltdb -**************** - Cache commands -**************** +************** +Cache commands +************** The ``cache`` command for {Project} allows you to view and clean up your cache, without manually inspecting the cache directories. @@ -212,14 +212,14 @@ use the ``--type`` / ``-T`` option: .. _sec:temporaryfolders: -******************* - Temporary Folders -******************* +***************** +Temporary Folders +***************** When building a container, or pulling/running {aProject} container from a Docker/OCI source, a temporary working space is required. The container is constructed in this temporary space before being packaged -into {aProject} SIF image. +into {aProject} SIF image. The location for temporary directories defaults to ``/tmp``. {Project} will also respect the environment variable ``TMPDIR``, and @@ -248,9 +248,9 @@ Remember to use ``-E`` option to pass the value of Set ``{ENVPREFIX}_TMPDIR`` to a disk location, or disable the ``tmpfs`` ``/tmp`` mount on your system if you experience problems. -********************** - Encrypted Containers -********************** +******************** +Encrypted Containers +******************** With {aProject} setuid installation it is possible to build and run encrypted containers. The containers are decrypted at runtime entirely @@ -258,9 +258,9 @@ in kernel space, meaning that no intermediate decrypted data is ever present on disk. See :ref:`encrypted containers ` for more details. -*********************** - Environment Variables -*********************** +********************* +Environment Variables +********************* #. If a flag is represented by both a CLI option and an environment variable, and both are set, the CLI option will always take diff --git a/cgroups.rst b/cgroups.rst index 572b74c0..6e5461be 100644 --- a/cgroups.rst +++ b/cgroups.rst @@ -1,8 +1,8 @@ .. _cgroups: -############################## - Limiting Container Resources -############################## +############################ +Limiting Container Resources +############################ It's often useful to limit the resources that are consumed by a container, e.g. to allow the container to only use 1 CPU, or 50% of the RAM on the system. @@ -23,16 +23,16 @@ There are three ways to apply limits to a container that is run with {Project}: * Using per-resource command line limit flags described below. - + * Using the ``--apply-cgroups`` flag to apply a ``cgroups.toml`` file that defines the resource limits. * Using external tools such as ``systemd-run`` tool to apply limits, and then call ``{command}``. -****************************** - Requirements - Linux Cgroups -****************************** +**************************** +Requirements - Linux Cgroups +**************************** Resource limits are applied to containers using functionality in the Linux kernel known as *control groups* or *cgroups*. There are two versions of @@ -61,9 +61,9 @@ satisfy these criteria by default. On older distributions support can often be enabled. Consult the admin documentation or speak to your system administrator about this. -*************************** - Command Line Limit Flags -*************************** +************************* +Command Line Limit Flags +************************* {Project} has a number of simple command line flags that you can use with `shell/run/exec` and the `instance` commands to directly apply resource @@ -86,7 +86,7 @@ use. The minimum is ``0.01`` or one tenth of a physical CPU. The maximum is the number of CPU cores on your system. .. code:: - + # Limit container to 3.5 CPUs $ {command} run --cpus 3.5 myfirstapp.sif @@ -98,7 +98,7 @@ there is contention for CPUs*, i.e. the containers are able to consume more CPU time than is available. .. code:: - + # Container A - twice as much CPU priority as container B $ {command} run --cpu-shares 1024 myfirstapp.sif @@ -113,7 +113,7 @@ run. For example, on a dual CPU system you might pin one container to the first should generally be set to the same value as ``--cpuset-cpus``. .. code:: - + # Container A - first CPU $ {command} run --cpuset-cpus 0-11 --cpuset-mems 0-11 myfirstapp.sif @@ -128,7 +128,7 @@ You can use suffixes such as ``M`` or ``G`` to specify megabytes or gigabytes. If the container tries to use more memory than its limit, the system will kill it. -.. code:: +.. code:: # Run a program that will use 10GB of RAM, with a 100MB limit $ {command} exec --memory 100M memhog.sif memhog 10G @@ -138,7 +138,7 @@ it. limit set with ``--memory``. When there is contention for memory, the system will attempt to make sure the container doesn't exceed the soft limit. -.. code:: +.. code:: # Kill my program if it exceeds 10G, but aim for 8G if there is contention $ {command} exec --memory 10G --memory-reservation 8G myfirstapp.sif @@ -167,7 +167,7 @@ value of ``-1`` means *unlimited swap*. If ``--memory-swap`` is not set or is IO Limits ========= -.. note:: +.. note:: Requires the ``cfq`` or ``bfq`` IO scheduler to be configured for block IO on the system. This is common on modern distributions, but not universal. Ask @@ -180,7 +180,7 @@ is contention for I/O with other containers. It may be useful to give high priority to a container that needs infrequent but time sensitive data access, running alongside an application that is continuously performing bulk reads. -.. code:: +.. code:: # Container A - ten times as much block IO priority as container B $ {command} run --blkio-weight 1000 myfirstapp.sif @@ -191,7 +191,7 @@ running alongside an application that is continuously performing bulk reads. ``--blkio-weight-device`` sets a relative weight for the container when performing block I/O on a specific device. Specify the device and weight as ``:weight``: -.. code:: +.. code:: # Container A - ten times as much block IO priority as container B on disk /dev/sda $ {command} run --blkio-weight-device /dev/sda:1000 myfirstapp.sif @@ -199,9 +199,9 @@ block I/O on a specific device. Specify the device and weight as `` # Container A - ten times less block IO priority as container A on disk /dev/sda $ {command} run --blkio-weight-device /dev/sda:100 mysecondapp.sif -******************************************** - Applying Resource Limits From a TOML file -******************************************** +****************************************** +Applying Resource Limits From a TOML file +****************************************** {Project} can directly apply resource limitations to systems configured for both cgroups v1 and the v2 unified hierarchy, using the @@ -225,7 +225,7 @@ configuration to be applied: $ {command} shell --apply-cgroups /path/to/cgroups.toml my_container.sif -.. note:: +.. note:: Using ``--apply-cgroups`` as a non-root user requires a cgroups v2 system, configured to use the ``systemd cgroups`` manager in ``apptainer.conf``. @@ -377,7 +377,7 @@ is specified in bytes per second. Device Limits ============= -.. note:: +.. note:: Device limits can only be applied when running as the root user, and will be ignored as a non-root user. @@ -415,9 +415,9 @@ See the `runtime spec for information about the available limits. Note that {Project} uses TOML format for the configuration file, rather than JSON. -********************************************** - Applying Resource Limits With External Tools -********************************************** +******************************************** +Applying Resource Limits With External Tools +******************************************** Because {Project} starts a container as a simple process, rather than using a daemon, you can limit resource usage by running the diff --git a/checkpoint.rst b/checkpoint.rst index bff9e357..faff560d 100644 --- a/checkpoint.rst +++ b/checkpoint.rst @@ -1,12 +1,12 @@ .. _checkpoint: -#################### - Checkpoint Feature -#################### +################## +Checkpoint Feature +################## -********** - Overview -********** +******** +Overview +******** The checkpoint feature allows users to transparently save the state of containerized applications while they are executing and then restart them from diff --git a/cli.rst b/cli.rst index 56684345..c7d413ab 100644 --- a/cli.rst +++ b/cli.rst @@ -1,8 +1,8 @@ .. _cli: -######################## - Command Line Interface -######################## +###################### +Command Line Interface +###################### Below are links to the automatically generated CLI docs diff --git a/contributing.rst b/contributing.rst index ce746174..1600473e 100644 --- a/contributing.rst +++ b/contributing.rst @@ -1,17 +1,17 @@ .. _contributing: -############## - Contributing -############## +############ +Contributing +############ {Project} is an open source project, meaning we have the challenge of limited resources. We are grateful for any support that you can offer. Helping other users, raising issues, helping write documentation, or contributing code are all ways to help! -******************** - Join the community -******************** +****************** +Join the community +****************** This is a huge endeavor, and your help would be greatly appreciated! Post to online communities about {Project}, and request that your @@ -25,9 +25,9 @@ join those are on the `apptainer help page `_. .. _report-a-issue: -**************** - Raise an Issue -**************** +************** +Raise an Issue +************** For general bugs/issues, you can open an issue `at the GitHub repo `_. However, if you @@ -36,9 +36,9 @@ security@apptainer.org. More information about the {Project} security policies and procedures can be found `here `__ -********************* - Write Documentation -********************* +******************* +Write Documentation +******************* We (like almost all open source software providers) have a documentation dilemma… We tend to focus on the code features and functionality before @@ -75,9 +75,9 @@ identical for contributions to the documentation and the code base. .. _contribute-to-the-code: -************************ - Contribute to the code -************************ +********************** +Contribute to the code +********************** We use the traditional `GitHub Flow `_ to develop. This means @@ -128,7 +128,7 @@ Step 3. Make your changes On your new branch, go nuts! Make changes, test them, and when you are happy commit the changes to the branch. The {Project} requires that all contributed git commits use the ``-s`` option -which adds a ``Signed-off-by`` line to indicate agreement with the +which adds a ``Signed-off-by`` line to indicate agreement with the `Developer Certificate of Origin `_. .. code:: diff --git a/definition_files.rst b/definition_files.rst index f553dafe..38cf18b2 100755 --- a/definition_files.rst +++ b/definition_files.rst @@ -1,8 +1,8 @@ .. _definition-files: -################## - Definition Files -################## +################ +Definition Files +################ .. _sec:deffiles: @@ -12,9 +12,9 @@ specifics about the base OS to build or the base container to start from, software to install, environment variables to set at runtime, files to add from the host system, and container metadata. -********** - Overview -********** +******** +Overview +******** {AProject} Definition file is divided into two parts: @@ -39,9 +39,9 @@ examples repository `_. For a comparison between Dockerfile and {Project} definition file, please see :ref:`this section `. -******** - Header -******** +****** +Header +****** The header should be written at the top of the def file. It tells {Project} about the base operating system that it should use to @@ -153,9 +153,9 @@ in SIF format. protect against malicious changes that could be made during the build process on a compromised machine. -********** - Sections -********** +******** +Sections +******** The main content of the bootstrap file is broken into sections. Different sections add different content or execute commands at @@ -664,9 +664,9 @@ After building the help can be displayed like so: This is a demo container used to illustrate a def file that uses all supported sections. -******************** - Multi-Stage Builds -******************** +****************** +Multi-Stage Builds +****************** Multi-stage builds are supported where one environment can be used for compilation, then the resulting binary @@ -717,9 +717,9 @@ above definition cannot copy files from the ``final`` stage, but the .. _apps: -*********** - SCIF Apps -*********** +********* +SCIF Apps +********* SCIF is a standard for encapsulating multiple apps into a container. A container with SCIF apps has multiple entry points, and you can choose @@ -823,9 +823,9 @@ variable changes depending on the app we specify: $ {command} exec --app bar my_container.sif env | grep SOFTWARE SOFTWARE=bar -********************************** - Best Practices for Build Recipes -********************************** +******************************** +Best Practices for Build Recipes +******************************** When crafting your recipe, it is best to consider the following: diff --git a/docker_and_oci.rst b/docker_and_oci.rst index c726c7c0..2027ac50 100755 --- a/docker_and_oci.rst +++ b/docker_and_oci.rst @@ -1,8 +1,8 @@ .. _docker-and-oci: -####################################### - Support for Docker and OCI Containers -####################################### +##################################### +Support for Docker and OCI Containers +##################################### The Open Containers Initiative (OCI) container format, which grew out of Docker, is the dominant standard for cloud-focused containerized @@ -27,9 +27,9 @@ This section will highlight these workflows, and discuss the limitations and best practices to keep in mind when creating containers targeting both Docker and {Project}. -**************************** - Containers From Docker Hub -**************************** +************************** +Containers From Docker Hub +************************** Docker Hub is the most common place that projects publish public container images. At some point, it's likely that you will want to run @@ -200,9 +200,9 @@ set for both ``{command}`` and ``docker`` operations. $ export {ENVPREFIX}_DOCKER_PASSWORD=mytoken $ {command} pull docker://myuser/private -********************************** - Containers From Other Registries -********************************** +******************************** +Containers From Other Registries +******************************** You can use ``docker://`` URIs with {Project} to pull and run containers from OCI registries other than Docker Hub. To do this, you'll @@ -400,9 +400,9 @@ which details how to use ``az acr token create`` to obtain a token name and password pair that can be used to authenticate with the above methods. -*************************************** - Building From Docker / OCI Containers -*************************************** +************************************* +Building From Docker / OCI Containers +************************************* If you wish to use an existing Docker or OCI container as the basis for a new container, you will need to specify it as the *bootstrap* source @@ -632,9 +632,9 @@ filename in the ``From:`` line: .. _sec:optional_headers_def_files: -*************************************** - Differences and Limitations vs Docker -*************************************** +************************************* +Differences and Limitations vs Docker +************************************* Though Docker / OCI container compatibility is a goal of {Project}, there are some differences and limitations due to the way {Project} @@ -715,7 +715,7 @@ account will generally require modification for use with {Project}. ``root`` user, mapped to the user's real account outside of the container. When using the fakeroot mode that is based on `/etc/subuid`, then inside the container it is possible to change to another user -account which is mapped to different subuids +account which is mapped to different subuids belonging to the original user. It may be possible to execute software expecting a fixed user account manually inside such a ``--fakeroot`` shell. @@ -910,9 +910,9 @@ around this, use the ``--no-init`` flag to disable the shim: .. _compat-flag: -******************************* - Docker-like ``--compat`` Flag -******************************* +***************************** +Docker-like ``--compat`` Flag +***************************** If Docker-like behavior is important, {Project} can be started with the ``--compat`` flag. This flag is a convenient short-hand alternative @@ -946,9 +946,9 @@ execute correctly under {Project}. The user namespace and network namespace are not used, as these negate benefits of SIF and direct access to high performance cluster networks. -**************************** - CMD / ENTRYPOINT Behaviour -**************************** +************************** +CMD / ENTRYPOINT Behaviour +************************** When a container is run using ``docker``, its default behavior depends on the ``CMD`` and/or ``ENTRYPOINT`` set in the ``Dockerfile`` that was @@ -1068,9 +1068,9 @@ runtimes as there is no evaluated runscript. .. _sec:best_practices: -********************************************************* - Best Practices for Docker & {Project} Compatibility -********************************************************* +******************************************************* +Best Practices for Docker & {Project} Compatibility +******************************************************* As detailed previously, {Project} can make use of most Docker and OCI images without issues, or via simple workarounds. In general, @@ -1134,9 +1134,9 @@ creating Docker / OCI containers that will also be run using .. _sec:troubleshooting: -***************** - Troubleshooting -***************** +*************** +Troubleshooting +*************** Registry Authentication Issues ============================== @@ -1193,9 +1193,9 @@ you believe they are due to a bug in {Project}. .. _sec:deffile-vs-dockerfile: -********************************************** - {Project} Definition file vs. Dockerfile -********************************************** +******************************************** +{Project} Definition file vs. Dockerfile +******************************************** An alternative to running Docker containers with {Project} is to re-write the ``Dockerfile`` as a definition file, and build a native SIF diff --git a/encryption.rst b/encryption.rst index be3d7369..823be888 100644 --- a/encryption.rst +++ b/encryption.rst @@ -1,15 +1,15 @@ .. _encryption: -###################### - Encrypted Containers -###################### +#################### +Encrypted Containers +#################### Users can build a secure, confidential container environment by encrypting the root file system. -********** - Overview -********** +******** +Overview +******** {Project} provides a feature to build and run encrypted containers to allow users to encrypt the file system @@ -32,9 +32,9 @@ Also, decryption still requires a setuid installation of {Project}. Ubuntu 18.04, Debian 10 and CentOS/RHEL 7, but users of older Linux versions may have to update. -************************ - Encrypting a container -************************ +********************** +Encrypting a container +********************** A container can be encrypted either by supplying a plaintext passphrase or a PEM file containing an asymmetric RSA public key. Of these two @@ -163,9 +163,9 @@ In this case it is necessary to use the ``--encrypt`` flag since the presence of an environment variable alone will not trigger the encrypted build workflow. -******************************** - Running an encrypted container -******************************** +****************************** +Running an encrypted container +****************************** To ``run``, ``shell``, or ``exec`` an encrypted image, credentials to decrypt the image need to be supplied at runtime either in a key-file or diff --git a/endpoint.rst b/endpoint.rst index ec70185f..d92631bb 100755 --- a/endpoint.rst +++ b/endpoint.rst @@ -1,12 +1,12 @@ .. _endpoints: -################## - Remote Endpoints -################## +################ +Remote Endpoints +################ -********** - Overview -********** +******** +Overview +******** The ``remote`` command group allows users to manage the service endpoints {Project} will interact with for many common command @@ -42,9 +42,9 @@ or `instance .. _sec:managing-remote-endpoints: -*************************** - Managing Remote Endpoints -*************************** +************************* +Managing Remote Endpoints +************************* A fresh installation of {Project} is configured with the ``DefaultRemote``, which does not support the Library API as it is only configured with a @@ -291,7 +291,7 @@ Formerly the default was set to point to Sylabs servers, but the read/write support of the ``oras://`` protocol by for example the :ref:`GitHub Container Registry ` makes it unnecessary. -The remote endpoint was also formerly used for builds using the +The remote endpoint was also formerly used for builds using the build ``--remote`` option, but {Project} does not support that. Instead, it supports :ref:`unprivileged local builds `. @@ -326,9 +326,9 @@ To set the defaults system-wide see the corresponding section in the `admin guide <{admindocs}/configfiles.html#restoring-pre-{command}-library-behavior>`_. -************************** - Keyserver Configurations -************************** +************************ +Keyserver Configurations +************************ By default, {Project} will use the keyserver correlated to the active cloud service endpoint. This behavior can be changed or @@ -456,9 +456,9 @@ Now we can see that ``https://pgp.example.com`` is logged in: .. _sec:managing_oci_registries: -************************* - Managing OCI Registries -************************* +*********************** +Managing OCI Registries +*********************** It is common for users of {Project} to use OCI registries as sources for their container images. Some registries require credentials to diff --git a/environment_and_metadata.rst b/environment_and_metadata.rst index 618da9d6..34608037 100644 --- a/environment_and_metadata.rst +++ b/environment_and_metadata.rst @@ -1,8 +1,8 @@ .. _environment-and-metadata: -########################## - Environment and Metadata -########################## +######################## +Environment and Metadata +######################## .. _sec:envandmetadata: @@ -22,9 +22,9 @@ details such as the version of {Project} used are present as :ref:`labels ` on a container. You can also specify your own to be recorded against your container. -********************** - Environment Overview -********************** +******************** +Environment Overview +******************** When you run a program in a container with {Project}, the environment variables that the program sees are a combination of: @@ -61,9 +61,9 @@ If you are interested in variables available when you are *building* a container, rather than when running a container, see :ref:`build environment section `. -******************************* - Environment From a Base Image -******************************* +***************************** +Environment From a Base Image +***************************** When you build a container with {Project} you might *bootstrap* from a library or Docker image, or using Linux distribution bootstrap tools @@ -91,9 +91,9 @@ You can override the inherited environment with ``{ENVPREFIX}ENV_`` vars, or the ``--env / --env-file`` flags (see below), but ``Dockerfile`` ``ENV`` vars will not be overridden by host environment variables of the same name. -************************************ - Environment From a Definition File -************************************ +********************************** +Environment From a Definition File +********************************** Environment variables can be included in your container by adding them to your definition file. Use ``export`` in the ``%environment`` section @@ -143,9 +143,9 @@ Variables set in the ``%post`` section through ``${ENVPREFIX}_ENVIRONMENT`` take precedence over those added via ``%environment``. -*************************** - Environment From the Host -*************************** +************************* +Environment From the Host +************************* If you have environment variables set outside of your container, on the host, then by default they will be available inside the container. @@ -214,9 +214,9 @@ environment variables for correct operation of most software. such as ``PYTHONPATH`` that can change the way code runs, and consider using ``--cleanenv``. -**************************************** - Environment From the {Project} Runtime -**************************************** +************************************** +Environment From the {Project} Runtime +************************************** It can be useful for a program to know when it is running in a {Project} container, and some basic information about the container @@ -244,9 +244,9 @@ program running in the container. See compatibility documentation for ``SINGULARITY_`` prefixed environment variable support :ref:`here `. -********************************** - Overriding Environment Variables -********************************** +******************************** +Overriding Environment Variables +******************************** You can override variables that have been set in the container image, or define additional variables, in various ways as appropriate for your @@ -530,9 +530,9 @@ environment is constructed in the following order: .. _sec:umask: -********************************** - Umask / Default File Permissions -********************************** +******************************** +Umask / Default File Permissions +******************************** The ``umask`` value on a Linux system controls the default permissions for newly created files. It is not an environment variable, but @@ -557,9 +557,9 @@ the value outside, unless: .. _sec:metadata: -******************** - Container Metadata -******************** +****************** +Container Metadata +****************** Each {Project} container has metadata describing the container, how it was built, etc. This metadata includes the definition file used to @@ -865,9 +865,9 @@ And the output would look like: "type": "container" } -*************************** - /.singularity.d directory -*************************** +************************* +/.singularity.d directory +************************* The ``/.singularity.d`` directory in a container contains scripts and environment files that are used when a container is executed. diff --git a/fakeroot.rst b/fakeroot.rst index 316eb624..a774cf5a 100644 --- a/fakeroot.rst +++ b/fakeroot.rst @@ -1,12 +1,12 @@ .. _fakeroot: -################## - Fakeroot feature -################## +################ +Fakeroot feature +################ -********** - Overview -********** +******** +Overview +******** The fakeroot feature allows an unprivileged user to run a container with the appearance of running as root. @@ -75,9 +75,9 @@ which means that this user: In addition, the first three modes above may have full privileges inside the requested network namespace (see below). -*********************** - Restrictions/security -*********************** +********************* +Restrictions/security +********************* Filesystem ========== @@ -89,7 +89,7 @@ such as ``/etc/shadow`` or the host ``/root`` directory. Additionally, all files or directories created by the "fake root" user are owned by ``root:root`` inside the container but as ``user:group`` -outside of the container. +outside of the container. Let's consider the following example. In this case "user" is authorized to use the rootless mode fakeroot feature and can use 65536 @@ -118,9 +118,9 @@ system. Network ======= -Normally the kernel prevents unprivileged users from connecting to +Normally the kernel prevents unprivileged users from connecting to ports below 1024, and the ``ping`` command requires a setcap capability in -order to work on the network. +order to work on the network. {Project} allows overriding these restrictions when all of the following conditions are true: @@ -140,12 +140,12 @@ on the host with the ``--network-args="portmap"`` option. .. note:: - Of course an unprivileged user can not map host ports below + Of course an unprivileged user can not map host ports below 1024 by using for example: ``--network-args="portmap=80:80/tcp"`` -******* - Usage -******* +***** +Usage +***** You can work as a fake root user inside a container by using the ``--fakeroot`` or ``-f`` option. diff --git a/gpu.rst b/gpu.rst index 7f42918d..27417f09 100644 --- a/gpu.rst +++ b/gpu.rst @@ -1,8 +1,8 @@ .. _gpu: -###################################### - GPU Support (NVIDIA CUDA & AMD ROCm) -###################################### +#################################### +GPU Support (NVIDIA CUDA & AMD ROCm) +#################################### {Project} natively supports running application containers that use NVIDIA's CUDA GPU compute framework, or AMD's ROCm solution. This allows @@ -21,9 +21,9 @@ functionality, accessible via the new ``--nvccli`` flag, improves compatibility with OCI runtimes and exposes additional container configuration options. -******************************* - NVIDIA GPUs & CUDA (Standard) -******************************* +***************************** +NVIDIA GPUs & CUDA (Standard) +***************************** Commands that ``run``, or otherwise execute containers (``shell``, ``exec``) can take an ``--nv`` option, which will setup the container's @@ -190,9 +190,9 @@ driver stack on the host first, by running a CUDA program there or ``modprobe nvidia_uvm`` as root, and using ``nvidia-persistenced`` to avoid driver unload. -******************************************* - NVIDIA GPUs & CUDA (nvidia-container-cli) -******************************************* +***************************************** +NVIDIA GPUs & CUDA (nvidia-container-cli) +***************************************** The ``--nvccli`` option instructs {Project} to perform GPU container setup using the @@ -231,9 +231,9 @@ Requirements & Limitations ``nvidia-container-cli`` also requires writing to the image, so either the ``--writable`` (``-w``) or ``--writable-tmpfs`` option is also required; if neither is given, ``--writable-tmpfs`` is - implied. + implied. That also means that the permissions on system directories such as - ``/usr/bin`` have to be writable, so either use a sandbox image that + ``/usr/bin`` have to be writable, so either use a sandbox image that has that directory writable by the user (for example built with the ``--fix-perms`` option) or use ``--fakeroot``. @@ -389,9 +389,9 @@ be found in the container-toolkit guide: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/user-guide.html#environment-variables-oci-spec -***************** - AMD GPUs & ROCm -***************** +*************** +AMD GPUs & ROCm +*************** {Project} has a ``--rocm`` flag to support GPU compute with the ROCm framework using AMD Radeon GPU cards. @@ -484,9 +484,9 @@ tensorflow ``list_local_devices()`` function: pciBusID 0000:09:00.0 ... -********************* - OpenCL Applications -********************* +******************* +OpenCL Applications +******************* Both the ``--rocm`` and ``--nv`` flags will bind the vendor OpenCL implementation libraries into a container that is being run. However, diff --git a/index.rst b/index.rst index 52a77063..e3ab82d4 100644 --- a/index.rst +++ b/index.rst @@ -1,6 +1,6 @@ -########################## - {Project} User Guide -########################## +######################## +{Project} User Guide +######################## Welcome to the {Project} User Guide! @@ -11,9 +11,9 @@ and running containers. For a detailed guide to installation and configuration, please see the separate `Admin Guide <{admindocs}>`_ for this version of {Project}. -****************************************** - Getting Started & Background Information -****************************************** +**************************************** +Getting Started & Background Information +**************************************** .. toctree:: :maxdepth: 2 @@ -22,9 +22,9 @@ separate `Admin Guide <{admindocs}>`_ for this version of {Project}. Quick Start Security in {Project} -********************* - Building Containers -********************* +******************* +Building Containers +******************* Learn how to write a definition file that can be used to build a container. Understand the environment within a build and how to build @@ -38,15 +38,15 @@ as a non-root user. Build Environment Fakeroot feature -******************************** - Container Signing & Encryption -******************************** +****************************** +Container Signing & Encryption +****************************** {Project} allows containers to be signed using a PGP key. The signature travels with the container image, allowing you to verify that the image is unmodified at any time. Encryption of containers using LUKS2 is also supported. Encrypted containers can be run without -decrypting them to disk first. +decrypting them to disk first. Using encrypted containers currently requires a setuid installation of {Project}. @@ -57,9 +57,9 @@ Using encrypted containers currently requires a setuid installation of Key management commands Encrypted Containers -*************************** - Sharing & Online Services -*************************** +************************* +Sharing & Online Services +************************* .. toctree:: :maxdepth: 1 @@ -67,9 +67,9 @@ Using encrypted containers currently requires a setuid installation of Remote Endpoints Library API Registries -**************** - Advanced Usage -**************** +************** +Advanced Usage +************** Once you've understood the basics, explore all the options which {Project} provides for accessing data, running persistent services @@ -89,9 +89,9 @@ networking and security configuration. Limiting Container Resources Application Checkpointing -*************** - Compatibility -*************** +************* +Compatibility +************* {Project} has unique benefits and supports easy access to GPUs and other hardware. It also strives for compatibility with Docker/OCI @@ -107,9 +107,9 @@ Docker, as well as how to use containerized MPI and GPU applications. {Project} and MPI applications GPU Support -************** - Get Involved -************** +************ +Get Involved +************ We'd love you to get involved in the {Project} community! Whether through contributing feature and fixes, helping to answer questions from @@ -120,9 +120,9 @@ other users, or simply testing new releases. Contributing -*********** - Reference -*********** +********* +Reference +********* .. toctree:: :maxdepth: 2 diff --git a/introduction.rst b/introduction.rst index ce301cdb..4ac311af 100644 --- a/introduction.rst +++ b/introduction.rst @@ -1,8 +1,8 @@ .. _introduction: -############################### - Introduction to {Project} -############################### +############################# +Introduction to {Project} +############################# {Project} is a *container* platform. It allows you to create and run containers that package up pieces of software in a way that is portable @@ -13,9 +13,9 @@ cloud, or on a workstation down the hall. Your container is a single file, and you don't have to worry about how to install all the software you need on each different operating system. -************************ - Why use {Project}? -************************ +********************** +Why use {Project}? +********************** {Project} was created to run complex applications on HPC clusters in a simple, portable, and reproducible way. First developed at Lawrence @@ -42,9 +42,9 @@ Many container platforms are available, but {Project} is focused on: container as outside, and cannot gain additional privilege on the host system by default. Read more about :ref:`security`. -********************* - Why use containers? -********************* +******************* +Why use containers? +******************* A Unix operating system is broken into two primary components, the kernel space, and the user space. The Kernel talks to the hardware, and @@ -72,9 +72,9 @@ system base fits their needs best, and create distributable runtime environments so that users never have to worry about dependencies and requirements, that they might not be able to satisfy on their systems. -*********** - Use Cases -*********** +********* +Use Cases +********* BYOE: Bring Your Own Environment! ================================= diff --git a/key_commands.rst b/key_commands.rst index 00738a90..19b9c77f 100644 --- a/key_commands.rst +++ b/key_commands.rst @@ -1,8 +1,8 @@ .. _key_commands: -############## - Key commands -############## +############ +Key commands +############ .. _sec:key_commands: @@ -13,9 +13,9 @@ the local keyring and are not related to the cloud keystore. .. _key_import: -****************************** - Global keyring -****************************** +**************************** +Global keyring +**************************** {Project} has a global keyring which can be managed by administrators with the ``--global`` option. This global keyring is @@ -23,9 +23,9 @@ used by `ECL <{admindocs}/configfiles.html#ecl-toml>`_ and allows administrators to manage public keys used during ECL image verification. -******************** - Key import command -******************** +****************** +Key import command +****************** {Project} allows you to import keys reading either from binary or armored key format and automatically detect if it is a private or public @@ -130,9 +130,9 @@ detected by the ``key import`` command (no need to specify the format). .. _key_export: -******************** - Key export command -******************** +****************** +Key export command +****************** The key export command allows you to export a key that is on your local keyring. This key could be either private or public, and the key can be @@ -177,9 +177,9 @@ and on binary format instead: .. _key_remove: -******************** - Key remove command -******************** +****************** +Key remove command +****************** In case you would want to remove a public key from your public local keystore, you can do so by running the following command: diff --git a/library_api.rst b/library_api.rst index 0e382f9b..051ca0a6 100644 --- a/library_api.rst +++ b/library_api.rst @@ -1,12 +1,12 @@ .. _library_api_registries: -######################## - Library API Registries -######################## +###################### +Library API Registries +###################### -********** - Overview -********** +******** +Overview +******** {Project} enables users to use `Library API Container Registries `_ to @@ -23,9 +23,9 @@ Once you have authenticated, you are ready to push your container! .. _push: -********************* - Pushing a Container -********************* +******************* +Pushing a Container +******************* The ``{command} push`` command will push a container to the container library with the given URL. Here's an example of a typical push command: @@ -72,9 +72,9 @@ your quota usage and the direct URL to view the container in your web browser. .. _pull: -********************* - Pulling a container -********************* +******************* +Pulling a container +******************* The ``{command} pull`` command will download a container from an `OCI Registry `_ (``docker://``), @@ -133,9 +133,9 @@ etc... automatically, but it's good practice to always specify your output file. -**************************** - Verify/Sign your Container -**************************** +************************** +Verify/Sign your Container +************************** Verify containers that you pull from the library, ensuring they are bit-for-bit reproductions of the original image. @@ -146,9 +146,9 @@ sign your own containers `. .. _search_the_library: -************************************** - Searching the Library for Containers -************************************** +************************************ +Searching the Library for Containers +************************************ To find interesting or useful containers in a library, you can open that library in your browser if that project supports a web GUI. diff --git a/license.rst b/license.rst index fd83790a..9d306847 100644 --- a/license.rst +++ b/license.rst @@ -1,19 +1,19 @@ -########## - Licenses -########## +######## +Licenses +######## -*************** - Documentation -*************** +************* +Documentation +************* This documentation is subject to the following 3-clause BSD license: .. include:: LICENSE :literal: -******************** - {Project} Software -******************** +****************** +{Project} Software +****************** .. mdinclude:: apptainer_source/LICENSE.md diff --git a/mpi.rst b/mpi.rst index 99a05880..1130a019 100644 --- a/mpi.rst +++ b/mpi.rst @@ -1,8 +1,8 @@ .. _mpi: -#################################### - {Project} and MPI applications -#################################### +################################## +{Project} and MPI applications +################################## .. _sec-mpi: @@ -34,9 +34,9 @@ host into the container. disabled by system administrators for operational reasons. If this is the case on your system please follow the *hybrid* approach. -************** - Hybrid model -************** +************ +Hybrid model +************ The basic idea behind the *Hybrid Approach* is when you execute a {Project} container with MPI code, you will call ``mpiexec`` or a @@ -280,9 +280,9 @@ when the containers start, the MPI binary is executed: Hello, I am rank 1/8 Hello, I am rank 7/8 -************ - Bind model -************ +********** +Bind model +********** Similar to the *Hybrid Approach*, the basic idea behind the *Bind Approach* is to start the MPI application by calling the MPI launcher @@ -396,9 +396,9 @@ to run the container in bind mode are: Hello, I am rank 4/8 Hello, I am rank 6/8 -************************* - Batch Scheduler / Slurm -************************* +*********************** +Batch Scheduler / Slurm +*********************** If your target system is setup with a batch system such as SLURM, a standard way to execute MPI applications is through a batch script. The @@ -429,9 +429,9 @@ A user can then submit a job by executing the following SLURM command: $ sbatch my_job.sh -*********************** - Alternative Launchers -*********************** +********************* +Alternative Launchers +********************* On many systems it is common to use an alternative launcher to start MPI applications, e.g. Slurm's ``srun`` rather than the ``mpirun`` provided @@ -443,9 +443,9 @@ launcher. In the bind mode the host MPI is used in the container, and should interact correctly with the same launchers as it does on the host. -**************************** - Interconnects / Networking -**************************** +************************** +Interconnects / Networking +************************** High performance interconnects such as Infiniband and Omnipath require that MPI implementations are built to support them. You may need to @@ -458,9 +458,9 @@ container. If you run a container using the ``--contain`` or to bind in additional ``/dev/`` entries manually to support the operation of your interconnect drivers in the container in this case. -********************** - Troubleshooting Tips -********************** +******************** +Troubleshooting Tips +******************** If your containers run N rank 0 processes, instead of operating correctly as an MPI application, it is likely that the MPI stack used to diff --git a/networking.rst b/networking.rst index fd299c0b..2b45b0f6 100644 --- a/networking.rst +++ b/networking.rst @@ -1,8 +1,8 @@ .. _networking: -######################## - Network virtualization -######################## +###################### +Network virtualization +###################### .. _sec:networking: @@ -25,9 +25,9 @@ configure a virtualized network for a container. See the `administrator guide <{admindocs}/configfiles.html#networking-options>`_ for details. -*********** - ``--dns`` -*********** +********* +``--dns`` +********* The ``--dns`` option allows you to specify a comma separated list of DNS servers to add to the ``/etc/resolv.conf`` file. @@ -43,9 +43,9 @@ servers to add to the ``/etc/resolv.conf`` file. $ sudo {command} exec --dns 8.8.8.8 ubuntu.sif cat /etc/resolv.conf nameserver 8.8.8.8 -**************** - ``--hostname`` -**************** +************** +``--hostname`` +************** The ``--hostname`` option accepts a string argument to change the hostname within the container. @@ -58,9 +58,9 @@ hostname within the container. $ sudo {command} exec --hostname hal-9000 my_container.sif hostname hal-9000 -*********** - ``--net`` -*********** +********* +``--net`` +********* Passing the ``--net`` flag will cause the container to join a new network namespace when it initiates. A bridge interface is also set up by @@ -74,9 +74,9 @@ default. $ sudo {command} exec --net my_container.sif hostname -I 10.22.0.4 -*************** - ``--network`` -*************** +************* +``--network`` +************* The ``--network`` option can only be invoked in combination with the ``--net`` flag. It accepts a comma delimited string of network types. @@ -116,9 +116,9 @@ Additional cni configuration files can be added to the ``network`` configuration directory as required, and {Project}'s provided configurations may also be modified. -******************** - ``--network-args`` -******************** +****************** +``--network-args`` +****************** The ``--network-args`` option provides a convenient way to specify arguments to pass directly to the cni plugins. It must be used in diff --git a/oci_runtime.rst b/oci_runtime.rst index 4a97ae7a..391e3653 100644 --- a/oci_runtime.rst +++ b/oci_runtime.rst @@ -3,21 +3,21 @@ .. TODO-MUST something with the long json snippet ... -##################### - OCI Runtime Support -##################### +################### +OCI Runtime Support +################### .. _sec:oci_runtime_overview: -********** - Overview -********** +******** +Overview +******** OCI is an acronym for the `Open Containers Initiative `_ - an independent organization whose mandate is to develop open standards relating to containerization. To date, standardization efforts have focused on container formats and -runtimes. +runtimes. It is {Project}'s compliance with the OCI Runtime Specification that is of concern here, not container formats. @@ -37,9 +37,9 @@ command group. .. TODO Compliance testing/validation - need to document ... https://github.com/opencontainers/runtime-tools -******************************** - Mounted OCI Filesystem Bundles -******************************** +****************************** +Mounted OCI Filesystem Bundles +****************************** Mounting an OCI Filesystem Bundle ================================= @@ -784,9 +784,9 @@ properties, refer to the `implementation guide filesystem bundle that conforms with the OCI runtime specification, this extensibility is evident. -******************************************** - Creating OCI Compliant Container Instances -******************************************** +****************************************** +Creating OCI Compliant Container Instances +****************************************** SIF files encapsulate the OCI runtime. By 'OCI mounting' a SIF file (see above), this encapsulated runtime is revealed; please refer to the note @@ -880,9 +880,9 @@ in deployments where auditing requirements exist. .. sandbox??? -*********************************** - Unmounting OCI Filesystem Bundles -*********************************** +********************************* +Unmounting OCI Filesystem Bundles +********************************* To unmount a mounted OCI filesystem bundle, the following command should be issued: diff --git a/persistent_overlays.rst b/persistent_overlays.rst index 1cb7fe0b..ad126181 100755 --- a/persistent_overlays.rst +++ b/persistent_overlays.rst @@ -1,15 +1,15 @@ -##################### - Persistent Overlays -##################### +################### +Persistent Overlays +################### Persistent overlay directories allow you to overlay a writable file system on an immutable read-only container for the illusion of read-write access. You can run a container and make changes, and these changes are kept separately from the base container image. -********** - Overview -********** +******** +Overview +******** A persistent overlay is a directory or file system image that "sits on top" of your immutable SIF container. When you install new software or @@ -40,9 +40,9 @@ You can use persistent overlays with the following commands: - ``shell`` - ``instance start`` -******* - Usage -******* +***** +Usage +***** Filesystem image overlay ======================== @@ -96,10 +96,10 @@ space on disk that the file is currently using: .. code:: - $ ls -lah /tmp/ext3_overlay.img + $ ls -lah /tmp/ext3_overlay.img -rw-------. 1 user user 1.0G Jan 27 11:47 /tmp/ext3_overlay.img - $ du -h /tmp/ext3_overlay.img + $ du -h /tmp/ext3_overlay.img 33M /tmp/ext3_overlay.img If you copy or move the sparse image you should ensure that the tool you use to @@ -140,8 +140,8 @@ For example: /usr/bin/vim An exception is if you are using the 4th :ref:`fakeroot mode ` -with a setuid installation and no unprivileged user namespaces available. -In that case the ``--fakeroot`` option to ``overlay create`` makes +with a setuid installation and no unprivileged user namespaces available. +In that case the ``--fakeroot`` option to ``overlay create`` makes the overlay image unwritable, so leave it out. This case also has other restrictions in that it only works when the underlying image is a sandbox directory, and yet the overlay itself must @@ -208,7 +208,7 @@ changes will be gone. Readonly overlay ================ -After all modifications to an overlay (either ext3 image or directory) +After all modifications to an overlay (either ext3 image or directory) have been completed, it can be mounted read-only by appending a ``:ro`` to the overlay path and no longer needs to use ``--fakeroot``. @@ -230,7 +230,7 @@ Overlay embedded in SIF It is possible to embed an overlay image into the SIF file that holds a container. This allows the read-only container image and your -modifications to it to be managed as a single file. +modifications to it to be managed as a single file. To add a 1 GiB writable overlay partition to an existing SIF image: diff --git a/plugins.rst b/plugins.rst index 17078723..b8ce7f24 100644 --- a/plugins.rst +++ b/plugins.rst @@ -1,16 +1,16 @@ .. _plugins: -######### - Plugins -######### +####### +Plugins +####### -********** - Overview -********** +******** +Overview +******** {AProject} plugin is a package that can be dynamically loaded by the {Project} runtime, augmenting {Project} with experimental, non-standard -and/or vendor-specific functionality. +and/or vendor-specific functionality. Plugins can influence the behaviour of {Project} in specific ways: @@ -26,9 +26,9 @@ Plugins can influence the behaviour of {Project} in specific ways: * A runtime plugin can use the ``RegisterImageDriver`` callback to implement an alternative way of providing a container image to execute. -**************************** - Limitations / Requirements -**************************** +************************** +Limitations / Requirements +************************** The way that plugin functionality is implemented in the Go language, which {Project} is written with, is quite restrictive. @@ -48,9 +48,9 @@ investigate whether the feature can be contributed to the main source tree directly via a PR. This simplifies future maintenance, and avoids the limitations of Go plugins. -*************** - Using Plugins -*************** +************* +Using Plugins +************* The ``list`` command prints the currently installed plugins. @@ -82,8 +82,8 @@ plugin's source code. Due to the structure of the {Project} project, and the strict requirements of Go plugin compilation, **all** plugins must be compiled from - within the {Project} source code tree. - + within the {Project} source code tree. + The ability to compile plugins outside of the {Project} tree, that previously existed, has been removed due to incompatible changes in Go 1.18. @@ -137,9 +137,9 @@ operation requires root privilege. $ {command} plugin list There are no plugins installed. -****************** - Writing a Plugin -****************** +**************** +Writing a Plugin +**************** Developers interested in writing {Project} plugins can get started by reading the `Go documentation diff --git a/quick_start.rst b/quick_start.rst index 643d749c..e384f29a 100644 --- a/quick_start.rst +++ b/quick_start.rst @@ -1,8 +1,8 @@ .. _quick-start: -############# - Quick Start -############# +########### +Quick Start +########### .. _sec:quickstart: @@ -18,9 +18,9 @@ https://apptainer.org/help .. _quick-installation: -******************** - Quick Installation -******************** +****************** +Quick Installation +****************** You will need a Linux system to run {Project} natively and it's easiest to install if you have root access. @@ -36,9 +36,9 @@ and using {Project} on Mac and Windows machines are discussed in the `installation section of the admin guide <{admindocs}/installation.html>`__. -***************************************** - Overview of the {Project} Interface -***************************************** +*************************************** +Overview of the {Project} Interface +*************************************** {Project}'s :ref:`command line interface ` allows you to build and interact with containers transparently. You can run programs inside @@ -178,9 +178,9 @@ particular container, you can view them like so. $ {command} inspect --helpfile --app=foo foo.sif # See the help for foo, if provided -******************** - Downloading images -******************** +****************** +Downloading images +****************** You can use the `pull `_ @@ -217,9 +217,9 @@ definition file with Dockerfile, please see: :ref:`this section .. _cowimage: -********************** - Interact with images -********************** +******************** +Interact with images +******************** You can interact with images in several ways, each of which can accept image URIs in addition to a local image path. @@ -391,9 +391,9 @@ quoting of arguments. The ``exec`` command replicates the Docker/OCI behavior as it calls the specified executable directly. -******************** - Working with Files -******************** +****************** +Working with Files +****************** Files on the host are reachable from within the container. @@ -438,9 +438,9 @@ do with normal Linux commands. .. _build-images-from-scratch: -*************************** - Build images from scratch -*************************** +************************* +Build images from scratch +************************* .. _sec:buildimagesfromscratch: diff --git a/running_services.rst b/running_services.rst index 6188c2b9..aa447fc9 100644 --- a/running_services.rst +++ b/running_services.rst @@ -1,8 +1,8 @@ .. _running_services: -################## - Running Services -################## +################ +Running Services +################ There are :ref:`different ways ` in which you can run {Project} containers. If you use commands like ``run``, ``exec`` and @@ -15,9 +15,9 @@ a web server or a database. To run services in {aProject} container one should use *instances*. A container instance is a persistent and isolated version of the container image that runs in the background. -********** - Overview -********** +******** +Overview +******** .. _sec:instances: @@ -46,9 +46,9 @@ couldn't easily kill or interface with it. This is a called an orphan process. {Project} instances give you the ability to handle services properly. -************************************** - Container Instances in {Project} -************************************** +************************************ +Container Instances in {Project} +************************************ For demonstration, let's use an easy (though somewhat useless) example of ``alpine_latest.sif`` from {Project}'s github container registry: @@ -157,9 +157,9 @@ commands are all identical. Note that you must escape the wildcard with a backslash like this ``\*`` to pass it properly. -************************************** - Nginx "Hello-world" in {Project} -************************************** +************************************ +Nginx "Hello-world" in {Project} +************************************ The above example, although not very useful, should serve as a fair introduction to the concept of {Project} instances and running @@ -230,9 +230,9 @@ image. And to confirm that it's correctly running: Visit localhost on your browser, you should see a Welcome message! -********************** - Putting all together -********************** +******************** +Putting all together +******************** In this section, we will demonstrate an example of packaging a service into a container and running it. The service we will be packaging is an @@ -569,9 +569,9 @@ running instance. $ {command} instance start --bind output/dir/outside/:/output/ nginx.sif web -******************************** - System integration / PID files -******************************** +****************************** +System integration / PID files +****************************** If you are running services in containers you may want them to be started on boot, and shutdown gracefully automatically. This is usually diff --git a/security.rst b/security.rst index 644632e8..e741a0c4 100644 --- a/security.rst +++ b/security.rst @@ -1,12 +1,12 @@ .. _security: -########################### - Security in {Project} -########################### +######################### +Security in {Project} +######################### -***************** - Security Policy -***************** +*************** +Security Policy +*************** If you suspect you have found a vulnerability in {Project} we want to work with you so that it can be investigated, fixed, and disclosed in @@ -20,9 +20,9 @@ all users to monitor new releases of {Project} for security information. Security patches are applied to the latest open-source release. -************ - Background -************ +********** +Background +********** {Project} grew out of the need to implement a container platform that was suitable for use on shared systems, such as HPC clusters. In @@ -44,11 +44,11 @@ wouldn't normally have permission to do. When a user runs a container with {Project}, it is started as a normal process running under the user's account. Standard file permissions and other security controls based on user accounts, groups, -and processes apply. +and processes apply. -************************** - Setuid & User Namespaces -************************** +************************ +Setuid & User Namespaces +************************ Using a setuid binary to run container setup operations used to be essential to support containers on the older Linux distributions that were @@ -70,17 +70,17 @@ component is not installed by default and the installer must separately install the ``{command}-suid`` package if setuid mode is desired. In non-suid mode *all* operations run as the user who starts the -``{command}`` program. +``{command}`` program. This has some advantages over suid mode: - Setuid-root programs are notoriously difficult to make fully secure. {Project} keeps the setuid portions to a minimum and has passed a careful review, but still it is a risk. -- Linux kernel developers believe that it is inherently unsafe to +- Linux kernel developers believe that it is inherently unsafe to allow unprivileged users to modify an underlying filesystem at will while kernel code is actively accessing the filesystem - (see `this article `__). + (see `this article `__). Kernel filesystem drivers do not and cannot protect against all kinds of modifications to that data which it has not itself written, and that fact could potentially be used to attack the kernel. @@ -122,7 +122,7 @@ However, there are also some disadvantages of the non-suid mode: scrutiny than the {Project} setuid software, there have been a greater number of announced vulnerabilities that are exploitable through kernel namespace code than have been announced for {Project} and - its predecessor. + its predecessor. Security experts generally argue that it is better to have the scrutiny than to have "security by obscurity", but urgently responding to those vulnerabilities causes additional @@ -132,9 +132,9 @@ However, there are also some disadvantages of the non-suid mode: of the admin guide for details about mitigating the impact of user namespace vulnerabilities through disabling network namespaces. -******************************** - Runtime & User Privilege Model -******************************** +****************************** +Runtime & User Privilege Model +****************************** While other runtimes have aimed to safely sandbox containers executing as the ``root`` user, so that they cannot affect the host system, @@ -165,9 +165,9 @@ If you do require the additional isolation of the network, devices, PIDs etc. provided by other runtimes, {Project} can make use of additional namespaces and functionality such as seccomp and cgroups. -******************************** - Singularity Image Format (SIF) -******************************** +****************************** +Singularity Image Format (SIF) +****************************** {Project} uses SIF as its default container format. A SIF container is a single file, which makes it easy to manage and distribute. Inside @@ -210,9 +210,9 @@ kernel. Unlike other container formats, an encrypted container is not decrypted to disk in order to run it. Encryption and decryption is not currently supported in non-suid mode. -********************************* - Configuration & Runtime Options -********************************* +******************************* +Configuration & Runtime Options +******************************* System administrators who manage {Project} can use configuration files to set security restrictions, grant or revoke a user's diff --git a/security_options.rst b/security_options.rst index b3927c91..79673a77 100644 --- a/security_options.rst +++ b/security_options.rst @@ -1,8 +1,8 @@ .. _security-options: -################## - Security Options -################## +################ +Security Options +################ .. _sec:security_options: @@ -11,9 +11,9 @@ container runtime. This document describes the methods users have for specifying the security scope and context when running {Project} containers. -******************** - Linux Capabilities -******************** +****************** +Linux Capabilities +****************** .. note:: @@ -103,9 +103,9 @@ The ``--add-caps`` and ``--drop-caps`` options will accept the ``all`` keyword. Of course appropriate caution should be exercised when using this keyword. -******************************* - Building encrypted containers -******************************* +***************************** +Building encrypted containers +***************************** With {aProject} setuid installation it is possible to build and run encrypted containers. @@ -113,9 +113,9 @@ The containers are decrypted at runtime entirely in kernel space, meaning that no intermediate decrypted data is ever present on disk. See :ref:`encrypted containers ` for more details. -********************************* - Security related action options -********************************* +******************************* +Security related action options +******************************* {Project} has many security related flags that can be passed to the action commands; ``shell``, ``exec``, and ``run`` allowing fine grained diff --git a/signNverify.rst b/signNverify.rst index 44180c42..decef291 100644 --- a/signNverify.rst +++ b/signNverify.rst @@ -1,8 +1,8 @@ .. _signnverify: -################################## - Signing and Verifying Containers -################################## +################################ +Signing and Verifying Containers +################################ .. _sec:signnverify: @@ -20,9 +20,9 @@ intended it. .. _verify_container_from_remote_sources: -****************************************** - Verifying containers from remote sources -****************************************** +**************************************** +Verifying containers from remote sources +**************************************** The ``verify`` command will allow you to verify that a container has been signed using a PGP key. This ensures that the container image on your disk @@ -47,14 +47,14 @@ is a bit-for-bit reproduction of the original image. In this example you can see that **Ian Kaneshiro** has signed the container. -This feature is available with SIF images like those you can pull from container +This feature is available with SIF images like those you can pull from container libraries or OCI registries via `oras://`. .. _sign_your_own_containers: -***************************** - Signing your own containers -***************************** +*************************** +Signing your own containers +*************************** Generating and managing PGP keys ================================ @@ -276,7 +276,7 @@ option to ``sign`` and ``verify``. .. code:: $ {command} sign --sif-id 1 my_container.sif - + Signing image: my_container.sif Enter key passphrase : Signature created and applied to my_container.sif diff --git a/singularity_compatibility.rst b/singularity_compatibility.rst index 0316840f..316e120e 100644 --- a/singularity_compatibility.rst +++ b/singularity_compatibility.rst @@ -1,8 +1,8 @@ .. _singularity_compatibility: -########################### - Singularity Compatibility -########################### +######################### +Singularity Compatibility +######################### Since the community decided to `move the project into the Linux Foundation `_ with the @@ -12,9 +12,9 @@ the move, please reach out to the `community `_ so we can help you! -************************* - SIF Image Compatibility -************************* +*********************** +SIF Image Compatibility +*********************** The {Project} project has decided to make no changes related to the project renaming at the image format level. This means that default metadata within @@ -30,9 +30,9 @@ collaborating with colleagues that still use a Singularity installation. .. _singularity_environment_variable_compatibility: -*************************************************** - Singularity Prefixed Environment Variable Support -*************************************************** +************************************************* +Singularity Prefixed Environment Variable Support +************************************************* {Project} respects environment variables with the ``SINGULARITY_`` and ``SINGULARITYENV_`` prefixes when their respective ``{ENVPREFIX}_`` and @@ -82,9 +82,9 @@ set to create the same environment variable in the container in case they were unaware of one of them existing in their environment. -***************************** - Singularity Command Symlink -***************************** +*************************** +Singularity Command Symlink +*************************** With the same intention as the environment variable handling, {Project} installations will include a symlink to the ``{command}`` binary named @@ -102,9 +102,9 @@ underlying binary: {command} version {InstallationVersion} -**************************************** - Automatic User Configuration Migration -**************************************** +************************************** +Automatic User Configuration Migration +************************************** {Project} stores user configuration in files and directories under ``~/.{command}``. Invocation of the ``{command}`` command will automatically