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

Environment Variables

259       Podman can set up environment variables from env of [engine]  table  in
260       containers.conf. These variables can be overridden by passing  environ‐
261       ment variables before the podman commands.
262
263

Remote Access

265       The Podman command can be used with remote services using the  --remote
266       flag.  Connections  can be made using local unix domain sockets, ssh or
267       directly to tcp sockets. When specifying the podman --remote flag, only
268       the  global  options  --url,  --identity, --log-level, --connection are
269       used.
270
271
272       Connection information can also be managed  using  the  containers.conf
273       file.
274
275

Exit Codes

277       The  exit  code  from  podman gives information about why the container
278       failed to run or why it exited.   When  podman  commands  exit  with  a
279       non-zero code, the exit codes follow the chroot standard, see below:
280
281
282       125 The error is with podman itself
283
284
285              $ podman run --foo busybox; echo $?
286              Error: unknown flag: --foo
287              125
288
289
290
291       126 Executing a contained command and the command cannot be invoked
292
293
294              $ podman run busybox /etc; echo $?
295              Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
296              126
297
298
299
300       127 Executing a contained command and the command cannot be found
301           $ podman run busybox foo; echo $?
302           Error:  container_linux.go:346:  starting  container process caused
303       "exec: \"foo\": executable file not found in $PATH": OCI runtime error
304           127
305
306
307       Exit code contained command exit code
308
309
310              $ podman run busybox /bin/sh -c 'exit 3'; echo $?
311              3
312
313
314

COMMANDS

316       ┌──────────────────────┬────────────────────────────────┐
317Command               Description                    
318       ├──────────────────────┼────────────────────────────────┤
319podman-attach(1)      │ Attach to a running container. │
320       ├──────────────────────┼────────────────────────────────┤
321podman-auto-update(1) │ Auto update containers accord‐ │
322       │                      │ ing  to their auto-update pol‐ │
323       │                      │ icy                            │
324       ├──────────────────────┼────────────────────────────────┤
325podman-build(1)       │ Build a container image  using │
326       │                      │ a Containerfile.               │
327       ├──────────────────────┼────────────────────────────────┤
328podman-commit(1)      │ Create  new image based on the │
329       │                      │ changed container.             │
330       ├──────────────────────┼────────────────────────────────┤
331podman-completion(1)  │ Generate   shell    completion │
332       │                      │ scripts                        │
333       ├──────────────────────┼────────────────────────────────┤
334podman-container(1)   │ Manage containers.             │
335       ├──────────────────────┼────────────────────────────────┤
336podman-cp(1)          │ Copy  files/folders  between a │
337       │                      │ container   and   the    local │
338       │                      │ filesystem.                    │
339       ├──────────────────────┼────────────────────────────────┤
340podman-create(1)      │ Create a new container.        │
341       ├──────────────────────┼────────────────────────────────┤
342podman-diff(1)        │ Inspect changes on a container │
343       │                      │ or image's filesystem.         │
344       ├──────────────────────┼────────────────────────────────┤
345podman-events(1)      │ Monitor Podman events          │
346       ├──────────────────────┼────────────────────────────────┤
347podman-exec(1)        │ Execute a command in a running │
348       │                      │ container.                     │
349       ├──────────────────────┼────────────────────────────────┤
350podman-export(1)      │ Export  a container's filesys‐ │
351       │                      │ tem contents as a tar archive. │
352       ├──────────────────────┼────────────────────────────────┤
353podman-generate(1)    │ Generate structured data based │
354       │                      │ for a containers and pods.     │
355       ├──────────────────────┼────────────────────────────────┤
356podman-healthcheck(1) │ Manage  healthchecks  for con‐ │
357       │                      │ tainers                        │
358       ├──────────────────────┼────────────────────────────────┤
359podman-history(1)     │ Show the history of an image.  │
360       ├──────────────────────┼────────────────────────────────┤
361podman-image(1)       │ Manage images.                 │
362       ├──────────────────────┼────────────────────────────────┤
363podman-images(1)      │ List images in local storage.  │
364       ├──────────────────────┼────────────────────────────────┤
365podman-import(1)      │ Import a tarball and  save  it │
366       │                      │ as a filesystem image.         │
367       ├──────────────────────┼────────────────────────────────┤
368podman-info(1)        │ Displays Podman related system │
369       │                      │ information.                   │
370       ├──────────────────────┼────────────────────────────────┤
371podman-init(1)        │ Initialize one  or  more  con‐ │
372       │                      │ tainers                        │
373       ├──────────────────────┼────────────────────────────────┤
374podman-inspect(1)     │ Display  a  container,  image, │
375       │                      │ volume, network, or pod's con‐ │
376       │                      │ figuration.                    │
377       ├──────────────────────┼────────────────────────────────┤
378podman-kill(1)        │ Kill  the  main process in one │
379       │                      │ or more containers.            │
380       ├──────────────────────┼────────────────────────────────┤
381podman-load(1)        │ Load image(s) from a  tar  ar‐ │
382       │                      │ chive into container storage.  │
383       ├──────────────────────┼────────────────────────────────┤
384podman-login(1)       │ Login to a container registry. │
385       ├──────────────────────┼────────────────────────────────┤
386podman-logout(1)      │ Logout  of  a  container  reg‐ │
387       │                      │ istry.                         │
388       ├──────────────────────┼────────────────────────────────┤
389podman-logs(1)        │ Display the  logs  of  one  or │
390       │                      │ more containers.               │
391       ├──────────────────────┼────────────────────────────────┤
392podman-manifest(1)    │ Create and manipulate manifest │
393       │                      │ lists and image indexes.       │
394       ├──────────────────────┼────────────────────────────────┤
395podman-mount(1)       │ Mount  a  working  container's │
396       │                      │ root filesystem.               │
397       ├──────────────────────┼────────────────────────────────┤
398podman-network(1)     │ Manage Podman CNI networks.    │
399       ├──────────────────────┼────────────────────────────────┤
400podman-pause(1)       │ Pause one or more containers.  │
401       ├──────────────────────┼────────────────────────────────┤
402podman-play(1)        │ Play pods and containers based │
403       │                      │ on a structured input file.    │
404       ├──────────────────────┼────────────────────────────────┤
405podman-pod(1)         │ Management tool for groups  of │
406       │                      │ containers, called pods.       │
407       ├──────────────────────┼────────────────────────────────┤
408podman-port(1)        │ List  port mappings for a con‐ │
409       │                      │ tainer.                        │
410       ├──────────────────────┼────────────────────────────────┤
411podman-ps(1)          │ Prints out  information  about │
412       │                      │ containers.                    │
413       ├──────────────────────┼────────────────────────────────┤
414podman-pull(1)        │ Pull an image from a registry. │
415       ├──────────────────────┼────────────────────────────────┤
416podman-push(1)        │ Push  an  image, manifest list │
417       │                      │ or  image  index  from   local │
418       │                      │ storage to elsewhere.          │
419       ├──────────────────────┼────────────────────────────────┤
420podman-rename(1)      │ Rename an existing container.  │
421       ├──────────────────────┼────────────────────────────────┤
422podman-restart(1)     │ Restart  one  or more contain‐ │
423       │                      │ ers.                           │
424       ├──────────────────────┼────────────────────────────────┤
425podman-rm(1)          │ Remove one or more containers. │
426       ├──────────────────────┼────────────────────────────────┤
427podman-rmi(1)         │ Removes one  or  more  locally │
428       │                      │ stored images.                 │
429       ├──────────────────────┼────────────────────────────────┤
430podman-run(1)         │ Run  a  command  in a new con‐ │
431       │                      │ tainer.                        │
432       ├──────────────────────┼────────────────────────────────┤
433podman-save(1)        │ Save image(s) to an archive.   │
434       ├──────────────────────┼────────────────────────────────┤
435podman-search(1)      │ Search  a  registry   for   an │
436       │                      │ image.                         │
437       ├──────────────────────┼────────────────────────────────┤
438podman-start(1)       │ Start one or more containers.  │
439       ├──────────────────────┼────────────────────────────────┤
440podman-stats(1)       │ Display  a  live stream of one │
441       │                      │ or more  container's  resource │
442       │                      │ usage statistics.              │
443       ├──────────────────────┼────────────────────────────────┤
444podman-stop(1)        │ Stop  one or more running con‐ │
445       │                      │ tainers.                       │
446       ├──────────────────────┼────────────────────────────────┤
447podman-system(1)      │ Manage podman.                 │
448       ├──────────────────────┼────────────────────────────────┤
449podman-tag(1)         │ Add an additional  name  to  a │
450       │                      │ local image.                   │
451       ├──────────────────────┼────────────────────────────────┤
452podman-top(1)         │ Display  the running processes │
453       │                      │ of a container.                │
454       ├──────────────────────┼────────────────────────────────┤
455podman-unmount(1)     │ Unmount a working  container's │
456       │                      │ root filesystem.               │
457       ├──────────────────────┼────────────────────────────────┤
458podman-unpause(1)     │ Unpause  one  or more contain‐ │
459       │                      │ ers.                           │
460       ├──────────────────────┼────────────────────────────────┤
461podman-unshare(1)     │ Run a command inside of a mod‐ │
462       │                      │ ified user namespace.          │
463       ├──────────────────────┼────────────────────────────────┤
464podman-untag(1)       │ Removes one or more names from │
465       │                      │ a locally-stored image.        │
466       ├──────────────────────┼────────────────────────────────┤
467podman-version(1)     │ Display  the  Podman   version │
468       │                      │ information.                   │
469       ├──────────────────────┼────────────────────────────────┤
470podman-volume(1)      │ Simple   management  tool  for │
471       │                      │ volumes.                       │
472       ├──────────────────────┼────────────────────────────────┤
473podman-wait(1)        │ Wait on one or more containers │
474       │                      │ to  stop  and print their exit │
475       │                      │ codes.                         │
476       ├──────────────────────┼────────────────────────────────┤
477       │                      │                                │
478       └──────────────────────┴────────────────────────────────┘
479

CONFIGURATION FILES

481       containers.conf  (/usr/share/containers/containers.conf,  /etc/contain‐
482       ers/containers.conf, $HOME/.config/containers/containers.conf)
483
484
485              Podman has builtin defaults for command line options. These defaults can be overridden using the containers.conf configuration files.
486
487
488
489       Distributions  ship the /usr/share/containers/containers.conf file with
490       their default settings. Administrators can override fields in this file
491       by  creating  the /etc/containers/containers.conf file.  Users can fur‐
492       ther modify defaults by creating the  $HOME/.config/containers/contain‐
493       ers.conf  file.  Podman  merges its builtin defaults with the specified
494       fields from these files, if they exist. Fields specified in  the  users
495       file  override  the administrator's file, which overrides the distribu‐
496       tion's file, which override the built-in defaults.
497
498
499       Podman uses builtin defaults if no containers.conf file is found.
500
501
502       mounts.conf (/usr/share/containers/mounts.conf)
503
504
505              The mounts.conf file specifies volume mount directories that are automatically mounted inside containers when executing the `podman run` or `podman start` commands. Administrators can override the defaults file by creating `/etc/containers/mounts.conf`.
506
507
508
509       When Podman runs in  rootless  mode,  the  file  $HOME/.config/contain‐
510       ers/mounts.conf will override the default if it exists. Please refer to
511       containers-mounts.conf(5) for further details.
512
513
514       policy.json (/etc/containers/policy.json)
515
516
517              Signature verification policy files are used to specify policy, e.g. trusted keys, applicable when deciding whether to accept an image, or individual signatures of that image, as valid.
518
519
520
521       registries.conf  (/etc/containers/registries.conf,   $HOME/.config/con‐
522       tainers/registries.conf)
523
524
525              registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
526
527              Non root users of Podman can create the `$HOME/.config/containers/registries.conf` file to be used instead of the system defaults.
528
529
530
531       storage.conf    (/etc/containers/storage.conf,   $HOME/.config/contain‐
532       ers/storage.conf)
533
534
535              storage.conf is the storage configuration file for all tools using containers/storage
536
537              The storage configuration file specifies all of the available container storage options for tools using shared container storage.
538
539              When Podman runs in rootless mode, the file `$HOME/.config/containers/storage.conf` is used instead of the system defaults.
540
541
542

Rootless mode

544       Podman can also be used as non-root user.  When podman runs in rootless
545       mode,  a  user namespace is automatically created for the user, defined
546       in /etc/subuid and /etc/subgid.
547
548
549       Containers created by a non-root user are not visible  to  other  users
550       and are not seen or managed by Podman running as root.
551
552
553       It is required to have multiple uids/gids set for an user.  Be sure the
554       user is present in the files /etc/subuid and /etc/subgid.
555
556
557       If you have a recent version of usermod, you can execute the  following
558       commands to add the ranges to the files
559
560
561              $ sudo usermod --add-subuids 10000-75535 USERNAME
562              $ sudo usermod --add-subgids 10000-75535 USERNAME
563
564
565
566       Or just add the content manually.
567
568
569              $ echo USERNAME:10000:65536 >> /etc/subuid
570              $ echo USERNAME:10000:65536 >> /etc/subgid
571
572
573
574       See the subuid(5) and subgid(5) man pages for more information.
575
576
577       Images  are pulled under XDG_DATA_HOME when specified, otherwise in the
578       home directory of the user under .local/share/containers/storage.
579
580
581       Currently the slirp4netns package is required to be installed to create
582       a network device, otherwise rootless containers need to run in the net‐
583       work namespace of the host.
584
585
586   NOTE: Unsupported file systems in rootless mode
587       The Overlay file system (OverlayFS) is not supported in rootless  mode.
588       The fuse-overlayfs package is a tool that provides the functionality of
589       OverlayFS in user namespace that allows mounting file systems in  root‐
590       less  environments.   It  is  recommended to install the fuse-overlayfs
591       package and to enable it by adding mount_program = "/usr/bin/fuse-over‐
592       layfs"  under  [storage.options]  in the $HOME/.config/containers/stor‐
593       age.conf file.
594
595
596       The Network File System (NFS) and other distributed file  systems  (for
597       example:  Lustre,  Spectrum  Scale,  the  General  Parallel File System
598       (GPFS)) are not supported when running in rootless mode as  these  file
599       systems do not understand user namespace.  However, rootless Podman can
600       make use of an NFS  Homedir  by  modifying  the  $HOME/.config/contain‐
601       ers/storage.conf  to  have  the  graphroot  option point to a directory
602       stored on local (Non NFS) storage.
603
604
605       For more information, please refer to the Podman  Troubleshooting  Page
606https://github.com/containers/podman/blob/master/troubleshooting.md⟩.
607
608

SEE ALSO

610       containers-mounts.conf(5),    containers-registries.conf(5),   contain‐
611       ers-storage.conf(5), buildah(1), containers.conf(5), oci-hooks(5), con‐
612       tainers-policy.json(5),   crun(8),   runc(8),   subuid(5),   subgid(5),
613       slirp4netns(1)
614
615

HISTORY

617       Dec  2016,  Originally  compiled   by   Dan   Walsh   dwalsh@redhat.com
618       ⟨mailto:dwalsh@redhat.com⟩
619
620
621
622                                                                   podman(1)()
Impressum