summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/Readme.md13
-rw-r--r--docs/source/Commands.rst2
-rw-r--r--docs/source/Introduction.rst106
-rw-r--r--docs/source/Reference.rst8
-rw-r--r--docs/source/Search.rst18
-rw-r--r--docs/source/Tutorials.rst10
-rw-r--r--docs/source/_static/api.html2
-rw-r--r--docs/source/includes.rst19
-rw-r--r--docs/source/index.rst25
-rw-r--r--docs/source/markdown/links/podman-image-search.11
-rw-r--r--docs/source/markdown/podman-auto-update.1.md16
-rw-r--r--docs/source/markdown/podman-container-cleanup.1.md7
-rw-r--r--docs/source/markdown/podman-create.1.md18
-rw-r--r--docs/source/markdown/podman-events.1.md2
-rw-r--r--docs/source/markdown/podman-exec.1.md4
-rw-r--r--docs/source/markdown/podman-generate-systemd.1.md12
-rw-r--r--docs/source/markdown/podman-history.1.md5
-rw-r--r--docs/source/markdown/podman-image-diff.1.md46
-rw-r--r--docs/source/markdown/podman-image.1.md2
-rw-r--r--docs/source/markdown/podman-info.1.md294
-rw-r--r--docs/source/markdown/podman-manifest-add.1.md2
-rw-r--r--docs/source/markdown/podman-manifest-annotate.1.md61
-rw-r--r--docs/source/markdown/podman-manifest-create.1.md2
-rw-r--r--docs/source/markdown/podman-manifest-inspect.1.md2
-rw-r--r--docs/source/markdown/podman-manifest-push.1.md76
-rw-r--r--docs/source/markdown/podman-manifest-remove.1.md23
-rw-r--r--docs/source/markdown/podman-manifest.1.md15
-rw-r--r--docs/source/markdown/podman-network-create.1.md2
-rw-r--r--docs/source/markdown/podman-network-inspect.1.md10
-rw-r--r--docs/source/markdown/podman-network-ls.1.md18
-rw-r--r--docs/source/markdown/podman-pod-inspect.1.md51
-rw-r--r--docs/source/markdown/podman-pull.1.md5
-rw-r--r--docs/source/markdown/podman-run.1.md11
-rw-r--r--docs/source/markdown/podman-search.1.md2
-rw-r--r--docs/source/markdown/podman-system-service.1.md6
-rw-r--r--docs/source/markdown/podman-varlink.1.md2
-rw-r--r--docs/source/markdown/podman-version.1.md13
-rw-r--r--docs/source/markdown/podman-wait.1.md3
-rw-r--r--docs/source/markdown/podman.1.md6
-rw-r--r--docs/tutorials/podman-derivative-api.md18
-rw-r--r--docs/tutorials/rootless_tutorial.md42
41 files changed, 797 insertions, 183 deletions
diff --git a/docs/Readme.md b/docs/Readme.md
index 209dcd6b4..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.
@@ -26,3 +26,14 @@ link on that page.
| ------------------------------------ | --------------------------- |
| docs/remote-docs.sh | Read the docs/source/markdown files and format for each platform |
| docs/links-to-html.lua | pandoc filter to do aliases for html files |
+
+## API Reference
+
+The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is
+automatically generated from committed upstream sources. There is a short-duration
+cache involved, in case old content or an error is returned, try clearing your browser
+cache or returning to the site after 10-30 minutes.
+
+***Maintainers Note***: Please refer to [the Cirrus-CI tasks
+documentation](../contrib/cirrus/README.md#docs-task) for
+important operational details.
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 0c7e28c3b..0c013c244 100644
--- a/docs/source/Tutorials.rst
+++ b/docs/source/Tutorials.rst
@@ -1,2 +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`.
+
+* `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..1c46f1c8a 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. Similar to 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-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md
index 93ad22f76..435a767c1 100644
--- a/docs/source/markdown/podman-auto-update.1.md
+++ b/docs/source/markdown/podman-auto-update.1.md
@@ -13,6 +13,8 @@ If the label is present and set to "image", Podman reaches out to the correspond
An image is considered updated if the digest in the local storage is different than the one of the remote image.
If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container.
+If "io.containers.autoupdate.authfile" label is present, Podman reaches out to corresponding authfile when pulling images.
+
At container-creation time, Podman looks up the "PODMAN_SYSTEMD_UNIT" environment variables and stores it verbatim in the container's label.
This variable is now set by all systemd units generated by `podman-generate-systemd` and is set to `%n` (i.e., the name of systemd unit starting the container).
This data is then being used in the auto-update sequence to instruct systemd (via DBUS) to restart the unit and hence to restart the container.
@@ -21,11 +23,23 @@ Note that `podman auto-update` relies on systemd and requires a fully-qualified
This enforcement is necessary to know which image to actually check and pull.
If an image ID was used, Podman would not know which image to check/pull anymore.
+## OPTIONS
+
+**--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)
+
+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`
+
## EXAMPLES
```
# Start a container
-$ podman run -d busybox:latest top
+$ podman run --label "io.containers.autoupdate=image" \
+ --label "io.containers.autoupdate.autfile=/some/authfile.json" \
+ -d busybox:latest top
bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d
# Generate a systemd unit for this container
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-create.1.md b/docs/source/markdown/podman-create.1.md
index f0494ca7d..3a6077832 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -278,7 +278,7 @@ See [**Environment**](#environment) note below for precedence and examples.
**--env-host**=*true|false*
-Use host environment inside of the container. See **Environment** note below for precedence.
+Use host environment inside of the container. See **Environment** note below for precedence. (Not available for remote commands)
**--env-file**=*file*
@@ -347,7 +347,7 @@ the container should not use any proxy. Proxy environment variables specified
for the container in any other way will override the values that would have
been passed through from the host. (Other ways to specify the proxy for the
container include passing the values with the `--env` flag, or hard coding the
-proxy environment at container build time.)
+proxy environment at container build time.) (Not available for remote commands)
For example, to disable passing these environment variables from host to
container:
@@ -358,12 +358,12 @@ Defaults to `true`
**--image-volume**, **builtin-volume**=*bind|tmpfs|ignore*
-Tells Podman how to handle the builtin image volumes. The options are: 'bind', 'tmpfs', or 'ignore' (default 'bind').
-bind: A directory is created inside the container state directory and bind mounted into
-the container for the volumes.
-tmpfs: The volume is mounted onto the container as a tmpfs, which allows the users to create
+Tells Podman how to handle the builtin image volumes. Default is **bind**.
+
+- **bind**: An anonymous named volume will be created and mounted into the container.
+- **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create
content that disappears when the container is stopped.
-ignore: All volumes are just ignored and no action is taken.
+- **ignore**: All volumes are just ignored and no action is taken.
**--init**
@@ -445,8 +445,6 @@ Remember that the MAC address in an Ethernet network must be unique.
The IPv6 link-local address will be based on the device's MAC address
according to RFC4862.
-Not currently supported
-
**--memory**, **-m**=*limit*
Memory limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
@@ -504,7 +502,7 @@ Current supported mount TYPES are `bind`, `volume`, and `tmpfs`.
· dst, destination, target: mount destination spec.
- · ro, read-only: true or false (default).
+ · ro, readonly: true or false (default).
Options specific to bind:
diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md
index bb1923574..a05047684 100644
--- a/docs/source/markdown/podman-events.1.md
+++ b/docs/source/markdown/podman-events.1.md
@@ -142,7 +142,7 @@ $ sudo podman events --since 5m
Show Podman events in JSON Lines format
```
-events --format json
+$ podman events --format json
{"ID":"683b0909d556a9c02fa8cd2b61c3531a965db42158627622d1a67b391964d519","Image":"localhost/myshdemo:latest","Name":"agitated_diffie","Status":"cleanup","Time":"2019-04-27T22:47:00.849932843-04:00","Type":"container"}
{"ID":"a0f8ab051bfd43f9c5141a8a2502139707e4b38d98ac0872e57c5315381e88ad","Image":"docker.io/library/alpine:latest","Name":"friendly_tereshkova","Status":"unmount","Time":"2019-04-28T13:43:38.063017276-04:00","Type":"container"}
```
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-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md
index fa04f81f9..72031b19b 100644
--- a/docs/source/markdown/podman-generate-systemd.1.md
+++ b/docs/source/markdown/podman-generate-systemd.1.md
@@ -40,6 +40,18 @@ Override the default stop timeout for the container with the given value.
Set the systemd restart policy. The restart-policy must be one of: "no", "on-success", "on-failure", "on-abnormal",
"on-watchdog", "on-abort", or "always". The default policy is *on-failure*.
+**--container-prefix**=*prefix*
+
+Set the systemd unit name prefix for containers. The default is *container*.
+
+**--pod-prefix**=*prefix*
+
+Set the systemd unit name prefix for pods. The default is *pod*.
+
+**--separator**=*separator*
+
+Set the systemd unit name seperator between the name/id of a container/pod and the prefix. The default is *-*.
+
## Examples
### Generate and print a systemd unit file for a container
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-add.1.md b/docs/source/markdown/podman-manifest-add.1.md
index 857a98e12..82f2071b9 100644
--- a/docs/source/markdown/podman-manifest-add.1.md
+++ b/docs/source/markdown/podman-manifest-add.1.md
@@ -73,4 +73,4 @@ podman manifest add --arch arm64 --variant v8 mylist:v1.11 docker://71c201d10fff
```
## SEE ALSO
-podman(1), podman-manifest(1), podman-manifest-create(1), podman-manifest-inspect(1), podman-rmi(1)
+podman(1), podman-manifest(1), podman-manifest-create(1), podman-manifest-inspect(1), podman-manifest-push(1), podman-manifest-remove(1), podman-rmi(1)
diff --git a/docs/source/markdown/podman-manifest-annotate.1.md b/docs/source/markdown/podman-manifest-annotate.1.md
new file mode 100644
index 000000000..4450de7fd
--- /dev/null
+++ b/docs/source/markdown/podman-manifest-annotate.1.md
@@ -0,0 +1,61 @@
+% podman-manifest-annotate(1)
+
+## NAME
+podman\-manifest\-annotate - Add or update information about an entry in a manifest list or image index
+
+## SYNOPSIS
+**podman manifest annotate** [options...] *listnameorindexname* *imagemanifestdigest*
+
+## DESCRIPTION
+
+Adds or updates information about an image included in a manifest list or image index.
+
+## OPTIONS
+
+**--annotation** *annotation=value*
+
+Set an annotation on the entry for the specified image.
+
+**--arch**
+
+Override the architecture which the list or index records as a requirement for
+the image. This is usually automatically retrieved from the image's
+configuration information, so it is rarely necessary to use this option.
+
+
+**--features**
+
+Specify the features list which the list or index records as requirements for
+the image. This option is rarely used.
+
+**--os**
+
+Override the OS which the list or index records as a requirement for the image.
+This is usually automatically retrieved from the image's configuration
+information, so it is rarely necessary to use this option.
+
+**--os-features**
+
+Specify the OS features list which the list or index records as requirements
+for the image. This option is rarely used.
+
+**--os-version**
+
+Specify the OS version which the list or index records as a requirement for the
+image. This option is rarely used.
+
+**--variant**
+
+Specify the variant which the list or index records for the image. This option
+is typically used to distinguish between multiple entries which share the same
+architecture value, but which expect different versions of its instruction set.
+
+## EXAMPLE
+
+```
+podman manifest annotate --arch arm64 --variant v8 mylist:v1.11 sha256:59eec8837a4d942cc19a52b8c09ea75121acc38114a2c68b98983ce9356b8610
+07ec8dc22b5dba3a33c60b68bce28bbd2b905e383fdb32a90708fa5eeac13a07: sha256:59eec8837a4d942cc19a52b8c09ea75121acc38114a2c68b98983ce9356b8610
+```
+
+## SEE ALSO
+podman(1), podman-manifest(1), podman-manifest-add(1), podman-manifest-create(1), podman-manifest-inspect(1), podman-rmi(1)
diff --git a/docs/source/markdown/podman-manifest-create.1.md b/docs/source/markdown/podman-manifest-create.1.md
index 941e70c32..537a641f2 100644
--- a/docs/source/markdown/podman-manifest-create.1.md
+++ b/docs/source/markdown/podman-manifest-create.1.md
@@ -40,4 +40,4 @@ podman manifest create --all mylist:v1.11 docker://fedora
```
## SEE ALSO
-podman(1), podman-manifest(1), podman-manifest-add(1), podman-manifest-inspect(1), podman-rmi(1)
+podman(1), podman-manifest(1), podman-manifest-add(1), podman-manifest-inspect(1), podman-manifest-push(1), podman-manifest-remove(1), podman-rmi(1)
diff --git a/docs/source/markdown/podman-manifest-inspect.1.md b/docs/source/markdown/podman-manifest-inspect.1.md
index efde02643..a4c58bd13 100644
--- a/docs/source/markdown/podman-manifest-inspect.1.md
+++ b/docs/source/markdown/podman-manifest-inspect.1.md
@@ -21,4 +21,4 @@ podman manifest inspect mylist:v1.11
```
## SEE ALSO
-podman(1), podman-manifest(1), podman-manifest-create(1), podman-manifest-add(1), podman-rmi(1)
+podman(1), podman-manifest(1), podman-manifest-create(1), podman-manifest-add(1), podman-manifest-push(1), podman-manifest-remove(1), podman-rmi(1)
diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md
new file mode 100644
index 000000000..ab3287a7c
--- /dev/null
+++ b/docs/source/markdown/podman-manifest-push.1.md
@@ -0,0 +1,76 @@
+% podman-manifest-push(1)
+
+## NAME
+podman\-manifest\-push - Push a manifest list or image index to a registry
+
+## SYNOPSIS
+**podman manifest push** [options...] *listnameorindexname* *transport:details*
+
+## DESCRIPTION
+Pushes a manifest list or image index to a registry.
+
+## RETURN VALUE
+The list image's ID and the digest of the image's manifest.
+
+## OPTIONS
+
+**--all**
+
+Push the images mentioned in the manifest list or image index, in addition to
+the list or index itself.
+
+**--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)
+
+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*
+
+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*
+
+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*
+
+After copying the image, write the digest of the resulting image to the file.
+
+**--format**, **-f**=*format*
+
+Manifest list type (oci or v2s2) to use when pushing the list (default is oci).
+
+**--purge**
+
+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 the pushed images using the GPG key that matches the specified fingerprint.
+
+**--tls-verify**
+
+Require HTTPS and verify certificates when talking to container registries (defaults to true) (Not available for remote commands)
+
+## EXAMPLE
+
+```
+podman manifest push mylist:v1.11 docker://registry.example.org/mylist:v1.11
+```
+
+## SEE ALSO
+podman(1), podman-manifest(1), podman-manifest-add(1), podman-manifest-create(1), podman-manifest-inspect(1), podman-manifest-remove(1), podman-rmi(1)
diff --git a/docs/source/markdown/podman-manifest-remove.1.md b/docs/source/markdown/podman-manifest-remove.1.md
new file mode 100644
index 000000000..c13714195
--- /dev/null
+++ b/docs/source/markdown/podman-manifest-remove.1.md
@@ -0,0 +1,23 @@
+% podman-manifest-remove(1)
+
+## NAME
+podman\-manifest\-remove - Remove an image from a manifest list or image index
+
+## SYNOPSIS
+**podman manifest remove** *listnameorindexname* *transport:details*
+
+## DESCRIPTION
+Removes the image with the specified digest from the specified manifest list or image index.
+
+## RETURN VALUE
+The list image's ID and the digest of the removed image's manifest.
+
+## EXAMPLE
+
+```
+podman manifest remove mylist:v1.11 sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221
+e604eabaaee4858232761b4fef84e2316ed8f93e15eceafce845966ee3400036 :sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221
+```
+
+## SEE ALSO
+podman(1), podman-manifest(1), podman-manifest-add(1), podman-manifest-create(1), podman-manifest-inspect(1), podman-manifest-push(1), podman-rmi(1)
diff --git a/docs/source/markdown/podman-manifest.1.md b/docs/source/markdown/podman-manifest.1.md
index 70d695883..3353979ac 100644
--- a/docs/source/markdown/podman-manifest.1.md
+++ b/docs/source/markdown/podman-manifest.1.md
@@ -13,11 +13,14 @@ The `podman manifest` command provides subcommands which can be used to:
## SUBCOMMANDS
-| Command | Man Page | Description |
-| ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
-| add | [podman-manifest-add(1)](podman-manifest-add.1.md) | Add an image to a manifest list or image index. |
-| create | [podman-manifest-create(1)](podman-manifest-create.1.md) | Create a manifest list or image index. |
-| inspect | [podman-manifest-inspect(1)](podman-manifest-inspect.1.md) | Display a manifest list or image index. |
+| Command | Man Page | Description |
+| -------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| add | [podman-manifest-add(1)](podman-manifest-add.1.md) | Add an image to a manifest list or image index. |
+| annotate | [podman-manifest-annotate(1)](podman-manifest-annotate.1.md) | Add or update information about an entry in a manifest list or image index. |
+| create | [podman-manifest-create(1)](podman-manifest-create.1.md) | Create a manifest list or image index. |
+| inspect | [podman-manifest-inspect(1)](podman-manifest-inspect.1.md) | Display a manifest list or image index. |
+| push | [podman-manifest-push(1)](podman-manifest-push.1.md) | Push a manifest list or image index to a registry. |
+| remove | [podman-manifest-remove(1)](podman-manifest-remove.1.md) | Remove an image from a manifest list or image index. |
## SEE ALSO
-podman(1), podman-manifest-add(1), podman-manifest-create(1), podman-manifest-inspect(1)
+podman(1), podman-manifest-add(1), podman-manifest-annotate(1), podman-manifest-create(1), podman-manifest-inspect(1), podman-manifest-push(1), podman-manifest-remove(1)
diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md
index cbdfee4d0..45d9d9b0b 100644
--- a/docs/source/markdown/podman-network-create.1.md
+++ b/docs/source/markdown/podman-network-create.1.md
@@ -24,7 +24,7 @@ resolution.
**-d**, **--driver**
-Driver to manage the network (default "bridge"). Currently on `bridge` is supported.
+Driver to manage the network (default "bridge"). Currently only `bridge` is supported.
**--gateway**
diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md
index dfa7e4b0c..86fa2552e 100644
--- a/docs/source/markdown/podman-network-inspect.1.md
+++ b/docs/source/markdown/podman-network-inspect.1.md
@@ -9,6 +9,11 @@ podman\-network\-inspect - Displays the raw CNI network configuration for one or
## DESCRIPTION
Display the raw (JSON format) network configuration. This command is not available for rootless users.
+## OPTIONS
+**--format**, **-f**
+
+Pretty-print networks to JSON or using a Go template.
+
## EXAMPLE
Inspect the default podman network
@@ -43,6 +48,11 @@ Inspect the default podman network
]
```
+```
+# podman network inspect podman --format '{{(index .plugins 0).ipam.ranges}}'
+[[map[gateway:10.88.0.1 subnet:10.88.0.0/16]]]
+```
+
## SEE ALSO
podman(1), podman-network(1), podman-network-ls(1)
diff --git a/docs/source/markdown/podman-network-ls.1.md b/docs/source/markdown/podman-network-ls.1.md
index 46e424593..7b20cf5e0 100644
--- a/docs/source/markdown/podman-network-ls.1.md
+++ b/docs/source/markdown/podman-network-ls.1.md
@@ -12,7 +12,15 @@ Displays a list of existing podman networks. This command is not available for r
## OPTIONS
**--quiet**, **-q**
-The `quiet` option will restrict the output to only the network names
+The `quiet` option will restrict the output to only the network names.
+
+**--format**, **-f**
+
+Pretty-print networks to JSON or using a Go template.
+
+**--filter**
+
+Provide filter values (e.g. 'name=podman').
## EXAMPLE
@@ -36,6 +44,14 @@ outside
podman9
```
+Display name of network which support bridge plugin
+```
+# podman network ls --filter plugin=portmap --format {{.Name}}
+podman
+podman2
+podman9
+```
+
## SEE ALSO
podman(1), podman-network(1), podman-network-inspect(1)
diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md
index 831d28259..bc04b2b32 100644
--- a/docs/source/markdown/podman-pod-inspect.1.md
+++ b/docs/source/markdown/podman-pod-inspect.1.md
@@ -18,21 +18,50 @@ to run pods such as CRI-O, the last started pod could be from either of those me
The latest option is not supported on the remote client.
+**-f**, **--format**=*format*
+
+Change the default output format. This can be of a supported type like 'json'
+or a Go template.
+Valid placeholders for the Go template are listed below:
+
+| **Placeholder** | **Description** |
+| ----------------- | ----------------------------------------------------------------------------- |
+| .ID | Pod ID |
+| .Name | Pod name |
+| .State | Pod state |
+| .Hostname | Pod hostname |
+| .Labels | Pod labels |
+| .Created | Time when the pod was created |
+| .CreateCgroup | Whether cgroup was created |
+| .CgroupParent | Pod cgroup parent |
+| .CgroupPath | Pod cgroup path |
+| .CreateInfra | Whether infrastructure created |
+| .InfraContainerID | Pod infrastructure ID |
+| .SharedNamespaces | Pod shared namespaces |
+| .NumContainers | Number of containers in the pod |
+| .Containers | Pod containers |
+
## EXAMPLE
```
# podman pod inspect foobar
{
- "Config": {
- "id": "3513ca70583dd7ef2bac83331350f6b6c47d7b4e526c908e49d89ebf720e4693",
- "name": "foobar",
- "labels": {},
- "cgroupParent": "/libpod_parent",
- "UsePodCgroup": true,
- "created": "2018-08-08T11:15:18.823115347-05:00"
- },
- "State": {
- "CgroupPath": ""
- },
+
+ "Id": "3513ca70583dd7ef2bac83331350f6b6c47d7b4e526c908e49d89ebf720e4693",
+ "Name": "foobar",
+ "Labels": {},
+ "CgroupParent": "/libpod_parent",
+ "CreateCgroup": true,
+ "Created": "2018-08-08T11:15:18.823115347-05:00"
+ "State": "created",
+ "Hostname": "",
+ "SharedNamespaces": [
+ "uts",
+ "ipc",
+ "net"
+ ]
+ "CreateInfra": false,
+ "InfraContainerID": "1020dd70583dd7ff2bac83331350f6b6e007de0d026c908e49d89ebf891d4699"
+ "CgroupPath": ""
"Containers": [
{
"id": "d53f8bf1e9730281264aac6e6586e327429f62c704abea4b6afb5d8a2b2c9f2c",
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-run.1.md b/docs/source/markdown/podman-run.1.md
index b21eb9da9..1e05b8999 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -294,7 +294,7 @@ See [**Environment**](#environment) note below for precedence and examples.
**--env-host**=**true**|**false**
-Use host environment inside of the container. See **Environment** note below for precedence.
+Use host environment inside of the container. See **Environment** note below for precedence. (Not available for remote commands)
**--env-file**=*file*
@@ -363,7 +363,7 @@ the container should not use any proxy. Proxy environment variables specified
for the container in any other way will override the values that would have
been passed through from the host. (Other ways to specify the proxy for the
container include passing the values with the **--env** flag, or hard coding the
-proxy environment at container build time.)
+proxy environment at container build time.) (Not available for remote commands)
Defaults to **true**.
@@ -371,8 +371,7 @@ Defaults to **true**.
Tells Podman how to handle the builtin image volumes. Default is **bind**.
-- **bind**: A directory is created inside the container state directory and bind mounted into
-the container for the volumes.
+- **bind**: An anonymous named volume will be created and mounted into the container.
- **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create
content that disappears when the container is stopped.
- **ignore**: All volumes are just ignored and no action is taken.
@@ -454,8 +453,6 @@ Remember that the MAC address in an Ethernet network must be unique.
The IPv6 link-local address will be based on the device's MAC address
according to RFC4862.
-Not currently supported
-
**--memory**, **-m**=_number_[_unit_]
Memory limit. A _unit_ can be **b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes).
@@ -514,7 +511,7 @@ Current supported mount TYPEs are **bind**, **volume**, and **tmpfs**.
· dst, destination, target: mount destination spec.
- · ro, read-only: true or false (default).
+ · ro, readonly: true or false (default).
Options specific to bind:
diff --git a/docs/source/markdown/podman-search.1.md b/docs/source/markdown/podman-search.1.md
index 31de6f839..75bfeb058 100644
--- a/docs/source/markdown/podman-search.1.md
+++ b/docs/source/markdown/podman-search.1.md
@@ -59,7 +59,7 @@ Valid placeholders for the Go template are listed below:
**--limit**=*limit*
-Limit the number of results
+Limit the number of results. This value can be in the range between 1 and 100. The default number of results is 25.
Note: The results from each registry will be limited to this value.
Example if limit is 10 and two registries are being searched, the total
number of results will be 20, 10 from each (if there are at least 10 matches in each).
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..440e12062 100644
--- a/docs/tutorials/rootless_tutorial.md
+++ b/docs/tutorials/rootless_tutorial.md
@@ -58,7 +58,7 @@ The number of user namespaces that are allowed on the system is specified in the
### /etc/subuid and /etc/subgid configuration
-Rootless podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid files. The `shadows-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. These files will need someone with root privileges on the system to add or update the entries within them. The following is a summarization from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com)
+Rootless Podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid files. The `shadows-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. These files will need someone with root privileges on the system to add or update the entries within them. The following is a summarization from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com)
Update the /etc/subuid and /etc/subgid with fields for each user that will be allowed to create containers that look like the following. Note that the values for each user must be unique and without any overlap. If there is an overlap, there is a potential for a user to use another’s namespace and they could corrupt it.
@@ -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.