1apptainer(1)                                                      apptainer(1)
2
3
4

NAME

6       apptainer-run - Run the user-defined default command within a container
7
8
9

SYNOPSIS

11       apptainer run [run options...]
12
13
14

DESCRIPTION

16       This command will launch an Apptainer container and execute a runscript
17         if  one  is  defined  for that container. The runscript is a metadata
18       file within
19         the container that contains shell commands. If the  file  is  present
20       (and
21         executable)  then this command will execute that file within the con‐
22       tainer
23         automatically. All arguments following the  container  name  will  be
24       passed
25         directly to the runscript.
26
27
28       apptainer run accepts the following container formats:
29
30
31       *.sif               Singularity Image Format (SIF). Native to Singular‐
32       ity
33                             (3.0+) and Apptainer (v1.0.0+)
34
35
36       *.sqsh              SquashFS format.  Native to Singularity 2.4+
37
38
39       *.img               ext3 format. Native to Singularity versions < 2.4.
40
41
42       directory/          sandbox format. Directory containing a  valid  root
43       file
44                             system and optionally Apptainer meta-data.
45
46
47       instance://*         A  local running instance of a container. (See the
48       instance
49                             command group.)
50
51
52       library://*         A SIF container hosted on a Library (no default)
53
54
55       docker://*          A Docker/OCI container hosted on Docker Hub or  an‐
56       other
57                             OCI registry.
58
59
60       shub://*            A container hosted on Singularity Hub.
61
62
63       oras://*            A SIF container hosted on an OCI registry that sup‐
64       ports
65                             the OCI Registry As Storage (ORAS) specification.
66
67
68

OPTIONS

70       --add-caps=""      a comma separated capability list to add
71
72
73       --allow-setuid[=false]      allow setuid binaries  in  container  (root
74       only)
75
76
77       --app=""      set an application to run inside a container
78
79
80       --apply-cgroups=""      apply cgroups from file for container processes
81       (root only)
82
83
84       -B, --bind=[]      a user-bind path specification.  spec has the format
85       src[:dest[:opts]], where src and dest are outside and inside paths.  If
86       dest is not given, it is set equal to src.  Mount options ('opts')  may
87       be  specified as 'ro' (read-only) or 'rw' (read/write, which is the de‐
88       fault). Multiple bind paths can be given by a comma separated list.
89
90
91       --blkio-weight=0      Block IO relative weight in range 10-1000,  0  to
92       disable
93
94
95       --blkio-weight-device=[]      Device specific block IO relative weight
96
97
98       -e, --cleanenv[=false]      clean environment before running container
99
100
101       --compat[=false]       apply settings for increased OCI/Docker compati‐
102       bility.  Infers   --containall,   --no-init,   --no-umask,   --no-eval,
103       --writable-tmpfs.
104
105
106       -c, --contain[=false]      use minimal /dev and empty other directories
107       (e.g. /tmp and $HOME) instead of sharing filesystems from your host
108
109
110       -C, --containall[=false]      contain not only file systems,  but  also
111       PID, IPC, and environment
112
113
114       --cpu-shares=-1      CPU shares for container
115
116
117       --cpus=""      Number of CPUs available to container
118
119
120       --cpuset-cpus=""      List of host CPUs available to container
121
122
123       --cpuset-mems=""      List of host memory nodes available to container
124
125
126       --disable-cache[=false]      do not use or create cache
127
128
129       --dns=""       list  of  DNS  server  separated by commas to add in re‐
130       solv.conf
131
132
133       --docker-login[=false]      login to a Docker Repository interactively
134
135
136       --drop-caps=""      a comma separated capability list to drop
137
138
139       --env=[]      pass environment variable to contained process
140
141
142       --env-file=""      pass environment variables from  file  to  contained
143       process
144
145
146       -f,  --fakeroot[=false]       run container with the appearance of run‐
147       ning as root
148
149
150       --fusemount=[]      A FUSE filesystem mount specification of  the  form
151       ': ' - where  is 'container' or 'host', specifying where the mount will
152       be performed ('container-daemon' or 'host-daemon'  will  run  the  FUSE
153       process  detached).   is  the path to the FUSE executable, plus options
154       for the mount.  is the location in the  container  to  which  the  FUSE
155       mount  will  be attached. E.g. 'container:sshfs 10.0.0.1:/ /sshfs'. Im‐
156       plies --pid.
157
158
159       -h, --help[=false]      help for run
160
161
162       -H, --home="/builddir"      a home directory specification.   spec  can
163       either  be  a src path or src:dest pair.  src is the source path of the
164       home directory outside the container and dest overrides the home direc‐
165       tory within the container.
166
167
168       --hostname=""      set container hostname
169
170
171       -i, --ipc[=false]      run container in a new IPC namespace
172
173
174       --keep-privs[=false]       let  root  user keep privileges in container
175       (root only)
176
177
178       --memory=""      Memory limit in bytes
179
180
181       --memory-reservation=""      Memory soft limit in bytes
182
183
184       --memory-swap=""      Swap limit, use -1 for unlimited swap
185
186
187       --mount=[]      a mount specification e.g.  'type=bind,source=/opt,des‐
188       tination=/hostopt'.
189
190
191       -n,  --net[=false]       run container in a new network namespace (sets
192       up a bridge network interface by default)
193
194
195       --network=""      specify desired network  type  separated  by  commas,
196       each network will bring up a dedicated interface inside container
197
198
199       --network-args=[]      specify network arguments to pass to CNI plugins
200
201
202       --no-eval[=false]       do not shell evaluate env vars or OCI container
203       CMD/ENTRYPOINT/ARGS
204
205
206       --no-home[=false]      do NOT mount users home directory  if  /home  is
207       not the current working directory
208
209
210       --no-https[=false]      use http instead of https for docker:// oras://
211       and library:///... URIs
212
213
214       --no-init[=false]      do NOT start shim process with --pid
215
216
217       --no-mount=[]      disable one or more 'mount xxx' options set in  app‐
218       tainer.conf and/or specify absolute destination path to disable a 'bind
219       path' entry
220
221
222       --no-privs[=false]      drop all privileges  from  root  user  in  con‐
223       tainer)
224
225
226       --no-umask[=false]       do  not  propagate umask to the container, set
227       default 0022 umask
228
229
230       --nv[=false]      enable Nvidia support
231
232
233       --nvccli[=false]      use nvidia-container-cli for GPU  setup  (experi‐
234       mental)
235
236
237       --oom-kill-disable[=false]      Disable OOM killer
238
239
240       -o,  --overlay=[]      use an overlayFS image for persistent data stor‐
241       age or as read-only layer of container
242
243
244       --passphrase[=false]      prompt for an encryption passphrase
245
246
247       --pem-path=""      enter an path to a PEM formatted RSA key for an  en‐
248       crypted container
249
250
251       -p, --pid[=false]      run container in a new PID namespace
252
253
254       --pids-limit=0       Limit  number of container PIDs, use -1 for unlim‐
255       ited
256
257
258       --pwd=""      initial working directory for payload process inside  the
259       container
260
261
262       --rocm[=false]      enable experimental Rocm support
263
264
265       -S,  --scratch=[]      include a scratch directory within the container
266       that is linked to a temporary dir (use -W to force location)
267
268
269       --security=[]      enable security features  (SELinux,  Apparmor,  Sec‐
270       comp)
271
272
273       --unsquash[=false]       Convert  SIF  file to temporary sandbox before
274       running
275
276
277       -u, --userns[=false]      run container in a new user namespace
278
279
280       --uts[=false]      run container in a new UTS namespace
281
282
283       --vm[=false]      enable VM support
284
285
286       --vm-cpu="1"      number of CPU cores to allocate  to  Virtual  Machine
287       (implies --vm)
288
289
290       --vm-err[=false]      enable attaching stderr from VM
291
292
293       --vm-ip="dhcp"       IP Address to assign for container usage. Defaults
294       to DHCP within bridge network.
295
296
297       --vm-ram="1024"      amount of RAM in MiB to allocate  to  Virtual  Ma‐
298       chine (implies --vm)
299
300
301       -W,  --workdir=""       working directory to be used for /tmp, /var/tmp
302       and $HOME (if -c/--contain was also used)
303
304
305       -w, --writable[=false]      by default  all  Apptainer  containers  are
306       available as read only. This option makes the file system accessible as
307       read/write.
308
309
310       --writable-tmpfs[=false]      makes the file system accessible as read-
311       write with non persistent data (with overlay support only)
312
313
314

EXAMPLE

316                # Here we see that the runscript prints "Hello world: "
317                $ apptainer exec /tmp/debian.sif cat /apptainer
318                #!/bin/sh
319                echo "Hello world: "
320
321                # It runs with our inputs when we run the image
322                $ apptainer run /tmp/debian.sif one two three
323                Hello world: one two three
324
325                # Note that this does the same thing
326                $ ./tmp/debian.sif one two three
327
328
329
330

SEE ALSO

332       apptainer(1)
333
334
335

HISTORY

337       10-Jan-2023 Auto generated by spf13/cobra
338
339
340
341Auto generated by spf13/cobra      Jan 2023                       apptainer(1)
Impressum