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

NAME

6       apptainer-instance-start  -  Start  a  named instance of the given con‐
7       tainer image
8
9
10

SYNOPSIS

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

DESCRIPTION

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

EXAMPLE

302                $ apptainer instance start /tmp/my-sql.sif mysql
303
304                $ apptainer shell instance://mysql
305                Apptainer my-sql.sif> pwd
306                /home/mibauer/mysql
307                Apptainer my-sql.sif> ps
308                PID TTY          TIME CMD
309                  1 pts/0    00:00:00 appinit
310                  2 pts/0    00:00:00 bash
311                  3 pts/0    00:00:00 ps
312                Apptainer my-sql.sif>
313
314                $ apptainer instance stop /tmp/my-sql.sif mysql
315                Stopping /tmp/my-sql.sif mysql
316
317
318
319

SEE ALSO

321       apptainer-instance(1)
322
323
324

HISTORY

326       10-Jan-2023 Auto generated by spf13/cobra
327
328
329
330Auto generated by spf13/cobra      Jan 2023                       apptainer(1)
Impressum