diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/generate.go | 3 | ||||
| -rw-r--r-- | docs/podman-derivative-api | 4 | ||||
| -rw-r--r-- | docs/source/Tutorials.rst | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-build.1.md | 11 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 176 | ||||
| -rw-r--r-- | docs/source/markdown/podman-network-create.1.md | 4 | ||||
| -rw-r--r-- | docs/source/markdown/podman-network-ls.1.md | 18 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pull.1.md | 29 | ||||
| -rw-r--r-- | docs/source/markdown/podman-push.1.md | 12 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 195 | ||||
| -rw-r--r-- | docs/tutorials/podman-derivative-api.md | 5 | ||||
| -rw-r--r-- | docs/tutorials/varlink_remote_client.md | 89 | ||||
| -rw-r--r-- | docs/varlink/apidoc.go | 279 |
13 files changed, 296 insertions, 531 deletions
diff --git a/docs/generate.go b/docs/generate.go deleted file mode 100644 index 2adca8fc1..000000000 --- a/docs/generate.go +++ /dev/null @@ -1,3 +0,0 @@ -package docs - -//go:generate go run varlink/apidoc.go ../pkg/varlink/io.podman.varlink ../API.md diff --git a/docs/podman-derivative-api b/docs/podman-derivative-api index 1b6153df5..2e085c248 100644 --- a/docs/podman-derivative-api +++ b/docs/podman-derivative-api @@ -52,10 +52,6 @@ Potential skew between multiple libpod versions operating on the same storage ca .RE -.SH Varlink -.PP -Some code exists for this; splits the difference. Future uncertain. - .SH Making the choice .PP A good question to ask first is: Do you want users to be able to use \fB\fCpodman\fR to manipulate the containers created by your project? 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/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 4570bf3ff..c71f4fae9 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -317,6 +317,10 @@ Pass through HTTP Proxy environment variables. Write the image ID to the file. +#### **--ignorefile** + +Path to an alternative .dockerignore file. + #### **--ipc**=*how* Sets the configuration for IPC namespaces when handling `RUN` instructions. @@ -844,9 +848,10 @@ $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz ### `.dockerignore` -If the file .dockerignore exists in the context directory, `podman build` reads -its contents. Podman uses the content to exclude files and directories from -the context directory, when executing COPY and ADD directives in the +If the file .dockerignore exists in the context directory, `buildah copy` reads +its contents. Use the `--ignorefile` flag to override .dockerignore path location. +Podman uses the content to exclude files and directories from the context +directory, when executing COPY and ADD directives in the Containerfile/Dockerfile Users can specify a series of Unix shell globals in a .dockerignore file to diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 5e73804ab..843e2b22f 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -22,12 +22,54 @@ 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. +## IMAGE + + The image is specified using transport:path format. If no transport is specified, the `docker` (container registry) +transport will be used by default. For remote Podman, `docker` is the only allowed transport. + + **dir:**_path_ + An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This +is a non-standardized format, primarily useful for debugging or noninvasive container inspection. + + $ podman save --format docker-dir fedora -o /tmp/fedora + $ podman create dir:/tmp/fedora echo hello + + **docker://**_docker-reference_ (Default) + An image reference stored in a remote container image registry. Example: "quay.io/podman/stable:latest". +The reference can include a path to a specific registry; if it does not, the +registries listed in registries.conf will be queried to find a matching image. +By default, credentials from `podman login` (stored at +$XDG_RUNTIME_DIR/containers/auth.json by default) will be used to authenticate; +otherwise it falls back to using credentials in $HOME/.docker/config.json. + + $ podman create registry.fedoraproject.org/fedora:latest echo hello + + **docker-archive:**_path_[**:**_docker-reference_] +An image stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a +file, and it must not contain a digest. + + $ podman save --format docker-archive fedora -o /tmp/fedora + $ podman create docker-archive:/tmp/fedora echo hello + + **docker-daemon:**_docker-reference_ + An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest). + + $ sudo docker pull fedora + $ sudo podman create docker-daemon:docker.io/library/fedora echo hello + + **oci-archive:**_path_**:**_tag_ + An image in a directory compliant with the "Open Container Image Layout Specification" at the specified _path_ +and specified with a _tag_. + + $ podman save --format oci-archive fedora -o /tmp/fedora + $ podman create oci-archive:/tmp/fedora echo hello + ## OPTIONS #### **--add-host**=*host* Add a custom host-to-IP mapping (host:ip) -Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** +Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times. #### **--annotation**=*key=value* @@ -77,7 +119,7 @@ Set the cgroup namespace mode for the container. **ns:<PATH>**: join the namespace at the specified path. **private**: create a new cgroup namespace. -If the host uses cgroups v1, the default is set to **host**. On cgroups v2 the default is **private**. +If the host uses cgroups v1, the default is set to **host**. On cgroups v2 the default is **private**. #### **--cgroups**=*mode* @@ -87,7 +129,7 @@ Valid values are *enabled*, *disabled*, *no-conmon*, *split*, which the default The *enabled* option will create a new cgroup under the cgroup-parent. The *disabled* option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). The *no-conmon* option disables a new CGroup only for the conmon process. -The *split* option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set *--cgroup-parent* with *split*. +The *split* option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set *--cgroup-parent* with *split*. #### **--cgroup-parent**=*path* @@ -95,7 +137,7 @@ Path to cgroups under which the cgroup for the container will be created. If the #### **--cgroup-conf**=*KEY=VALUE* -When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. +When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. #### **--cidfile**=*id* @@ -248,7 +290,7 @@ Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda: #### **--disable-content-trust** This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided +registry and is not supported by Podman. This flag is a NOOP and provided solely for scripting compatibility. #### **--dns**=*dns* @@ -292,7 +334,7 @@ You need to specify multi option commands in the form of a json string. Set environment variables -This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. If an environment variable ending in __*__ is specified, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. If an environment variable with a trailing ***** is specified, then a value must be supplied. +This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. If an environment variable ending in __*__ is specified, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. If an environment variable with a trailing ***** is specified, then a value must be supplied. See [**Environment**](#environment) note below for precedence and examples. @@ -311,7 +353,7 @@ on the host system. #### **--gidmap**=*container_gid:host_gid:amount* -GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. +GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host. `--gidmap=0:30000:2000` @@ -322,8 +364,8 @@ Add additional groups to run as #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* Set or alter a healthcheck command for a container. The command is a command to be executed inside your -container that determines your container health. The command is required for other healthcheck options -to be applied. A value of `none` disables existing healthchecks. +container that determines your container health. The command is required for other healthcheck options +to be applied. A value of `none` disables existing healthchecks. Multiple options can be passed in the form of a JSON array; otherwise, the command will be interpreted as an argument to `/bin/sh -c`. @@ -334,17 +376,17 @@ Set an interval for the healthchecks (a value of `disable` results in no automat #### **--health-retries**=*retries* -The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is `3`. +The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is `3`. #### **--health-start-period**=*period* The initialization time needed for a container to bootstrap. The value can be expressed in time format like -`2m3s`. The default value is `0s` +`2m3s`. The default value is `0s` #### **--health-timeout**=*timeout* -The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the -value can be expressed in a time format such as `1m22s`. The default value is `30s`. +The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the +value can be expressed in a time format such as `1m22s`. The default value is `30s`. #### **--hostname**=*name*, **-h** @@ -359,13 +401,13 @@ Print usage statement #### **--http-proxy**=*true|false* By default proxy environment variables are passed into the container if set -for the Podman process. This can be disabled by setting the `--http-proxy` -option to `false`. The environment variables passed in include `http_proxy`, +for the Podman process. This can be disabled by setting the `--http-proxy` +option to `false`. The environment variables passed in include `http_proxy`, `https_proxy`, `ftp_proxy`, `no_proxy`, and also the upper case versions of -those. This option is only needed when the host system must use a proxy but -the container should not use any proxy. Proxy environment variables specified +those. This option is only needed when the host system must use a proxy but +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 +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.) (Not available for remote commands) @@ -411,9 +453,9 @@ The address must be within the CNI network's IP address pool (default **10.88.0. #### **--ipc**=*ipc* Default is to create a private IPC namespace (POSIX SysV IPC) for the container - 'container:<name|id>': reuses another container shared memory, semaphores and message queues - 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. - 'ns:<path>' path to an IPC namespace to join. + 'container:<name|id>': reuses another container shared memory, semaphores and message queues + 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. + 'ns:<path>' path to an IPC namespace to join. #### **--kernel-memory**=*number[unit]* @@ -439,7 +481,7 @@ Not implemented #### **--log-driver**="*k8s-file*" -Logging driver for the container. Currently available options are *k8s-file*, *journald*, and *none*, with *json-file* aliased to *k8s-file* for scripting compatibility. +Logging driver for the container. Currently available options are *k8s-file*, *journald*, and *none*, with *json-file* aliased to *k8s-file* for scripting compatibility. #### **--log-opt**=*name*=*value* @@ -496,7 +538,7 @@ as memory limit. A limit value equal to memory plus swap. Must be used with the **-m** (**--memory**) flag. The swap `LIMIT` should always be larger than **-m** -(**--memory**) value. By default, the swap `LIMIT` will be set to double +(**--memory**) value. By default, the swap `LIMIT` will be set to double the value of --memory. The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), @@ -547,7 +589,7 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). - . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. + . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. . relabel: shared, private. @@ -559,7 +601,7 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. - · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. + · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. · notmpcopyup: Disable copying files from the image to the tmpfs. @@ -588,10 +630,10 @@ 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; -- **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; +- _network-id_: connect to a user-defined network, multiple networks should be comma separated; - **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: +- **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: - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false. - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`). @@ -632,7 +674,7 @@ Override the architecture, defaults to hosts, of the image to be pulled. For exa Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. #### **--override-variant**=*VARIANT* -Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. +Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. #### **--pid**=*pid* @@ -659,7 +701,7 @@ To make a pod with more granular options, use the `podman pod create` command be #### **--pod-id-file**=*path* -Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. #### **--privileged**=*true|false* @@ -693,7 +735,7 @@ If it is not, the container port will be randomly assigned a port on the host. Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT` **Note:** if a container will be run within a pod, it is not necessary to publish the port for -the containers in the pod. The port must only be published by the pod itself. Pod network +the containers in the pod. The port must only be published by the pod itself. Pod network stacks act like the network stack on the host - you have a variety of containers in the pod, and programs in the container, all sharing a single interface and IP address, and associated ports. If one container binds to a port, no other container can use that port @@ -730,16 +772,16 @@ Suppress output information when pulling images Mount the container's root filesystem as read only. By default a container will have its root filesystem writable allowing processes -to write files anywhere. By specifying the `--read-only` flag the container will have +to write files anywhere. By specifying the `--read-only` flag the container will have its root filesystem mounted as read only prohibiting any writes. #### **--read-only-tmpfs**=*true|false* -If container is running in --read-only mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The default is *true* +If container is running in --read-only mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The default is *true* #### **--replace**=**true**|**false** -If another container with the same name already exists, replace and remove it. The default is **false**. +If another container with the same name already exists, replace and remove it. The default is **false**. #### **--restart**=*policy* @@ -777,9 +819,9 @@ of the container is assumed to be managed externally. Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. Default is **container**, which means allow the OCI runtime to proxy the socket into the -container to receive ready notification. Podman will set the MAINPID to conmon's pid. +container to receive ready notification. Podman will set the MAINPID to conmon's pid. The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container -has started. The socket is never passed to the runtime or the container. +has started. The socket is never passed to the runtime or the container. The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes, for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it. @@ -808,7 +850,7 @@ Security Options - `seccomp=unconfined` : Turn off seccomp confinement for the container - `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter -- `proc-opts=OPTIONS` : Comma separated list of options to use for the /proc mount. More details for the +- `proc-opts=OPTIONS` : Comma separated list of options to use for the /proc mount. More details for the possible mount options are specified at **proc(5)** man page. Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file. @@ -830,11 +872,11 @@ Remote connections use local containers.conf for defaults #### **--subgidname**=*name* -Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. +Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. #### **--subuidname**=*name* -Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. +Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. #### **--sysctl**=*SYSCTL* @@ -857,7 +899,7 @@ Note: if you use the --network=host option these sysctls will not be allowed. Run container in systemd mode. The default is *true*. The value *always* enforces the systemd mode is enforced without -looking at the executable name. Otherwise, if set to true and the +looking at the executable name. Otherwise, if set to true and the command you are running inside the container is systemd, /usr/sbin/init, /sbin/init or /usr/local/sbin/init. @@ -871,7 +913,7 @@ It will also set the default stop signal to SIGRTMIN+3. This allow systemd to run in a confined container without any modifications. Note: On `SELinux` systems, systemd attempts to write to the cgroup -file system. Containers writing to the cgroup file system are denied by default. +file system. Containers writing to the cgroup file system are denied by default. The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system. `setsebool -P container_manage_cgroup true` @@ -884,7 +926,7 @@ Mount a temporary filesystem (`tmpfs`) mount into a container, for example: $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image -This command mounts a `tmpfs` at `/tmp` within the container. The supported mount +This command mounts a `tmpfs` at `/tmp` within the container. The supported mount options are the same as the Linux default `mount` flags. If you do not specify any options, the systems uses the following options: `rw,noexec,nosuid,nodev`. @@ -912,7 +954,7 @@ Remote connections use local containers.conf for defaults #### **--uidmap**=*container_uid:host_uid:amount* -UID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subuidname` flags. +UID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subuidname` flags. The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host. `--uidmap=0:30000:2000` @@ -938,11 +980,11 @@ Without this argument the command will be run as root in the container. #### **--userns**=private #### **--userns**=*ns:my_namespace* -Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled. +Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled. -- `auto`: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are - **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace. +- `auto`: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are + **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace. **uidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a UID mapping to be present in the user namespace. **gidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a GID mapping to be present in the user namespace. - `container`: join the user namespace of the specified container. @@ -951,7 +993,7 @@ Set the user namespace mode for the container. It defaults to the **PODMAN_USER - `ns`: run the container in the given existing user namespace. - `private`: create a new namespace for the container (default) -This option is incompatible with --gidmap, --uidmap, --subuid and --subgid +This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. #### **--uts**=*mode* @@ -964,9 +1006,9 @@ Set the UTS namespace mode for the container. The following values are supported #### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] -Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman -bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the podman -container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume +Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman +container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume in the host to the container. If no such named volume exists, Podman will create one. The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup> @@ -984,18 +1026,21 @@ The _options_ is a comma delimited list and can be: The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume will be mounted into the container at this directory. -Volumes may specify a source as well, as either a directory on the host or the -name of a named volume. If no source is given, the volume will be created as an -anonymous named volume with a randomly generated name, and will be removed when +Volumes may specify a source as well, as either a directory on the host +or the name of a named volume. If no source is given, the volume will be created as an +anonymously named volume with a randomly generated name, and will be removed when the container is removed via the `--rm` flag or `podman rm --volumes`. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. Any source that does -not begin with a `.` or `/` will be treated as the name of a named volume. -If a volume with that name does not exist, it will be created. Volumes created -with names are not anonymous. They are not removed by the `--rm` option and the -`podman rm --volumes` command. +are resolved relative to the directory Podman is run in. If the source does not +exist, Podman will return an error. Users must pre-create the source files or +directories. + +Any source that does not begin with a `.` or `/` will be treated as the name of +a named volume. If a volume with that name does not exist, it will be created. +Volumes created with names are not anonymous, and they are not removed by the `--rm` +option and the `podman rm --volumes` command. You can specify multiple **-v** options to mount one or more volumes into a container. @@ -1026,13 +1071,13 @@ Only the current container can use a private volume. The `:O` flag tells Podman to mount the directory from the host as a temporary storage using the `overlay file system`. The container processes can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source +container storage in a separate directory. In overlay terms, the source directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. Subsequent executions of the container will see the original source directory -content, any changes from previous container executions no longer exists. +content, any changes from previous container executions no longer exist. One use case of the overlay mount is sharing the package cache from the host into the container to allow speeding up builds. @@ -1047,7 +1092,7 @@ and can read/write `container_file_t`. If you can not change the labels on a source volume, SELinux container separation must be disabled for the container to work. - The source directory mounted into the container with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended +should not be modified, it can cause unexpected failures. It is recommended that you do not modify the directory until the container finishes running. `Mounts propagation` @@ -1070,7 +1115,7 @@ slave volumes, the source mount point has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> If you want to recursively mount a volume and all of its submounts into a -container, then you can use the `rbind` option. By default the bind option is +container, then you can use the `rbind` option. By default the bind option is used, and submounts of the source directory will not be mounted into the container. @@ -1129,7 +1174,7 @@ default, Podman does not change the labels set by the OS. To change a label in the container context, you can add `z` to the volume mount. This suffix tells Podman to relabel file objects on the shared volumes. The `z` option tells Podman that two containers share the volume content. As a result, -podman labels the content with a shared content label. Shared volume labels allow +Podman labels the content with a shared content label. Shared volume labels allow all containers to read/write content. If the location of the volume from the source container overlaps with @@ -1184,7 +1229,7 @@ $ podman create --tz=US/Eastern alpine date ### Rootless Containers Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils -be installed. The shadow-utils package must include the newuidmap and newgidmap executables. +be installed. The shadow-utils package must include the newuidmap and newgidmap executables. Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released. @@ -1204,7 +1249,7 @@ Precedence order (later entries override earlier entries): - **--env-host** : Host environment of the process executing Podman is added. - **--http-proxy**: By default, several environment variables will be passed in from the host, such as **http_proxy** and **no_proxy**. See **--http-proxy** for details. - Container image : Any environment variables specified in the container image. -- **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. +- **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. - **--env** : Any environment variables specified will override previous settings. Create containers and set the environment ending with a __*__ and a ***** @@ -1228,7 +1273,8 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**. +**podman**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-kill**(1), **podman-stop**(1), +**podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**. ## HISTORY October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman <dwalsh@redhat.com> diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index cbf9d26dc..d787809cd 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -40,6 +40,10 @@ Restrict external access of this network Allocate container IP from a range. The range must be a complete subnet and in CIDR notation. The *ip-range* option must be used with a *subnet* option. +#### **--label** + +Set metadata for a network (e.g., --label mykey=value). + #### **--macvlan** Create a *Macvlan* based connection rather than a classic bridge. You must pass an interface name from the host for the diff --git a/docs/source/markdown/podman-network-ls.1.md b/docs/source/markdown/podman-network-ls.1.md index 34b40b3ae..fcba51190 100644 --- a/docs/source/markdown/podman-network-ls.1.md +++ b/docs/source/markdown/podman-network-ls.1.md @@ -14,13 +14,25 @@ Displays a list of existing podman networks. This command is not available for r The `quiet` option will restrict the output to only the network names. -#### **--format**, **-f** +#### **--format** Pretty-print networks to JSON or using a Go template. -#### **--filter** +#### **--filter**, **-f** -Provide filter values (e.g. 'name=podman'). +Filter output based on conditions given. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| ---------- | ------------------------------------------------------------------------------------- | +| name | [Name] Network name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a network | +| plugin | [Plugin] CNI plugins included in a network (e.g `bridge`,`portmap`,`firewall`,`tuning`,`dnsname`,`macvlan`) | +| driver | [Driver] Only `bridge` is supported | ## EXAMPLE diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index b28d34c64..44a7e83b6 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -27,25 +27,42 @@ Images are stored in local image storage. ## SOURCE The SOURCE is the location from which the container images are pulled. - The Image "SOURCE" uses a "transport":"details" format. + The Image "SOURCE" uses a "transport":"details" format. Only the `docker` (container registry) + transport is allowed for remote access. Multiple transports are supported: **dir:**_path_ - An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. + An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This + is a non-standardized format, primarily useful for debugging or noninvasive container inspection. - **docker://**_docker-reference_ - An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. + $ podman pull dir:/tmp/myimage + + **docker://**_docker-reference_ (Default) + An image reference stored in a remote container image registry. The reference can include a path to a + specific registry; if it does not, the registries listed in registries.conf will be queried to find a matching + image. By default, credentials from podman login (stored at $XDG_RUNTIME_DIR/containers/auth.json by default) + will be used to authenticate; if these cannot be found, we will fall back to using credentials in + $HOME/.docker/config.json. + + $ podman pull quay.io/username/myimage **docker-archive:**_path_[**:**_docker-reference_] - An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a file, and it must not contain a digest. + An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a + file, and it must not contain a digest. + + $ podman pull docker-archive:/tmp/myimage **docker-daemon:**_docker-reference_ - An image _docker-reference_ stored in the docker daemon internal storage. _docker-reference_ must contain either a tag or a digest. Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID). + An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest). + + $ sudo podman pull docker-daemon:docker.io/library/myimage:33 **oci-archive:**_path_**:**_tag_ An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. + $ podman pull oci-archive:/tmp/myimage + ## OPTIONS #### **--all-tags**, **a** diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index 87e64858c..68ea528cb 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -29,18 +29,28 @@ Images are pushed from those stored in local image storage. **dir:**_path_ An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. + $ podman push myimage dir:/tmp/myimage + **docker://**_docker-reference_ An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. + $ podman push myimage quay.io/username/myimage + **docker-archive:**_path_[**:**_docker-reference_] An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a file, and it must not contain a digest. + $ podman push myimage docker-archive:/tmp/myimage + **docker-daemon:**_docker-reference_ - An image _docker-reference_ stored in the docker daemon internal storage. _docker-reference_ must contain either a tag or a digest. Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID). + An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag. + + $ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 **oci-archive:**_path_**:**_tag_ An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. + $ podman push myimage oci-archive:/tmp/myimage + ## OPTIONS #### **--authfile**=*path* diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 897210749..83aaa33e8 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -16,7 +16,7 @@ which starts the process may define defaults related to the process that will be run in the container, the networking to expose, and more, but **podman run** gives final control to the operator or administrator who starts the container from the image. For that reason **podman run** has more options than any other -podman command. +Podman command. If the _image_ is not already loaded then **podman run** will pull the _image_, and all image dependencies, from the repository in the same way running **podman @@ -37,6 +37,48 @@ Default settings are defined in `containers.conf`. Most settings for remote connections use the servers containers.conf, except when documented in man pages. +## IMAGE + + The image is specified using transport:path format. If no transport is specified, the `docker` (container registry) +transport will be used by default. For remote Podman, `docker` is the only allowed transport. + + **dir:**_path_ + An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This +is a non-standardized format, primarily useful for debugging or noninvasive container inspection. + + $ podman save --format docker-dir fedora -o /tmp/fedora + $ podman run dir:/tmp/fedora echo hello + + **docker://**_docker-reference_ (Default) + An image reference stored in a remote container image registry. Example: "quay.io/podman/stable:latest". +The reference can include a path to a specific registry; if it does not, the +registries listed in registries.conf will be queried to find a matching image. +By default, credentials from `podman login` (stored at +$XDG_RUNTIME_DIR/containers/auth.json by default) will be used to authenticate; +otherwise it falls back to using credentials in $HOME/.docker/config.json. + + $ podman run registry.fedoraproject.org/fedora:latest echo hello + + **docker-archive:**_path_[**:**_docker-reference_] +An image stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a +file, and it must not contain a digest. + + $ podman save --format docker-archive fedora -o /tmp/fedora + $ podman run docker-archive:/tmp/fedora echo hello + + **docker-daemon:**_docker-reference_ + An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest). + + $ sudo docker pull fedora + $ sudo podman run docker-daemon:docker.io/library/fedora echo hello + + **oci-archive:**_path_**:**_tag_ + An image in a directory compliant with the "Open Container Image Layout Specification" at the specified _path_ +and specified with a _tag_. + + $ podman save --format oci-archive fedora -o /tmp/fedora + $ podman run oci-archive:/tmp/fedora echo hello + ## OPTIONS #### **--add-host**=_host_:_ip_ @@ -91,7 +133,7 @@ Set the cgroup namespace mode for the container. - **private**: create a new cgroup namespace. - **ns:**_path_: join the namespace at the specified path. -If the host uses cgroups v1, the default is set to **host**. On cgroups v2, the default is **private**. +If the host uses cgroups v1, the default is set to **host**. On cgroups v2, the default is **private**. #### **--cgroups**=**enabled**|**disabled**|**no-conmon**|**split** @@ -102,7 +144,7 @@ Default is **enabled**. The **enabled** option will create a new cgroup under the cgroup-parent. The **disabled** option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). The **no-conmon** option disables a new CGroup only for the **conmon** process. -The **split** option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **--cgroup-parent** with **split**. +The **split** option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **--cgroup-parent** with **split**. #### **--cgroup-parent**=*path* @@ -110,7 +152,7 @@ Path to cgroups under which the cgroup for the container will be created. If the #### **--cgroup-conf**=*KEY=VALUE* -When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. +When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB. #### **--cidfile**=*file* @@ -254,7 +296,7 @@ from inside a rootless container will fail. The **crun**(1) runtime offers a workaround for this by adding the option **--annotation run.oci.keep_original_groups=1**. Podman may load kernel modules required for using the specified -device. The devices that podman will load modules when necessary are: +device. The devices that Podman will load modules when necessary are: /dev/fuse. #### **--device-cgroup-rule**=rule @@ -280,7 +322,7 @@ Limit write rate (in IO operations per second) to a device (e.g. **--device-writ #### **--disable-content-trust** This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided +registry and is not supported by Podman. This flag is a NOOP and provided solely for scripting compatibility. #### **--dns**=*ipaddr* @@ -326,7 +368,7 @@ You need to specify multi option commands in the form of a json string. Set environment variables. -This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. If an environment variable ending in __*__ is specified, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. If an environment variable with a trailing ***** is specified, then a value must be supplied. +This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. If an environment variable ending in __*__ is specified, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. If an environment variable with a trailing ***** is specified, then a value must be supplied. See [**Environment**](#environment) note below for precedence and examples. @@ -356,8 +398,8 @@ Add additional groups to run as #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* Set or alter a healthcheck command for a container. The command is a command to be executed inside your -container that determines your container health. The command is required for other healthcheck options -to be applied. A value of **none** disables existing healthchecks. +container that determines your container health. The command is required for other healthcheck options +to be applied. A value of **none** disables existing healthchecks. Multiple options can be passed in the form of a JSON array; otherwise, the command will be interpreted as an argument to **/bin/sh -c**. @@ -373,12 +415,12 @@ The number of retries allowed before a healthcheck is considered to be unhealthy #### **--health-start-period**=*period* The initialization time needed for a container to bootstrap. The value can be expressed in time format like -**2m3s**. The default value is **0s**. +**2m3s**. The default value is **0s**. #### **--health-timeout**=*timeout* -The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the -value can be expressed in a time format such as **1m22s**. The default value is **30s**. +The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the +value can be expressed in a time format such as **1m22s**. The default value is **30s**. #### **--help** @@ -393,13 +435,13 @@ Sets the container host name that is available inside the container. Can only be #### **--http-proxy**=**true**|**false** By default proxy environment variables are passed into the container if set -for the Podman process. This can be disabled by setting the value to **false**. +for the Podman process. This can be disabled by setting the value to **false**. The environment variables passed in include **http_proxy**, **https_proxy**, **ftp_proxy**, **no_proxy**, and also the upper case versions of -those. This option is only needed when the host system must use a proxy but -the container should not use any proxy. Proxy environment variables specified +those. This option is only needed when the host system must use a proxy but +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 +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.) (Not available for remote commands) @@ -443,7 +485,7 @@ Set the IPC namespace mode for a container. The default is to create a private IPC namespace. - **container:**_id_: reuses another container shared memory, semaphores and message queues -- **host**: use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. +- **host**: use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. - **ns:**_path_: path to an IPC namespace to join. #### **--kernel-memory**=_number_[_unit_] @@ -522,9 +564,9 @@ as memory limit. A limit value equal to memory plus swap. A _unit_ can be **b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes). -Must be used with the **-m** (**--memory**) flag. +Must be used with the **-m** (**--memory**) flag. The argument value should always be larger than that of - **-m** (**--memory**). By default, it is set to double + **-m** (**--memory**) By default, it is set to double the value of **--memory**. Set _number_ to **-1** to enable unlimited swap. @@ -573,7 +615,7 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). - . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. + . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. . relabel: shared, private. @@ -585,7 +627,7 @@ Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. - · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. + · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. · notmpcopyup: Disable copying files from the image to the tmpfs. @@ -614,10 +656,10 @@ 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; -- **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; +- _network-id_: connect to a user-defined network, multiple networks should be comma separated; - **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: +- **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: - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false. - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`). @@ -659,7 +701,7 @@ Override the architecture, defaults to hosts, of the image to be pulled. For exa Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. #### **--override-variant**=*VARIANT* -Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. +Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. #### **--pid**=*mode* @@ -688,19 +730,21 @@ If a container is run with a pod, and the pod has an infra-container, the infra- #### **--pod-id-file**=*path* -Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +Run container in an existing pod and read the pod's ID from the specified file. +If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. #### **--preserve-fds**=*N* -Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. +Pass down to the process N additional file descriptors (in addition to 0, 1, 2). +The total FDs will be 3+N. #### **--privileged**=**true**|**false** Give extended privileges to this container. The default is **false**. By default, Podman containers are unprivileged (**=false**) and cannot, for -example, modify parts of the operating system. This is because by default a -container is only allowed limited access to devices. A "privileged" container +example, modify parts of the operating system. This is because by default a +container is only allowed limited access to devices. A "privileged" container is given the same access to devices as the user launching the container. A privileged container turns off the security features that isolate the @@ -725,7 +769,7 @@ If it is not, the container port will be randomly assigned a port on the host. Use **podman port** to see the actual mapping: **podman port $CONTAINER $CONTAINERPORT**. **Note:** if a container will be run within a pod, it is not necessary to publish the port for -the containers in the pod. The port must only be published by the pod itself. Pod network +the containers in the pod. The port must only be published by the pod itself. Pod network stacks act like the network stack on the host - you have a variety of containers in the pod, and programs in the container, all sharing a single interface and IP address, and associated ports. If one container binds to a port, no other container can use that port @@ -750,7 +794,7 @@ To find the mapping between the host ports and the exposed ports, use **podman p Pull image before running. The default is **missing**. - **missing**: attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally. -- **always**: Pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally. +- **always**: Pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally. - **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally. #### **--quiet**, **-q** @@ -762,7 +806,7 @@ Suppress output information when pulling images Mount the container's root filesystem as read only. By default a container will have its root filesystem writable allowing processes -to write files anywhere. By specifying the **--read-only** flag, the container will have +to write files anywhere. By specifying the **--read-only** flag, the container will have its root filesystem mounted as read only prohibiting any writes. #### **--read-only-tmpfs**=**true**|**false** @@ -771,7 +815,7 @@ If container is running in **--read-only** mode, then mount a read-write tmpfs o #### **--replace**=**true**|**false** -If another container with the same name already exists, replace and remove it. The default is **false**. +If another container with the same name already exists, replace and remove it. The default is **false**. #### **--restart**=*policy* @@ -817,9 +861,9 @@ Note: On **SELinux** systems, the rootfs needs the correct label, which is by de Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify. Default is **container**, which means allow the OCI runtime to proxy the socket into the -container to receive ready notification. Podman will set the MAINPID to conmon's pid. +container to receive ready notification. Podman will set the MAINPID to conmon's pid. The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container -has started. The socket is never passed to the runtime or the container. +has started. The socket is never passed to the runtime or the container. The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes, for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it. @@ -843,15 +887,15 @@ Security Options - **label=disable**: Turn off label separation for the container - **no-new-privileges**: Disable container processes from gaining additional privileges - **seccomp=unconfined**: Turn off seccomp confinement for the container -- **seccomp**=_profile.json_: Allowed syscall list seccomp JSON file to be used as a seccomp filter -- **proc-opts**=_OPTIONS_ : Comma separated list of options to use for the /proc mount. More details +- **seccomp**=_profile.json_: Allowed syscall list seccomp JSON file to be used as a seccomp filter +- **proc-opts**=_OPTIONS_ : Comma separated list of options to use for the /proc mount. More details for the possible mount options are specified at **proc(5)** man page. Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file. #### **--shm-size**=_number_[_unit_] -Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes). +Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kilobytes), **m** (megabytes), or **g** (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the default is **64m**. When _size_ is **0**, there is no limit on the amount of memory used for IPC by the container. @@ -909,7 +953,7 @@ Note: if you use the **--network=host** option, these sysctls will not be allowe Run container in systemd mode. The default is **true**. The value *always* enforces the systemd mode is enforced without -looking at the executable name. Otherwise, if set to **true** and the +looking at the executable name. Otherwise, if set to **true** and the command you are running inside the container is systemd, _/usr/sbin/init_, _/sbin/init_ or _/usr/local/sbin/init_. @@ -927,7 +971,7 @@ It will also set the default stop signal to **SIGRTMIN+3**. This allows systemd to run in a confined container without any modifications. Note that on **SELinux** systems, systemd attempts to write to the cgroup -file system. Containers writing to the cgroup file system are denied by default. +file system. Containers writing to the cgroup file system are denied by default. The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system. ``` setsebool -P container_manage_cgroup true @@ -943,7 +987,7 @@ Mount a temporary filesystem (**tmpfs**) mount into a container, for example: $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image ``` -This command mounts a **tmpfs** at _/tmp_ within the container. The supported mount +This command mounts a **tmpfs** at _/tmp_ within the container. The supported mount options are the same as the Linux default mount flags. If you do not specify any options, the systems uses the following options: **rw,noexec,nosuid,nodev**. @@ -992,10 +1036,10 @@ When a user namespace is not in use, the UID and GID used within the container a #### **--userns**=**auto**|**host**|**keep-id**|**container:**_id_|**ns:**_namespace_ -Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled unless an explicit mapping is set with they `--uidmapping` and `--gidmapping` options. +Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled unless an explicit mapping is set with they `--uidmapping` and `--gidmapping` options. -- **auto**: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are - **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace. +- **auto**: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are + **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace. **uidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a UID mapping to be present in the user namespace. **gidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a GID mapping to be present in the user namespace. - **host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). @@ -1004,7 +1048,7 @@ Set the user namespace mode for the container. It defaults to the **PODMAN_USER - **private**: create a new namespace for the container. - **container**: join the user namespace of the specified container. -This option is incompatible with **--gidmap**, **--uidmap**, **--subuid** and **--subgid**. +This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. #### **--uts**=*mode* @@ -1015,11 +1059,11 @@ Set the UTS namespace mode for the container. The following values are supported - **ns:[path]**: run the container in the given existing UTS namespace. - **container:[container]**: join the UTS namespace of the specified container. -#### **--volume**, **-v**[=[[_source-volume_|_host-dir_:]_container-dir_[:_options_]]] +#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] -Create a bind mount. If you specify _/host-dir_:_/container-dir_, Podman -bind mounts _host-dir_ in the host to _container-dir_ in the Podman -container. Similarly, _source-volume_:_/container-dir_ will mount the volume +Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman +bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman +container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume in the host to the container. If no such named volume exists, Podman will create one. @@ -1034,24 +1078,30 @@ The _options_ is a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup> * [**no**]**suid** * [**O**] -The _container-dir_ must be an absolute path. +The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume +will be mounted into the container at this directory. -Volumes may specify a source as well, as either a directory on the host or the -name of a named volume. If no source is given, the volume will be created as an -anonymous named volume with a randomly generated name, and will be removed when -the container is removed via the **--rm** flag or **podman rm --volumes**. +Volumes may specify a source as well, as either a directory on the host +or the name of a named volume. If no source is given, the volume will be created as an +anonymously named volume with a randomly generated name, and will be removed when +the container is removed via the `--rm` flag or `podman rm --volumes`. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. Any source that does -not begin with a **.** or **/** will be treated as the name of a named volume. -If a volume with that name does not exist, it will be created. Volumes created -with names are not anonymous and are not removed by **--rm** and -**podman rm --volumes**. +are resolved relative to the directory Podman is run in. If the source does not +exist, Podman will return an error. Users must pre-create the source files or +directories. + +Any source that does not begin with a `.` or `/` will be treated as the name of +a named volume. If a volume with that name does not exist, it will be created. +Volumes created with names are not anonymous, and they are not removed by the `--rm` +option and the `podman rm --volumes` command. -You can specify multiple **-v** options to mount one or more volumes into a +You can specify multiple **-v** options to mount one or more volumes into a container. + `Write Protected Volume Mounts` + You can add **:ro** or **:rw** option to mount a volume in read-only or read-write mode, respectively. By default, the volumes are mounted read-write. @@ -1074,13 +1124,13 @@ The **Z** option tells Podman to label the content with a private unshared label The `:O` flag tells Podman to mount the directory from the host as a temporary storage using the `overlay file system`. The container processes can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source +container storage in a separate directory. In overlay terms, the source directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. Subsequent executions of the container will see the original source directory -content, any changes from previous container executions no longer exists. +content, any changes from previous container executions no longer exist. One use case of the overlay mount is sharing the package cache from the host into the container to allow speeding up builds. @@ -1095,7 +1145,7 @@ and can read/write `container_file_t`. If you can not change the labels on a source volume, SELinux container separation must be disabled for the container to work. - The source directory mounted into the container with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended +should not be modified, it can cause unexpected failures. It is recommended that you do not modify the directory until the container finishes running. Only the current container can use a private volume. @@ -1120,7 +1170,7 @@ slave volumes, source mount has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> If you want to recursively mount a volume and all of its submounts into a -container, then you can use the **rbind** option. By default the bind option is +container, then you can use the **rbind** option. By default the bind option is used, and submounts of the source directory will not be mounted into the container. @@ -1179,7 +1229,7 @@ default, Podman does not change the labels set by the OS. To change a label in the container context, you can add `z` to the volume mount. This suffix tells Podman to relabel file objects on the shared volumes. The `z` option tells Podman that two containers share the volume content. As a result, -podman labels the content with a shared content label. Shared volume labels allow +Podman labels the content with a shared content label. Shared volume labels allow all containers to read/write content. If the location of the volume from the source container overlaps with @@ -1197,7 +1247,7 @@ can override the working directory by using the **-w** option. ## Exit Status The exit code from **podman run** gives information about why the container -failed to run or why it exited. When **podman run** exits with a non-zero code, +failed to run or why it exited. When **podman run** exits with a non-zero code, the exit codes follow the **chroot**(1) standard, see below: **125** The error is with Podman itself @@ -1228,12 +1278,12 @@ the exit codes follow the **chroot**(1) standard, see below: ### Running container in read-only mode During container image development, containers often need to write to the image -content. Installing packages into _/usr_, for example. In production, +content. Installing packages into _/usr_, for example. In production, applications seldom need to write to the image. Container applications write -to volumes if they need to write to file systems at all. Applications can be +to volumes if they need to write to file systems at all. Applications can be made more secure by running them in read-only mode using the **--read-only** switch. This protects the containers image from modification. Read only containers may -still need to write temporary data. The best way to handle this is to mount +still need to write temporary data. The best way to handle this is to mount tmpfs directories on _/run_ and _/tmp_. ``` @@ -1467,7 +1517,7 @@ $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello ### Configuring Storage Options from the command line Podman allows for the configuration of storage by changing the values -in the _/etc/container/storage.conf_ or by using global options. This +in the _/etc/container/storage.conf_ or by using global options. This shows how to setup and use fuse-overlayfs for a one time run of busybox using global options. @@ -1486,7 +1536,7 @@ $ podman run --tz=US/Eastern alpine date ### Rootless Containers Podman runs as a non root user on most systems. This feature requires that a new enough version of **shadow-utils** -be installed. The **shadow-utils** package must include the **newuidmap**(1) and **newgidmap**(1) executables. +be installed. The **shadow-utils** package must include the **newuidmap**(1) and **newgidmap**(1) executables. Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released. @@ -1505,7 +1555,7 @@ in the following order of precedence (later entries override earlier entries): - Container image: Any environment variables specified in the container image. - **--http-proxy**: By default, several environment variables will be passed in from the host, such as **http_proxy** and **no_proxy**. See **--http-proxy** for details. - **--env-host**: Host environment of the process executing Podman is added. -- **--env-file**: Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. +- **--env-file**: Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. - **--env**: Any environment variables specified will override previous settings. Run containers and set the environment ending with a __*__ and a __*****__: @@ -1528,7 +1578,8 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**. +**podman**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-kill**(1), **podman-stop**(1), +**podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**. ## HISTORY September 2018, updated by Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp> diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md index 8a1f40fc0..e38c2b13d 100644 --- a/docs/tutorials/podman-derivative-api.md +++ b/docs/tutorials/podman-derivative-api.md @@ -46,11 +46,6 @@ Disadvantages: - Binary size - Potential skew between multiple libpod versions operating on the same storage can cause problems -Varlink ---- - -The Varlink API is presently deprecated. We do not recommend adopting it for new projects. - Making the choice --- diff --git a/docs/tutorials/varlink_remote_client.md b/docs/tutorials/varlink_remote_client.md deleted file mode 100644 index 54c648a48..000000000 --- a/docs/tutorials/varlink_remote_client.md +++ /dev/null @@ -1,89 +0,0 @@ -# Podman varlink remote-client tutorial [DEPRECATED] - -## What is the varlink client - -This API has been deprecated by the [REST API](https://docs.podman.io/en/latest/_static/api.html). -For usage on Windows and Mac, please reference the [Podman Mac/Windows tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md) -Varlink support is in maintenance mode, and will be removed in a future release. -For more details, you can see [this blog](https://podman.io/blogs/2020/01/17/podman-new-api.html). - -The purpose of the Podman remote-client is to allow users to interact with a Podman "backend" -while on a separate client. The command line interface of the remote client is exactly the -same as the regular Podman commands with the exception of some flags being removed as they -do not apply to the remote-client. - -## What you need -To use the remote-client, you will need a binary for your client and a Podman "backend"; hereafter -referred to as the Podman node. In this context, a Podman node is a Linux system with Podman -installed on it and the varlink service activated. You will also need to be able to ssh into this -system as a user with privileges to the varlink socket (more on this later). - -## Building the remote client -At this time, the Podman remote-client is not being packaged for any distribution. It must be built from -source. To set up your build environment, see [Installation notes](https://github.com/containers/podman/blob/master/install.md) and follow the -section [Building from scratch](https://github.com/containers/podman/blob/master/install.md#building-from-scratch). Once you can successfully -build the regular Podman binary, you can now build the remote-client. -``` -$ make podman-remote -``` -Like building the regular Podman, the resulting binary will be in the *bin* directory. This is the binary -you will run on the remote node later in the instructions. - -## Setting up the remote and Podman nodes - -To use the remote-client, you must perform some setup on both the remote and Podman nodes. In this case, -the remote node refers to where the remote-client is being run; and the Podman node refers to where -Podman and its storage reside. - - -### Podman node setup - -Varlink bridge support is provided by the varlink cli command and installed using: -``` -$ sudo dnf install varlink-cli -``` - -The Podman node must have Podman (not the remote-client) installed as normal. If your system uses systemd, -then simply start the Podman varlink socket. -``` -$ sudo systemctl start io.podman.socket -``` - -If your system cannot use systemd, then you can manually establish the varlink socket with the Podman -command: -``` -$ sudo podman --log-level debug varlink --timeout 0 unix://run/podman/io.podman -``` - -### Required permissions -For now, the remote-client requires that you be able to run a privileged Podman and have privileged ssh -access to the remote system. This limitation is being worked on. - -### Remote node setup - -#### Initiate an ssh session to the Podman node -To use the remote client, an ssh connection to the Podman server must be established. - -Using the varlink bridge, an ssh tunnel must be initiated to connect to the server. Podman must then be informed of the location of the sshd server on the targeted server - -``` -$ export PODMAN_VARLINK_BRIDGE=$'ssh -T -p22 root@remotehost -- "varlink -A \'podman varlink \$VARLINK_ADDRESS\' bridge"' -$ bin/podman-remote images -REPOSITORY TAG IMAGE ID CREATED SIZE -docker.io/library/ubuntu latest 47b19964fb50 2 weeks ago 90.7 MB -docker.io/library/alpine latest caf27325b298 3 weeks ago 5.8 MB -quay.io/cevich/gcloud_centos latest 641dad61989a 5 weeks ago 489 MB -k8s.gcr.io/pause 3.1 da86e6ba6ca1 14 months ago 747 kB -``` - -The PODMAN_VARLINK_BRIDGE variable may be added to your log in settings. It does not change per connection. - -If coming from a Windows machine, the PODMAN_VARLINK_BRIDGE is formatted as: -``` -set PODMAN_VARLINK_BRIDGE=C:\Windows\System32\OpenSSH\ssh.exe -T -p22 root@remotehost -- varlink -A "podman varlink $VARLINK_ADDRESS" bridge -``` - -The arguments before the `--` are presented to ssh while the arguments after are for the varlink cli. The varlink arguments should be copied verbatim. - - `-p` is the port on the remote host for the ssh tunnel. `22` is the default. - - `root` is the currently supported user, while `remotehost` is the name or IP address of the host providing the Podman service. - - `-i` may be added to select an identity file. diff --git a/docs/varlink/apidoc.go b/docs/varlink/apidoc.go deleted file mode 100644 index 87304de15..000000000 --- a/docs/varlink/apidoc.go +++ /dev/null @@ -1,279 +0,0 @@ -package main - -import ( - "bytes" - "fmt" - "io/ioutil" - "os" - "sort" - "strings" - - "github.com/varlink/go/varlink/idl" -) - -func readFileToString(path string) (string, error) { - content, err := ioutil.ReadFile(path) - if err != nil { - return "", err - } - return string(content), nil -} - -func exit(err error) { - fmt.Println(err.Error()) - os.Exit(1) -} - -func typeToString(input *idl.Type) string { - switch input.Kind { - case idl.TypeString: - return "string" - case idl.TypeBool: - return "bool" - case idl.TypeFloat: - return "float" - case idl.TypeArray: - result := input.ElementType.Alias - if result == "" { - return fmt.Sprintf("[]%s", typeToString(input.ElementType)) - } - return result - case idl.TypeAlias: - return input.Alias - case idl.TypeMap: - return "map[string]" - case idl.TypeInt: - return "int" - case idl.TypeMaybe: - return fmt.Sprintf("?%s", typeToString(input.ElementType)) - } - return "" -} - -func typeToLink(input string) string { - switch input { - case "string": - return "https://godoc.org/builtin#string" - case "int": - return "https://godoc.org/builtin#int" - case "bool": - return "https://godoc.org/builtin#bool" - case "float": - return "https://golang.org/src/builtin/builtin.go#L58" - default: - return fmt.Sprintf("#%s", input) - } -} - -type funcArgs struct { - paramName string - paramKind string -} -type funcDescriber struct { - Name string - inputParams []funcArgs - returnParams []funcArgs - doc string -} - -type funcSorter []funcDescriber - -func (a funcSorter) Len() int { return len(a) } -func (a funcSorter) Swap(i, j int) { a[i], a[j] = a[j], a[i] } -func (a funcSorter) Less(i, j int) bool { return a[i].Name < a[j].Name } - -type typeAttrs struct { - Name string - AttrType string -} -type typeDescriber struct { - Name string - doc string - Attrs []typeAttrs -} - -type typeSorter []typeDescriber - -func (a typeSorter) Len() int { return len(a) } -func (a typeSorter) Swap(i, j int) { a[i], a[j] = a[j], a[i] } -func (a typeSorter) Less(i, j int) bool { return a[i].Name < a[j].Name } - -type err struct { - Name string - doc string -} - -type errorSorter []err - -func (a errorSorter) Len() int { return len(a) } -func (a errorSorter) Swap(i, j int) { a[i], a[j] = a[j], a[i] } -func (a errorSorter) Less(i, j int) bool { return a[i].Name < a[j].Name } - -// collects defined types in the idl -func getTypes(tidl *idl.IDL) []typeDescriber { - var types []typeDescriber - for _, x := range tidl.Aliases { - i := typeDescriber{ - Name: x.Name, - doc: x.Doc, - } - ta := []typeAttrs{} - for _, y := range x.Type.Fields { - result := typeToString(y.Type) - ta = append(ta, typeAttrs{Name: y.Name, AttrType: result}) - } - i.Attrs = ta - types = append(types, i) - } - return types -} - -// collects defined methods in the idl -func getMethods(midl *idl.IDL) []funcDescriber { - var methods []funcDescriber - for _, t := range midl.Methods { - m := funcDescriber{ - Name: t.Name, - doc: t.Doc, - } - fa := []funcArgs{} - fo := []funcArgs{} - - for _, i := range t.In.Fields { - fa = append(fa, funcArgs{paramName: i.Name, paramKind: typeToString(i.Type)}) - - } - for _, f := range t.Out.Fields { - fo = append(fo, funcArgs{paramName: f.Name, paramKind: typeToString(f.Type)}) - } - m.inputParams = fa - m.returnParams = fo - methods = append(methods, m) - } - return methods -} - -// collects defined errors in the idl -func getErrors(midl *idl.IDL) []err { - var errors []err - for _, e := range midl.Errors { - myError := err{ - Name: e.Name, - doc: e.Doc, - } - errors = append(errors, myError) - } - return errors -} - -// generates the index for the top of the markdown page -func generateIndex(methods []funcDescriber, types []typeDescriber, errors []err, b bytes.Buffer) bytes.Buffer { - // Sort the methods, types, and errors by alphabetical order - sort.Sort(funcSorter(methods)) - sort.Sort(typeSorter(types)) - sort.Sort(errorSorter(errors)) - - for _, method := range methods { - var inArgs []string - var outArgs []string - for _, inArg := range method.inputParams { - inArgs = append(inArgs, fmt.Sprintf("%s: %s", inArg.paramName, inArg.paramKind)) - - } - for _, outArg := range method.returnParams { - outArgs = append(outArgs, outArg.paramKind) - - } - b.WriteString(fmt.Sprintf("\n[func %s(%s) %s](#%s)\n", method.Name, strings.Join(inArgs, ", "), strings.Join(outArgs, ", "), method.Name)) - } - b.WriteString("\n") - for _, t := range types { - b.WriteString(fmt.Sprintf("[type %s](#%s)\n\n", t.Name, t.Name)) - } - for _, e := range errors { - b.WriteString(fmt.Sprintf("[error %s](#%s)\n\n", e.Name, e.Name)) - } - return b -} - -// performs the output for defined methods -func generateFuncDescriptions(methods []funcDescriber, b bytes.Buffer) bytes.Buffer { - for _, method := range methods { - b.WriteString(fmt.Sprintf("### <a name=\"%s\"></a>func %s\n", method.Name, method.Name)) - var inArgs []string - var outArgs []string - for _, inArg := range method.inputParams { - inArgs = append(inArgs, fmt.Sprintf("%s: [%s](%s)", inArg.paramName, inArg.paramKind, typeToLink(inArg.paramKind))) - } - for _, outArg := range method.returnParams { - outArgs = append(outArgs, fmt.Sprintf("[%s](%s)", outArg.paramKind, typeToLink(outArg.paramKind))) - } - b.WriteString(fmt.Sprintf("<div style=\"background-color: #E8E8E8; padding: 15px; margin: 10px; border-radius: 10px;\">\n\nmethod %s(%s) %s</div>", method.Name, strings.Join(inArgs, ", "), strings.Join(outArgs, ", "))) - b.WriteString("\n") - b.WriteString(method.doc) - b.WriteString("\n") - } - return b -} - -// performs the output for defined types/structs -func generateTypeDescriptions(types []typeDescriber, b bytes.Buffer) bytes.Buffer { - for _, t := range types { - b.WriteString(fmt.Sprintf("### <a name=\"%s\"></a>type %s\n", t.Name, t.Name)) - b.WriteString(fmt.Sprintf("\n%s\n", t.doc)) - for _, i := range t.Attrs { - b.WriteString(fmt.Sprintf("\n%s [%s](%s)\n", i.Name, i.AttrType, typeToLink(i.AttrType))) - } - } - return b -} - -// performs the output for defined errors -func generateErrorDescriptions(errors []err, b bytes.Buffer) bytes.Buffer { - for _, e := range errors { - b.WriteString(fmt.Sprintf("### <a name=\"%s\"></a>type %s\n", e.Name, e.Name)) - b.WriteString(fmt.Sprintf("\n%s\n", e.doc)) - } - return b -} - -func main() { - args := os.Args - if len(args) < 2 { - exit(fmt.Errorf("you must provide an input and output path")) - } - varlinkFile := args[1] - mdFile := args[2] - - varlinkInput, err := readFileToString(varlinkFile) - if err != nil { - exit(err) - } - varlinkInput = strings.TrimRight(varlinkInput, "\n") - - // Run the idl parser - midl, err := idl.New(varlinkInput) - if err != nil { - exit(err) - } - // Collect up the info from the idl - methods := getMethods(midl) - types := getTypes(midl) - errors := getErrors(midl) - - out := bytes.Buffer{} - out.WriteString(fmt.Sprintf("# %s\n", midl.Name)) - out.WriteString(fmt.Sprintf("%s\n", midl.Doc)) - out.WriteString("## Index\n") - out = generateIndex(methods, types, errors, out) - out.WriteString("## Methods\n") - out = generateFuncDescriptions(methods, out) - out.WriteString("## Types\n") - out = generateTypeDescriptions(types, out) - out.WriteString("## Errors\n") - out = generateErrorDescriptions(errors, out) - if err := ioutil.WriteFile(mdFile, out.Bytes(), 0755); err != nil { - fmt.Fprintf(os.Stderr, "Error writing file: %v\n", err) - os.Exit(1) - } -} |