1podman(1)() podman(1)()
2
6 podman - Simple management tool for pods, containers and images
7
10 podman [options] command
11
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 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 podman [GLOBAL OPTIONS]
28
31 --cgroup-manager=manager
32 CGroup manager to use for container cgroups. Supported values are
35 cgroupfs or systemd. Default is systemd unless overridden in the lib‐
36 pod.conf file.
37 Note: Setting this flag can cause certain commands to break when called
40 on containers previously created by the other CGroup manager type.
41 Note: CGroup manager is not supported in rootless mode when using
42 CGroups Version V1.
43 --cni-config-dir Path of the configuration directory for CNI networks.
46 (Default: /etc/cni/net.d)
47 --conmon Path of the conmon binary (Default path is configured in lib‐
50 pod.conf)
51 --events-backend=type
54 Backend to use for storing events. Allowed values are file, journald,
57 and none.
58 --help, -h
61 Print usage statement
64 --hooks-dir=path
67 Each *.json file in the path configures a hook for Podman containers.
70 For more details on the syntax of the JSON files and the semantics of
71 hook injection, see oci-hooks(5). Podman and libpod currently support
72 both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is
73 deprecated.
74 This option may be set multiple times; paths from later options have
77 higher precedence (oci-hooks(5) discusses directory precedence).
78 For the annotation conditions, libpod uses any annotations set in the
81 generated OCI configuration.
82 For the bind-mount conditions, only mounts explicitly requested by the
85 caller via --volume are considered. Bind mounts that libpod inserts by
86 default (e.g. /dev/shm) are not considered.
87 If --hooks-dir is unset for root callers, Podman and libpod will cur‐
90 rently default to /usr/share/containers/oci/hooks.d and /etc/contain‐
91 ers/oci/hooks.d in order of increasing precedence. Using these
92 defaults is deprecated, and callers should migrate to explicitly set‐
93 ting --hooks-dir.
94 Podman and libpod currently support an additional precreate state which
97 is called before the runtime's create operation. Unlike the other
98 stages, which receive the container state on their standard input,
99 precreate hooks receive the proposed runtime configuration on their
100 standard input. They may alter that configuration as they see fit, and
101 write the altered form to their standard output.
102 WARNING: the precreate hook lets you do powerful things, such as adding
105 additional mounts to the runtime configuration. That power also makes
106 it easy to break things. Before reporting libpod errors, try running
107 your container with precreate hooks disabled to see if the problem is
108 due to one of your hooks.
109 --log-level=level
112 Log messages above specified level: debug, info, warn, error (default),
115 fatal or panic (default: "error")
116 --namespace=namespace
119 Set libpod namespace. Namespaces are used to separate groups of con‐
122 tainers and pods in libpod's state. When namespace is set, created
123 containers and pods will join the given namespace, and only containers
124 and pods in the given namespace will be visible to Podman.
125 --network-cmd-path=path Path to the command binary to use for setting
128 up a network. It is currently only used for setting up a slirp4netns
129 network. If "" is used then the binary is looked up using the $PATH
130 environment variable.
131 --root=value
134 Storage root dir in which data, including images, is stored (default:
137 "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/contain‐
138 ers/storage" for other users). Default root dir is configured in
139 /etc/containers/storage.conf.
140 --runroot=value
143 Storage state directory where all state information is stored (default:
146 "/var/run/containers/storage" for UID 0, "/var/run/user/$UID/run" for
147 other users). Default state dir is configured in /etc/containers/stor‐
148 age.conf.
149 --runtime=value
152 Name of the OCI runtime as specified in libpod.conf or absolute path to
155 the OCI compatible binary used to run containers.
156 --storage-driver=value
159 Storage driver. The default storage driver for UID 0 is configured in
162 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
163 rootless mode), and is vfs for non-root users when fuse-overlayfs is
164 not available. The STORAGE_DRIVER environment variable overrides the
165 default. The --storage-driver specified driver overrides all.
166 Overriding this option will cause the storage-opt settings in /etc/con‐
169 tainers/storage.conf to be ignored. The user must specify additional
170 options via the --storage-opt flag.
171 --storage-opt=value
174 Storage driver option, Default storage driver options are configured in
177 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
178 rootless mode). The STORAGE_OPTS environment variable overrides the
179 default. The --storage-opt specified options overrides all.
180 --syslog=true|false
183 Output logging information to syslog as well as the console (default
186 false).
187 On remote clients, logging is directed to the file $HOME/.config/con‐
190 tainers/podman.log.
191 --tmpdir
194 Path to the tmp directory, for libpod runtime content.
197 NOTE --tmpdir is not used for the temporary storage of downloaded
200 images. Use the environment variable TMPDIR to change the temporary
201 storage location of downloaded container images. Podman defaults to use
202 /var/tmp.
203 --version, -v
206 Print the version
209
212 The exit code from podman gives information about why the container
213 failed to run or why it exited. When podman commands exit with a
214 non-zero code, the exit codes follow the chroot standard, see below:
215 125 The error is with podman itself
218 $ podman run --foo busybox; echo $?
221 Error: unknown flag: --foo
222 125
223 126 Executing a contained command and the command cannot be invoked
227 $ podman run busybox /etc; echo $?
230 Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
231 126
232 127 Executing a contained command and the command cannot be found
236 $ podman run busybox foo; echo $?
237 Error: container_linux.go:346: starting container process caused
238 "exec: \"foo\": executable file not found in $PATH": OCI runtime error
239 127
240 Exit code contained command exit code
243 $ podman run busybox /bin/sh -c 'exit 3'; echo $?
246 3
247
251 ┌──────────────────────┬────────────────────────────────┐
252 │Command │ Description │
253 ├──────────────────────┼────────────────────────────────┤
254 │podman-attach(1) │ Attach to a running container. │
255 ├──────────────────────┼────────────────────────────────┤
256 │podman-auto-update(1) │ Auto update containers accord‐ │
257 │ │ ing to their auto-update pol‐ │
258 │ │ icy │
259 ├──────────────────────┼────────────────────────────────┤
260 │podman-build(1) │ Build a container image using │
261 │ │ a Containerfile. │
262 ├──────────────────────┼────────────────────────────────┤
263 │podman-commit(1) │ Create new image based on the │
264 │ │ changed container. │
265 ├──────────────────────┼────────────────────────────────┤
266 │podman-container(1) │ Manage containers. │
267 ├──────────────────────┼────────────────────────────────┤
268 │podman-cp(1) │ Copy files/folders between a │
269 │ │ container and the local │
270 │ │ filesystem. │
271 ├──────────────────────┼────────────────────────────────┤
272 │podman-create(1) │ Create a new container. │
273 ├──────────────────────┼────────────────────────────────┤
274 │podman-diff(1) │ Inspect changes on a container │
275 │ │ or image's filesystem. │
276 ├──────────────────────┼────────────────────────────────┤
277 │podman-events(1) │ Monitor Podman events │
278 ├──────────────────────┼────────────────────────────────┤
279 │podman-exec(1) │ Execute a command in a running │
280 │ │ container. │
281 ├──────────────────────┼────────────────────────────────┤
282 │podman-export(1) │ Export a container's filesys‐ │
283 │ │ tem contents as a tar archive. │
284 ├──────────────────────┼────────────────────────────────┤
285 │podman-generate(1) │ Generate structured data based │
286 │ │ for a containers and pods. │
287 ├──────────────────────┼────────────────────────────────┤
288 │podman-healthcheck(1) │ Manage healthchecks for con‐ │
289 │ │ tainers │
290 ├──────────────────────┼────────────────────────────────┤
291 │podman-history(1) │ Show the history of an image. │
292 ├──────────────────────┼────────────────────────────────┤
293 │podman-image(1) │ Manage images. │
294 ├──────────────────────┼────────────────────────────────┤
295 │podman-images(1) │ List images in local storage. │
296 ├──────────────────────┼────────────────────────────────┤
297 │podman-import(1) │ Import a tarball and save it │
298 │ │ as a filesystem image. │
299 ├──────────────────────┼────────────────────────────────┤
300 │podman-info(1) │ Displays Podman related system │
301 │ │ information. │
302 ├──────────────────────┼────────────────────────────────┤
303 │podman-init(1) │ Initialize one or more con‐ │
304 │ │ tainers │
305 ├──────────────────────┼────────────────────────────────┤
306 │podman-inspect(1) │ Display a container or image's │
307 │ │ configuration. │
308 ├──────────────────────┼────────────────────────────────┤
309 │podman-kill(1) │ Kill the main process in one │
310 │ │ or more containers. │
311 ├──────────────────────┼────────────────────────────────┤
312 │podman-load(1) │ Load an image from a container │
313 │ │ image archive into container │
314 │ │ storage. │
315 ├──────────────────────┼────────────────────────────────┤
316 │podman-login(1) │ Login to a container registry. │
317 ├──────────────────────┼────────────────────────────────┤
318 │podman-logout(1) │ Logout of a container reg‐ │
319 │ │ istry. │
320 ├──────────────────────┼────────────────────────────────┤
321 │podman-logs(1) │ Display the logs of one or │
322 │ │ more containers. │
323 ├──────────────────────┼────────────────────────────────┤
324 │podman-mount(1) │ Mount a working container's │
325 │ │ root filesystem. │
326 ├──────────────────────┼────────────────────────────────┤
327 │podman-network(1) │ Manage Podman CNI networks. │
328 ├──────────────────────┼────────────────────────────────┤
329 │podman-pause(1) │ Pause one or more containers. │
330 ├──────────────────────┼────────────────────────────────┤
331 │podman-play(1) │ Play pods and containers based │
332 │ │ on a structured input file. │
333 ├──────────────────────┼────────────────────────────────┤
334 │podman-pod(1) │ Management tool for groups of │
335 │ │ containers, called pods. │
336 ├──────────────────────┼────────────────────────────────┤
337 │podman-port(1) │ List port mappings for a con‐ │
338 │ │ tainer. │
339 ├──────────────────────┼────────────────────────────────┤
340 │podman-ps(1) │ Prints out information about │
341 │ │ containers. │
342 ├──────────────────────┼────────────────────────────────┤
343 │podman-pull(1) │ Pull an image from a registry. │
344 ├──────────────────────┼────────────────────────────────┤
345 │podman-push(1) │ Push an image from local stor‐ │
346 │ │ age to elsewhere. │
347 ├──────────────────────┼────────────────────────────────┤
348 │podman-restart(1) │ Restart one or more contain‐ │
349 │ │ ers. │
350 ├──────────────────────┼────────────────────────────────┤
351 │podman-rm(1) │ Remove one or more containers. │
352 ├──────────────────────┼────────────────────────────────┤
353 │podman-rmi(1) │ Removes one or more locally │
354 │ │ stored images. │
355 ├──────────────────────┼────────────────────────────────┤
356 │podman-run(1) │ Run a command in a new con‐ │
357 │ │ tainer. │
358 ├──────────────────────┼────────────────────────────────┤
359 │podman-save(1) │ Save an image to a container │
360 │ │ archive. │
361 ├──────────────────────┼────────────────────────────────┤
362 │podman-search(1) │ Search a registry for an │
363 │ │ image. │
364 ├──────────────────────┼────────────────────────────────┤
365 │podman-start(1) │ Start one or more containers. │
366 ├──────────────────────┼────────────────────────────────┤
367 │podman-stats(1) │ Display a live stream of one │
368 │ │ or more container's resource │
369 │ │ usage statistics. │
370 ├──────────────────────┼────────────────────────────────┤
371 │podman-stop(1) │ Stop one or more running con‐ │
372 │ │ tainers. │
373 ├──────────────────────┼────────────────────────────────┤
374 │podman-system(1) │ Manage podman. │
375 ├──────────────────────┼────────────────────────────────┤
376 │podman-tag(1) │ Add an additional name to a │
377 │ │ local image. │
378 ├──────────────────────┼────────────────────────────────┤
379 │podman-top(1) │ Display the running processes │
380 │ │ of a container. │
381 ├──────────────────────┼────────────────────────────────┤
382 │podman-umount(1) │ Unmount a working container's │
383 │ │ root filesystem. │
384 ├──────────────────────┼────────────────────────────────┤
385 │podman-unpause(1) │ Unpause one or more contain‐ │
386 │ │ ers. │
387 ├──────────────────────┼────────────────────────────────┤
388 │podman-unshare(1) │ Run a command inside of a mod‐ │
389 │ │ ified user namespace. │
390 ├──────────────────────┼────────────────────────────────┤
391 │podman-untag(1) │ Removes one or more names from │
392 │ │ a locally-stored image. │
393 ├──────────────────────┼────────────────────────────────┤
394 │podman-varlink(1) │ Runs the varlink backend │
395 │ │ interface. │
396 ├──────────────────────┼────────────────────────────────┤
397 │podman-version(1) │ Display the Podman version │
398 │ │ information. │
399 ├──────────────────────┼────────────────────────────────┤
400 │podman-volume(1) │ Simple management tool for │
401 │ │ volumes. │
402 ├──────────────────────┼────────────────────────────────┤
403 │podman-wait(1) │ Wait on one or more containers │
404 │ │ to stop and print their exit │
405 │ │ codes. │
406 └──────────────────────┴────────────────────────────────┘
407
409 libpod.conf (/usr/share/containers/libpod.conf)
410 libpod.conf is the configuration file for all tools using libpod to manage containers, when run as root. Administrators can override the defaults file by creating `/etc/containers/libpod.conf`. When Podman runs in rootless mode, the file `$HOME/.config/containers/libpod.conf` is created and replaces some fields in the system configuration file.
413 Podman uses builtin defaults if no libpod.conf file is found.
415 mounts.conf (/usr/share/containers/mounts.conf)
419 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`.
422 When Podman runs in rootless mode, the file $HOME/.config/contain‐
426 ers/mounts.conf will override the default if it exists. Please refer to
427 containers-mounts.conf(5) for further details.
428 policy.json (/etc/containers/policy.json)
431 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.
434 registries.conf (/etc/containers/registries.conf)
438 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.
441 Non root users of Podman can create the `$HOME/.config/containers/registries.conf` file to be used instead of the system defaults.
443 storage.conf (/etc/containers/storage.conf)
447 storage.conf is the storage configuration file for all tools using containers/storage
450 The storage configuration file specifies all of the available container storage options for tools using shared container storage.
452 When Podman runs in rootless mode, the file `$HOME/.config/containers/storage.conf` is used instead of the system defaults.
454
458 Podman can also be used as non-root user. When podman runs in rootless
459 mode, a user namespace is automatically created for the user, defined
460 in /etc/subuid and /etc/subgid.
461 Containers created by a non-root user are not visible to other users
464 and are not seen or managed by Podman running as root.
465 It is required to have multiple uids/gids set for an user. Be sure the
468 user is present in the files /etc/subuid and /etc/subgid.
469 If you have a recent version of usermod, you can execute the following
472 commands to add the ranges to the files
473 $ sudo usermod --add-subuids 10000-75535 USERNAME
476 $ sudo usermod --add-subgids 10000-75535 USERNAME
477 Or just add the content manually.
481 $ echo USERNAME:10000:65536 >> /etc/subuid
484 $ echo USERNAME:10000:65536 >> /etc/subgid
485 See the subuid(5) and subgid(5) man pages for more information.
489 Images are pulled under XDG_DATA_HOME when specified, otherwise in the
492 home directory of the user under .local/share/containers/storage.
493 Currently the slirp4netns package is required to be installed to create
496 a network device, otherwise rootless containers need to run in the net‐
497 work namespace of the host.
498 NOTE: Unsupported file systems in rootless mode
501 The Overlay file system (OverlayFS) is not supported in rootless mode.
502 The fuse-overlayfs package is a tool that provides the functionality of
503 OverlayFS in user namespace that allows mounting file systems in root‐
504 less environments. It is recommended to install the fuse-overlayfs
505 package and to enable it by adding mount_program = "/usr/bin/fuse-over‐
506 layfs" under [storage.options] in the $HOME/.config/containers/stor‐
507 age.conf file.
508 The Network File System (NFS) and other distributed file systems (for
511 example: Lustre, Spectrum Scale, the General Parallel File System
512 (GPFS)) are not supported when running in rootless mode as these file
513 systems do not understand user namespace. However, rootless Podman can
514 make use of an NFS Homedir by modifying the $HOME/.config/contain‐
515 ers/storage.conf to have the graphroot option point to a directory
516 stored on local (Non NFS) storage.
517 For more information, please refer to the Podman Troubleshooting Page
520 ⟨https://github.com/containers/libpod/blob/master/troubleshooting.md⟩.
521
524 containers-mounts.conf(5), containers-registries.conf(5), contain‐
525 ers-storage.conf(5), buildah(1), libpod.conf(5), oci-hooks(5), contain‐
526 ers-policy.json(5), subuid(5), subgid(5), slirp4netns(1)
527
530 Dec 2016, Originally compiled by Dan Walsh dwalsh@redhat.com
531 ⟨mailto:dwalsh@redhat.com⟩
532 podman(1)()