summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Holzinger <paul.holzinger@web.de>2020-08-26 14:18:35 +0200
committerPaul Holzinger <paul.holzinger@web.de>2020-08-27 20:03:06 +0200
commit7dce7a64ca7fa4b2fec418509bf8a57c232e5102 (patch)
tree61cf83755bb4b781d1a8231796dd298cb5ad2140
parent7d3cadcc54cbad9a109471f586c10541544bc7db (diff)
downloadpodman-7dce7a64ca7fa4b2fec418509bf8a57c232e5102.tar.gz
podman-7dce7a64ca7fa4b2fec418509bf8a57c232e5102.tar.bz2
podman-7dce7a64ca7fa4b2fec418509bf8a57c232e5102.zip
[CI:DOCS] Update podman-remote docs
Add support for multi level subcommands. e.g. podman system connection. Update the flags and add note for containers.conf. Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
-rwxr-xr-xdocs/remote-docs.sh44
-rw-r--r--docs/source/markdown/podman-remote.1.md30
2 files changed, 45 insertions, 29 deletions
diff --git a/docs/remote-docs.sh b/docs/remote-docs.sh
index 183399b71..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,19 @@ 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
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**