diff options
Diffstat (limited to 'docs')
26 files changed, 514 insertions, 152 deletions
diff --git a/docs/Readme.md b/docs/Readme.md index 4d10cfa56..987a5b8e4 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -1,7 +1,7 @@ # Podman Documentation The online man pages and other documents regarding Podman can be found at -[Read The Docs](https://podman.readthedocs.io/en/latest/index.html). The man pages +[Read The Docs](https://podman.readthedocs.io). The man pages can be found under the [Commands](https://podman.readthedocs.io/en/latest/Commands.html) link on that page. diff --git a/docs/source/Commands.rst b/docs/source/Commands.rst index 028f03429..e3dbf8ecd 100644 --- a/docs/source/Commands.rst +++ b/docs/source/Commands.rst @@ -1,3 +1,5 @@ +.. include:: includes.rst + Commands ======== diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst index c516b3317..a1f9d605e 100644 --- a/docs/source/Introduction.rst +++ b/docs/source/Introduction.rst @@ -1,2 +1,106 @@ +.. include:: includes.rst + Introduction -============ +================================== +Containers_ simplify the consumption of applications with all of their dependencies and default configuration files. Users test drive or deploy a new application with one or two commands instead of following pages of installation instructions. Here's how to find your first `Container Image`_:: + + podman search busybox + +Output:: + + INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED + docker.io docker.io/library/busybox Busybox base image. 1882 [OK] + docker.io docker.io/radial/busyboxplus Full-chain, Internet enabled, busybox made f... 30 [OK] + docker.io docker.io/yauritux/busybox-curl Busybox with CURL 8 + ... + +The previous command returned a list of publicly available container images on DockerHub. These container images are easy to consume, but of differing levels of quality and maintenance. Let’s use the first one listed because it seems to be well maintained. + +To run the busybox container image, it’s just a single command:: + + podman run -it docker.io/library/busybox + +Output:: + + / # + +You can poke around in the busybox container for a while, but you’ll quickly find that running small container with a few Linux utilities in it provides limited value, so exit out:: + + exit + +There’s an old saying that “nobody runs an operating system just to run an operating system” and the same is true with containers. It’s the workload running on top of an operating system or in a container that’s interesting and valuable. + +Sometimes we can find a publicly available container image for the exact workload we’re looking for and it will already be packaged exactly how we want. But, more often than not, there’s something that we want to add, remove, or customize. It could be as simple as a configuration setting for security or performance, or as complex as adding a complex workload. Either way, containers make it fairly easy to make the changes we need. + +Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build the new and can easily be shared with others publicly using tools like GitHub. + +Here's an example of how to build an Nginx web server on top of a Debian base image using the Dockerfile maintained by Nginx and published in GitHub:: + + podman build -t nginx https://git.io/Jf8ol + +Once, the image build completes, it’s easy to run the new image from our local cache:: + + podman run -d -p 8080:80 nginx + curl localhost:8080 + +Output:: + + ... + <p><em>Thank you for using nginx.</em></p> + ... + +Building new images is great, but sharing our work with others let’s them review our work, critique how we built them, and offer improved versions. Our newly built Nginx image could be published at quay.io or docker.io to share it with the world. Everything needed to run the Nginx application is provided in the container image. Others could easily pull it down and use it, or make improvements to it. + +Standardizing on container images and `Container Registries`_ enable a new level of collaboration through simple consumption. This simple consumption model is possible because every major Container Engine and Registry Server uses the Open Containers Initiative (OCI_) format. This allows users to find, run, build, share and deploy containers anywhere they want. Podman and other `Container Engines`_ like CRI-O, Docker, or containerd can create and consume container images from docker.io, quay.io, an on premise registry or even one provided by a cloud provider. The OCI image format facilitates this ecosystem through a single standard. + +For example, if we wanted to share our newly built Nginx container image on quay.io it’s easy. First log in to quay:: + + podman login quay.io +Input:: + + Username: USERNAME + Password: ******** + Login Succeeded! + +Nex, tag the image so that we can push it into our user account:: + + podman tag localhost/nginx quay.io/USERNAME/nginx + +Finally, push the image:: + + podman push quay.io/USERNAME/nginx + +Output:: + + Getting image source signatures + Copying blob 38c40d6c2c85 done + Copying blob fee76a531659 done + Copying blob c2adabaecedb done + Copying config 7f3589c0b8 done + Writing manifest to image destination + Copying config 7f3589c0b8 done + Writing manifest to image destination + Storing signatures + +Notice that we pushed four layers to our registry and now it’s available for others to share. Take a quick look:: + + podman inspect quay.io/USERNAME/nginx + +Output:: + + [ + { + "Id": "7f3589c0b8849a9e1ff52ceb0fcea2390e2731db9d1a7358c2f5fad216a48263", + "Digest": "sha256:7822b5ba4c2eaabdd0ff3812277cfafa8a25527d1e234be028ed381a43ad5498", + "RepoTags": [ + "quay.io/USERNAME/nginx:latest", + ... + +To summarize, Podman makes it easy to find, run, build and share containers. + +* Find: whether finding a container on dockerhub.io or quay.io, an internal registry server, or directly from a vendor, a couple of `podman search`_, and `podman pull`_ commands make it easy +* Run: it's easy to consume pre-built images with everything needed to run an entire application, or start from a Linux distribution base image with the `podman run`_ command +* Build: creating new layers with small tweaks, or major overhauls is easy with `podman build` +* Share: Podman let’s you push your newly built containers anywhere you want with a single `podman push`_ command + +For more instructions on use cases, take a look at our :doc:`Tutorials` page. diff --git a/docs/source/Reference.rst b/docs/source/Reference.rst index c6a131bc7..d194c55a3 100644 --- a/docs/source/Reference.rst +++ b/docs/source/Reference.rst @@ -1,4 +1,10 @@ +.. include:: includes.rst + Reference ========= -Check out our new in-development `API documentation <_static/api.html>`_ +To see full screen version please visit: `API documentation <https://docs.podman.io/en/latest/_static/api.html>`_ + +.. raw:: html + + <iframe src="_static/api.html" allowfullscreen="true" height="600px" width="120%"></iframe> diff --git a/docs/source/Search.rst b/docs/source/Search.rst new file mode 100644 index 000000000..a80c229f4 --- /dev/null +++ b/docs/source/Search.rst @@ -0,0 +1,18 @@ +.. include:: includes.rst + +Search +================================== + +.. raw:: html + + <p> + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. + </p> + <form action="/en/latest/search.html" method="get" _lpchecked="1"> + <input type="text" name="q" value=""> + <input type="submit" value="search"> + <span id="search-progress" style="padding-left: 10px"></span> + </form> diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst index 85ae59131..0c013c244 100644 --- a/docs/source/Tutorials.rst +++ b/docs/source/Tutorials.rst @@ -1,4 +1,12 @@ +.. include:: includes.rst + Tutorials ========= +Here are a number of useful tutorials to get you up and running with Podman. If you are familiar with the Docker `Container Engine`_ the command in Podman_ should be quite familiar. If are brand new to containers, take a look at our `Introduction`. -`Podman Tutorials on GitHub <https://github.com/containers/libpod/tree/master/docs/tutorials>`_ +* `Basic Setup and Use of Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/podman_tutorial.md>`_: Learn how to setup Podman and perform some basic commands with the utility. +* `Basic Setup and Use of Podman in a Rootless environment <https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated. +* `Podman Mac Client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md>`_: Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented. +* `How to sign and distribute container images using Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman. +* `Podman remote-client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client. +* `How to use libpod for custom/derivative projects <https://github.com/containers/libpod/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project. diff --git a/docs/source/_static/api.html b/docs/source/_static/api.html index 08f55b620..8b9d66e0d 100644 --- a/docs/source/_static/api.html +++ b/docs/source/_static/api.html @@ -1,7 +1,7 @@ <!DOCTYPE html> <html> <head> - <title>ReDoc</title> + <title>Reference</title> <!-- needed for adaptive design --> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, initial-scale=1"> diff --git a/docs/source/includes.rst b/docs/source/includes.rst new file mode 100644 index 000000000..4794f454a --- /dev/null +++ b/docs/source/includes.rst @@ -0,0 +1,19 @@ +.. highlight:: bash +.. _Podman: http://podman.io +.. _OCI: https://www.opencontainers.org/ +.. _Container Engine: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo3l +.. _Container Engines: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo3l +.. _Container Runtime: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.6yt1ex5wfo55 +.. _Container: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.j2uq93kgxe0e +.. _Containers: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.j2uq93kgxe0e +.. _Container Image: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw +.. _Container Images: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw +.. _Container Registry: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq +.. _Container Registries: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq +.. _libpod: https://github.com/containers/libpod +.. _podman search: http://docs.podman.io/en/latest/markdown/podman-search.1.html +.. _podman pull: http://docs.podman.io/en/latest/markdown/podman-pull.1.html +.. _podman run: http://docs.podman.io/en/latest/markdown/podman-run.1.html +.. _podman build: http://docs.podman.io/en/latest/markdown/podman-build.1.html +.. _podman push: http://docs.podman.io/en/latest/markdown/podman-push.1.html +.. image:: https://github.com/containers/libpod/blob/master/logo/podman-logo.png?raw=true diff --git a/docs/source/index.rst b/docs/source/index.rst index 9dd61a6a6..9cc8e7af8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,10 +1,14 @@ -.. Podman documentation master file, created by - sphinx-quickstart on Tue Oct 22 15:20:30 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. include:: includes.rst -Welcome to Podman's documentation! +What is Podman? ================================== +Podman_ is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI_) Containers_ and `Container Images`_. Podman provides a command line interface (CLI) familiar to anyone who has used the Docker `Container Engine`_. Most users can simply alias Docker to Podman (`alias docker=podman`) without any problems. Similiar other common `Container Engines`_ (Docker, CRI-O, containerd), Podman relies on an OCI compliant `Container Runtime`_ (runc, crun, runv, etc) to interface with the operating system and create the running containers.This makes the running containers created by Podman nearly indistinguishable from those created by any other common container engine. + +Containers under the control of Podman can either be run by root or by a non-privileged user. Podman manages the entire container ecosystem which includes pods, containers, container images, and container volumes using the libpod_ library. Podman specializes in all of the commands and functions that help you to maintain and modify OCI container images, such as pulling and tagging. It allows you to create, run, and maintain those containers and container images in a production environment. + +The Podman service runs only on Linux platforms, however a REST API and clients are currently under development which will allow Mac and Windows platforms to call the service. There is currently a Varlink based remote client which runs on Mac or Windows platforms that allows the remote client to talk to the Podman server on a Linux platform. In addition to those clients, there is also a Mac client. NOTE: the Varlink remote client will be deprecated after the REST API is completed. + +If you are completely new to containers, we recommend that you check out the :doc:`Introduction`. For power users or those comming from Docker, check out our :doc:`Tutorials`. For advanced users and contributors, you can get very detailed information about the Podman CLI by looking our :doc:`Commands` page. Finally, for Developers looking at how to interact with the Podman API, please see our API documentation :doc:`Reference`. .. toctree:: :maxdepth: 2 @@ -14,13 +18,4 @@ Welcome to Podman's documentation! Commands Reference Tutorials - - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + Search diff --git a/docs/source/markdown/links/podman-image-search.1 b/docs/source/markdown/links/podman-image-search.1 new file mode 100644 index 000000000..73e70d3e3 --- /dev/null +++ b/docs/source/markdown/links/podman-image-search.1 @@ -0,0 +1 @@ +.so man1/podman-search.1 diff --git a/docs/source/markdown/podman-container-cleanup.1.md b/docs/source/markdown/podman-container-cleanup.1.md index 66a6cff62..a200c2c36 100644 --- a/docs/source/markdown/podman-container-cleanup.1.md +++ b/docs/source/markdown/podman-container-cleanup.1.md @@ -16,6 +16,13 @@ Sometimes container's mount points and network stacks can remain if the podman c Cleanup all containers. +**--exec**=_session_ + +Clean up an exec session for a single container. +Can only be specified if a single container is being cleaned up (conflicts with **--all** as such). +If **--rm** is not specified, temporary files for the exec session will be cleaned up; if it is, the exec session will be removed from the container. +Conflicts with **--rmi** as the container is not being cleaned up so the image cannot be removed. + **--latest**, **-l** Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. diff --git a/docs/source/markdown/podman-exec.1.md b/docs/source/markdown/podman-exec.1.md index 1bd10f9ba..f44a3d3d9 100644 --- a/docs/source/markdown/podman-exec.1.md +++ b/docs/source/markdown/podman-exec.1.md @@ -13,6 +13,10 @@ podman\-exec - Execute a command in a running container ## OPTIONS +**--detach**, **-d** + +Start the exec session, but do not attach to it. The command will run in the background and the exec session will be automatically removed when it completes. The **podman exec** command will print the ID of the exec session and exit immediately after it starts. + **--detach-keys**=*sequence* Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. diff --git a/docs/source/markdown/podman-history.1.md b/docs/source/markdown/podman-history.1.md index 1a8f8906c..26b213af9 100644 --- a/docs/source/markdown/podman-history.1.md +++ b/docs/source/markdown/podman-history.1.md @@ -37,10 +37,13 @@ Display sizes and dates in human readable format (default *true*). Do not truncate the output (default *false*). +**--notruncate** + +Do not truncate the output + **--quiet**, **-q**=*true|false* Print the numeric IDs only (default *false*). - **--format**=*format* Alter the output for a format like 'json' or a Go template. diff --git a/docs/source/markdown/podman-image-diff.1.md b/docs/source/markdown/podman-image-diff.1.md new file mode 100644 index 000000000..1e7397cd8 --- /dev/null +++ b/docs/source/markdown/podman-image-diff.1.md @@ -0,0 +1,46 @@ +% podman-image-diff(1) + +## NAME +podman-image-diff - Inspect changes on an image's filesystem + +## SYNOPSIS +**podman image diff** [*options*] *name* + +## DESCRIPTION +Displays changes on a container or image's filesystem. The container or image will be compared to its parent layer + +## OPTIONS + +**--format** + +Alter the output into a different format. The only valid format for diff is `json`. + +## EXAMPLE + +``` +# podman diff redis:old redis:alpine +C /usr +C /usr/local +C /usr/local/bin +A /usr/local/bin/docker-entrypoint.sh +``` + +``` +# podman diff --format json redis:old redis:alpine +{ + "changed": [ + "/usr", + "/usr/local", + "/usr/local/bin" + ], + "added": [ + "/usr/local/bin/docker-entrypoint.sh" + ] +} +``` + +## SEE ALSO +podman(1) + +## HISTORY +August 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/markdown/podman-image.1.md b/docs/source/markdown/podman-image.1.md index 1552098ac..dfff57b31 100644 --- a/docs/source/markdown/podman-image.1.md +++ b/docs/source/markdown/podman-image.1.md @@ -14,6 +14,7 @@ The image command allows you to manage images | Command | Man Page | Description | | -------- | ----------------------------------------------- | --------------------------------------------------------------------------- | | build | [podman-build(1)](podman-build.1.md) | Build a container using a Dockerfile. | +| diff | [podman-image-diff(1)](podman-image-diff.1.md) | Inspect changes on an image's filesystem. | | exists | [podman-image-exists(1)](podman-image-exists.1.md) | Check if an image exists in local storage. | | history | [podman-history(1)](podman-history.1.md) | Show the history of an image. | | import | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | @@ -25,6 +26,7 @@ The image command allows you to manage images | push | [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. | | rm | [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. | | save | [podman-save(1)](podman-save.1.md) | Save an image to docker-archive or oci. | +| search | [podman-search(1)](podman-search.1.md) | Search a registry for an image. | | sign | [podman-image-sign(1)](podman-image-sign.1.md) | Create a signature for an image. | | tag | [podman-tag(1)](podman-tag.1.md) | Add an additional name to a local image. | | untag | [podman-untag(1)](podman-untag.1.md) | Removes one or more names from a locally-stored image. | diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index d9da4c3f8..24ab97c91 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -30,128 +30,212 @@ Run podman info with plain text response: ``` $ podman info host: - BuildahVersion: 1.4-dev - Conmon: - package: Unknown - path: /usr/libexec/podman/conmon - version: 'conmon version 1.12.0-dev, commit: d724f3d54ad2d95b6de741085d4990190ebfd7ff' - Distribution: - distribution: fedora - version: "28" - MemFree: 1271083008 - MemTotal: 33074233344 - OCIRuntime: - package: runc-1.0.0-51.dev.gitfdd8055.fc28.x86_64 - path: /usr/bin/runc - version: 'runc version spec: 1.0.0' - SwapFree: 34309664768 - SwapTotal: 34359734272 arch: amd64 + buildahVersion: 1.15.0 + cgroupVersion: v1 + conmon: + package: conmon-2.0.16-2.fc32.x86_64 + path: /usr/bin/conmon + version: 'conmon version 2.0.16, commit: 1044176f7dd177c100779d1c63931d6022e419bd' cpus: 8 + distribution: + distribution: fedora + version: "32" + eventLogger: file hostname: localhost.localdomain - kernel: 4.18.7-200.fc28.x86_64 + idMappings: + gidmap: + - container_id: 0 + host_id: 3267 + size: 1 + - container_id: 1 + host_id: 100000 + size: 65536 + uidmap: + - container_id: 0 + host_id: 3267 + size: 1 + - container_id: 1 + host_id: 100000 + size: 65536 + kernel: 5.6.11-300.fc32.x86_64 + linkmode: dynamic + memFree: 1401929728 + memTotal: 16416161792 + ociRuntime: + name: runc + package: containerd.io-1.2.10-3.2.fc31.x86_64 + path: /usr/bin/runc + version: |- + runc version 1.0.0-rc8+dev + commit: 3e425f80a8c931f88e6d94a8c831b9d5aa481657 + spec: 1.0.1-dev os: linux - uptime: 218h 49m 33.66s (Approximately 9.08 days) + rootless: true + slirp4netns: + executable: /bin/slirp4netns + package: slirp4netns-1.0.0-1.fc32.x86_64 + version: |- + slirp4netns version 1.0.0 + commit: a3be729152a33e692cd28b52f664defbf2e7810a + libslirp: 4.2.0 + swapFree: 8291610624 + swapTotal: 8296329216 + uptime: 52h 29m 39.78s (Approximately 2.17 days) registries: - docker.io: - Blocked: true - Insecure: true - Location: docker.io - MirrorByDigestOnly: false - Mirrors: - - Insecure: true - Location: example2.io/example/ubi8-minimal - Prefix: docker.io - redhat.com: - Blocked: false - Insecure: false - Location: registry.access.redhat.com/ubi8 - MirrorByDigestOnly: true - Mirrors: - - Insecure: false - Location: example.io/example/ubi8-minimal - - Insecure: true - Location: example3.io/example/ubi8-minimal - Prefix: redhat.com + search: + - registry.fedoraproject.org + - registry.access.redhat.com + - registry.centos.org + - docker.io store: - ConfigFile: /etc/containers/storage.conf - ContainerStore: - number: 37 - GraphDriverName: overlay - GraphOptions: - - overlay.mountopt=nodev - - overlay.override_kernel_check=true - GraphRoot: /var/lib/containers/storage - GraphStatus: + configFile: /home/dwalsh/.config/containers/storage.conf + containerStore: + number: 2 + paused: 0 + running: 0 + stopped: 2 + graphDriverName: overlay + graphOptions: + overlay.mount_program: + Executable: /home/dwalsh/bin/fuse-overlayfs + Package: Unknown + Version: |- + fusermount3 version: 3.9.1 + fuse-overlayfs: version 0.7.2 + FUSE library version 3.9.1 + using FUSE kernel interface version 7.31 + graphRoot: /home/dwalsh/.local/share/containers/storage + graphStatus: Backing Filesystem: extfs - Native Overlay Diff: "true" + Native Overlay Diff: "false" Supports d_type: "true" - ImageStore: - number: 17 - RunRoot: /var/run/containers/storage - + Using metacopy: "false" + imageStore: + number: 7 + runRoot: /run/user/3267/containers + volumePath: /home/dwalsh/.local/share/containers/storage/volumes +version: + Built: 1589899246 + BuiltTime: Tue May 19 10:40:46 2020 + GitCommit: c3678ce3289f4195f3f16802411e795c6a587c9f-dirty + GoVersion: go1.14.2 + OsArch: linux/amd64 + APIVersion: 1 + Version: 2.0.0 ``` Run podman info with JSON formatted response: ``` { - "host": { - "BuildahVersion": "1.4-dev", - "Conmon": { - "package": "Unknown", - "path": "/usr/libexec/podman/conmon", - "version": "conmon version 1.12.0-dev, commit: d724f3d54ad2d95b6de741085d4990190ebfd7ff" - }, - "Distribution": { - "distribution": "fedora", - "version": "28" + "host": { + "arch": "amd64", + "buildahVersion": "1.15.0", + "cgroupVersion": "v1", + "conmon": { + "package": "conmon-2.0.16-2.fc32.x86_64", + "path": "/usr/bin/conmon", + "version": "conmon version 2.0.16, commit: 1044176f7dd177c100779d1c63931d6022e419bd" + }, + "cpus": 8, + "distribution": { + "distribution": "fedora", + "version": "32" + }, + "eventLogger": "file", + "hostname": "localhost.localdomain", + "idMappings": { + "gidmap": [ + { + "container_id": 0, + "host_id": 3267, + "size": 1 }, - "MemFree": 1204109312, - "MemTotal": 33074233344, - "OCIRuntime": { - "package": "runc-1.0.0-51.dev.gitfdd8055.fc28.x86_64", - "path": "/usr/bin/runc", - "version": "runc version spec: 1.0.0" + { + "container_id": 1, + "host_id": 100000, + "size": 65536 + } + ], + "uidmap": [ + { + "container_id": 0, + "host_id": 3267, + "size": 1 }, - "SwapFree": 34309664768, - "SwapTotal": 34359734272, - "arch": "amd64", - "cpus": 8, - "hostname": "localhost.localdomain", - "kernel": "4.18.7-200.fc28.x86_64", - "os": "linux", - "uptime": "218h 50m 35.02s (Approximately 9.08 days)" + { + "container_id": 1, + "host_id": 100000, + "size": 65536 + } + ] }, - "insecure registries": { - "registries": [] + "kernel": "5.6.11-300.fc32.x86_64", + "memFree": 1380356096, + "memTotal": 16416161792, + "ociRuntime": { + "name": "runc", + "package": "containerd.io-1.2.10-3.2.fc31.x86_64", + "path": "/usr/bin/runc", + "version": "runc version 1.0.0-rc8+dev\ncommit: 3e425f80a8c931f88e6d94a8c831b9d5aa481657\nspec: 1.0.1-dev" }, - "registries": { - "registries": [ - "quay.io", - "registry.fedoraproject.org", - "docker.io", - "registry.access.redhat.com" - ] + "os": "linux", + "rootless": true, + "slirp4netns": { + "executable": "/bin/slirp4netns", + "package": "slirp4netns-1.0.0-1.fc32.x86_64", + "version": "slirp4netns version 1.0.0\ncommit: a3be729152a33e692cd28b52f664defbf2e7810a\nlibslirp: 4.2.0" }, - "store": { - "ContainerStore": { - "number": 37 - }, - "GraphDriverName": "overlay", - "GraphOptions": [ - "overlay.mountopt=nodev", - "overlay.override_kernel_check=true" - ], - "GraphRoot": "/var/lib/containers/storage", - "GraphStatus": { - "Backing Filesystem": "extfs", - "Native Overlay Diff": "true", - "Supports d_type": "true" - }, - "ImageStore": { - "number": 17 - }, - "RunRoot": "/var/run/containers/storage" - } + "swapFree": 8291610624, + "swapTotal": 8296329216, + "uptime": "52h 27m 39.38s (Approximately 2.17 days)", + "linkmode": "dynamic" + }, + "store": { + "configFile": "/home/dwalsh/.config/containers/storage.conf", + "containerStore": { + "number": 2, + "paused": 0, + "running": 0, + "stopped": 2 + }, + "graphDriverName": "overlay", + "graphOptions": { + "overlay.mount_program": { + "Executable": "/home/dwalsh/bin/fuse-overlayfs", + "Package": "Unknown", + "Version": "fusermount3 version: 3.9.1\nfuse-overlayfs: version 0.7.2\nFUSE library version 3.9.1\nusing FUSE kernel interface version 7.31" +} + }, + "graphRoot": "/home/dwalsh/.local/share/containers/storage", + "graphStatus": { + "Backing Filesystem": "extfs", + "Native Overlay Diff": "false", + "Supports d_type": "true", + "Using metacopy": "false" + }, + "imageStore": { + "number": 7 + }, + "runRoot": "/run/user/3267/containers", + "volumePath": "/home/dwalsh/.local/share/containers/storage/volumes" + }, + "registries": { + "search": [ + "registry.fedoraproject.org", + "registry.access.redhat.com", + "registry.centos.org", + "docker.io" +] + }, + "version": { + "APIVersion": 1, + "Version": "2.0.0", + "GoVersion": "go1.14.2", + "GitCommit": "c3678ce3289f4195f3f16802411e795c6a587c9f-dirty", + "BuiltTime": "Tue May 19 10:40:46 2020", + "Built": 1589899246, + "OsArch": "linux/amd64" + } } ``` Run podman info and only get the registries information. diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md index 38d0c5904..ab3287a7c 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md @@ -19,7 +19,7 @@ The list image's ID and the digest of the image's manifest. Push the images mentioned in the manifest list or image index, in addition to the list or index itself. -**--authfile** *path* +**--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) @@ -27,22 +27,22 @@ If the authorization state is not found there, $HOME/.docker/config.json is chec Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` -**--cert-dir** *path* +**--cert-dir**=*path* Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) -**--creds** *creds* +**--creds**=*creds* The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. -**--digestfile** *Digestfile* +**--digestfile**=*Digestfile* After copying the image, write the digest of the resulting image to the file. -**--format, -f** +**--format**, **-f**=*format* Manifest list type (oci or v2s2) to use when pushing the list (default is oci). @@ -50,15 +50,19 @@ Manifest list type (oci or v2s2) to use when pushing the list (default is oci). Delete the manifest list or image index from local storage if pushing succeeds. +**--quiet**, **-q** + +When writing the manifest, suppress progress output + **--remove-signatures** Don't copy signatures when pushing images. -**--sign-by** *fingerprint* +**--sign-by**=*fingerprint* Sign the pushed images using the GPG key that matches the specified fingerprint. -**--tls-verify** *bool-value* +**--tls-verify** Require HTTPS and verify certificates when talking to container registries (defaults to true) (Not available for remote commands) diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index ca6875d18..86fa2552e 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/docs/source/markdown/podman-network-inspect.1.md @@ -10,10 +10,6 @@ podman\-network\-inspect - Displays the raw CNI network configuration for one or Display the raw (JSON format) network configuration. This command is not available for rootless users. ## OPTIONS -**--quiet**, **-q** - -The `quiet` option will restrict the output to only the network names. - **--format**, **-f** Pretty-print networks to JSON or using a Go template. diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index aa558526a..5d941219a 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -73,7 +73,10 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. -**--override-arch**=ARCH +**--override-os**=*OS* +Use OS instead of the running OS for choosing images + +**--override-arch**=*ARCH* Override the machine's default architecture of the image to be pulled. For example, `arm`. diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index a2fefe4dd..48e595641 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -15,15 +15,11 @@ example *unix:/run/user/1000/podman/podman.sock*) ## OPTIONS -**--timeout**, **-t** +**--time**, **-t** The time until the session expires in _milliseconds_. The default is 1 second. A value of `0` means no timeout and the session will not expire. -**--varlink** - -Use the varlink protocol instead of the REST-based protocol. This option will be deprecated in the future. - **--help**, **-h** Print usage statement. diff --git a/docs/source/markdown/podman-varlink.1.md b/docs/source/markdown/podman-varlink.1.md index 0d2ab1668..0b04d5ba3 100644 --- a/docs/source/markdown/podman-varlink.1.md +++ b/docs/source/markdown/podman-varlink.1.md @@ -19,7 +19,7 @@ The varlink service should generally be done with systemd. See _Configuration_ Print usage statement -**--timeout**, **-t** +**--time**, **-t** The time until the varlink session expires in _milliseconds_. The default is 1 second. A value of `0` means no timeout and the session will not expire. diff --git a/docs/source/markdown/podman-version.1.md b/docs/source/markdown/podman-version.1.md index 86c270e02..185e8e296 100644 --- a/docs/source/markdown/podman-version.1.md +++ b/docs/source/markdown/podman-version.1.md @@ -25,17 +25,18 @@ Change output format to "json" or a Go template. A sample output of the `version` command: ``` $ podman version -Version: 0.11.1 -Go Version: go1.11 -Git Commit: "8967a1d691ed44896b81ad48c863033f23c65eb0-dirty" -Built: Thu Nov 8 22:35:40 2018 -OS/Arch: linux/amd64 +Version: 2.0.0 +API Version: 1 +Go Version: go1.14.2 +Git Commit: 4520664f63c3a7f9a80227715359e20069d95542 +Built: Tue May 19 10:48:59 2020 +OS/Arch: linux/amd64 ``` Filtering out only the version: ``` $ podman version --format '{{.Client.Version}}' -1.6.3 +2.0.0 ``` ## SEE ALSO diff --git a/docs/source/markdown/podman-wait.1.md b/docs/source/markdown/podman-wait.1.md index ce1c70a5f..886bbc55b 100644 --- a/docs/source/markdown/podman-wait.1.md +++ b/docs/source/markdown/podman-wait.1.md @@ -15,6 +15,9 @@ After the container stops, the container's return code is printed. ## OPTIONS +**--condition**=*state* +Condition to wait on (default "stopped") + **--help**, **-h** Print usage statement diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 6bac0cc9d..02f23e6cc 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -58,6 +58,9 @@ Podman and libpod currently support an additional `precreate` state which is cal **WARNING**: the `precreate` hook lets you do powerful things, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running your container with `precreate` hooks disabled to see if the problem is due to one of your hooks. +**--identity**=*path* +Path to SSH identity file + **--log-level**=*level* Log messages above specified level: debug, info, warn, error (default), fatal or panic (default: "error") @@ -70,6 +73,9 @@ When namespace is set, created containers and pods will join the given namespace **--network-cmd-path**=*path* Path to the command binary to use for setting up a network. It is currently only used for setting up a slirp4netns network. If "" is used then the binary is looked up using the $PATH environment variable. +**--remote**, **-r**=*url* +URL to access Podman service (default "unix:/run/user/3267/podman/podman.sock") + **--root**=*value* Storage root dir in which data, including images, is stored (default: "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/containers/storage" for other users). diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md index 065b0c4a9..8a1f40fc0 100644 --- a/docs/tutorials/podman-derivative-api.md +++ b/docs/tutorials/podman-derivative-api.md @@ -4,6 +4,20 @@ libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages. +Using the REST API +--- + +Advantages: + + - Stable, versioned API + - Language-agnostic + - [Well-documented](http://docs.podman.io/en/latest/_static/api.html) API + +Disadvantages: + + - Error handling is less verbose than Golang API + - May be slower + Running as a subprocess --- @@ -35,12 +49,12 @@ Disadvantages: Varlink --- -Some code exists for this; splits the difference. Future uncertain. +The Varlink API is presently deprecated. We do not recommend adopting it for new projects. Making the choice --- A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project? -If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally +If so, that makes it more likely that you want to run `podman` as a subprocess or using the HTTP API. If you want a separate image store and a fundamentally different experience; if what you're doing with containers is quite different from those created by the `podman` CLI, that may drive you towards vendoring. diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 8e048c746..93726b3b1 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -110,6 +110,46 @@ The Podman configuration files for root reside in `/usr/share/containers` with o The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`. +### Using volumes + +Rootless Podman is not, and will never be, root; it's not a setuid binary, and gains no privileges when it runs. Instead, Podman makes use of a user namespace to shift the UIDs and GIDs of a block of users it is given access to on the host (via the newuidmap and newgidmap executables) and your own user within the containers that podman creates. + +If your container runs with the root user, then `root` in the container is actually your user on the host. UID/GID 1 is the first UID/GID specified in your user's mapping in `/etc/subuid` and `/etc/subgid`, etc. If you mount a directory from the host into a container as a rootless user, and create a file in that directory as root in the container, you'll see it's actually owned by your user on the host. + +So, for example, + +``` +> whoami +john + +# a folder which is empty +host> ls /home/john/folder +host> podman run -v /home/john/folder:/container/volume mycontainer /bin/bash + +# Now I'm in the container +root@container> whoami +root +root@container> touch /container/volume/test +root@container> ls -l /container/volume +total 0 +-rw-r--r-- 1 root root 0 May 20 21:47 test +root@container> exit + +# I check again +host> ls -l /home/john/folder +total 0 +-rw-r--r-- 1 john john 0 May 20 21:47 test +``` + +We do recognize that this doesn't really match how many people intend to use rootless Podman - they want their UID inside and outside the container to match. Thus, we provide the `--userns=keep-id` flag, which ensures that your user is mapped to its own UID and GID inside the container. + +It is also helpful to distinguish between running podman as a rootless user, and a container which is built to run rootless. If the container you're trying you run has a `USER` which is not root, then when mounting volumes you **must** use `--userns=keep-id`. This is because the container user would not be able to become `root` and access the mounted volumes. + +Other considerations in regards to volumes: + +- You should always give the full path to the volume you'd like to mount +- The mount point must exist in the container + ## More information If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/libpod/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment. |