diff options
Diffstat (limited to 'docs')
| -rwxr-xr-x | docs/remote-docs.sh | 62 | ||||
| -rw-r--r-- | docs/source/markdown/podman-build.1.md | 57 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 12 | ||||
| -rw-r--r-- | docs/source/markdown/podman-remote.1.md | 30 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 12 |
5 files changed, 140 insertions, 33 deletions
diff --git a/docs/remote-docs.sh b/docs/remote-docs.sh index 6d520fae6..a9fda4696 100755 --- a/docs/remote-docs.sh +++ b/docs/remote-docs.sh @@ -12,21 +12,22 @@ function usage() { echo >&2 "$0 PLATFORM TARGET SOURCES..." echo >&2 "PLATFORM: Is either linux, darwin or windows." echo >&2 "TARGET: Is the directory where files will be staged. eg, docs/build/remote/linux" - echo >&2 "SOURCES: Are the directories of source files. eg, docs/markdown" + echo >&2 "SOURCES: Are the directories of source files. eg, docs/source/markdown" } function fail() { - echo >&2 -e "$@\n" - usage + echo >&2 -e "$(dirname $0): $@\n" exit 1 } case $PLATFORM in darwin|linux) PUBLISHER=man_fn + ext=1 ;; windows) PUBLISHER=html_fn + ext=1.md ;; -help) usage @@ -54,7 +55,7 @@ function man_fn() { local dir=$(dirname $page) if [[ ! -f $page ]]; then - page=$dir/links/${file%.*}.1 + page=$dir/links/${file%.*}.$ext fi install $page $TARGET/${file%%.*}.1 } @@ -72,6 +73,22 @@ function html_fn() { pandoc --ascii --lua-filter=docs/links-to-html.lua -o $TARGET/${file%%.*}.html $markdown } +# Run 'podman help' (possibly against a subcommand, e.g. 'podman help image') +# and return a list of each first word under 'Available Commands', that is, +# the command name but not its description. +function podman_commands() { + $PODMAN help "$@" |\ + awk '/^Available Commands:/{ok=1;next}/^Flags:/{ok=0}ok { print $1 }' |\ + grep . +} + +function podman_all_commands(){ + for cmd in $(podman_commands "$@") ; do + echo $@ $cmd + podman_all_commands $@ $cmd + done +} + ## pub_pages finds and publishes the remote manual pages function pub_pages() { local source=$1 @@ -80,12 +97,29 @@ function pub_pages() { $publisher $f done - for c in "container" "image" "pod" "volume" ""; do - local cmd=${c:+-$c} - for s in $($PODMAN $c --help | sed -n '/^Available Commands:/,/^Flags:/p' | sed -e '1d;$d' -e '/^$/d' | awk '{print $1}'); do - $publisher $(echo $source/podman$cmd-$s.*) - done - done + + while IFS= read -r cmd; do + file="podman-${cmd// /-}" + + # Source dir may have man (.1) files (linux/darwin) or .1.md (windows) + # but the links subdir will always be .1 (man) files + if [ -f $source/$file.$ext -o -f $source/links/$file.1 ]; then + $publisher $(echo $source/$file.$ext) + else + # This is worth failing CI for + fail "no doc file nor link $source/$file.$ext for 'podman $cmd'" + fi + done <<< "$(podman_all_commands)" +} + +## sed syntax is different on darwin and linux +## sed --help fails on mac, meaning we have to use mac syntax +function sed_os(){ + if sed --help > /dev/null 2>&1 ; then + $(sed -i "$@") + else + $(sed -i "" "$@") + fi } ## rename renames podman-remote.ext to podman.ext, and fixes up contents to reflect change @@ -95,14 +129,14 @@ function rename (){ local ext=${remote##*.} mv $remote $TARGET/podman.$ext - $(sed -i "s/podman\\\*-remote/podman/g" $TARGET/podman.$ext) - $(sed -i "s/A\ remote\ CLI\ for\ Podman\:\ //g" $TARGET/podman.$ext) + sed_os "s/podman\\\*-remote/podman/g" $TARGET/podman.$ext + sed_os "s/A\ remote\ CLI\ for\ Podman\:\ //g" $TARGET/podman.$ext case $PLATFORM in darwin|linux) - $(sed -i "s/Podman\\\*-remote/Podman\ for\ Mac/g" $TARGET/podman.$ext) + sed_os "s/Podman\\\*-remote/Podman\ for\ Mac/g" $TARGET/podman.$ext ;; windows) - $(sed -i "s/Podman\\\*-remote/Podman\ for\ Windows/g" $TARGET/podman.$ext) + sed_os "s/Podman\\\*-remote/Podman\ for\ Windows/g" $TARGET/podman.$ext ;; esac fi diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index a07b55924..6618df1b9 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -351,6 +351,15 @@ another process. Do not use existing cached images for the container build. Build from the start with a new set of cached layers. +**--omit-timestamp** *bool-value* + +Set the create timestamp to epoch 0 to allow for deterministic builds (defaults to false). +By default, the created timestamp is changed and written into the image manifest with every commit, +causing the image's sha256 hash to be different even if the sources are exactly the same otherwise. +When --omit-timestamp is set to true, the created timestamp is always set to the epoch and therefore not +changed, allowing the image's sha256 to remain the same. All files committed to the layers of the image +will get the epoch 0 timestamp. + **--os**=*string* Set the OS to the provided value instead of the current operating system of the host. @@ -736,6 +745,52 @@ $ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz ## Files +### `.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 +Containerfile/Dockerfile + +Users can specify a series of Unix shell globals in a .dockerignore file to +identify files/directories to exclude. + +Podman supports a special wildcard string `**` which matches any number of +directories (including zero). For example, **/*.go will exclude all files that +end with .go that are found in all directories. + +Example .dockerignore file: + +``` +# exclude this content for image +*/*.c +**/output* +src +``` + +`*/*.c` +Excludes files and directories whose names ends with .c in any top level subdirectory. For example, the source file include/rootless.c. + +`**/output*` +Excludes files and directories starting with `output` from any directory. + +`src` +Excludes files named src and the directory src as well as any content in it. + +Lines starting with ! (exclamation mark) can be used to make exceptions to +exclusions. The following is an example .dockerignore file that uses this +mechanism: +``` +*.doc +!Help.doc +``` + +Exclude all doc files except Help.doc from the image. + +This functionality is compatible with the handling of .dockerignore files described here: + +https://docs.docker.com/engine/reference/builder/#dockerignore-file + **registries.conf** (`/etc/containers/registries.conf`) registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. @@ -752,6 +807,8 @@ If you are using `useradd` within your build script, you should pass the `--no-l podman(1), buildah(1), containers-registries.conf(5), crun(8), runc(8), useradd(8) ## HISTORY +Aug 2020, Additional options and .dockerignore added by Dan Walsh <dwalsh@redhat.com> + May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com> December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com> diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 976a1e681..2f59f8a09 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -89,6 +89,10 @@ The *split* option splits the current cgroup in two sub-cgroups: one for conmon Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. +**--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. + **--cidfile**=*id* Write the container ID to the file @@ -648,6 +652,14 @@ Host port does not have to be specified (e.g. `podman run -p 127.0.0.1::80`). 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 +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 +within the pod while it is in use. Containers in the pod can also communicate over localhost +by having one container bind to localhost in the pod, and another connect to that port. + **--publish-all**, **-P**=*true|false* Publish all exposed ports to random ports on the host interfaces. The default is *false*. diff --git a/docs/source/markdown/podman-remote.1.md b/docs/source/markdown/podman-remote.1.md index 23ccaf0e6..3dcfae606 100644 --- a/docs/source/markdown/podman-remote.1.md +++ b/docs/source/markdown/podman-remote.1.md @@ -17,7 +17,9 @@ 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. -Podman-remote provides a local client interacting with a Podman backend node through a RESTful API tunneled through a ssh connection. In this context, a Podman node is a Linux system with Podman installed on it and the API service activated. Credentials for this session can be passed in using flags, environment variables, or in `podman-remote.conf` +Podman-remote provides a local client interacting with a Podman backend node through a RESTful API tunneled through a ssh connection. In this context, a Podman node is a Linux system with Podman installed on it and the API service activated. Credentials for this session can be passed in using flags, environment variables, or in `containers.conf`. + +The `containers.conf` file should be placed under `$HOME/.config/containers/containers.conf` on Linux and Mac and `%APPDATA%\containers\containers.conf` on Windows. **podman [GLOBAL OPTIONS]** @@ -31,29 +33,19 @@ Remote connection name Print usage statement -**--log-level**=*level* - -Log messages above specified level: debug, info, warn, error (default), fatal or panic - -**--port**=*integer* - -Use an alternative port for the ssh connections. The default port is 22 +**--identity**=*path* -**--remote-config-path**=*path* +Path to ssh identity file. If the identity file has been encrypted, Podman prompts the user for the passphrase. +If no identity file is provided and no user is given, Podman defaults to the user running the podman command. +Podman prompts for the login password on the remote server. -Alternate path for configuration file - -**--remote-host**=*ip* - -Remote host IP - -**--syslog** +**--log-level**=*level* -Output logging information to syslog as well as the console +Log messages above specified level: debug, info, warn, error (default), fatal or panic -**--username**=*string* +**--url**=*value* -Username on the remote host (defaults to current username) +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). **--version** diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index b6c1fab17..c86090167 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -104,6 +104,10 @@ The **split** option splits the current cgroup in two sub-cgroups: one for conmo Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. +**--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. + **--cidfile**=*file* Write the container ID to *file*. @@ -662,6 +666,14 @@ 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 +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 +within the pod while it is in use. Containers in the pod can also communicate over localhost +by having one container bind to localhost in the pod, and another connect to that port. + **--publish-all**, **-P**=**true**|**false** Publish all exposed ports to random ports on the host interfaces. The default is **false**. |