summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/links-to-html.lua5
-rw-r--r--docs/podman-cp.1.md4
-rw-r--r--docs/podman-create.1.md9
-rw-r--r--docs/podman-derivative-api.md44
-rw-r--r--docs/podman-events.1.md8
-rw-r--r--docs/podman-network-rm.1.md19
-rw-r--r--docs/podman-remote.1.md4
-rw-r--r--docs/podman-remote.conf.5.md4
-rwxr-xr-xdocs/podman-remote.sh105
-rw-r--r--docs/podman-run.1.md11
-rw-r--r--docs/tutorials/README.md12
-rw-r--r--docs/tutorials/mac_client.md99
-rw-r--r--docs/tutorials/podman_tutorial.md3
-rw-r--r--docs/tutorials/remote_client.md77
14 files changed, 384 insertions, 20 deletions
diff --git a/docs/links-to-html.lua b/docs/links-to-html.lua
new file mode 100644
index 000000000..74072a9e4
--- /dev/null
+++ b/docs/links-to-html.lua
@@ -0,0 +1,5 @@
+# links-to-html.lua
+function Link(el)
+ el.target = string.gsub(el.target, "%.1.md", ".html")
+ return el
+end
diff --git a/docs/podman-cp.1.md b/docs/podman-cp.1.md
index e3d992b55..0f54b2e8b 100644
--- a/docs/podman-cp.1.md
+++ b/docs/podman-cp.1.md
@@ -29,7 +29,7 @@ Assuming a path separator of /, a first argument of **src_path** and second argu
- **dest_path** does not exist
- the file is saved to a file created at **dest_path**
- **dest_path** does not exist and ends with /
- - **dest_path** is created as a directory and the file is copied into this directory using the basename from **src_path**
+ - Error condition: the destination directory must exist.
- **dest_path** exists and is a file
- the destination is overwritten with the source file's contents
- **dest_path** exists and is a directory
@@ -65,7 +65,7 @@ Extract the tar file into the destination directory. If the destination director
**--pause**
-Pause the container while copying into it to avoid potential security issues around symlinks. Defaults to *false*.
+Pause the container while copying into it to avoid potential security issues around symlinks. Defaults to *true*. On rootless containers with cgroups V1, defaults to false.
## ALTERNATIVES
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index 996ef3863..c088f3e94 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -464,12 +464,16 @@ Tune a container's memory swappiness behavior. Accepts an integer between 0 and
Attach a filesystem mount to the container
-Current supported mount TYPES are bind, and tmpfs.
+Current supported mount TYPES are `bind`, `volume`, and `tmpfs`.
e.g.
type=bind,source=/path/on/host,destination=/path/in/container
+ type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
+
+ type=volume,source=vol1,destination=/path/in/container,ro=true
+
type=tmpfs,tmpfs-size=512M,destination=/path/in/container
Common Options:
@@ -483,8 +487,11 @@ Current supported mount TYPES are bind, and tmpfs.
Options specific to bind:
· bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
+
. bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
+ . relabel: shared, private.
+
Options specific to tmpfs:
· tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
diff --git a/docs/podman-derivative-api.md b/docs/podman-derivative-api.md
new file mode 100644
index 000000000..0342bb740
--- /dev/null
+++ b/docs/podman-derivative-api.md
@@ -0,0 +1,44 @@
+# How to use libpod for custom/derivative projects
+
+libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages.
+
+Running as a subprocess
+---
+
+Advantages:
+
+ - Many commands output JSON
+ - Works with languages other than Golang
+ - Easy to get started
+
+Disadvantages:
+
+ - Error handling is harder
+ - May be slower
+ - Can't hook into or control low-level things like how images are pulled
+
+Vendoring into a Go project
+---
+
+Advantages:
+
+ - Significant power and control
+
+Disadvantages:
+
+ - You are now on the hook for container runtime security updates (partially, `runc`/`crun` are separate)
+ - Binary size
+ - Potential skew between multiple libpod versions operating on the same storage can cause problems
+
+Varlink
+---
+
+Some code exists for this; splits the difference. Future uncertain.
+
+Making the choice
+---
+
+A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project?
+If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally
+different experience; if what you're doing with containers is quite different from those created by the `podman` CLI,
+that may drive you towards vendoring. \ No newline at end of file
diff --git a/docs/podman-events.1.md b/docs/podman-events.1.md
index a5a715098..bb1923574 100644
--- a/docs/podman-events.1.md
+++ b/docs/podman-events.1.md
@@ -11,7 +11,9 @@ podman\-events - Monitor Podman events
Monitor and print events that occur in Podman. Each event will include a timestamp,
a type, a status, name (if applicable), and image (if applicable). The default logging
mechanism is *journald*. This can be changed in libpod.conf by changing the `events_logger`
-value to `file`. Only `file` and `journald` are the accepted.
+value to `file`. Only `file` and `journald` are accepted. A `none` logger is also
+available but this logging mechanism completely disables events; nothing will be reported by
+`podman events`.
The *container* event type will report the follow statuses:
* attach
@@ -54,6 +56,10 @@ The *image* event type will report the following statuses:
* tag
* untag
+The *system* type will report the following statuses:
+ * refresh
+ * renumber
+
The *volume* type will report the following statuses:
* create
* prune
diff --git a/docs/podman-network-rm.1.md b/docs/podman-network-rm.1.md
index c95c93cd8..c71f0d8fd 100644
--- a/docs/podman-network-rm.1.md
+++ b/docs/podman-network-rm.1.md
@@ -9,13 +9,26 @@ podman\-network\-rm - Remove one or more CNI networks
## DESCRIPTION
Delete one or more Podman networks.
+## OPTIONS
+**--force**, **-f**
+
+The `force` option will remove all containers that use the named network. If the container is
+running, the container will be stopped and removed.
+
## EXAMPLE
-Delete the `podman9` network
+Delete the `cni-podman9` network
+
+```
+# podman network rm cni-podman9
+Deleted: cni-podman9
+```
+
+Delete the `fred` network and all containers associated with the network.
```
-# podman network rm podman
-Deleted: podman9
+# podman network rm -f fred
+Deleted: fred
```
## SEE ALSO
diff --git a/docs/podman-remote.1.md b/docs/podman-remote.1.md
index 84042a842..04010abaf 100644
--- a/docs/podman-remote.1.md
+++ b/docs/podman-remote.1.md
@@ -35,6 +35,10 @@ Print usage statement
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
+
**--remote-config-path**=*path*
Alternate path for configuration file
diff --git a/docs/podman-remote.conf.5.md b/docs/podman-remote.conf.5.md
index 3e1cffb02..3c8a1a801 100644
--- a/docs/podman-remote.conf.5.md
+++ b/docs/podman-remote.conf.5.md
@@ -22,6 +22,9 @@ of the user's remote connections.
Denotes whether the connection is the default connection for the user. The default connection
is used when the user does not specify a destination or connection name to `podman`.
+**port** = int
+ Use an alternative port for the ssh connections. The default port is 22.
+
## EXAMPLE
@@ -37,6 +40,7 @@ is designated as the default connection.
[connections.host2]
destination = "192.168.122.133"
username = "fedora"
+ port = 2222
```
## FILES
diff --git a/docs/podman-remote.sh b/docs/podman-remote.sh
index db3bb6d50..2f8e76d1b 100755
--- a/docs/podman-remote.sh
+++ b/docs/podman-remote.sh
@@ -1,11 +1,100 @@
-#!/bin/sh
+#!/bin/bash -e
+# Assemble remote man pages for darwin or windows from markdown files
-BREWDIR=$1
-mkdir -p $BREWDIR
-docs() {
-[ -z $1 ] || type="-$1"
-for i in $(podman-remote $1 --help | sed -n '/^Available Commands:/,/^Flags:/p'| sed -e '1d;$d' -e '/^$/d' | awk '{print $1}'); do install podman$type-$i.1 $BREWDIR 2>/dev/null || install links/podman$type-$i.1 $BREWDIR; done
+PLATFORM=$1 ## windows or darwin
+TARGET=$2 ## where to output files
+SOURCES=${@:3} ## directories to find markdown files
+
+PODMAN=${PODMAN:-bin/podman-remote} ## location overridden for testing
+
+function usage() {
+ echo >&2 "$0 PLATFORM TARGET SOURCES..."
+ echo >&2 "PLATFORM: Is either darwin or windows."
+ echo >&2 "TARGET: Is the directory where files will be staged."
+ echo >&2 "SOURCES: Are the directories to source markdown files."
+}
+
+function fail() {
+ echo >&2 -e "$@\n"
+ usage
+ exit 1
+}
+
+case $PLATFORM in
+'darwin')
+ EXT=1
+ PUBLISHER=darwin_fn
+ ;;
+'windows')
+ EXT=1.md
+ PUBLISHER=windows_fn
+ ;;
+'-help')
+ usage
+ exit 0
+ ;;
+*) fail '"darwin" and "windows" are currently the only supported platforms.' ;;
+esac
+
+if [[ -z $TARGET ]]; then
+ fail 'TARGET directory is required'
+fi
+
+if [[ -z $SOURCES ]]; then
+ fail 'At least one SOURCE directory is required'
+fi
+
+if [[ ! -x $PODMAN ]]; then
+ fail "$PODMAN does not exist"
+fi
+
+## darwin_fn copies the markdown page or link to flattened directory
+function darwin_fn() {
+ local markdown=$1
+ local file=$(basename $markdown)
+ local dir=$(dirname $markdown)
+
+ if [[ -f $dir/links/$file ]]; then
+ markdown=$dir/links/$file
+ fi
+ install $markdown $TARGET
+}
+
+## windows_fn converts the markdown page or link to HTML
+function windows_fn() {
+ local markdown=$1
+ local file=$(basename $markdown)
+ local dir=$(dirname $markdown)
+
+ if [[ ! -f $markdown ]]; then
+ local link=$(sed -e 's?.so man1/\(.*\)?\1?' <$dir/links/${file%.md})
+ markdown=$dir/$link.md
+ fi
+ pandoc --ascii --lua-filter=$dir/links-to-html.lua -o $TARGET/${file%.$EXT}.html $markdown
+}
+
+## pub_pages finds and publishes the remote manual pages
+function pub_pages() {
+ local source=$1
+ local publisher=$2
+ for f in $(ls $source/podman-remote*$EXT); do
+ $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 $source/podman$cmd-$s.$EXT
+ done
+ done
}
-docs
-for cmd in 'container image pod volume'; do docs $cmd; done
+## walk the SOURCES for markdown sources
+mkdir -p $TARGET
+for s in $SOURCES; do
+ if [[ -d $s ]]; then
+ pub_pages $s $PUBLISHER
+ else
+ echo >&2 "Warning: $s does not exist"
+ fi
+done
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index 0dbd4ea6f..d677f8262 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -475,13 +475,15 @@ Tune a container's memory swappiness behavior. Accepts an integer between 0 and
Attach a filesystem mount to the container
-Current supported mount TYPES are bind, and tmpfs.
+Current supported mount TYPES are `bind`, `volume`, and `tmpfs`.
e.g.
type=bind,source=/path/on/host,destination=/path/in/container
- type=bind,source=volume-name,destination=/path/in/container
+ type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
+
+ type=volume,source=vol1,destination=/path/in/container,ro=true
type=tmpfs,tmpfs-size=512M,destination=/path/in/container
@@ -495,9 +497,12 @@ Current supported mount TYPES are bind, and tmpfs.
Options specific to bind:
- · bind-propagation: Z, z, shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
+ · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
+
. bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
+ . relabel: shared, private.
+
Options specific to tmpfs:
· tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
index 925cfb970..2cf9613b6 100644
--- a/docs/tutorials/README.md
+++ b/docs/tutorials/README.md
@@ -4,10 +4,18 @@
## Links to a number of useful tutorials for the Podman utility.
-**[Introduction Tutorial](https://github.com/containers/libpod/tree/master/docs/tutorials/podman_tutorial.md)**
+**[Introduction Tutorial](podman_tutorial.md)**
Learn how to setup Podman and perform some basic commands with the utility.
-**[Basic Setup and Use of Podman in a Rootless environment.](https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md).
+**[Basic Setup and Use of Podman in a Rootless environment](rootless_tutorial.md)**
The steps required to setup rootless Podman are enumerated.
+
+**[Setup on OS X](mac_client.md)**
+
+Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented.
+
+**[Remote Client](remote_client.md)**
+
+A brief how-to on using the Podman remote-client.
diff --git a/docs/tutorials/mac_client.md b/docs/tutorials/mac_client.md
new file mode 100644
index 000000000..bf08e8cc1
--- /dev/null
+++ b/docs/tutorials/mac_client.md
@@ -0,0 +1,99 @@
+# Podman Mac Client tutorial
+
+## What is the Podman Mac Client
+
+First and foremost, the Mac Client is under heavy development. We are working on getting the
+Mac client to be packaged and run for a native-like experience. This is the setup tutorial
+for the Mac client at its current stage of development and packaging.
+
+The purpose of the Mac client for Podman is to allow users to run Podman on a Mac. Since Podman is a Linux
+container engine, The Mac client is actually a version of the [Podman-remote client](remote_client.md),
+edited to that the client side works on a Mac machine, and connects to a Podman "backend" on a Linux
+machine, virtual or physical. The goal is to have a native-like experience when working with the Mac
+client, so the command line interface of the remote client is exactly the same as the regular Podman
+commands with the exception of some flags and commands that do not apply to the Mac client.
+
+## What you need
+
+To use the Mac client, you will need a binary built for MacOS and a Podman "backend" on a Linux machine;
+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).
+
+For best results, use the most recent version of MacOS
+
+## Getting the Mac client
+The Mac client is available through [Homebrew](https://brew.sh/).
+```
+$ brew cask install podman
+```
+
+## Setting up the client and Podman node connection
+
+To use the Mac client, you must perform some setup on both the Mac and Podman nodes. In this case,
+the Mac node refers to the Mac on which Podman is being run; and the Podman node refers to where
+Podman and its storage reside.
+
+### Connection settings
+Your Linux box must have ssh enabled, and you must copy your Mac's public key from `~/.sconf sh/id.pub` to
+`/root/.ssh/authorized_keys` on your Linux box using `ssh-copy-id` This allows for the use of SSH keys
+for remote access.
+
+You may need to edit your `/etc/ssh/sshd_config` in your Linux machine as follows:
+```
+PermitRootLogin yes
+```
+
+Use of SSH keys are strongly encouraged to ensure a secure login. However, if you wish to avoid ‘logging in’ every
+time you run a Podman command, you may edit your `/etc/ssh/sshd_config` on your Linux machine as follows:
+```
+PasswordAuthentication no
+PermitRootLogin without-password
+```
+
+### Podman node setup
+The Podman node must be running a Linux distribution that supports Podman and must have Podman (not the Mac
+client) installed. You must also have root access to the node. Check if your system uses systemd:
+```
+$cat /proc/1/comm
+systemd
+```
+If it does, then simply start the Podman varlink socket:
+```
+$ sudo systemctl start io.podman.socket
+$ sudo systemctl enable 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 Mac 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.
+
+#### Running the remote client
+There are three different ways to pass connection information into the client: flags, conf file, and
+environment variables. All three require information on username and a remote host ip address. Most often,
+your username should be root and you can obtain your remote-host-ip using `ip addr`
+
+To connect using flags, you can use
+```
+$ podman --remote-host remote-host-ip --username root images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+quay.io/podman/stable latest 9c1e323be87f 10 days ago 414 MB
+localhost/test latest 4b8c27c343e1 4 weeks ago 253 MB
+k8s.gcr.io/pause 3.1 da86e6ba6ca1 20 months ago 747 kB
+```
+If the conf file is set up, you may simply use Podman as you would on the linux machine. Take a look at
+[podman-remote.conf.5.md](https://github.com/containers/libpod/blob/master/docs/podman-remote.conf.5.md) on how to use the conf file:
+
+```
+$ podman images
+REPOSITORY TAG IMAGE ID CREATED SIZE
+quay.io/podman/stable latest 9c1e323be87f 10 days ago 414 MB
+localhost/test latest 4b8c27c343e1 4 weeks ago 253 MB
+k8s.gcr.io/pause 3.1 da86e6ba6ca1 20 months ago 747 kB
+```
diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md
index d2f8e08fa..169cefc0e 100644
--- a/docs/tutorials/podman_tutorial.md
+++ b/docs/tutorials/podman_tutorial.md
@@ -5,6 +5,9 @@ Podman is a utility provided as part of the libpod library. It can be used to c
containers. The following tutorial will teach you how to set up Podman and perform some basic
commands with Podman.
+If you are running on a Mac, you should instead follow the [Mac tutorial](https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md)
+to set up the remote Podman client.
+
**NOTE**: the code samples are intended to be run as a non-root user, and use `sudo` where
root escalation is required.
diff --git a/docs/tutorials/remote_client.md b/docs/tutorials/remote_client.md
new file mode 100644
index 000000000..197ff3d26
--- /dev/null
+++ b/docs/tutorials/remote_client.md
@@ -0,0 +1,77 @@
+# Podman remote-client tutorial
+
+## What is the remote-client
+
+First and foremost, the remote-client is under heavy development. We are adding new
+commands and functions frequently. We also are working on a rootless implementation that
+does not require privileged users.
+
+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 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/libpod/blob/master/install.md) and follow the
+section [Building from scratch](https://github.com/containers/libpod/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
+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, we must establish an ssh connection to the Podman server. We will also use
+that session to bind the remote varlink socket locally.
+
+```
+$ ssh -L 127.0.0.1:1234:/run/podman/io.podman root@remotehost
+```
+Note here we are binding the Podman socket to a local TCP socket on port 1234.
+
+#### Running the remote client
+With the ssh session established, we can now run the remote client in a different terminal window. You
+must inform Podman where to look for the bound socket you created in the previous step using an
+environment variable.
+
+```
+$ PODMAN_VARLINK_ADDRESS="tcp:127.0.0.1:1234" 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
+```
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-18 01:17:40 +0000