267 lines
8.8 KiB
Groff
267 lines
8.8 KiB
Groff
'\" t
|
|
.nh
|
|
.TH podman-remote 1
|
|
.SH NAME
|
|
podman-remote \- A remote CLI for Podman: A Simple management tool for pods, containers and images.
|
|
|
|
.SH SYNOPSIS
|
|
\fBpodman-remote\fP [\fIoptions\fP] \fIcommand\fP
|
|
|
|
.SH DESCRIPTION
|
|
Podman (Pod Manager) is a fully featured container engine that is a simple daemonless tool.
|
|
Podman provides a Docker-CLI comparable command line that eases the transition from other
|
|
container engines and allows the management of pods, containers and images. Simply put: \fBalias docker=podman\fR\&.
|
|
Most Podman commands can be run as a regular user, without requiring additional
|
|
privileges.
|
|
|
|
.PP
|
|
Podman uses Buildah(1) internally to create container images. Both tools share image
|
|
(not container) storage, hence each can use or manipulate images (but not containers)
|
|
created by the other.
|
|
|
|
.PP
|
|
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 \fBcontainers.conf\fR\&.
|
|
|
|
.PP
|
|
The \fBcontainers.conf\fR file is placed under \fB$HOME/.config/containers/containers.conf\fR on Linux and Mac and \fB%APPDATA%\\containers\\containers.conf\fR on Windows.
|
|
|
|
.PP
|
|
\fBpodman [GLOBAL OPTIONS]\fP
|
|
|
|
.SH GLOBAL OPTIONS
|
|
.SS \fB--connection\fP=\fIname\fP, \fB-c\fP
|
|
Remote connection name
|
|
|
|
.PP
|
|
Overrides environment variable \fBCONTAINER_CONNECTION\fR if set.
|
|
|
|
.SS \fB--help\fP, \fB-h\fP
|
|
Print usage statement
|
|
|
|
.SS \fB--identity\fP=\fIpath\fP
|
|
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.
|
|
|
|
.PP
|
|
Identity value resolution precedence:
|
|
- command line value
|
|
- environment variable \fBCONTAINER_SSHKEY\fR, if \fBCONTAINER_HOST\fR is found
|
|
- \fBcontainers.conf\fR
|
|
|
|
.SS \fB--log-level\fP=\fIlevel\fP
|
|
Log messages above specified level: debug, info, warn, error (default), fatal or panic
|
|
|
|
.SS \fB--url\fP=\fIvalue\fP
|
|
URL to access Podman service (default from \fBcontainers.conf\fR, rootless "unix:///run/user/$UID/podman/podman.sock" or as root "unix:///run/podman/podman.sock).
|
|
.IP \(bu 2
|
|
\fBCONTAINER_HOST\fR is of the format \fB<schema>://[<user[:<password>]@]<host>[:<port>][<path>]\fR
|
|
.IP \(bu 2
|
|
\fBCONTAINER_PROXY\fR is of the format \fB<socks5|socks5h>://[<user[:<password>]@]<host>[:<port>]\fR
|
|
|
|
.PP
|
|
Details:
|
|
- \fBschema\fR is one of:
|
|
* \fBssh\fR (default): a local unix(7) socket on the named \fBhost\fR and \fBport\fR, reachable via SSH
|
|
* \fBtcp\fR: an unencrypted, unauthenticated TCP connection to the named \fBhost\fR and \fBport\fR, can work with proxy if \fBCONTAINER_PROXY\fR is set
|
|
* \fBunix\fR: a local unix(7) socket at the specified \fBpath\fR, or the default for the user
|
|
- \fBuser\fR defaults to either \fBroot\fR or the current running user (\fBssh\fR only)
|
|
- \fBpassword\fR has no default (\fBssh\fR only)
|
|
- \fBhost\fR must be provided and is either the IP or name of the machine hosting the Podman service (\fBssh\fR and \fBtcp\fR)
|
|
- \fBport\fR defaults to 22 (\fBssh\fR and \fBtcp\fR)
|
|
- \fBpath\fR defaults to either \fB/run/podman/podman.sock\fR, or \fB/run/user/$UID/podman/podman.sock\fR if running rootless (\fBunix\fR), or must be explicitly specified (\fBssh\fR)
|
|
- \fBCONTAINER_PROXY\fR: use proxy (\fBsocks5\fR or \fBsocks5h\fR) to access Podman service (\fBtcp\fR only)
|
|
|
|
.PP
|
|
URL value resolution precedence:
|
|
- command line value
|
|
- environment variable \fBCONTAINER_HOST\fR
|
|
- \fBengine.service_destinations\fR table in containers.conf, excluding the /usr/share/containers directory
|
|
- \fBunix:///run/podman/podman.sock\fR
|
|
|
|
.PP
|
|
Remote connections use local containers.conf for default.
|
|
|
|
.PP
|
|
Some example URL values in valid formats:
|
|
- unix:///run/podman/podman.sock
|
|
- unix:///run/user/$UID/podman/podman.sock
|
|
- ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock
|
|
- ssh://root@localhost:22/run/podman/podman.sock
|
|
- tcp://localhost:34451
|
|
- tcp://127.0.0.1:34451
|
|
|
|
.SS \fB--version\fP
|
|
Print the version
|
|
|
|
.SH Environment Variables
|
|
Podman can set up environment variables from env of [engine] table in containers.conf. These variables can be overridden by passing environment variables before the \fBpodman\fR commands.
|
|
|
|
.SS \fBCONTAINERS_CONF\fP
|
|
Set default locations of containers.conf file
|
|
|
|
.SS \fBCONTAINER_CONNECTION\fP
|
|
Set default \fB--connection\fR value to access Podman service.
|
|
|
|
.SS \fBCONTAINER_HOST\fP
|
|
Set default \fB--url\fR value to access Podman service.
|
|
|
|
.SS \fBCONTAINER_SSHKEY\fP
|
|
Set default \fB--identity\fR path to ssh key file value used to access Podman service.
|
|
|
|
.SH Exit Status
|
|
The exit code from \fBpodman\fR gives information about why the container
|
|
failed to run or why it exited. When \fBpodman\fR commands exit with a non-zero code,
|
|
the exit codes follow the \fBchroot\fR standard, see below:
|
|
|
|
.PP
|
|
\fB125\fP The error is with podman itself
|
|
|
|
.EX
|
|
$ podman run --foo busybox; echo $?
|
|
Error: unknown flag: --foo
|
|
125
|
|
.EE
|
|
|
|
.PP
|
|
\fB126\fP Executing a \fIcontained command\fP and the \fIcommand\fP cannot be invoked
|
|
|
|
.EX
|
|
$ podman run busybox /etc; echo $?
|
|
Error: container_linux.go:346: starting container process caused "exec: \\"/etc\\": permission denied": OCI runtime error
|
|
126
|
|
.EE
|
|
|
|
.PP
|
|
\fB127\fP Executing a \fIcontained command\fP and the \fIcommand\fP cannot be found
|
|
$ podman run busybox foo; echo $?
|
|
Error: container_linux.go:346: starting container process caused "exec: \\"foo\\": executable file not found in $PATH": OCI runtime error
|
|
127
|
|
|
|
.PP
|
|
\fBExit code\fP \fIcontained command\fP exit code
|
|
|
|
.EX
|
|
$ podman run busybox /bin/sh -c 'exit 3'; echo $?
|
|
3
|
|
.EE
|
|
|
|
.SH COMMANDS
|
|
.TS
|
|
allbox;
|
|
l l
|
|
l l .
|
|
\fBCommand\fP \fBDescription\fP
|
|
podman-attach(1) Attach to a running container.
|
|
podman-build(1) T{
|
|
Build a container image using a Dockerfile.
|
|
T}
|
|
podman-commit(1) T{
|
|
Create new image based on the changed container.
|
|
T}
|
|
podman-container(1) Manage containers.
|
|
podman-cp(1) T{
|
|
Copy files/folders between a container and the local filesystem.
|
|
T}
|
|
podman-create(1) Create a new container.
|
|
podman-diff(1) T{
|
|
Inspect changes on a container or image's filesystem.
|
|
T}
|
|
podman-events(1) Monitor Podman events
|
|
podman-export(1) T{
|
|
Export a container's filesystem contents as a tar archive.
|
|
T}
|
|
podman-generate(1) T{
|
|
Generate structured data based on containers and pods.
|
|
T}
|
|
podman-healthcheck(1) T{
|
|
Manage healthchecks for containers
|
|
T}
|
|
podman-history(1) Show the history of an image.
|
|
podman-image(1) Manage images.
|
|
podman-images(1) List images in local storage.
|
|
podman-import(1) T{
|
|
Import a tarball and save it as a filesystem image.
|
|
T}
|
|
podman-info(1) T{
|
|
Display Podman related system information.
|
|
T}
|
|
podman-init(1) Initialize a container
|
|
podman-inspect(1) T{
|
|
Display a container or image's configuration.
|
|
T}
|
|
podman-kill(1) T{
|
|
Kill the main process in one or more containers.
|
|
T}
|
|
podman-load(1) T{
|
|
Load an image from a container image archive into container storage.
|
|
T}
|
|
podman-logs(1) T{
|
|
Display the logs of a container.
|
|
T}
|
|
podman-pause(1) Pause one or more containers.
|
|
podman-pod(1) T{
|
|
Management tool for groups of containers, called pods.
|
|
T}
|
|
podman-port(1) T{
|
|
List port mappings for a container.
|
|
T}
|
|
podman-ps(1) T{
|
|
Print out information about containers.
|
|
T}
|
|
podman-pull(1) Pull an image from a registry.
|
|
podman-push(1) T{
|
|
Push an image from local storage to elsewhere.
|
|
T}
|
|
podman-restart(1) T{
|
|
Restart one or more containers.
|
|
T}
|
|
podman-rm(1) Remove one or more containers.
|
|
podman-rmi(1) T{
|
|
Remove one or more locally stored images.
|
|
T}
|
|
podman-run(1) T{
|
|
Run a command in a new container.
|
|
T}
|
|
podman-save(1) T{
|
|
Save an image to a container archive.
|
|
T}
|
|
podman-start(1) Start one or more containers.
|
|
podman-stop(1) T{
|
|
Stop one or more running containers.
|
|
T}
|
|
podman-system(1) Manage podman.
|
|
podman-tag(1) T{
|
|
Add an additional name to a local image.
|
|
T}
|
|
podman-top(1) T{
|
|
Display the running processes of a container.
|
|
T}
|
|
podman-unpause(1) T{
|
|
Unpause one or more containers.
|
|
T}
|
|
podman-version(1) T{
|
|
Display the Podman version information.
|
|
T}
|
|
podman-volume(1) Manage Volumes.
|
|
.TE
|
|
|
|
.SH FILES
|
|
\fBcontainers.conf\fP (\fB$HOME/.config/containers/containers.conf\fR)
|
|
|
|
.PP
|
|
Podman has builtin defaults for command line options. These defaults can be overridden using the containers.conf configuration files.
|
|
|
|
.PP
|
|
Users can modify defaults by creating the \fB$HOME/.config/containers/containers.conf\fR file. Podman merges its builtin defaults with the specified fields from this file, if it exists. Fields specified in the users file override the built-in defaults.
|
|
|
|
.PP
|
|
Podman uses builtin defaults if no containers.conf file is found.
|
|
|
|
.SH SEE ALSO
|
|
\fBpodman(1)\fP, \fBpodman-system-service(1)\fP, \fBcontainers.conf(5)\fP
|
|
|
|
.SS Troubleshooting
|
|
See podman-troubleshooting(7)
|
|
for solutions to common issues.
|