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

NAME

6       apptainer-shell - Run a shell within a container
7
8
9

SYNOPSIS

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

DESCRIPTION

16       apptainer shell supports the following formats:
17
18
19       *.sif               Singularity Image Format (SIF). Native to Singular‐
20       ity
21                             (3.0+) and Apptainer (v1.0.0+)
22
23
24       *.sqsh              SquashFS format.  Native to Singularity 2.4+
25
26
27       *.img               ext3 format. Native to Singularity versions < 2.4.
28
29
30       directory/          sandbox format. Directory containing a  valid  root
31       file
32                             system and optionally Apptainer meta-data.
33
34
35       instance://*         A  local running instance of a container. (See the
36       instance
37                             command group.)
38
39
40       library://*         A SIF container hosted on a Library (no default)
41
42
43       docker://*          A Docker/OCI container hosted on Docker Hub or  an‐
44       other
45                             OCI registry.
46
47
48       shub://*            A container hosted on Singularity Hub.
49
50
51       oras://*            A SIF container hosted on an OCI registry that sup‐
52       ports
53                             the OCI Registry As Storage (ORAS) specification.
54
55
56

OPTIONS

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

EXAMPLE

310                $ apptainer shell /tmp/Debian.sif
311                Apptainer/Debian.sif> pwd
312                /home/gmk/test
313                Apptainer/Debian.sif> exit
314
315                $ apptainer shell -C /tmp/Debian.sif
316                Apptainer/Debian.sif> pwd
317                /home/gmk
318                Apptainer/Debian.sif> ls -l
319                total 0
320                Apptainer/Debian.sif> exit
321
322                $ sudo apptainer shell -w /tmp/Debian.sif
323                $ sudo apptainer shell --writable /tmp/Debian.sif
324
325                $ apptainer shell instance://my_instance
326
327                $ apptainer shell instance://my_instance
328                Apptainer: Invoking an interactive shell within container...
329                Apptainer container:~> ps -ef
330                UID        PID  PPID  C STIME TTY          TIME CMD
331                ubuntu       1     0  0 20:00 ?        00:00:00 /usr/local/bin/apptainer/bin/appinit
332                ubuntu       2     0  0 20:01 pts/8    00:00:00 /bin/bash --norc
333                ubuntu       3     2  0 20:02 pts/8    00:00:00 ps -ef
334
335
336
337

SEE ALSO

339       apptainer(1)
340
341
342

HISTORY

344       29-Mar-2023 Auto generated by spf13/cobra
345
346
347
348Auto generated by spf13/cobra      Mar 2023                       apptainer(1)
Impressum