1podman(1)()                                                        podman(1)()
2
3
4

NAME

6       podman - Simple management tool for pods, containers and images
7
8

SYNOPSIS

10       podman [options] command
11
12

DESCRIPTION

14       Podman  (Pod  Manager)  is  a fully featured container engine that is a
15       simple daemonless tool.  Podman provides a Docker-CLI  comparable  com‐
16       mand  line  that  eases the transition from other container engines and
17       allows the management of pods,  containers  and  images.   Simply  put:
18       alias  docker=podman.   Most  Podman  commands  can be run as a regular
19       user, without requiring additional privileges.
20
21
22       Podman uses Buildah(1) internally  to  create  container  images.  Both
23       tools share image (not container) storage, hence each can use or manip‐
24       ulate images (but not containers) created by the other.
25
26
27       Default settings for flags are defined in  containers.conf.  Most  set‐
28       tings  for  Remote connections use the server's containers.conf, except
29       when documented in man pages.
30
31
32       podman [GLOBAL OPTIONS]
33
34

GLOBAL OPTIONS

36   --cgroup-manager=manager
37       The CGroup manager to use for container cgroups. Supported  values  are
38       cgroupfs  or  systemd. Default is systemd unless overridden in the con‐
39       tainers.conf file.
40
41
42       Note: Setting this flag can cause certain commands to break when called
43       on  containers  previously  created  by  the other CGroup manager type.
44       Note: CGroup manager is not  supported  in  rootless  mode  when  using
45       CGroups Version V1.
46
47
48   --conmon
49       Path  of  the  conmon  binary  (Default  path is configured in contain‐
50       ers.conf)
51
52
53   --connection, -c
54       Connection to use for remote podman, including Mac and Windows (exclud‐
55       ing  WSL2)  machines,  (Default  connection  is  configured in contain‐
56       ers.conf) Setting this option will switch the --remote option to  true.
57       Remote connections use local containers.conf for default.
58
59
60   --events-backend=type
61       Backend  to  use for storing events. Allowed values are file, journald,
62       and none. When file is specified, the events are stored under a  subdi‐
63       rectory of the tmpdir location (see --tmpdir below).
64
65
66   --help, -h
67       Print usage statement
68
69
70   --hooks-dir=path
71       Each  *.json  file in the path configures a hook for Podman containers.
72       For more details on the syntax of the JSON files and the  semantics  of
73       hook  injection, see oci-hooks(5).  Podman and libpod currently support
74       both the 1.0.0 and 0.1.0 hook schemas, although  the  0.1.0  schema  is
75       deprecated.
76
77
78       This  option  may  be set multiple times; paths from later options have
79       higher precedence (oci-hooks(5) discusses directory precedence).
80
81
82       For the annotation conditions, libpod uses any annotations set  in  the
83       generated OCI configuration.
84
85
86       For  the bind-mount conditions, only mounts explicitly requested by the
87       caller via --volume are considered.  Bind mounts that libpod inserts by
88       default (e.g. /dev/shm) are not considered.
89
90
91       If  --hooks-dir  is unset for root callers, Podman and libpod will cur‐
92       rently default to /usr/share/containers/oci/hooks.d  and  /etc/contain‐
93       ers/oci/hooks.d  in  order  of  increasing precedence.  Using these de‐
94       faults is deprecated, and callers should migrate to explicitly  setting
95       --hooks-dir.
96
97
98       Podman and libpod currently support an additional precreate state which
99       is called before the runtime's  create  operation.   Unlike  the  other
100       stages,  which  receive  the  container  state on their standard input,
101       precreate hooks receive the proposed  runtime  configuration  on  their
102       standard input.  They may alter that configuration as they see fit, and
103       write the altered form to their standard output.
104
105
106       WARNING: the precreate hook lets you do powerful things, such as adding
107       additional  mounts to the runtime configuration.  That power also makes
108       it easy to break things.  Before reporting libpod errors,  try  running
109       your  container  with precreate hooks disabled to see if the problem is
110       due to one of your hooks.
111
112
113   --identity=path
114       Path to ssh identity file. If the identity  file  has  been  encrypted,
115       podman  prompts  the  user  for the passphrase.  If no identity file is
116       provided and no user is given, podman defaults to the user running  the
117       podman  command.   Podman  prompts for the login password on the remote
118       server.
119
120
121       Identity value resolution precedence:
122        - command line value
123        - environment variable CONTAINER_SSHKEY, if CONTAINER_HOST is found
124        - containers.conf Remote connections use local containers.conf for de‐
125       fault.
126
127
128   --log-level=level
129       Log  messages  at  and above specified level: debug, info, warn, error,
130       fatal or panic (default: "warn")
131
132
133   --namespace=namespace
134       Set libpod namespace. Namespaces are used to separate  groups  of  con‐
135       tainers  and  pods  in  libpod's state.  When namespace is set, created
136       containers and pods will join the given namespace, and only  containers
137       and pods in the given namespace will be visible to Podman.
138
139
140   --network-cmd-path=path
141       Path to the command binary to use for setting up a network.  It is cur‐
142       rently only used for setting up a slirp4netns network.  If ""  is  used
143       then the binary is looked up using the $PATH environment variable.
144
145
146   --network-config-dir=directory
147       Path  to  the  directory where network configuration files are located.
148       For the CNI  backend  the  default  is  "/etc/cni/net.d"  as  root  and
149       "$HOME/.config/cni/net.d"   as  rootless.   For  the  netavark  backend
150       "/etc/containers/networks" is used as root and "$graphroot/networks" as
151       rootless.
152
153
154   --noout
155       Redirect stdout to /dev/null. This command will prevent all stdout from
156       the Podman command. The --noout  option will not block stderr or stdout
157       from containers.
158
159
160   --remote, -r
161       When  true,  access  to  the Podman service will be remote. Defaults to
162       false.  Settings can be modified in the containers.conf  file.  If  the
163       CONTAINER_HOST  environment  variable  is  set, the --remote option de‐
164       faults to true.
165
166
167   --root=value
168       Storage root dir in which data, including images, is  stored  (default:
169       "/var/lib/containers/storage"  for  UID 0, "$HOME/.local/share/contain‐
170       ers/storage"  for  other  users).   Default  root  dir  configured   in
171       /etc/containers/storage.conf.
172
173
174       Overriding this option will cause the storage-opt settings in /etc/con‐
175       tainers/storage.conf to be ignored.  The user must  specify  additional
176       options via the --storage-opt flag.
177
178
179   --runroot=value
180       Storage state directory where all state information is stored (default:
181       "/run/containers/storage" for UID  0,  "/run/user/$UID/run"  for  other
182       users).  Default state dir configured in /etc/containers/storage.conf.
183
184
185   --runtime=value
186       Name  of  the  OCI  runtime as specified in containers.conf or absolute
187       path to the OCI compatible binary used to run containers.
188
189
190   --runtime-flag=flag
191       Adds global flags for the container  runtime.  To  list  the  supported
192       flags,  please  consult  the manpages of the selected container runtime
193       (runc is the default runtime, the manpage to consult is runc(8).   When
194       the  machine  is configured for cgroup V2, the default runtime is crun,
195       the manpage to consult is crun(8).).
196
197
198       Note: Do not pass the leading -- to the flag. To  pass  the  runc  flag
199       --log-format json to podman build, the option given would be --runtime-
200       flag log-format=json.
201
202
203   --storage-driver=value
204       Storage driver.  The default storage driver for UID 0 is configured  in
205       /etc/containers/storage.conf  ($HOME/.config/containers/storage.conf in
206       rootless mode), and is vfs for non-root users  when  fuse-overlayfs  is
207       not  available.   The STORAGE_DRIVER environment variable overrides the
208       default.  The --storage-driver specified driver overrides all.
209
210
211       Overriding this option will cause the storage-opt settings in /etc/con‐
212       tainers/storage.conf  to  be ignored.  The user must specify additional
213       options via the --storage-opt flag.
214
215
216   --storage-opt=value
217       Storage driver option, Default storage driver options are configured in
218       /etc/containers/storage.conf  ($HOME/.config/containers/storage.conf in
219       rootless mode). The STORAGE_OPTS environment variable overrides the de‐
220       fault.  The --storage-opt specified options overrides all. If you spec‐
221       ify --storage-opt="", no storage options will be used.
222
223
224   --syslog
225       Output logging information to syslog as well as  the  console  (default
226       false).
227
228
229       On remote clients, including Mac and Windows (excluding WSL2) machines,
230       logging is directed to the file $HOME/.config/containers/podman.log.
231
232
233   --tmpdir
234       Path to the tmp directory, for libpod runtime content.
235
236
237       NOTE --tmpdir is not used for the temporary storage of  downloaded  im‐
238       ages.   Use  the  environment  variable  TMPDIR to change the temporary
239       storage location of downloaded container images. Podman defaults to use
240       /var/tmp.
241
242
243   --url=value
244       URL  to  access  Podman service (default from containers.conf, rootless
245       unix://run/user/$UID/podman/podman.sock  or  as  root   unix://run/pod‐
246       man/podman.sock).   Setting this option will switch the --remote option
247       to true.
248
249
250CONTAINER_HOST  is  of  the  format  <schema>://[<user[:<pass‐
251                word>]@]<host>[:<port>][<path>]
252
253
254
255       Details:
256        - schema is one of:
257          *  ssh (default): a local unix(7) socket on the named host and port,
258       reachable via SSH
259          * tcp: an unencrypted, unauthenticated TCP connection to  the  named
260       host and port
261          * unix: a local unix(7) socket at the specified path, or the default
262       for the user
263        - user will default to either root or the current  running  user  (ssh
264       only)
265        - password has no default (ssh only)
266        -  host  must  be provided and is either the IP or name of the machine
267       hosting the Podman service (ssh and tcp)
268        - port defaults to 22 (ssh and tcp)
269        -   path    defaults    to    either    /run/podman/podman.sock,    or
270       /run/user/$UID/podman/podman.sock  if  running rootless (unix), or must
271       be explicitly specified (ssh)
272
273
274       URL value resolution precedence:
275        - command line value
276        - environment variable CONTAINER_HOST
277        - containers.conf service_destinations table
278        - unix://run/podman/podman.sock
279
280
281       Remote connections use local containers.conf for default.
282
283
284       Some example URL values in valid formats:
285        - unix://run/podman/podman.sock
286        - unix://run/user/$UID/podman/podman.sock
287        - ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock
288        - ssh://root@localhost:22/run/podman/podman.sock
289        - tcp://localhost:34451
290        - tcp://127.0.0.1:34451
291
292
293   --version, -v
294       Print the version
295
296
297   --volumepath=value
298       Volume directory where builtin volume information is  stored  (default:
299       "/var/lib/containers/storage/volumes"    for    UID    0,   "$HOME/.lo‐
300       cal/share/containers/storage/volumes" for other users). Default  volume
301       path can be overridden in containers.conf.
302
303

Environment Variables

305       Podman  can  set up environment variables from env of [engine] table in
306       containers.conf. These variables can be overridden by passing  environ‐
307       ment variables before the podman commands.
308
309
310   CONTAINERS_CONF
311       Set default locations of containers.conf file
312
313
314   CONTAINERS_REGISTRIES_CONF
315       Set default location of the registries.conf file.
316
317
318   CONTAINERS_STORAGE_CONF
319       Set default location of the storage.conf file.
320
321
322   CONTAINER_CONNECTION
323       Override  default --connection value to access Podman service. Also en‐
324       abled --remote option.
325
326
327   CONTAINER_HOST
328       Set default --url value to access Podman service. Also enabled --remote
329       option.
330
331
332   CONTAINER_SSHKEY
333       Set default --identity path to ssh key file value used to access Podman
334       service.
335
336
337   STORAGE_DRIVER
338       Set default --storage-driver value.
339
340
341   STORAGE_OPTS
342       Set default --storage-opts value.
343
344
345   TMPDIR
346       Set the temporary storage location of downloaded container images. Pod‐
347       man defaults to use /var/tmp.
348
349
350   XDG_CONFIG_HOME
351       In Rootless mode configuration files are read from XDG_CONFIG_HOME when
352       specified,  otherwise  in  the  home  directory  of  the   user   under
353       $HOME/.config/containers.
354
355
356   XDG_DATA_HOME
357       In  Rootless mode images are pulled under XDG_DATA_HOME when specified,
358       otherwise  in  the  home  directory  of  the  user   under   $HOME/.lo‐
359       cal/share/containers/storage.
360
361
362   XDG_RUNTIME_DIR
363       In  Rootless  mode temporary configuration data is stored in ${XDG_RUN‐
364       TIME_DIR}/containers.
365
366

Remote Access

368       The Podman command can be used with remote services using the  --remote
369       flag.  Connections  can be made using local unix domain sockets, ssh or
370       directly to tcp sockets. When specifying the podman --remote flag, only
371       the  global  options  --url,  --identity, --log-level, --connection are
372       used.
373
374
375       Connection information can also be managed  using  the  containers.conf
376       file.
377
378

Exit Codes

380       The  exit  code  from  podman gives information about why the container
381       failed to run or why it exited.  When podman commands exit with a  non-
382       zero code, the exit codes follow the chroot standard, see below:
383
384
385       125 The error is with podman itself
386
387
388              $ podman run --foo busybox; echo $?
389              Error: unknown flag: --foo
390              125
391
392
393
394       126 Executing a contained command and the command cannot be invoked
395
396
397              $ podman run busybox /etc; echo $?
398              Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
399              126
400
401
402
403       127 Executing a contained command and the command cannot be found
404           $ podman run busybox foo; echo $?
405           Error:  container_linux.go:346:  starting  container process caused
406       "exec: \"foo\": executable file not found in $PATH": OCI runtime error
407           127
408
409
410       Exit code contained command exit code
411
412
413              $ podman run busybox /bin/sh -c 'exit 3'; echo $?
414              3
415
416
417

COMMANDS

419       ┌──────────────────────┬────────────────────────────────┐
420Command               Description                    
421       ├──────────────────────┼────────────────────────────────┤
422podman-attach(1)      │ Attach to a running container. │
423       ├──────────────────────┼────────────────────────────────┤
424podman-auto-update(1) │ Auto update containers accord‐ │
425       │                      │ ing  to their auto-update pol‐ │
426       │                      │ icy                            │
427       ├──────────────────────┼────────────────────────────────┤
428podman-build(1)       │ Build a container image  using │
429       │                      │ a Containerfile.               │
430       ├──────────────────────┼────────────────────────────────┤
431podman-commit(1)      │ Create  new image based on the │
432       │                      │ changed container.             │
433       ├──────────────────────┼────────────────────────────────┤
434podman-completion(1)  │ Generate   shell    completion │
435       │                      │ scripts                        │
436       ├──────────────────────┼────────────────────────────────┤
437podman-container(1)   │ Manage containers.             │
438       ├──────────────────────┼────────────────────────────────┤
439podman-cp(1)          │ Copy  files/folders  between a │
440       │                      │ container   and   the    local │
441       │                      │ filesystem.                    │
442       ├──────────────────────┼────────────────────────────────┤
443podman-create(1)      │ Create a new container.        │
444       ├──────────────────────┼────────────────────────────────┤
445podman-diff(1)        │ Inspect changes on a container │
446       │                      │ or image's filesystem.         │
447       ├──────────────────────┼────────────────────────────────┤
448podman-events(1)      │ Monitor Podman events          │
449       ├──────────────────────┼────────────────────────────────┤
450podman-exec(1)        │ Execute a command in a running │
451       │                      │ container.                     │
452       ├──────────────────────┼────────────────────────────────┤
453podman-export(1)      │ Export  a container's filesys‐ │
454       │                      │ tem contents as a tar archive. │
455       ├──────────────────────┼────────────────────────────────┤
456podman-generate(1)    │ Generate structured data based │
457       │                      │ on  containers,  pods  or vol‐ │
458       │                      │ umes.                          │
459       ├──────────────────────┼────────────────────────────────┤
460podman-healthcheck(1) │ Manage healthchecks  for  con‐ │
461       │                      │ tainers                        │
462       ├──────────────────────┼────────────────────────────────┤
463podman-history(1)     │ Show the history of an image.  │
464       ├──────────────────────┼────────────────────────────────┤
465podman-image(1)       │ Manage images.                 │
466       ├──────────────────────┼────────────────────────────────┤
467podman-images(1)      │ List images in local storage.  │
468       ├──────────────────────┼────────────────────────────────┤
469podman-import(1)      │ Import  a  tarball and save it │
470       │                      │ as a filesystem image.         │
471       ├──────────────────────┼────────────────────────────────┤
472podman-info(1)        │ Displays Podman related system │
473       │                      │ information.                   │
474       ├──────────────────────┼────────────────────────────────┤
475podman-init(1)        │ Initialize  one  or  more con‐ │
476       │                      │ tainers                        │
477       ├──────────────────────┼────────────────────────────────┤
478podman-inspect(1)     │ Display  a  container,  image, │
479       │                      │ volume, network, or pod's con‐ │
480       │                      │ figuration.                    │
481       ├──────────────────────┼────────────────────────────────┤
482podman-kill(1)        │ Kill the main process  in  one │
483       │                      │ or more containers.            │
484       ├──────────────────────┼────────────────────────────────┤
485podman-load(1)        │ Load  image(s)  from a tar ar‐ │
486       │                      │ chive into container storage.  │
487       ├──────────────────────┼────────────────────────────────┤
488podman-login(1)       │ Login to a container registry. │
489       ├──────────────────────┼────────────────────────────────┤
490podman-logout(1)      │ Logout  of  a  container  reg‐ │
491       │                      │ istry.                         │
492       ├──────────────────────┼────────────────────────────────┤
493podman-logs(1)        │ Display  the  logs  of  one or │
494       │                      │ more containers.               │
495       ├──────────────────────┼────────────────────────────────┤
496podman-machine(1)     │ Manage  Podman's  virtual  ma‐ │
497       │                      │ chine                          │
498       ├──────────────────────┼────────────────────────────────┤
499podman-manifest(1)    │ Create and manipulate manifest │
500       │                      │ lists and image indexes.       │
501       ├──────────────────────┼────────────────────────────────┤
502podman-mount(1)       │ Mount  a  working  container's │
503       │                      │ root filesystem.               │
504       ├──────────────────────┼────────────────────────────────┤
505podman-network(1)     │ Manage Podman networks.        │
506       ├──────────────────────┼────────────────────────────────┤
507podman-pause(1)       │ Pause one or more containers.  │
508       ├──────────────────────┼────────────────────────────────┤
509podman-play(1)        │ Play  containers, pods or vol‐ │
510       │                      │ umes based on a structured in‐ │
511       │                      │ put file.                      │
512       ├──────────────────────┼────────────────────────────────┤
513podman-pod(1)         │ Management  tool for groups of │
514       │                      │ containers, called pods.       │
515       ├──────────────────────┼────────────────────────────────┤
516podman-port(1)        │ List port mappings for a  con‐ │
517       │                      │ tainer.                        │
518       ├──────────────────────┼────────────────────────────────┤
519podman-ps(1)          │ Prints  out  information about │
520       │                      │ containers.                    │
521       ├──────────────────────┼────────────────────────────────┤
522podman-pull(1)        │ Pull an image from a registry. │
523       ├──────────────────────┼────────────────────────────────┤
524podman-push(1)        │ Push an image,  manifest  list │
525       │                      │ or   image  index  from  local │
526       │                      │ storage to elsewhere.          │
527       ├──────────────────────┼────────────────────────────────┤
528podman-rename(1)      │ Rename an existing container.  │
529       ├──────────────────────┼────────────────────────────────┤
530podman-restart(1)     │ Restart one or  more  contain‐ │
531       │                      │ ers.                           │
532       ├──────────────────────┼────────────────────────────────┤
533podman-rm(1)          │ Remove one or more containers. │
534       ├──────────────────────┼────────────────────────────────┤
535podman-rmi(1)         │ Removes  one  or  more locally │
536       │                      │ stored images.                 │
537       ├──────────────────────┼────────────────────────────────┤
538podman-run(1)         │ Run a command in  a  new  con‐ │
539       │                      │ tainer.                        │
540       ├──────────────────────┼────────────────────────────────┤
541podman-save(1)        │ Save image(s) to an archive.   │
542       ├──────────────────────┼────────────────────────────────┤
543podman-search(1)      │ Search  a  registry for an im‐ │
544       │                      │ age.                           │
545       ├──────────────────────┼────────────────────────────────┤
546podman-secret(1)      │ Manage podman secrets.         │
547       ├──────────────────────┼────────────────────────────────┤
548podman-start(1)       │ Start one or more containers.  │
549       ├──────────────────────┼────────────────────────────────┤
550podman-stats(1)       │ Display a live stream  of  one │
551       │                      │ or  more  container's resource │
552       │                      │ usage statistics.              │
553       ├──────────────────────┼────────────────────────────────┤
554podman-stop(1)        │ Stop one or more running  con‐ │
555       │                      │ tainers.                       │
556       ├──────────────────────┼────────────────────────────────┤
557podman-system(1)      │ Manage podman.                 │
558       ├──────────────────────┼────────────────────────────────┤
559podman-tag(1)         │ Add  an  additional  name to a │
560       │                      │ local image.                   │
561       ├──────────────────────┼────────────────────────────────┤
562podman-top(1)         │ Display the running  processes │
563       │                      │ of a container.                │
564       ├──────────────────────┼────────────────────────────────┤
565podman-unmount(1)     │ Unmount  a working container's │
566       │                      │ root filesystem.               │
567       ├──────────────────────┼────────────────────────────────┤
568podman-unpause(1)     │ Unpause one or  more  contain‐ │
569       │                      │ ers.                           │
570       ├──────────────────────┼────────────────────────────────┤
571podman-unshare(1)     │ Run a command inside of a mod‐ │
572       │                      │ ified user namespace.          │
573       ├──────────────────────┼────────────────────────────────┤
574podman-untag(1)       │ Removes one or more names from │
575       │                      │ a locally-stored image.        │
576       ├──────────────────────┼────────────────────────────────┤
577podman-version(1)     │ Display the Podman version in‐ │
578       │                      │ formation.                     │
579       ├──────────────────────┼────────────────────────────────┤
580podman-volume(1)      │ Simple  management  tool   for │
581       │                      │ volumes.                       │
582       ├──────────────────────┼────────────────────────────────┤
583podman-wait(1)        │ Wait on one or more containers │
584       │                      │ to stop and print  their  exit │
585       │                      │ codes.                         │
586       └──────────────────────┴────────────────────────────────┘
587

CONFIGURATION FILES

589       containers.conf  (/usr/share/containers/containers.conf,  /etc/contain‐
590       ers/containers.conf, $HOME/.config/containers/containers.conf)
591
592
593       Podman has builtin defaults for command line  options.  These  defaults
594       can be overridden using the containers.conf configuration files.
595
596
597       Distributions  ship the /usr/share/containers/containers.conf file with
598       their default settings. Administrators can override fields in this file
599       by  creating  the /etc/containers/containers.conf file.  Users can fur‐
600       ther modify defaults by creating the  $HOME/.config/containers/contain‐
601       ers.conf  file.  Podman  merges its builtin defaults with the specified
602       fields from these files, if they exist. Fields specified in  the  users
603       file  override  the administrator's file, which overrides the distribu‐
604       tion's file, which override the built-in defaults.
605
606
607       Podman uses builtin defaults if no containers.conf file is found.
608
609
610       If the CONTAINERS_CONF environment variable is set, then its  value  is
611       used for the containers.conf file rather than the default.
612
613
614       mounts.conf (/usr/share/containers/mounts.conf)
615
616
617       The  mounts.conf file specifies volume mount directories that are auto‐
618       matically mounted inside containers when executing the  podman  run  or
619       podman start commands. Administrators can override the defaults file by
620       creating /etc/containers/mounts.conf.
621
622
623       When Podman runs in  rootless  mode,  the  file  $HOME/.config/contain‐
624       ers/mounts.conf will override the default if it exists. Please refer to
625       containers-mounts.conf(5) for further details.
626
627
628       policy.json (/etc/containers/policy.json)
629
630
631       Signature verification policy files are used to  specify  policy,  e.g.
632       trusted  keys,  applicable when deciding whether to accept an image, or
633       individual signatures of that image, as valid.
634
635
636       registries.conf  (/etc/containers/registries.conf,   $HOME/.config/con‐
637       tainers/registries.conf)
638
639
640       registries.conf  is  the  configuration file which specifies which con‐
641       tainer registries should be consulted when completing image names which
642       do not include a registry or domain portion.
643
644
645       Non  root  users of Podman can create the $HOME/.config/containers/reg‐
646       istries.conf file to be used instead of the system defaults.
647
648
649       If the CONTAINERS_REGISTRIES_CONF environment variable is set, then its
650       value is used for the registries.conf file rather than the default.
651
652
653       storage.conf    (/etc/containers/storage.conf,   $HOME/.config/contain‐
654       ers/storage.conf)
655
656
657       storage.conf is the storage configuration file for all tools using con‐
658       tainers/storage
659
660
661       The storage configuration file specifies all of the available container
662       storage options for tools using shared container storage.
663
664
665       When Podman runs in  rootless  mode,  the  file  $HOME/.config/contain‐
666       ers/storage.conf is used instead of the system defaults.
667
668
669       If  the  CONTAINERS_STORAGE_CONF  environment variable is set, then its
670       value is used for the storage.conf file rather than the default.
671
672

Rootless mode

674       Podman can also be used as non-root user. When podman runs in  rootless
675       mode,  a  user namespace is automatically created for the user, defined
676       in /etc/subuid and /etc/subgid.
677
678
679       Containers created by a non-root user are not visible  to  other  users
680       and are not seen or managed by Podman running as root.
681
682
683       It  is required to have multiple uids/gids set for a user.  Be sure the
684       user is present in the files /etc/subuid and /etc/subgid.
685
686
687       If you have a recent version of usermod, you can execute the  following
688       commands to add the ranges to the files
689
690
691              $ sudo usermod --add-subuids 10000-75535 USERNAME
692              $ sudo usermod --add-subgids 10000-75535 USERNAME
693
694
695
696       Or just add the content manually.
697
698
699              $ echo USERNAME:10000:65536 >> /etc/subuid
700              $ echo USERNAME:10000:65536 >> /etc/subgid
701
702
703
704       See the subuid(5) and subgid(5) man pages for more information.
705
706
707       Images  are pulled under XDG_DATA_HOME when specified, otherwise in the
708       home directory of the user under .local/share/containers/storage.
709
710
711       Currently the slirp4netns package is required to be installed to create
712       a network device, otherwise rootless containers need to run in the net‐
713       work namespace of the host.
714
715
716       In certain environments like HPC (High  Performance  Computing),  users
717       cannot  take  advantage  of  the  additional  UIDs  and  GIDs  from the
718       /etc/subuid and /etc/subgid systems.   However,  in  this  environment,
719       rootless  Podman can operate with a single UID.  To make this work, set
720       the ignore_chown_errors option in the  /etc/containers/storage.conf  or
721       in  ~/.config/containers/storage.conf  files.  This option tells Podman
722       when pulling an image to ignore chown errors when attempting to  change
723       a  file  in  a  container image to match the non-root UID in the image.
724       This means all files get saved as the user's UID. Note this could cause
725       issues when running the container.
726
727
728   NOTE: Unsupported file systems in rootless mode
729       The Overlay file system (OverlayFS) is not supported with kernels prior
730       to 5.12.9 in rootless mode.  The fuse-overlayfs package is a tool  that
731       provides  the  functionality of OverlayFS in user namespace that allows
732       mounting file systems in rootless environments.  It is  recommended  to
733       install  the fuse-overlayfs package.  In rootless mode, Podman will au‐
734       tomatically use the fuse-overlayfs program as the mount_program if  in‐
735       stalled,  as long as the $HOME/.config/containers/storage.conf file was
736       not previously created.  If storage.conf exists  in  the  homedir,  add
737       mount_program  = "/usr/bin/fuse-overlayfs" under [storage.options.over‐
738       lay] to enable this feature.
739
740
741       The Network File System (NFS) and other distributed file  systems  (for
742       example:  Lustre,  Spectrum  Scale,  the  General  Parallel File System
743       (GPFS)) are not supported when running in rootless mode as  these  file
744       systems do not understand user namespace.  However, rootless Podman can
745       make use of an NFS  Homedir  by  modifying  the  $HOME/.config/contain‐
746       ers/storage.conf  to  have  the  graphroot  option point to a directory
747       stored on local (Non NFS) storage.
748
749
750       For more information, please refer to the Podman Troubleshooting Page.
751
752

SEE ALSO

754       containers-mounts.conf(5),     containers.conf(5),      containers-reg‐
755       istries.conf(5),  containers-storage.conf(5), buildah(1), oci-hooks(5),
756       containers-policy.json(5),  crun(1),  runc(8),  subuid(5),   subgid(5),
757       slirp4netns(1), conmon(8)
758
759

HISTORY

761       Dec   2016,   Originally   compiled   by  Dan  Walsh  dwalsh@redhat.com
762       ⟨mailto:dwalsh@redhat.com⟩
763
764
765
766                                                                   podman(1)()
Impressum