diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ee47c8f..28341102 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## udocker (1.3.18) - 2025-08-22 + +* New environment variable `UDOCKER_SET_EXECUTION_MODE` and configuration parameter + `set_execution_mode` to automatically set execution mode when running containers + from images. When set, this automatically creates a container and sets the + execution mode before running, equivalent to running `create`, `setup --execmode`, + and `run` commands in sequence. + ## udocker (1.3.17) - 2024-08-28 * Update docker tools url location diff --git a/codemeta.json b/codemeta.json index d688d7e2..76064394 100644 --- a/codemeta.json +++ b/codemeta.json @@ -6,7 +6,7 @@ "@type": "SoftwareSourceCode", "identifier": "udocker", "name": "udocker", - "version": "1.3.17", + "version": "1.3.18", "description": "A basic user tool to execute simple docker containers in batch or interactive systems without root privileges", "license": "Apache Software License 2.0, OSI Approved :: Apache Software License", "author": [ diff --git a/docs/installation_manual.md b/docs/installation_manual.md index b2c11ec9..5aca2179 100644 --- a/docs/installation_manual.md +++ b/docs/installation_manual.md @@ -201,6 +201,7 @@ The configuration files allow overriding of the udocker `Config` class dockerio_registry_url = "https://myregistry.mydomain:5000" http_insecure = True verbose_level = 5 +set_execution_mode = "F3" ``` udocker loads the following configuration files if they are present: @@ -269,6 +270,11 @@ from the host or from the udocker installation. in udocker under `$HOME/.udocker/lib`. * `UDOCKER_DEFAULT_EXECUTION_MODE`: default execution mode can be P1, P2, F1, S1, R1, R2 or R3. +* `UDOCKER_SET_EXECUTION_MODE`: automatically set execution mode when running + containers from images. When set, this automatically creates a container and + sets the execution mode before running, equivalent to running `create`, + `setup --execmode`, and `run` commands in sequence. Can also be set via + configuration file as `set_execution_mode`. Several executables and libraries are shipped with udocker. For instance the executable for the Rn modes can be selected to be either `runc` or @@ -283,6 +289,16 @@ export UDOCKER_DEFAULT_EXECUTION_MODE=R1 udocker run ``` +``` +# Automatically set execution mode when running from images +export UDOCKER_SET_EXECUTION_MODE=F3 +udocker run quay.io/pacbio/hiphase:1.5.0_build1 hiphase --help +# This is equivalent to: +# udocker create --name=hiphase quay.io/pacbio/hiphase:1.5.0_build1 +# udocker setup --execmode=F3 hiphase +# udocker run hiphase hiphase --help +``` + ## 6. External tools and libraries ### 6.1. Source code repositories diff --git a/docs/reference_card.md b/docs/reference_card.md index 703455c7..0f5fa873 100644 --- a/docs/reference_card.md +++ b/docs/reference_card.md @@ -22,6 +22,7 @@ The configuration files allow overriding of the udocker `Config` class dockerio_registry_url = https://myregistry.mydomain:5000 http_insecure = True verbose_level = 5 +set_execution_mode = F3 ``` udocker loads the following configuration files if they are present: @@ -45,6 +46,8 @@ udocker loads the following configuration files if they are present: * `UDOCKER_REGISTRY`: override default registry default is Docker Hub. * `UDOCKER_INDEX`: override default index default is Docker Hub. * `UDOCKER_DEFAULT_EXECUTION_MODE`: change default execution mode +* `UDOCKER_SET_EXECUTION_MODE`: automatically set execution mode when running + containers from images (can also be set via configuration file as `set_execution_mode`) * `UDOCKER_USE_CURL_EXECUTABLE`: pathname for curl executable * `UDOCKER_USE_PROOT_EXECUTABLE`: change pathname for proot executable * `UDOCKER_USE_RUNC_EXECUTABLE`: change pathname for runc executable @@ -53,7 +56,26 @@ udocker loads the following configuration files if they are present: * `UDOCKER_FAKECHROOT_EXPAND_SYMLINKS`: translate symbolic links in Fn modes * `UDOCKER_NOSYSCONF`: prevent loading of udocker system wide configuration -## 4. Verbosity +## 4. Automatic Execution Mode Setting + +The `UDOCKER_SET_EXECUTION_MODE` environment variable allows automatic setting +of execution mode when running containers from images. When set, udocker will +automatically create a container and set the execution mode before running, +equivalent to running `create`, `setup --execmode`, and `run` commands in sequence. + +```bash +export UDOCKER_SET_EXECUTION_MODE=F3 +udocker run quay.io/pacbio/hiphase:1.5.0_build1 hiphase --help +``` + +This is equivalent to: +```bash +udocker create --name=hiphase quay.io/pacbio/hiphase:1.5.0_build1 +udocker setup --execmode=F3 hiphase +udocker run hiphase hiphase --help +``` + +## 5. Verbosity The verbosity level of udocker can be enforced. Removing banners and most messages can be achieved by executing with `UDOCKER_LOGLEVEL=2`: @@ -66,7 +88,7 @@ Optionally invoke udocker with `--quiet` or `-q` to decrease verbosity. udocker --quiet run ``` -## 5. Security +## 6. Security udocker does not require any type of privileges nor the deployment of services by system administrators. It can be downloaded and executed @@ -77,7 +99,7 @@ Most udocker execution modes do not provide process isolation features such as docker. Due to the lack of isolation udocker must not be run by privileged users. -## 6. Troubleshooting +## 7. Troubleshooting Invoke udocker with `-D` for debugging. @@ -85,7 +107,7 @@ Invoke udocker with `-D` for debugging. udocker -D run ``` -## 7. Documentation +## 8. Documentation For Python 3: diff --git a/docs/user_manual.md b/docs/user_manual.md index b5c20410..e273897d 100644 --- a/docs/user_manual.md +++ b/docs/user_manual.md @@ -619,6 +619,11 @@ within a container. Execution modes can be changed using the command `udocker setup --execmode= ` for more information on available modes and their characteristics see section 3.27. +When running containers from images (using `udocker run REPO/IMAGE:TAG`), +the execution mode can be automatically set using the environment variable +`UDOCKER_SET_EXECUTION_MODE` or the configuration parameter `set_execution_mode`. +This automatically creates a container and sets the execution mode before running. + Options: * `--rm` delete the container after execution @@ -677,6 +682,11 @@ udocker run fedora:29 cat /etc/redhat-release # calls to run only create a single container that is then reused. udocker run --name=F29 --pull=reuse fedora:29 cat /etc/redhat-release +# Automatically set execution mode when running from images +export UDOCKER_SET_EXECUTION_MODE=F3 +udocker run quay.io/pacbio/hiphase:1.5.0_build1 hiphase --help +# This automatically creates a container and sets F3 execution mode + # In this example the host /tmp is mapped to the container /tmp udocker run --volume=/tmp myfed /bin/bash @@ -986,10 +996,25 @@ default modes: **P1**, **P2**, **F1**, **S1**, and **R1**. Changing the default execution mode can be useful if the default does not work as expected. -Example: +Additionally, udocker provides an automatic execution mode setting feature +through the environment variable **UDOCKER_SET_EXECUTION_MODE** or the +configuration parameter **set_execution_mode**. When set, this automatically +creates a container and sets the execution mode before running when using +`udocker run` with an image name, equivalent to running `create`, +`setup --execmode`, and `run` commands in sequence. + +Examples: ```bash UDOCKER_DEFAULT_EXECUTION_MODE=P2 ./udocker run mycontainer /bin/ls + +# Automatically set execution mode when running from images +export UDOCKER_SET_EXECUTION_MODE=F3 +udocker run quay.io/pacbio/hiphase:1.5.0_build1 hiphase --help +# This is equivalent to: +# udocker create --name=hiphase quay.io/pacbio/hiphase:1.5.0_build1 +# udocker setup --execmode=F3 hiphase +# udocker run hiphase hiphase --help ``` ### 3.28. tag diff --git a/udocker/__init__.py b/udocker/__init__.py index 3e9ff88f..2ac76df6 100644 --- a/udocker/__init__.py +++ b/udocker/__init__.py @@ -32,5 +32,5 @@ "Singularity http://singularity.lbl.gov" ] __license__ = "Licensed under the Apache License, Version 2.0" -__version__ = "1.3.17" -__date__ = "2024" +__version__ = "1.3.18" +__date__ = "2025" diff --git a/udocker/cli.py b/udocker/cli.py index d54a9cec..4050ea10 100644 --- a/udocker/cli.py +++ b/udocker/cli.py @@ -810,6 +810,11 @@ def do_run(self, cmdp): if not container_id: Msg().err("Error: image or container not available") return self.STATUS_ERROR + if Config.conf['set_execution_mode']: + Msg().out("setting execmode: %s" % (Config.conf['set_execution_mode'])) + exec_mode = ExecutionMode(self.localrepo, container_id) + if not exec_mode.set_mode(Config.conf['set_execution_mode'].upper(), False): + return self.STATUS_ERROR if name and container_id: if not self.localrepo.set_container_name(container_id, name): if pull != "reuse": diff --git a/udocker/config.py b/udocker/config.py index 76d1dfa8..0cfdf084 100644 --- a/udocker/config.py +++ b/udocker/config.py @@ -75,6 +75,8 @@ class Config(object): 'arm64': "P1", 'arm': "P2", 'ppc64le': "R1", 'DEFAULT': "R1"} + conf['set_execution_mode'] = "" + # PRoot override seccomp # conf['proot_noseccomp'] = True conf['proot_noseccomp'] = None @@ -255,6 +257,9 @@ def _env_override(self): Config.conf['override_default_execution_mode'] = \ os.getenv("UDOCKER_DEFAULT_EXECUTION_MODE", Config.conf['override_default_execution_mode']) + Config.conf['set_execution_mode'] = \ + os.getenv("UDOCKER_SET_EXECUTION_MODE", + Config.conf['set_execution_mode']) Config.conf['fakechroot_so'] = \ os.getenv("UDOCKER_FAKECHROOT_SO", Config.conf['fakechroot_so']) Config.conf['fakechroot_libc'] = \