1podman-remote(1)            General Commands Manual           podman-remote(1)
2
3
4

NAME

6       podman-remote  -  A remote CLI for Podman: A Simple management tool for
7       pods, containers and images.
8
9

SYNOPSIS

11       podman-remote [options] command
12
13

DESCRIPTION

15       Podman (Pod Manager) is a fully featured container  engine  that  is  a
16       simple  daemonless  tool.  Podman provides a Docker-CLI comparable com‐
17       mand line that eases the transition from other  container  engines  and
18       allows  the  management  of  pods,  containers and images.  Simply put:
19       alias docker=podman.  Most Podman commands can  be  run  as  a  regular
20       user, without requiring additional privileges.
21
22
23       Podman  uses  Buildah(1)  internally  to  create container images. Both
24       tools share image (not container) storage, hence each can use or manip‐
25       ulate images (but not containers) created by the other.
26
27
28       Podman-remote provides a local client interacting with a Podman backend
29       node through a RESTful API tunneled through a ssh connection.  In  this
30       context,  a  Podman  node is a Linux system with Podman installed on it
31       and the API service activated. Credentials  for  this  session  can  be
32       passed in using flags, environment variables, or in containers.conf.
33
34
35       The  containers.conf file is placed under $HOME/.config/containers/con‐
36       tainers.conf on Linux and Mac and  %APPDATA%\containers\containers.conf
37       on Windows.
38
39
40       podman [GLOBAL OPTIONS]
41
42

GLOBAL OPTIONS

44   --connection=name, -c
45       Remote connection name
46
47
48       Overrides environment variable CONTAINER_CONNECTION if set.
49
50
51   --help, -h
52       Print usage statement
53
54
55   --identity=path
56       Path  to  ssh  identity  file. If the identity file has been encrypted,
57       Podman prompts the user for the passphrase.  If  no  identity  file  is
58       provided  and no user is given, Podman defaults to the user running the
59       podman command.  Podman prompts for the login password  on  the  remote
60       server.
61
62
63       Identity value resolution precedence:
64        - command line value
65        - environment variable CONTAINER_SSHKEY, if CONTAINER_HOST is found
66        - containers.conf
67
68
69   --log-level=level
70       Log messages above specified level: debug, info, warn, error (default),
71       fatal or panic
72
73
74   --url=value
75       URL to access Podman service (default  from  containers.conf,  rootless
76       "unix:///run/user/$UID/podman/podman.sock" or as root "unix:///run/pod‐
77       man/podman.sock).
78
79
80CONTAINER_HOST  is  of  the  format  <schema>://[<user[:<pass‐
81                word>]@]<host>[:<port>][<path>]
82
83CONTAINER_PROXY         is         of        the        format
84                <socks5|socks5h>://[<user[:<password>]@]<host>[:<port>]
85
86
87
88       Details:
89        - schema is one of:
90          * ssh (default): a local unix(7) socket on the named host and  port,
91       reachable via SSH
92          *  tcp:  an unencrypted, unauthenticated TCP connection to the named
93       host and port, can work with proxy if CONTAINER_PROXY is set
94          * unix: a local unix(7) socket at the specified path, or the default
95       for the user
96        - user defaults to either root or the current running user (ssh only)
97        - password has no default (ssh only)
98        -  host  must  be provided and is either the IP or name of the machine
99       hosting the Podman service (ssh and tcp)
100        - port defaults to 22 (ssh and tcp)
101        -   path    defaults    to    either    /run/podman/podman.sock,    or
102       /run/user/$UID/podman/podman.sock  if  running rootless (unix), or must
103       be explicitly specified (ssh)
104        - CONTAINER_PROXY: use proxy (socks5 or socks5h) to access Podman ser‐
105       vice (tcp only)
106
107
108       URL value resolution precedence:
109        - command line value
110        - environment variable CONTAINER_HOST
111        -  engine.service_destinations table in containers.conf, excluding the
112       /usr/share/containers directory
113        - unix:///run/podman/podman.sock
114
115
116       Remote connections use local containers.conf for default.
117
118
119       Some example URL values in valid formats:
120        - unix:///run/podman/podman.sock
121        - unix:///run/user/$UID/podman/podman.sock
122        - ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock
123        - ssh://root@localhost:22/run/podman/podman.sock
124        - tcp://localhost:34451
125        - tcp://127.0.0.1:34451
126
127
128   --version
129       Print the version
130
131

Environment Variables

133       Podman can set up environment variables from env of [engine]  table  in
134       containers.conf. These variables can be overridden by passing  environ‐
135       ment variables before the podman commands.
136
137
138   CONTAINERS_CONF
139       Set default locations of containers.conf file
140
141
142   CONTAINER_CONNECTION
143       Set default --connection value to access Podman service.
144
145
146   CONTAINER_HOST
147       Set default --url value to access Podman service.
148
149
150   CONTAINER_SSHKEY
151       Set default --identity path to ssh key file value used to access Podman
152       service.
153
154

Exit Status

156       The  exit  code  from  podman gives information about why the container
157       failed to run or why it exited.  When podman commands exit with a  non-
158       zero code, the exit codes follow the chroot standard, see below:
159
160
161       125 The error is with podman itself
162
163       $ podman run --foo busybox; echo $?
164       Error: unknown flag: --foo
165       125
166
167
168
169       126 Executing a contained command and the command cannot be invoked
170
171       $ podman run busybox /etc; echo $?
172       Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
173       126
174
175
176
177       127 Executing a contained command and the command cannot be found
178           $ podman run busybox foo; echo $?
179           Error:  container_linux.go:346:  starting  container process caused
180       "exec: \"foo\": executable file not found in $PATH": OCI runtime error
181           127
182
183
184       Exit code contained command exit code
185
186       $ podman run busybox /bin/sh -c 'exit 3'; echo $?
187       3
188
189
190

COMMANDS

192       ┌──────────────────────┬────────────────────────────────┐
193Command               Description                    
194       ├──────────────────────┼────────────────────────────────┤
195podman-attach(1)      │ Attach to a running container. │
196       ├──────────────────────┼────────────────────────────────┤
197podman-build(1)       │ Build a container image  using │
198       │                      │ a Dockerfile.                  │
199       ├──────────────────────┼────────────────────────────────┤
200podman-commit(1)      │ Create  new image based on the │
201       │                      │ changed container.             │
202       ├──────────────────────┼────────────────────────────────┤
203podman-container(1)   │ Manage containers.             │
204       ├──────────────────────┼────────────────────────────────┤
205podman-cp(1)          │ Copy files/folders  between  a │
206       │                      │ container    and   the   local │
207       │                      │ filesystem.                    │
208       ├──────────────────────┼────────────────────────────────┤
209podman-create(1)      │ Create a new container.        │
210       ├──────────────────────┼────────────────────────────────┤
211podman-diff(1)        │ Inspect changes on a container │
212       │                      │ or image's filesystem.         │
213       ├──────────────────────┼────────────────────────────────┤
214podman-events(1)      │ Monitor Podman events          │
215       ├──────────────────────┼────────────────────────────────┤
216podman-export(1)      │ Export  a container's filesys‐ │
217       │                      │ tem contents as a tar archive. │
218       ├──────────────────────┼────────────────────────────────┤
219podman-generate(1)    │ Generate structured data based │
220       │                      │ on containers and pods.        │
221       ├──────────────────────┼────────────────────────────────┤
222podman-healthcheck(1) │ Manage  healthchecks  for con‐ │
223       │                      │ tainers                        │
224       ├──────────────────────┼────────────────────────────────┤
225podman-history(1)     │ Show the history of an image.  │
226       ├──────────────────────┼────────────────────────────────┤
227podman-image(1)       │ Manage images.                 │
228       ├──────────────────────┼────────────────────────────────┤
229podman-images(1)      │ List images in local storage.  │
230       ├──────────────────────┼────────────────────────────────┤
231podman-import(1)      │ Import a tarball and  save  it │
232       │                      │ as a filesystem image.         │
233       ├──────────────────────┼────────────────────────────────┤
234podman-info(1)        │ Display  Podman related system │
235       │                      │ information.                   │
236       ├──────────────────────┼────────────────────────────────┤
237podman-init(1)        │ Initialize a container         │
238       ├──────────────────────┼────────────────────────────────┤
239podman-inspect(1)     │ Display a container or image's │
240       │                      │ configuration.                 │
241       ├──────────────────────┼────────────────────────────────┤
242podman-kill(1)        │ Kill  the  main process in one │
243       │                      │ or more containers.            │
244       ├──────────────────────┼────────────────────────────────┤
245podman-load(1)        │ Load an image from a container │
246       │                      │ image  archive  into container │
247       │                      │ storage.                       │
248       ├──────────────────────┼────────────────────────────────┤
249podman-logs(1)        │ Display the  logs  of  a  con‐ │
250       │                      │ tainer.                        │
251       ├──────────────────────┼────────────────────────────────┤
252podman-pause(1)       │ Pause one or more containers.  │
253       ├──────────────────────┼────────────────────────────────┤
254podman-pod(1)         │ Management  tool for groups of │
255       │                      │ containers, called pods.       │
256       ├──────────────────────┼────────────────────────────────┤
257podman-port(1)        │ List port mappings for a  con‐ │
258       │                      │ tainer.                        │
259       ├──────────────────────┼────────────────────────────────┤
260podman-ps(1)          │ Print  out  information  about │
261       │                      │ containers.                    │
262       ├──────────────────────┼────────────────────────────────┤
263podman-pull(1)        │ Pull an image from a registry. │
264       ├──────────────────────┼────────────────────────────────┤
265podman-push(1)        │ Push an image from local stor‐ │
266       │                      │ age to elsewhere.              │
267       ├──────────────────────┼────────────────────────────────┤
268podman-restart(1)     │ Restart  one  or more contain‐ │
269       │                      │ ers.                           │
270       ├──────────────────────┼────────────────────────────────┤
271podman-rm(1)          │ Remove one or more containers. │
272       ├──────────────────────┼────────────────────────────────┤
273podman-rmi(1)         │ Remove  one  or  more  locally │
274       │                      │ stored images.                 │
275       ├──────────────────────┼────────────────────────────────┤
276podman-run(1)         │ Run  a  command  in a new con‐ │
277       │                      │ tainer.                        │
278       ├──────────────────────┼────────────────────────────────┤
279podman-save(1)        │ Save an image to  a  container │
280       │                      │ archive.                       │
281       ├──────────────────────┼────────────────────────────────┤
282podman-start(1)       │ Start one or more containers.  │
283       ├──────────────────────┼────────────────────────────────┤
284podman-stop(1)        │ Stop  one or more running con‐ │
285       │                      │ tainers.                       │
286       ├──────────────────────┼────────────────────────────────┤
287podman-system(1)      │ Manage podman.                 │
288       ├──────────────────────┼────────────────────────────────┤
289podman-tag(1)         │ Add an additional  name  to  a │
290       │                      │ local image.                   │
291       ├──────────────────────┼────────────────────────────────┤
292podman-top(1)         │ Display  the running processes │
293       │                      │ of a container.                │
294       ├──────────────────────┼────────────────────────────────┤
295podman-unpause(1)     │ Unpause one or  more  contain‐ │
296       │                      │ ers.                           │
297       ├──────────────────────┼────────────────────────────────┤
298podman-version(1)     │ Display the Podman version in‐ │
299       │                      │ formation.                     │
300       ├──────────────────────┼────────────────────────────────┤
301podman-volume(1)      │ Manage Volumes.                │
302       └──────────────────────┴────────────────────────────────┘
303

FILES

305       containers.conf ($HOME/.config/containers/containers.conf)
306
307
308       Podman has builtin defaults for command line  options.  These  defaults
309       can be overridden using the containers.conf configuration files.
310
311
312       Users can modify defaults by creating the $HOME/.config/containers/con‐
313       tainers.conf file. Podman merges its builtin defaults with  the  speci‐
314       fied fields from this file, if it exists. Fields specified in the users
315       file override the built-in defaults.
316
317
318       Podman uses builtin defaults if no containers.conf file is found.
319
320

SEE ALSO

322       podman(1), podman-system-service(1), containers.conf(5)
323
324
325
326                                                              podman-remote(1)
Impressum