Skip to content

Latest commit

 

History

History
executable file
·
1223 lines (838 loc) · 39.1 KB

appendix.rst

File metadata and controls

executable file
·
1223 lines (838 loc) · 39.1 KB
Raw

Appendix

{Singularity}'s environment variables

{Singularity} 3.0 comes with some environment variables you can set or modify depending on your needs. You can see them listed alphabetically below with their respective functionality.

A

  1. SINGULARITY_ADD_CAPS: To specify a list (comma separated string) of capabilities to be added. Default is an empty string.
  2. SINGULARITY_ALL: List all the users and groups capabilities.
  3. SINGULARITY_ALLOW_SETUID: To specify that setuid binaries should or not be allowed in the container. (root only) Default is set to false.
  4. SINGULARITY_ALLOW_UNSIGNED: Set to true to allow pushing unsigned SIF images to a library:// destination. Default is false.
  5. SINGULARITY_APP and SINGULARITY_APPNAME: Sets the name of an application to be run inside a container.
  6. SINGULARITY_APPLY_CGROUPS: Used to apply cgroups from an input file for container processes. (it requires root privileges)
  7. SINGULARITY_ARCH and SINGULARITY_PULL_ARCH: Set the architecture (e.g. arm64) of an image to pull from a library:// or OCI source. Defaults to the host architecture.
  8. SINGULARITY_AUTHFILE: Specify a non-standard location for storing / reading login credentials for OCI/Docker registries. See the authfile documentation <sec:authfile>.

B

  1. SINGULARITY_BINDPATH and SINGULARITY_BIND: Comma separated string source:<dest> list of paths to bind between the host and the container.
  2. SINGULARITY_BLKIO_WEIGHT: Specify a relative weight for block device access during contention. Range 10-1000. Default is 0 (disabled).
  3. SINGULARITY_BLKIO_WEIGHT_DEVICE: Specify a relative weight for block device access during contention on a specific device. Must be supplied in <device path>:weight format. Default is unset.
  4. SINGULARITY_BOOT: Set to false by default, considers if executing /sbin/init when container boots (root only).
  5. SINGULARITY_BUILD_ARCH: Specify an architecture to use when building a container via the remote build service (--remote).
  6. SINGULARITY_BUILDER: To specify the remote builder service URL. Defaults to our remote builder.

C

  1. SINGULARITY_CACHEDIR: Specifies the directory for image downloads to be cached in. See sec:cache.
  2. SINGULARITY_CAP_GROUP: Specify a group to modify when managing permitted capabilities with the capability command.
  3. SINGULARITY_CAP_USER: Specify a user to modify when managing permitted capabilities with the capability command.
  4. SINGULARITY_CLEANENV: Specifies if the environment should be cleaned or not before running the container. Default is set to false.
  5. SINGULARITY_COMPAT: Set to true to enable Docker/OCI compatibility mode. Equivalent to setting --containall --no-eval --no-init --no-umask --writable-tmpfs. Default is false for the native runtime, true in OCI-mode.
  6. SINGULARITY_CONFIG_FILE: Use a custom singularity.conf configuration file. Only supported for non-root users in non-setuid mode.
  7. SINGULARITY_CONTAIN: To use minimal /dev and empty other directories (e.g. /tmp and $HOME) instead of sharing filesystems from your host. Default is set to false.
  8. SINGULARITY_CONTAINALL: To contain not only file systems, but also PID, IPC, and environment. Default is set to false.
  9. SINGULARITY_CONTAINLIBS: Used to specify a string of file names (comma separated string) to bind to the /.singularity.d/libs directory.
  10. SINGULARITY_CPU_SHARES: Specify a relative share of CPU time available to the container. Default is -1 (disabled).
  11. SINGULARITY_CPUS: Specify a fractional number of CPUs available to the container. Default is unset.
  12. SINGULARITY_CPUSET_CPUS: Specify a list or range of CPU cores available to the container. Default is unset.
  13. SINGULARITY_CPUSET_MEMS: Specify a list or range of memory nodes available to the container. Default is unset.
  14. SINGULARITY_CWD (deprecated SINGULARITY_PWD and SINGULARITY_TARGET_PWD): The initial working directory for payload process inside the container.

D

  1. SINGULARITY_DEBUG: Enable debug output when set. Equivalent to -d / --debug.
  2. SINGULARITY_DEFFILE: Shows the {Singularity} recipe that was used to generate the image.
  3. SINGULARITY_DESC: Contains a description of the capabilities.
  4. SINGULARITY_DETACHED: To submit a build job and print the build ID (no real-time logs and also requires --remote). Default is set to false.
  5. SINGULARITY_DISABLE_CACHE: To disable all caching of docker/oci, library, oras, etc. downloads and built SIFs. Default is set to false.
  6. SINGULARITY_DNS: A list of the DNS server addresses separated by commas to be added in resolv.conf.
  7. SINGULARITY_DOCKER_HOST: Host address / socket to use when pulling images from a docker-daemon source. DOCKER_HOST without the SINGULARITY_ prefix is also accepted.
  8. SINGULARITY_DOCKER_LOGIN: To specify the interactive prompt for docker authentication.
  9. SINGULARITY_DOCKER_PASSWORD: To specify the password for docker authentication. DOCKER_PASSWORD without the SINGULARITY_ prefix is also accepted.
  10. SINGULARITY_DOCKER_USERNAME: To specify the username for docker authentication. DOCKER_USERNAME without the SINGULARITY_ prefix is also accepted.
  11. SINGULARITY_DOWNLOAD_CONCURRENCY: To specify how many concurrent streams when downloading (pulling) an image from cloud library.
  12. SINGULARITY_DOWNLOAD_PART_SIZE: To specify the size of each part (bytes) when concurrent downloads are enabled.
  13. SINGULARITY_DOWNLOAD_BUFFER_SIZE: To specify the transfer buffer size (bytes) when concurrent downloads are enabled.
  14. SINGULARITY_DROP_CAPS: To specify a list (comma separated string) of capabilities to be dropped. Default is an empty string.

E

  1. SINGULARITY_ENCRYPTION_PASSPHRASE: Used to specify the plaintext passphrase to encrypt the container.
  2. SINGULARITY_ENCRYPTION_PEM_PATH: Used to specify the path of the file containing public or private key to encrypt the container in PEM format.
  3. SINGULARITY_ENV_FILE: Specify a file containing KEY=VAL environment variables that should be set in the container.
  4. SINGULARITY_ENVIRONMENT: Set during a build to the path to a file into which KEY=VAL environment variables can be added. The file is evaluated at container startup.
  5. SINGULARITYENV_*: Allows you to transpose variables into the container at runtime. You can see more in detail how to use this variable in our environment and metadata section <environment-and-metadata>.
  6. SINGULARITYENV_APPEND_PATH: Used to append directories to the end of the $PATH environment variable. You can see more in detail on how to use this variable in our environment and metadata section <environment-and-metadata>.
  7. SINGULARITYENV_PATH: A specified path to override the $PATH environment variable within the container. You can see more in detail on how to use this variable in our environment and metadata section <environment-and-metadata>.
  8. SINGULARITYENV_PREPEND_PATH: Used to prepend directories to the beginning of $PATH environment variable. You can see more in detail on how to use this variable in our environment and metadata section <environment-and-metadata>.

F

  1. SINGULARITY_FAKEROOT: Run or build a container using a user namespace with a root uid/gid mapping.
  2. SINGULARITY_FIXPERMS: Set to true to ensure owner has rwX permissions on all files in a container built from an OCI source.
  3. SINGULARITY_FORCE: Skip confirmation for destructive actions, e.g. overwriting a container image or killing an instance.
  4. SINGULARITY_FUSESPEC: A FUSE filesystem mount specification of the form '<type>:<fuse command> <mountpoint>', that will be mounted in the container.

H

  1. SINGULARITY_HELPFILE: Specifies the runscript helpfile, if it exists.
  2. SINGULARITY_HOME : A home directory specification, it could be a source or destination path. The source path is the home directory outside the container and the destination overrides the home directory within the container.
  3. SINGULARITY_HOSTNAME: The container's hostname.

I

  1. SINGULARITY_IMAGE: Filename of the container.

J

  1. SINGULARITY_JSON: Use JSON as an input or output format. Applies to the build and instance list commands. Default is false.

K

  1. SINGULARITY_KEEP_PRIVS: To let root user keep privileges in the container. Default is set to false.

L

  1. SINGULARITY_LABELS: Specifies the labels associated with the image.
  2. SINGULARITY_LIBRARY: Specifies the library to pull from. Default is set to our Cloud Library.
  3. SINGULARITY_LOCAL_VERIFY: Set to true to only use the local keyring when verifying PGP signed SIF images. Disables retrieval of public keys from configured keyservers. Default is false.
  4. SINGULARITY_LOGIN_USERNAME: Set the username to use when logging in to a remote endpoint, registry, or keyserver.
  5. SINGULARITY_LOGIN_PASSWORD: Set the password to use when logging in to a remote endpoint, registry, or keyserver.
  6. SINGULARITY_LOGIN_INSECURE: Set to true to use HTTP (not HTTPS) when logging in to a remote endpoint. Default is false.
  7. SINGULARITY_LOGS: Set to true to show the path to instance log files in instance list output. Default is false.

M

  1. SINGULARITY_MEMORY: Specify a memory limit in bytes for the container. Default is unset (no limit).
  2. SINGULARITY_MEMORY_RESERVATION: Specify a memory soft limit in bytes for the container. Default is unset (no limit).
  3. SINGULARITY_MEMORY_SWAP: Specify a limit for memory + swap usage by the container. Default is unset. Effect depends on SINGULARITY_MEMORY.
  4. SINGULARITY_MOUNT: To specify host to container mounts, using the syntax understood by the --mount flag. Multiple mounts should be separated by newline characters.

N

  1. SINGULARITY_NAME: Specifies a custom image name.
  2. SINGULARITY_NETWORK: Used to specify a desired network. If more than one parameters is used, addresses should be separated by commas, where each network will bring up a dedicated interface inside the container.
  3. SINGULARITY_NETWORK_ARGS: To specify the network arguments to pass to CNI plugins.
  4. SINGULARITY_NOCLEANUP: To not clean up the bundle after a failed build, this can be helpful for debugging. Default is set to false.
  5. SINGULARITY_NO_COMPAT: Set to true to emulate traditional Singularity behavior (e.g. home, cwd mounts) when running in OCI mode.
  6. SINGULARITY_NO_HTTPS and SINGULARITY_NOHTTPS: Set to true to use HTTP (not HTTPS) to communicate with registry servers. Default is false.
  7. SINGULARITY_NO_EVAL: Set to true in order to prevent {Singularity} performing shell evaluation on environment variables / runscript arguments at startup.
  8. SINGULARITY_NO_HOME: Considers not mounting users home directory if home is not the current working directory. Default is set to false.
  9. SINGULARITY_NO_INIT and SINGULARITY_NOSHIMINIT: Considers not starting the shim process with --pid.
  10. SINGULARITY_NO_MOUNT: Disable an automatic mount that has been set in singularity.conf. Accepts proc / sys / dev / devpts / home / tmp / hostfs / cwd, or the source path for a system specifc bind.
  11. SINGULARITY_NO_NV: Flag to disable NVIDIA support. Opposite of SINGULARITY_NV.
  12. SINGULARITY_NO_PID: Set to true to disable the PID namespace, when it is inferred by other options (e.g.--containall )
  13. SINGULARITY_NO_PRIVS: To drop all the privileges from root user in the container. Default is false.
  14. SINGULARITY_NO_SETGROUPS: When set to true, do not clear supplementary group membership when entering a fakeroot user namespace. Default is false.
  15. SINGULARITY_NOTEST: Set to true to disable execution of %test sections when building a container.
  16. SINGULARITY_NO_UMASK: Set to true to prevent host umask propagating to container, and use a default 0022 unmask instead. Default is false.
  17. SINGULARITY_NV: To enable NVIDIA GPU support. Default is set to false.
  18. SINGULARITY_NVCCLI: To use nvidia-container-cli for container GPU setup (experimental).
  19. SINGULARITY_NO_TMP_SANDBOX: Set to true to disable fall-back approach of extracting a container to a temporary sandbox when SIF / OCI-SIF mounts cannot be used. Default is false. Temporary sandboxes may also be disabled permanently by setting tmp sandbox = no in singularity.conf.

O

  1. SINGULARITY_OCI: Set to true to run containers in OCI mode, and pull OCI images to the OCI-SIF format. Default is taken from oci mode directive in singularity.conf.
  2. SINGULARITY_NO_OCI: Set to true to disable OCI mode, and pull OCI images to the native SIF format, when oci mode is enabled in singularity.conf.
  3. SINGULARITY_OOM_KILL_DISABLE: Set to true to disable OOM killer for container processes, if possible. Default is false.
  4. SINGULARITY_OVERLAY and SINGULARITY_OVERLAYIMAGE: To indicate the use of an overlay file system image for persistent data storage or as read-only layer of container.

P

  1. SINGULARITY_PULLDIR and SINGULARITY_PULLFOLDER: Specify destination directory when pulling a container image.
  2. SINGULARITY_PID_FILE: When starting an instance, write the instance PID to the specified file.
  3. SINGULARITY_PIDS_LIMIT: Specify maximum number of processes that the container may spawne. Default is 0 (no limit).
  4. SINGULARITY_PLATFORM: Set the platform (e.g. linux/arm/v7) of an image to pull from a library:// or OCI source. Defaults to the host platform. Note that library:// pulls ignore the platform variant.

R

  1. SINGULARITY_REMOTE: Set to true to build an image remotely using a remote build service. Default is set to false.
  2. SINGULARITY_ROOTFS: During a build SINGULARITY_ROOTFS is set to the path of the rootfs for the container. It can be used within a definition file to manipulate the rootfs (e.g. from the %setup section).
  3. SINGULARITY_ROCM: Set to true to expose ROCm devices and libraries inside the container. Default is false.
  4. SINGULARITY_RUNSCRIPT: Specifies the runscript of the image.

S

  1. SINGULARITY_SANDBOX: Set to true to specify that the format of the image should be a sandbox. Default is set to false.
  2. SINGULARITY_SCRATCH and SINGULARITY_SCRATCHDIR: Used to include a scratch directory within the container that is linked to a temporary directory. (use -W to force location)
  3. SINGULARITY_SECTION: Set to specify a comma separated string of all the sections to be run from the deffile (setup, post, files, environment, test, labels, none)
  4. SINGULARITY_SECURITY: Used to enable security features. (SELinux, Apparmor, Seccomp)
  5. SINGULARITY_SECRET: Lists all the private keys instead of the default which display the public ones.
  6. SINGULARITY_SHELL: The path to the program to be used as an interactive shell.
  7. SINGULARITY_SIF_FUSE: (deprecated) Set to true to attempt to mount SIF images with squashfuse in unprivileged user namespace workflows. This is now the default behaviour from {Singularity} 4.1.
  8. SINGULARITY_SIGNAL: Specifies the signal to send to an instance with singularity instance stop.
  9. SINGULARITY_SIGN_KEY: Set the path to a key file to be used when signing a SIF image.
  10. SINGULARITY_SPARSE: Set to true to create sparse overlay image files with the overlay command.

T

  1. SINGULARITY_TMP_SANDBOX: Set to true to force fall-back approach of extracting a container to a temporary sandbox, even direct when SIF / OCI-SIF mounts could be used. Default is false.
  2. SINGULARITY_TEST: Specifies the test script for the image.
  3. SINGULARITY_TMPDIR: Specify a location for temporary files to be used when pulling and building container images. See sec:temporaryfolders.

U

  1. SINGULARITY_UNSHARE_PID: To specify that the container will run in a new PID namespace. Default is set to false.
  2. SINGULARITY_UNSHARE_IPC: To specify that the container will run in a new IPC namespace. Default is set to false.
  3. SINGULARITY_UNSHARE_NET: To specify that the container will run in a new network namespace (sets up a bridge network interface by default). Default is set to false.
  4. SINGULARITY_UNSHARE_UTS: To specify that the container will run in a new UTS namespace. Default is set to false.
  5. SINGULARITY_UPDATE: To run the definition over an existing container (skips the header). Default is set to false.
  6. SINGULARITY_URL: Specifies the key server URL.
  7. SINGULARITY_USER: As root, specify a user to manage that user's instances with the instance commands.
  8. SINGULARITY_USERNS and SINGULARITY_UNSHARE_USERNS: To specify that the container will run in a new user namespace, allowing {Singularity} to run completely unprivileged on recent kernels. This may not support every feature of {Singularity}. (Sandbox image only). Default is set to false.

V

  1. SINGULARITY_VERIFY_CERTIFICATE: Set the path to a PEM file containing the certificate to be used when verifying an x509 signed SIF image.
  2. SINGULARITY_VERIFY_INTERMEDIATES: Set the path to a PEM file containing an intermediate certificate / chain to be used when verifying an x509 signed SIF image.
  3. SINGULARITY_VERIFY_KEY: Set the path to a key file to be used when verifying a key signed SIF image.
  4. SINGULARITY_VERIFY_OCSP: Set to true to enable OCSP verification of certificates. Default is false.
  5. SINGULARITY_VERIFY_ROOTS: Set the path to a PEM file containing root certificate(s) to be used when verifying an x509 signed SIF image.

W

  1. SINGULARITY_WORKDIR: The working directory to be used for /tmp, /var/tmp and $HOME (if -c or --contain was also used)
  2. SINGULARITY_WRITABLE: By default, all {Singularity} containers are available as read only, this option makes the file system accessible as read/write. Default set to false.
  3. SINGULARITY_WRITABLE_TMPFS: Makes the file system accessible as read-write with non-persistent data (with overlay support only). Default is set to false.

Build Modules

library bootstrap agent

Overview

You can use an existing container on the Container Library as your “base,” and then add customization. This allows you to build multiple images from the same starting point. For example, you may want to build several containers with the same custom python installation, the same custom compiler toolchain, or the same base MPI installation. Instead of building these from scratch each time, you could create a base container on the Container Library and then build new containers from that existing base container adding customizations in %post, %environment, %runscript, etc.

Keywords

Bootstrap: library

The Bootstrap keyword is always mandatory. It describes the bootstrap module to use.

From: <entity>/<collection>/<container>:<tag>

The From keyword is mandatory. It specifies the container to use as a base. entity is optional and defaults to library. collection is optional and defaults to default. This is the correct namespace to use for some official containers (alpine for example). tag is also optional and will default to latest.

Library: http://custom/library

The Library keyword is optional. It will default to https://library.sylabs.io.

Fingerprints: 22045C8C0B1004D058DE4BEDA20C27EE7FF7BA84

The Fingerprints keyword is optional. It specifies one or more comma separated fingerprints corresponding to PGP public keys. If present, the bootstrap image will be verified and the build will only proceed if it is signed by keys matching all of the specified fingerprints.

docker bootstrap agent

Overview

Docker images are comprised of layers that are assembled at runtime to create an image. You can use Docker layers to create a base image, and then add your own custom software. For example, you might use Docker’s Ubuntu image layers to create an Ubuntu {Singularity} container. You could do the same with CentOS, Debian, Arch, Suse, Alpine, BusyBox, etc.

Or maybe you want a container that already has software installed. For instance, maybe you want to build a container that uses CUDA and cuDNN to leverage the GPU, but you don’t want to install from scratch. You can start with one of the nvidia/cuda containers and install your software on top of that.

Or perhaps you have already invested in Docker and created your own Docker containers. If so, you can seamlessly convert them to {Singularity} with the docker bootstrap module.

Keywords

Bootstrap: docker

The Bootstrap keyword is always mandatory. It describes the bootstrap module to use.

From: <registry>/<namespace>/<container>:<tag>@<digest>

The From keyword is mandatory. It specifies the container to use as a base. registry is optional and defaults to index.docker.io. namespace is optional and defaults to library. This is the correct namespace to use for some official containers (ubuntu for example). tag is also optional and will default to latest

See {Singularity} and Docker <singularity-and-docker> for more detailed info on using Docker registries.

Registry: http://custom_registry

The Registry keyword is optional. It will default to index.docker.io.

Namespace: namespace

The Namespace keyword is optional. It will default to library.

Notes

Docker containers are stored as a collection of tarballs called layers. When building from a Docker container the layers must be downloaded and then assembled in the proper order to produce a viable file system. Then the file system must be converted to Singularity Image File (sif) format.

Building from Docker Hub is not considered reproducible because if any of the layers of the image are changed, the container will change. If reproducibility is important to your workflow, consider hosting a base container on the Container Library and building from it instead.

For detailed information about setting your build environment see Build Customization <build-environment>.

shub bootstrap agent

Overview

You can use an existing container on Singularity Hub as your “base,” and then add customization. This allows you to build multiple images from the same starting point. For example, you may want to build several containers with the same custom python installation, the same custom compiler toolchain, or the same base MPI installation. Instead of building these from scratch each time, you could create a base container on Singularity Hub and then build new containers from that existing base container adding customizations in %post , %environment, %runscript, etc.

Keywords

Bootstrap: shub

The Bootstrap keyword is always mandatory. It describes the bootstrap module to use.

From: shub://<registry>/<username>/<container-name>:<tag>@digest

The From keyword is mandatory. It specifies the container to use as a base. registry is optional and defaults tosingularity-hub.org.taganddigestare also optional.tagdefaults tolatestanddigestcan be left blank if you want the latest build. Notes ----- When bootstrapping from a Singularity Hub image, all previous definition files that led to the creation of the current image will be stored in a directory within the container called/.singularity.d/bootstrap_history. {Singularity} will also alert you if environment variables have been changed between the base image and the new image during bootstrap. .. _build-oras:orasbootstrap agent ======================== Overview -------- Using, this module, a container from supporting OCI Registries - Eg: ACR (Azure Container Registry), local container registries, etc can be used as your “base” image and later customized. This allows you to build multiple images from the same starting point. For example, you may want to build several containers with the same custom python installation, the same custom compiler toolchain, or the same base MPI installation. Instead of building these from scratch each time, you could make use oforasto pull an appropriate base container and then build new containers by adding customizations in%post,%environment,%runscript, etc. Keywords -------- .. code:: singularity Bootstrap: oras The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. .. code:: singularity From: registry/namespace/image:tag TheFromkeyword is mandatory. It specifies the container to use as a base. Also,tagis mandatory that refers to the version of image you want to use. .. _build-localimage:localimagebootstrap agent ============================== .. _sec:build-localimage: This module allows you to build a container from an existing {Singularity} container on your host system. The name is somewhat misleading because your container can be in either image or directory format. Overview -------- You can use an existing container image as your “base”, and then add customization. This allows you to build multiple images from the same starting point. For example, you may want to build several containers with the same custom python installation, the same custom compiler toolchain, or the same base MPI installation. Instead of building these from scratch each time, you could start with the appropriate local base container and then customize the new container in%post,%environment,%runscript, etc. Keywords -------- .. code:: singularity Bootstrap: localimage The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. .. code:: singularity From: /path/to/container/file/or/directory TheFromkeyword is mandatory. It specifies the local container to use as a base. .. code:: singularity Fingerprints: 22045C8C0B1004D058DE4BEDA20C27EE7FF7BA84 The Fingerprints keyword is optional. It specifies one or more comma separated fingerprints corresponding to PGP public keys. If present, and theFrom:keyword points to a SIF format image, it will be verified and the build will only proceed if it is signed by keys matching *all* of the specified fingerprints. Notes ----- When building from a local container, all previous definition files that led to the creation of the current container will be stored in a directory within the container called/.singularity.d/bootstrap_history. {Singularity} will also alert you if environment variables have been changed between the base image and the new image during bootstrap. .. _build-yum:yumbootstrap agent ======================= .. _sec:build-yum: This module allows you to build a Red Hat/CentOS/Scientific Linux style container from a mirror URI. Overview -------- Use theyummodule to specify a base for a CentOS-like container. You must also specify the URI for the mirror you would like to use. Keywords -------- .. code:: singularity Bootstrap: yum The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. .. code:: singularity OSVersion: 7 The OSVersion keyword is optional. It specifies the OS version you would like to use. It is only required if you have specified a %{OSVERSION} variable in theMirrorURLkeyword. .. code:: singularity MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/$basearch/ The MirrorURL keyword is mandatory. It specifies the URI to use as a mirror to download the OS. If you define theOSVersionkeyword, then you can use it in the URI as in the example above. .. code:: singularity Include: yum The Include keyword is optional. It allows you to install additional packages into the core operating system. It is a best practice to supply only the bare essentials such that the%postsection has what it needs to properly complete the build. One common package you may want to install when using theyumbuild module is YUM itself. Notes ----- There is a major limitation with using YUM to bootstrap a container. The RPM database that exists within the container will be created using the RPM library and Berkeley DB implementation that exists on the host system. If the RPM implementation inside the container is not compatible with the RPM database that was used to create the container, RPM and YUM commands inside the container may fail. This issue can be easily demonstrated by bootstrapping an older RHEL compatible image by a newer one (e.g. bootstrap a Centos 5 or 6 container from a Centos 7 host). In order to use theyumbuild module, you must haveyuminstalled on your system. It may seem counter-intuitive to install YUM on a system that uses a different package manager, but you can do so. For instance, on Ubuntu you can install it like so: .. code:: $ sudo apt-get update && sudo apt-get install yum .. _build-debootstrap:debootstrapbuild agent =========================== .. _sec:build-debootstrap: This module allows you to build a Debian/Ubuntu style container from a mirror URI. Overview -------- Use thedebootstrapmodule to specify a base for a Debian-like container. You must also specify the OS version and a URI for the mirror you would like to use. Keywords -------- .. code:: singularity Bootstrap: debootstrap The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. .. code:: singularity OSVersion: xenial The OSVersion keyword is mandatory. It specifies the OS version you would like to use. For Ubuntu you can use code words liketrusty(14.04),xenial(16.04), andyakkety(17.04). For Debian you can use values likestable,oldstable,testing, andunstableor code words likewheezy(7),jesse(8), andstretch(9). .. code:: singularity MirrorURL: http://us.archive.ubuntu.com/ubuntu/ The MirrorURL keyword is mandatory. It specifies a URI to use as a mirror when downloading the OS. .. code:: singularity Include: somepackage The Include keyword is optional. It allows you to install additional packages into the core operating system. It is a best practice to supply only the bare essentials such that the%postsection has what it needs to properly complete the build. Notes ----- In order to use thedebootstrapbuild module, you must havedebootstrapinstalled on your system. On Ubuntu you can install it like so: .. code:: $ sudo apt-get update && sudo apt-get install debootstrap On CentOS you can install it from the epel repos like so: .. code:: $ sudo yum update && sudo yum install epel-release && sudo yum install debootstrap.noarch .. _build-arch:archbootstrap agent ======================== .. _sec:build-arch: This module allows you to build a Arch Linux based container. Overview -------- Use thearchmodule to specify a base for an Arch Linux based container. Arch Linux uses the aptly namedpacmanpackage manager (all puns intended). Keywords -------- .. code:: singularity Bootstrap: arch The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. The Arch Linux bootstrap module does not name any additional keywords at this time. By defining thearchmodule, you have essentially given all of the information necessary for that particular bootstrap module to build a core operating system. Notes ----- Arch Linux is, by design, a very stripped down, light-weight OS. You may need to perform a significant amount of configuration to get a usable OS. Please refer to this `README.md <https://github.com/sylabs/singularity/blob/main/examples/arch/README.md>`_ and the `Arch Linux example <https://github.com/sylabs/singularity/blob/main/examples/arch/Singularity>`_ for more info. .. _build-busybox:busyboxbootstrap agent =========================== .. _sec:build-busybox: This module allows you to build a container based on BusyBox. Overview -------- Use thebusyboxmodule to specify a BusyBox base for container. You must also specify a URI for the mirror you would like to use. Keywords -------- .. code:: singularity Bootstrap: busybox The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. .. code:: singularity MirrorURL: https://www.busybox.net/downloads/binaries/1.26.1-defconfig-multiarch/busybox-x86_64 The MirrorURL keyword is mandatory. It specifies a URI to use as a mirror when downloading the OS. Notes ----- You can build a fully functional BusyBox container that only takes up ~600kB of disk space! .. _build-zypper:zypperbootstrap agent ========================== .. _sec:build-zypper: This module allows you to build a Suse style container from a mirror URI. .. note::zypperversion 1.11.20 or greater is required on the host system, as {Singularity} requires the--releaseverflag. Overview -------- Use thezyppermodule to specify a base for a Suse-like container. You must also specify a URI for the mirror you would like to use. Keywords -------- .. code:: singularity Bootstrap: zypper The Bootstrap keyword is always mandatory. It describes the bootstrap module to use. .. code:: singularity OSVersion: 42.2 The OSVersion keyword is optional. It specifies the OS version you would like to use. It is only required if you have specified a %{OSVERSION} variable in theMirrorURLkeyword. .. code:: singularity Include: somepackage The Include keyword is optional. It allows you to install additional packages into the core operating system. It is a best practice to supply only the bare essentials such that the%postsection has what it needs to properly complete the build. One common package you may want to install when using the zypper build module iszypperitself. .. _docker-daemon:docker-daemonbootstrap agent ================================= Overview --------docker-daemonallows you to build a SIF from any Docker image currently residing in the Docker daemon's internal storage: .. code:: console $ docker images alpine REPOSITORY TAG IMAGE ID CREATED SIZE alpine latest 965ea09ff2eb 7 weeks ago 5.55MB $ singularity run docker-daemon:alpine:latest INFO: Converting OCI blobs to SIF format INFO: Starting build... Getting image source signatures Copying blob 77cae8ab23bf done Copying config 759e71f0d3 done Writing manifest to image destination Storing signatures 2019/12/11 14:53:24 info unpack layer: sha256:eb7c47c7f0fd0054242f35366d166e6b041dfb0b89e5f93a82ad3a3206222502 INFO: Creating SIF file... Singularity> TheSINGULARITY_DOCKER_HOSTorDOCKER_HOSTenvironment variables may be set to instruct {{Singularity}} 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 setDOCKER_HOSTe.g. .. code:: To connect the Docker client to the Docker daemon, please set export DOCKER_HOST=tcp://192.168.59.103:2375 Keywords -------- In a definition file, thedocker-daemonbootstrap agent requires the source container reference to be provided with theFrom:keyword: .. code:: singularity Bootstrap: docker-daemon From: <image>:<tag> where both<image>and<tag>are mandatory fields that must be written explicitly. .. _docker-archive:docker-archivebootstrap agent ================================== Overview -------- Thedocker-archiveboostrap agent allows you to create a {Singularity} image from a docker image stored in adocker saveformatted tar file: .. code:: console $ docker save -o alpine.tar alpine:latest $ singularity run docker-archive:$(pwd)/alpine.tar INFO: Converting OCI blobs to SIF format INFO: Starting build... Getting image source signatures Copying blob 77cae8ab23bf done Copying config 759e71f0d3 done Writing manifest to image destination Storing signatures 2019/12/11 15:25:09 info unpack layer: sha256:eb7c47c7f0fd0054242f35366d166e6b041dfb0b89e5f93a82ad3a3206222502 INFO: Creating SIF file... Singularity> Keywords -------- In a definition file, thedocker-archivebootstrap agent requires the path to the tar file containing the image to be specified with theFrom:keyword. .. code:: singularity Bootstrap: docker-archive From: <path-to-tar-file> .. _scratch-agent:scratchbootstrap agent =========================== The scratch bootstrap agent allows you to start from a completely empty container. You are then responsible for adding any and all executables, libraries etc. that are required. Starting with a scratch container can be useful when you are aiming to minimize container size, and have a simple application / static binaries. Overview -------- A minimal container providing a shell can be created by copying thebusybox`` static binary into an empty scratch container:

Bootstrap: scratch

%setup
    # Runs on host - fetch static busybox binary
    curl -o /tmp/busybox https://www.busybox.net/downloads/binaries/1.31.0-i686-uclibc/busybox
    # It needs to be executable
    chmod +x /tmp/busybox

%files
    # Copy from host into empty container
    /tmp/busybox /bin/sh

%runscript
   /bin/sh

The resulting container provides a shell, and is 696KiB in size:

$ ls -lah scratch.sif
-rwxr-xr-x. 1 dave dave 696K May 28 13:29 scratch.sif

$ singularity run scratch.sif
WARNING: passwd file doesn't exist in container, not updating
WARNING: group file doesn't exist in container, not updating
Singularity> echo "Hello from a 696KiB container"
Hello from a 696KiB container

Keywords

Bootstrap: scratch

There are no additional keywords for the scratch bootstrap agent.