aboutsummaryrefslogtreecommitdiff
path: root/docs/source
diff options
context:
space:
mode:
authorjortkoopmans <jort@jabo-solutions.eu>2020-11-25 18:26:22 +0100
committerjortkoopmans <jort@jabo-solutions.eu>2020-11-25 18:27:31 +0100
commit5cfbe0b78e3672dd67cd028b85d816fc19d6a614 (patch)
tree375fe5a96bca7d04154daf63ac9b644ebb1adc34 /docs/source
parenta18365c908d45a8ee9348c5e32a240a7b9a4091b (diff)
downloadpodman-5cfbe0b78e3672dd67cd028b85d816fc19d6a614.tar.gz
podman-5cfbe0b78e3672dd67cd028b85d816fc19d6a614.tar.bz2
podman-5cfbe0b78e3672dd67cd028b85d816fc19d6a614.zip
squash
Signed-off-by: jortkoopmans <jort@jabo-solutions.eu>
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/Tutorials.rst2
-rw-r--r--docs/source/conf.py4
-rw-r--r--docs/source/managecontainers.rst2
-rw-r--r--docs/source/markdown/links/podman-list.11
-rw-r--r--docs/source/markdown/links/podman-ls.11
-rw-r--r--docs/source/markdown/podman-container.1.md1
-rw-r--r--docs/source/markdown/podman-create.1.md9
-rw-r--r--docs/source/markdown/podman-export.1.md2
-rw-r--r--docs/source/markdown/podman-import.1.md1
-rw-r--r--docs/source/markdown/podman-load.1.md3
-rw-r--r--docs/source/markdown/podman-ps.1.md8
-rw-r--r--docs/source/markdown/podman-run.1.md9
-rw-r--r--docs/source/markdown/podman-save.1.md4
-rw-r--r--docs/source/markdown/podman-system-service.1.md5
-rw-r--r--docs/source/markdown/podman-top.1.md2
-rw-r--r--docs/source/markdown/podman.1.md12
16 files changed, 47 insertions, 19 deletions
diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst
index 83818e3ae..e3e869d5b 100644
--- a/docs/source/Tutorials.rst
+++ b/docs/source/Tutorials.rst
@@ -2,7 +2,7 @@
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`.
+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 you are brand new to containers, take a look at our `Introduction`.
* `Basic Setup and Use of Podman <https://github.com/containers/podman/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/podman/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 368d7cc29..e3715937d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -28,11 +28,11 @@ author = "team"
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
- 'sphinx_markdown_tables',
+ "sphinx_markdown_tables",
]
source_parsers = {
- '.md': 'recommonmark.parser.CommonMarkParser',
+ ".md": "recommonmark.parser.CommonMarkParser",
}
diff --git a/docs/source/managecontainers.rst b/docs/source/managecontainers.rst
index 849fd1d25..9926f9996 100644
--- a/docs/source/managecontainers.rst
+++ b/docs/source/managecontainers.rst
@@ -39,6 +39,8 @@ Manage Containers
:doc:`prune <markdown/podman-container-prune.1>` Remove all stopped containers
+:doc:`ps <markdown/podman-ps.1>` List containers
+
:doc:`restart <markdown/podman-restart.1>` Restart one or more containers
:doc:`restore <markdown/podman-container-restore.1>` Restores one or more containers from a checkpoint
diff --git a/docs/source/markdown/links/podman-list.1 b/docs/source/markdown/links/podman-list.1
deleted file mode 100644
index f7f44c704..000000000
--- a/docs/source/markdown/links/podman-list.1
+++ /dev/null
@@ -1 +0,0 @@
-.so man1/podman-ps.1
diff --git a/docs/source/markdown/links/podman-ls.1 b/docs/source/markdown/links/podman-ls.1
deleted file mode 100644
index f7f44c704..000000000
--- a/docs/source/markdown/links/podman-ls.1
+++ /dev/null
@@ -1 +0,0 @@
-.so man1/podman-ps.1
diff --git a/docs/source/markdown/podman-container.1.md b/docs/source/markdown/podman-container.1.md
index 0a6ceea33..9da5db601 100644
--- a/docs/source/markdown/podman-container.1.md
+++ b/docs/source/markdown/podman-container.1.md
@@ -32,6 +32,7 @@ The container command allows you to manage containers
| pause | [podman-pause(1)](podman-pause.1.md) | Pause one or more containers. |
| port | [podman-port(1)](podman-port.1.md) | List port mappings for the container. |
| prune | [podman-container-prune(1)](podman-container-prune.1.md)| Remove all stopped containers from local storage. |
+| ps | [podman-ps(1)](podman-ps.1.md) | Prints out information about containers. |
| restart | [podman-restart(1)](podman-restart.1.md) | Restart one or more containers. |
| restore | [podman-container-restore(1)](podman-container-restore.1.md) | Restores one or more containers from a checkpoint. |
| rm | [podman-rm(1)](podman-rm.1.md) | Remove one or more containers. |
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 749af8a66..eb73609d4 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -18,6 +18,10 @@ any point.
The initial status of the container created with **podman create** is 'created'.
+Default settings for flags are defined in `containers.conf`. Most settings for
+remote connections use the server's containers.conf, except when documented in
+man pages.
+
## OPTIONS
#### **--add-host**=*host*
@@ -584,7 +588,7 @@ Valid _mode_ values are:
- **none**: no networking;
- **container:**_id_: reuse another container's network stack;
- **host**: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure;
-- _network-id_: connect to a user-defined network, multiple networks should be comma separated;
+- **cni-network**: connect to a user-defined network, multiple networks should be comma-separated or they can be specified with multiple uses of the **--network** option;
- **ns:**_path_: path to a network namespace to join;
- **private**: create a new namespace for the container (default)
- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
@@ -817,6 +821,7 @@ Signal to stop a container. Default is SIGTERM.
#### **--stop-timeout**=*seconds*
Timeout (in seconds) to stop a container. Default is 10.
+Remote connections use local containers.conf for defaults
#### **--subgidname**=*name*
@@ -893,10 +898,12 @@ standard input.
#### **--tz**=*timezone*
Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones.
+Remote connections use local containers.conf for defaults
#### **--umask**=*umask*
Set the umask inside the container. Defaults to `0022`.
+Remote connections use local containers.conf for defaults
#### **--uidmap**=*container_uid:host_uid:amount*
diff --git a/docs/source/markdown/podman-export.1.md b/docs/source/markdown/podman-export.1.md
index 647c25770..63989a4db 100644
--- a/docs/source/markdown/podman-export.1.md
+++ b/docs/source/markdown/podman-export.1.md
@@ -12,6 +12,8 @@ podman\-export - Export a container's filesystem contents as a tar archive
**podman export** exports the filesystem of a container and saves it as a tarball
on the local machine. **podman export** writes to STDOUT by default and can be
redirected to a file using the `--output` flag.
+The image of the container exported by **podman export** can be imported by **podman import**.
+To export image(s) with parent layers, use **podman save**.
Note: `:` is a restricted character and cannot be part of the file name.
**podman [GLOBAL OPTIONS]**
diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md
index ebedf90b4..427c67da4 100644
--- a/docs/source/markdown/podman-import.1.md
+++ b/docs/source/markdown/podman-import.1.md
@@ -14,6 +14,7 @@ and saves it as a filesystem image. Remote tarballs can be specified using a URL
Various image instructions can be configured with the **--change** flag and
a commit message can be set using the **--message** flag.
**reference**, if present, is a tag to assign to the image.
+**podman import** is used for importing from the archive generated by **podman export**, that includes the container's filesystem. To import the archive of image layers created by **podman save**, use **podman load**.
Note: `:` is a restricted character and cannot be part of the file name.
## OPTIONS
diff --git a/docs/source/markdown/podman-load.1.md b/docs/source/markdown/podman-load.1.md
index cdc99fbf2..177709a43 100644
--- a/docs/source/markdown/podman-load.1.md
+++ b/docs/source/markdown/podman-load.1.md
@@ -1,7 +1,7 @@
% podman-load(1)
## NAME
-podman\-load - Load an image from a container image archive into container storage
+podman\-load - Load image(s) from a tar archive into container storage
## SYNOPSIS
**podman load** [*options*] [*name*[:*tag*]]
@@ -11,6 +11,7 @@ podman\-load - Load an image from a container image archive into container stora
## DESCRIPTION
**podman load** loads an image from either an **oci-archive** or a **docker-archive** stored on the local machine into container storage. **podman load** reads from stdin by default or a file if the **input** option is set.
You can also specify a name for the image if the archive does not contain a named reference, of if you want an additional name for the local image.
+**podman load** is used for loading from the archive generated by **podman save**, that includes the image parent layers. To load the archive of container's filesystem created by **podman export**, use **podman import**.
The local client further supports loading an **oci-dir** or a **docker-dir** as created with **podman save** (1).
diff --git a/docs/source/markdown/podman-ps.1.md b/docs/source/markdown/podman-ps.1.md
index f542daf4c..b94964f6c 100644
--- a/docs/source/markdown/podman-ps.1.md
+++ b/docs/source/markdown/podman-ps.1.md
@@ -6,15 +6,11 @@ podman\-ps - Prints out information about containers
## SYNOPSIS
**podman ps** [*options*]
-**podman container list** [*options*]
-
-**podman container ls** [*options*]
-
**podman container ps** [*options*]
-**podman list** [*options*]
+**podman container list** [*options*]
-**podman ls** [*options*]
+**podman container ls** [*options*]
## DESCRIPTION
**podman ps** lists the running containers on the system. Use the **--all** flag to view
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 5b2cdd6a5..184c12acd 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -33,6 +33,10 @@ is located at _/run/.containerenv_.
When running from a user defined network namespace, the _/etc/netns/NSNAME/resolv.conf_
will be used if it exists, otherwise _/etc/resolv.conf_ will be used.
+Default settings are defined in `containers.conf`. Most settings for remote
+connections use the servers containers.conf, except when documented in man
+pages.
+
## OPTIONS
#### **--add-host**=_host_:_ip_
@@ -610,7 +614,7 @@ Valid _mode_ values are:
- **none**: no networking;
- **container:**_id_: reuse another container's network stack;
- **host**: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure;
-- _network-id_: connect to a user-defined network, multiple networks should be comma separated;
+- **cni-network**: connect to a user-defined network, multiple networks should be comma-separated or they can be specified with multiple uses of the **--network** option;
- **ns:**_path_: path to a network namespace to join;
- **private**: create a new namespace for the container (default)
- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
@@ -857,6 +861,7 @@ Signal to stop a container. Default is **SIGTERM**.
#### **--stop-timeout**=*seconds*
Timeout to stop a container. Default is **10**.
+Remote connections use local containers.conf for defaults
#### **--subgidname**=*name*
@@ -952,10 +957,12 @@ standard input.
#### **--tz**=*timezone*
Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones.
+Remote connections use local containers.conf for defaults
#### **--umask**=*umask*
Set the umask inside the container. Defaults to `0022`.
+Remote connections use local containers.conf for defaults
#### **--uidmap**=*container_uid*:*host_uid*:*amount*
diff --git a/docs/source/markdown/podman-save.1.md b/docs/source/markdown/podman-save.1.md
index bfb52e7f8..fb79cfd2a 100644
--- a/docs/source/markdown/podman-save.1.md
+++ b/docs/source/markdown/podman-save.1.md
@@ -1,7 +1,7 @@
% podman-save(1)
## NAME
-podman\-save - Save an image to a container archive
+podman\-save - Save image(s) to an archive
## SYNOPSIS
**podman save** [*options*] *name*[:*tag*]
@@ -12,6 +12,8 @@ podman\-save - Save an image to a container archive
**podman save** saves an image to either **docker-archive**, **oci-archive**, **oci-dir** (directory with oci manifest type), or **docker-dir** (directory with v2s2 manifest type) on the local machine,
default is **docker-archive**. **podman save** writes to STDOUT by default and can be redirected to a
file using the **output** flag. The **quiet** flag suppresses the output when set.
+**podman save** will save parent layers of the image(s) and the image(s) can be loaded using **podman load**.
+To export the containers, use the **podman export**.
Note: `:` is a restricted character and cannot be part of the file name.
**podman [GLOBAL OPTIONS]**
diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md
index 39e30ec02..1fdecfa5c 100644
--- a/docs/source/markdown/podman-system-service.1.md
+++ b/docs/source/markdown/podman-system-service.1.md
@@ -17,12 +17,14 @@ The REST API provided by **podman system service** is split into two parts: a co
Documentation for the latter is available at *https://docs.podman.io/en/latest/_static/api.html*.
Both APIs are versioned, but the server will not reject requests with an unsupported version set.
+Note: The default systemd unit files (system and user) change the log-level option to *info* from *error*. This change provides additional information on each API call.
+
## OPTIONS
#### **--time**, **-t**
The time until the session expires in _seconds_. The default is 5
-seconds. A value of `0` means no timeout and the session will not expire.
+seconds. A value of `0` means no timeout, therefore the session will not expire.
#### **--help**, **-h**
@@ -40,3 +42,4 @@ podman(1), podman-system-service(1), podman-system-connection(1)
## HISTORY
January 2020, Originally compiled by Brent Baude<bbaude@redhat.com>
+November 2020, Updated by Jhon Honce <jhonce at redhat.com>
diff --git a/docs/source/markdown/podman-top.1.md b/docs/source/markdown/podman-top.1.md
index f307f96da..cfb89567c 100644
--- a/docs/source/markdown/podman-top.1.md
+++ b/docs/source/markdown/podman-top.1.md
@@ -9,7 +9,7 @@ podman\-top - Display the running processes of a container
**podman container top** [*options*] *container* [*format-descriptors*]
## DESCRIPTION
-Display the running processes of the container. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container.
+Display the running processes of the container. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container. Please use the "h*" descriptors if you want to extract host-related information. For instance, `podman top $name hpid huser` to display the PID and user of the processes in the host context.
## OPTIONS
diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md
index 1954ca2aa..7da01d389 100644
--- a/docs/source/markdown/podman.1.md
+++ b/docs/source/markdown/podman.1.md
@@ -17,6 +17,10 @@ Podman uses Buildah(1) internally to create container images. Both tools share i
(not container) storage, hence each can use or manipulate images (but not containers)
created by the other.
+Default settings for flags are defined in `containers.conf`. Most settings for
+Remote connections use the server's containers.conf, except when documented in
+man pages.
+
**podman [GLOBAL OPTIONS]**
## GLOBAL OPTIONS
@@ -33,6 +37,7 @@ Path of the configuration directory for CNI networks. (Default: `/etc/cni/net.d
#### **--connection**, **-c**
Connection to use for remote podman (Default connection is configured in `containers.conf`)
+Remote connections use local containers.conf for default.
#### **--conmon**
Path of the conmon binary (Default path is configured in `containers.conf`)
@@ -71,6 +76,7 @@ Identity value resolution precedence:
- command line value
- environment variable `CONTAINER_SSHKEY`, if `CONTAINER_HOST` is found
- `containers.conf`
+Remote connections use local containers.conf for default.
#### **--log-level**=*level*
@@ -86,6 +92,7 @@ Path to the command binary to use for setting up a network. It is currently onl
#### **--remote**, **-r**
Access Podman service will be remote
+Remote connections use local containers.conf for default.
#### **--url**=*value*
URL to access Podman service (default from `containers.conf`, rootless `unix://run/user/$UID/podman/podman.sock` or as root `unix://run/podman/podman.sock`).
@@ -104,6 +111,7 @@ URL value resolution precedence:
- environment variable `CONTAINER_HOST`
- `containers.conf`
- `unix://run/podman/podman.sock`
+Remote connections use local containers.conf for default.
#### **--root**=*value*
@@ -223,7 +231,7 @@ the exit codes follow the `chroot` standard, see below:
| [podman-init(1)](podman-init.1.md) | Initialize one or more containers |
| [podman-inspect(1)](podman-inspect.1.md) | Display a container, image, volume, network, or pod's configuration. |
| [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. |
-| [podman-load(1)](podman-load.1.md) | Load an image from a container image archive into container storage. |
+| [podman-load(1)](podman-load.1.md) | Load image(s) from a tar archive into container storage. |
| [podman-login(1)](podman-login.1.md) | Login to a container registry. |
| [podman-logout(1)](podman-logout.1.md) | Logout of a container registry. |
| [podman-logs(1)](podman-logs.1.md) | Display the logs of one or more containers. |
@@ -241,7 +249,7 @@ the exit codes follow the `chroot` standard, see below:
| [podman-rm(1)](podman-rm.1.md) | Remove one or more containers. |
| [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. |
| [podman-run(1)](podman-run.1.md) | Run a command in a new container. |
-| [podman-save(1)](podman-save.1.md) | Save an image to a container archive. |
+| [podman-save(1)](podman-save.1.md) | Save image(s) to an archive. |
| [podman-search(1)](podman-search.1.md) | Search a registry for an image. |
| [podman-start(1)](podman-start.1.md) | Start one or more containers. |
| [podman-stats(1)](podman-stats.1.md) | Display a live stream of one or more container's resource usage statistics. |