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 --help, -h
32 Print usage statement
35 --cgroup-manager=manager
38 CGroup manager to use for container cgroups. Supported values are
41 cgroupfs or systemd. Default is systemd unless overridden in the lib‐
42 pod.conf file.
43 Note: Setting this flag can cause certain commands to break when called
46 on containers previously created by the other CGroup manager type.
47 Note: CGroup manager is not supported in rootless mode when using
48 CGroups Version V1.
49 --cpu-profile=path
52 Path to where the cpu performance results should be written
55 --events-backend=type
58 Backend to use for storing events. Allowed values are file, journald,
61 and none.
62 --hooks-dir=path
65 Each *.json file in the path configures a hook for Podman containers.
68 For more details on the syntax of the JSON files and the semantics of
69 hook injection, see oci-hooks(5). Podman and libpod currently support
70 both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is
71 deprecated.
72 This option may be set multiple times; paths from later options have
75 higher precedence (oci-hooks(5) discusses directory precedence).
76 For the annotation conditions, libpod uses any annotations set in the
79 generated OCI configuration.
80 For the bind-mount conditions, only mounts explicitly requested by the
83 caller via --volume are considered. Bind mounts that libpod inserts by
84 default (e.g. /dev/shm) are not considered.
85 If --hooks-dir is unset for root callers, Podman and libpod will cur‐
88 rently default to /usr/share/containers/oci/hooks.d and /etc/contain‐
89 ers/oci/hooks.d in order of increasing precedence. Using these
90 defaults is deprecated, and callers should migrate to explicitly set‐
91 ting --hooks-dir.
92 Podman and libpod currently support an additional precreate state which
95 is called before the runtime's create operation. Unlike the other
96 stages, which receive the container state on their standard input,
97 precreate hooks receive the proposed runtime configuration on their
98 standard input. They may alter that configuration as they see fit, and
99 write the altered form to their standard output.
100 WARNING: the precreate hook lets you do powerful things, such as adding
103 additional mounts to the runtime configuration. That power also makes
104 it easy to break things. Before reporting libpod errors, try running
105 your container with precreate hooks disabled to see if the problem is
106 due to one of your hooks.
107 --log-level=level
110 Log messages above specified level: debug, info, warn, error (default),
113 fatal or panic
114 --namespace=namespace
117 Set libpod namespace. Namespaces are used to separate groups of con‐
120 tainers and pods in libpod's state. When namespace is set, created
121 containers and pods will join the given namespace, and only containers
122 and pods in the given namespace will be visible to Podman.
123 --root=value
126 Storage root dir in which data, including images, is stored (default:
129 "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/contain‐
130 ers/storage" for other users). Default root dir is configured in
131 /etc/containers/storage.conf.
132 --runroot=value
135 Storage state directory where all state information is stored (default:
138 "/var/run/containers/storage" for UID 0, "/var/run/user/$UID/run" for
139 other users). Default state dir is configured in /etc/containers/stor‐
140 age.conf.
141 --runtime=value
144 Name of the OCI runtime as specified in libpod.conf or absolute path to
147 the OCI compatible binary used to run containers.
148 --network-cmd-path=path Path to the command binary to use for setting
151 up a network. It is currently only used for setting up a slirp4netns
152 network. If "" is used then the binary is looked up using the $PATH
153 environment variable.
154 --storage-driver=value
157 Storage driver. The default storage driver for UID 0 is configured in
160 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
161 rootless mode), and is vfs for non-root users when fuse-overlayfs is
162 not available. The STORAGE_DRIVER environment variable overrides the
163 default. The --storage-driver specified driver overrides all.
164 Overriding this option will cause the storage-opt settings in /etc/con‐
167 tainers/storage.conf to be ignored. The user must specify additional
168 options via the --storage-opt flag.
169 --storage-opt=value
172 Storage driver option, Default storage driver options are configured in
175 /etc/containers/storage.conf ($HOME/.config/containers/storage.conf in
176 rootless mode). The STORAGE_OPTS environment variable overrides the
177 default. The --storage-opt specified options overrides all.
178 --syslog
181 output logging information to syslog as well as the console
184 On remote clients, logging is directed to the file /.config/contain‐
187 ers/podman.log
188 --version, -v
191 Print the version
194
197 The exit code from podman gives information about why the container
198 failed to run or why it exited. When podman commands exit with a
199 non-zero code, the exit codes follow the chroot standard, see below:
200 125 if the error is with podman itself
203 $ podman run --foo busybox; echo $?
206 Error: unknown flag: --foo
207 125
208 126 if executing a contained command and the command cannot be invoked
212 $ podman run busybox /etc; echo $?
215 Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
216 126
217 127 if executing a contained command and the command cannot be found
221 $ podman run busybox foo; echo $?
222 Error: container_linux.go:346: starting container process caused
223 "exec: \"foo\": executable file not found in $PATH": OCI runtime error
224 127
225 Exit code of contained command otherwise
228 $ podman run busybox /bin/sh -c 'exit 3'
231 # 3
232
236 ┌──────────────────────┬────────────────────────────────┐
237 │Command │ Description │
238 ├──────────────────────┼────────────────────────────────┤
239 │podman-attach(1) │ Attach to a running container. │
240 ├──────────────────────┼────────────────────────────────┤
241 │podman-build(1) │ Build a container image using │
242 │ │ a Containerfile. │
243 ├──────────────────────┼────────────────────────────────┤
244 │podman-commit(1) │ Create new image based on the │
245 │ │ changed container. │
246 ├──────────────────────┼────────────────────────────────┤
247 │podman-container(1) │ Manage containers. │
248 ├──────────────────────┼────────────────────────────────┤
249 │podman-cp(1) │ Copy files/folders between a │
250 │ │ container and the local │
251 │ │ filesystem. │
252 ├──────────────────────┼────────────────────────────────┤
253 │podman-create(1) │ Create a new container. │
254 ├──────────────────────┼────────────────────────────────┤
255 │podman-diff(1) │ Inspect changes on a container │
256 │ │ or image's filesystem. │
257 ├──────────────────────┼────────────────────────────────┤
258 │podman-events(1) │ Monitor Podman events │
259 ├──────────────────────┼────────────────────────────────┤
260 │podman-exec(1) │ Execute a command in a running │
261 │ │ container. │
262 ├──────────────────────┼────────────────────────────────┤
263 │podman-export(1) │ Export a container's filesys‐ │
264 │ │ tem contents as a tar archive. │
265 ├──────────────────────┼────────────────────────────────┤
266 │podman-generate(1) │ Generate structured data based │
267 │ │ for a containers and pods. │
268 ├──────────────────────┼────────────────────────────────┤
269 │podman-healthcheck(1) │ Manage healthchecks for con‐ │
270 │ │ tainers │
271 ├──────────────────────┼────────────────────────────────┤
272 │podman-history(1) │ Show the history of an image. │
273 ├──────────────────────┼────────────────────────────────┤
274 │podman-image(1) │ Manage images. │
275 ├──────────────────────┼────────────────────────────────┤
276 │podman-images(1) │ List images in local storage. │
277 ├──────────────────────┼────────────────────────────────┤
278 │podman-import(1) │ Import a tarball and save it │
279 │ │ as a filesystem image. │
280 ├──────────────────────┼────────────────────────────────┤
281 │podman-info(1) │ Displays Podman related system │
282 │ │ information. │
283 ├──────────────────────┼────────────────────────────────┤
284 │podman-init(1) │ Initialize one or more con‐ │
285 │ │ tainers │
286 ├──────────────────────┼────────────────────────────────┤
287 │podman-inspect(1) │ Display a container or image's │
288 │ │ configuration. │
289 ├──────────────────────┼────────────────────────────────┤
290 │podman-kill(1) │ Kill the main process in one │
291 │ │ or more containers. │
292 ├──────────────────────┼────────────────────────────────┤
293 │podman-load(1) │ Load an image from a container │
294 │ │ image archive into container │
295 │ │ storage. │
296 ├──────────────────────┼────────────────────────────────┤
297 │podman-login(1) │ Login to a container registry. │
298 ├──────────────────────┼────────────────────────────────┤
299 │podman-logout(1) │ Logout of a container reg‐ │
300 │ │ istry. │
301 ├──────────────────────┼────────────────────────────────┤
302 │podman-logs(1) │ Display the logs of one or │
303 │ │ more containers. │
304 ├──────────────────────┼────────────────────────────────┤
305 │podman-mount(1) │ Mount a working container's │
306 │ │ root filesystem. │
307 ├──────────────────────┼────────────────────────────────┤
308 │podman-network(1) │ Manage Podman CNI networks. │
309 ├──────────────────────┼────────────────────────────────┤
310 │podman-pause(1) │ Pause one or more containers. │
311 ├──────────────────────┼────────────────────────────────┤
312 │podman-play(1) │ Play pods and containers based │
313 │ │ on a structured input file. │
314 ├──────────────────────┼────────────────────────────────┤
315 │podman-pod(1) │ Management tool for groups of │
316 │ │ containers, called pods. │
317 ├──────────────────────┼────────────────────────────────┤
318 │podman-port(1) │ List port mappings for a con‐ │
319 │ │ tainer. │
320 ├──────────────────────┼────────────────────────────────┤
321 │podman-ps(1) │ Prints out information about │
322 │ │ containers. │
323 ├──────────────────────┼────────────────────────────────┤
324 │podman-pull(1) │ Pull an image from a registry. │
325 ├──────────────────────┼────────────────────────────────┤
326 │podman-push(1) │ Push an image from local stor‐ │
327 │ │ age to elsewhere. │
328 ├──────────────────────┼────────────────────────────────┤
329 │podman-restart(1) │ Restart one or more contain‐ │
330 │ │ ers. │
331 ├──────────────────────┼────────────────────────────────┤
332 │podman-rm(1) │ Remove one or more containers. │
333 ├──────────────────────┼────────────────────────────────┤
334 │podman-rmi(1) │ Removes one or more locally │
335 │ │ stored images. │
336 ├──────────────────────┼────────────────────────────────┤
337 │podman-run(1) │ Run a command in a new con‐ │
338 │ │ tainer. │
339 ├──────────────────────┼────────────────────────────────┤
340 │podman-save(1) │ Save an image to a container │
341 │ │ archive. │
342 ├──────────────────────┼────────────────────────────────┤
343 │podman-search(1) │ Search a registry for an │
344 │ │ image. │
345 ├──────────────────────┼────────────────────────────────┤
346 │podman-start(1) │ Start one or more containers. │
347 ├──────────────────────┼────────────────────────────────┤
348 │podman-stats(1) │ Display a live stream of one │
349 │ │ or more container's resource │
350 │ │ usage statistics. │
351 ├──────────────────────┼────────────────────────────────┤
352 │podman-stop(1) │ Stop one or more running con‐ │
353 │ │ tainers. │
354 ├──────────────────────┼────────────────────────────────┤
355 │podman-system(1) │ Manage podman. │
356 ├──────────────────────┼────────────────────────────────┤
357 │podman-tag(1) │ Add an additional name to a │
358 │ │ local image. │
359 ├──────────────────────┼────────────────────────────────┤
360 │podman-top(1) │ Display the running processes │
361 │ │ of a container. │
362 ├──────────────────────┼────────────────────────────────┤
363 │podman-umount(1) │ Unmount a working container's │
364 │ │ root filesystem. │
365 ├──────────────────────┼────────────────────────────────┤
366 │podman-unpause(1) │ Unpause one or more contain‐ │
367 │ │ ers. │
368 ├──────────────────────┼────────────────────────────────┤
369 │podman-unshare(1) │ Run a command inside of a mod‐ │
370 │ │ ified user namespace. │
371 ├──────────────────────┼────────────────────────────────┤
372 │podman-varlink(1) │ Runs the varlink backend │
373 │ │ interface. │
374 ├──────────────────────┼────────────────────────────────┤
375 │podman-version(1) │ Display the Podman version │
376 │ │ information. │
377 ├──────────────────────┼────────────────────────────────┤
378 │podman-volume(1) │ Simple management tool for │
379 │ │ volumes. │
380 ├──────────────────────┼────────────────────────────────┤
381 │podman-wait(1) │ Wait on one or more containers │
382 │ │ to stop and print their exit │
383 │ │ codes. │
384 └──────────────────────┴────────────────────────────────┘
385
387 libpod.conf (/usr/share/containers/libpod.conf)
388 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.
391 Podman uses builtin defaults if no libpod.conf file is found.
393 mounts.conf (/usr/share/containers/mounts.conf)
397 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`.
400 When Podman runs in rootless mode, the file $HOME/.config/contain‐
404 ers/mounts.conf will override the default if it exists. Please refer to
405 containers-mounts.conf(5) for further details.
406 policy.json (/etc/containers/policy.json)
409 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.
412 registries.conf (/etc/containers/registries.conf)
416 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.
419 Non root users of Podman can create the `$HOME/.config/containers/registries.conf` file to be used instead of the system defaults.
421 storage.conf (/etc/containers/storage.conf)
425 storage.conf is the storage configuration file for all tools using containers/storage
428 The storage configuration file specifies all of the available container storage options for tools using shared container storage.
430 When Podman runs in rootless mode, the file `$HOME/.config/containers/storage.conf` is used instead of the system defaults.
432
436 Podman can also be used as non-root user. When podman runs in rootless
437 mode, a user namespace is automatically created for the user, defined
438 in /etc/subuid and /etc/subgid.
439 Containers created by a non-root user are not visible to other users
442 and are not seen or managed by Podman running as root.
443 It is required to have multiple uids/gids set for an user. Be sure the
446 user is present in the files /etc/subuid and /etc/subgid.
447 If you have a recent version of usermod, you can execute the following
450 commands to add the ranges to the files
451 $ sudo usermod --add-subuids 10000-75535 USERNAME
454 $ sudo usermod --add-subgids 10000-75535 USERNAME
455 Or just add the content manually.
459 $ echo USERNAME:10000:65536 >> /etc/subuid
462 $ echo USERNAME:10000:65536 >> /etc/subgid
463 See the subuid(5) and subgid(5) man pages for more information.
467 Images are pulled under XDG_DATA_HOME when specified, otherwise in the
470 home directory of the user under .local/share/containers/storage.
471 Currently the slirp4netns package is required to be installed to create
474 a network device, otherwise rootless containers need to run in the net‐
475 work namespace of the host.
476 NOTE: Unsupported file systems in rootless mode
479 The Overlay file system (OverlayFS) is not supported in rootless mode.
480 The fuse-overlayfs package is a tool that provides the functionality of
481 OverlayFS in user namespace that allows mounting file systems in root‐
482 less environments. It is recommended to install the fuse-overlayfs
483 package and to enable it by adding mount_program = "/usr/bin/fuse-over‐
484 layfs" under [storage.options] in the /.config/containers/storage.conf
485 file.
486 The Network File System (NFS) and other distributed file systems (for
489 example: Lustre, Spectrum Scale, the General Parallel File System
490 (GPFS)) are not supported when running in rootless mode as these file
491 systems do not understand user namespace. However, rootless Podman can
492 make use of an NFS Homedir by modifying the /.config/containers/stor‐
493 age.conf to have the graphroot option point to a directory stored on
494 local (Non NFS) storage.
495 For more information, please refer to the Podman Troubleshooting Page
498 ⟨https://github.com/containers/libpod/blob/master/troubleshooting.md⟩.
499
502 containers-mounts.conf(5), containers-registries.conf(5), contain‐
503 ers-storage.conf(5), buildah(1), libpod.conf(5), oci-hooks(5), pol‐
504 icy.json(5), subuid(5), subgid(5), slirp4netns(1)
505
508 Dec 2016, Originally compiled by Dan Walsh dwalsh@redhat.com
509 ⟨mailto:dwalsh@redhat.com⟩
510 podman(1)()