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

NAME

6       apptainer-instance-run  -  Run  a named instance of the given container
7       image
8
9
10

SYNOPSIS

12       apptainer instance run [start options...]   [runscript args...]
13
14
15

DESCRIPTION

17       The instance run command allows you to create a new named instance from
18       an
19         existing  container  image that will begin running in the background.
20       If a
21         runscript is defined in the container metadata the commands  in  that
22       script
23         will  be  executed with the instance run command as well. You can op‐
24       tionally
25         pass arguments to runscript.
26
27
28       NOTE: This command was added to Apptainer significantly later than  the
29       other
30         action  commands  and  will  not  work with older containers. In that
31       case, you may
32         need to rebuild the container.
33
34
35       apptainer instance run accepts the following container formats
36
37
38       *.sif               Singularity Image Format (SIF). Native to Singular‐
39       ity
40                             (3.0+) and Apptainer (v1.0.0+)
41
42
43       *.sqsh              SquashFS format.  Native to Singularity 2.4+
44
45
46       *.img               ext3 format. Native to Singularity versions < 2.4.
47
48
49       directory/           sandbox  format. Directory containing a valid root
50       file
51                             system and optionally Apptainer meta-data.
52
53
54       instance://*        A local running instance of a container.  (See  the
55       instance
56                             command group.)
57
58
59       library://*         A SIF container hosted on a Library (no default)
60
61
62       docker://*           A Docker/OCI container hosted on Docker Hub or an‐
63       other
64                             OCI registry.
65
66
67       shub://*            A container hosted on Singularity Hub.
68
69
70       oras://*            A SIF container hosted on an OCI registry that sup‐
71       ports
72                             the OCI Registry As Storage (ORAS) specification.
73
74
75

OPTIONS

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

EXAMPLE

318                $ apptainer instance run /tmp/my-sql.sif mysql
319
320                $ apptainer shell instance://mysql
321                Apptainer my-sql.sif> pwd
322                /home/mibauer/mysql
323                Apptainer my-sql.sif> ps
324                PID TTY          TIME CMD
325                  1 pts/0    00:00:00 appinit
326                  2 pts/0    00:00:00 bash
327                  3 pts/0    00:00:00 ps
328                Apptainer my-sql.sif>
329
330                $ apptainer instance stop /tmp/my-sql.sif mysql
331                Stopping /tmp/my-sql.sif mysql
332
333
334
335

SEE ALSO

337       apptainer-instance(1)
338
339
340

HISTORY

342       22-Nov-2023 Auto generated by spf13/cobra
343
344
345
346Auto generated by spf13/cobra      Nov 2023                       apptainer(1)
Impressum