Skip to content

Commit 98ae84c

Browse files
ashley-cuiashley-cui
committed
[CI:DOCS] Update remote tutorials
update remote tutorial update mac/windows tutorial move varlink tutorial Signed-off-by: Ashley Cui <[email protected]>
1 parent be7778d commit 98ae84c

8 files changed

+288
-161
lines changed

Diff for: ‎README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -177,8 +177,8 @@ familiar container cli commands. For more details, see the
177177
[Container Tools Guide](https://github.com/containers/buildah/tree/master/docs/containertools).
178178

179179
## Podman Legacy API (Varlink)
180-
Podman offers a Varlink-based API for remote management of containers.
181-
However, this API has been deprecated by the REST API.
180+
Podman offers a [Varlink-based API](https://github.com/containers/podman/blob/master/docs/tutorials/varlink_remote_client.md)
181+
for remote management of containers. However, this API has been deprecated by the REST API.
182182
Varlink support is in maintenance mode, and will be removed in a future release.
183183
For more details, you can see [this blog](https://podman.io/blogs/2020/01/17/podman-new-api.html).
184184

Diff for: ‎docs/source/Tutorials.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Here are a number of useful tutorials to get you up and running with Podman. If
66

77
* `Basic Setup and Use of Podman <https://github.com/containers/podman/blob/master/docs/tutorials/podman_tutorial.md>`_: Learn how to setup Podman and perform some basic commands with the utility.
88
* `Basic Setup and Use of Podman in a Rootless environment <https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated.
9-
* `Podman Mac Client tutorial <https://github.com/containers/podman/blob/master/docs/tutorials/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.
9+
* `Podman Mac/Windows tutorial <https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md>`_: Special setup for running the Podman remote client on a Mac or Windows PC and connecting to Podman running on a Linux VM are documented.
1010
* `How to sign and distribute container images using Podman <https://github.com/containers/podman/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman.
1111
* `Podman remote-client tutorial <https://github.com/containers/podman/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client.
1212
* `How to use libpod for custom/derivative projects <https://github.com/containers/podman/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project.

Diff for: ‎docs/tutorials/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ Learn how to setup Podman and perform some basic commands with the utility.
1212

1313
The steps required to setup rootless Podman are enumerated.
1414

15-
**[Setup on OS X](mac_client.md)**
15+
**[Setup Mac/Windows](mac_win_client.md)
1616

17-
Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented.
17+
Special setup for running the Podman remote client on a Mac or Windows PC and connecting to Podman running on a Linux VM are documented.
1818

1919
**[Remote Client](remote_client.md)**
2020

Diff for: ‎docs/tutorials/mac_client.md

+2-99
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,2 @@
1-
# Podman Mac Client tutorial
2-
3-
## What is the Podman Mac Client
4-
5-
First and foremost, the Mac Client is under heavy development. We are working on getting the
6-
Mac client to be packaged and run for a native-like experience. This is the setup tutorial
7-
for the Mac client at its current stage of development and packaging.
8-
9-
The purpose of the Mac client for Podman is to allow users to run Podman on a Mac. Since Podman is a Linux
10-
container engine, The Mac client is actually a version of the [Podman-remote client](remote_client.md),
11-
edited to that the client side works on a Mac machine, and connects to a Podman "backend" on a Linux
12-
machine, virtual or physical. The goal is to have a native-like experience when working with the Mac
13-
client, so the command line interface of the remote client is exactly the same as the regular Podman
14-
commands with the exception of some flags and commands that do not apply to the Mac client.
15-
16-
## What you need
17-
18-
To use the Mac client, you will need a binary built for MacOS and a Podman "backend" on a Linux machine;
19-
hereafter referred to as the Podman node. In this context, a Podman node is a Linux system with Podman
20-
installed on it and the varlink service activated. You will also need to be able to ssh into this
21-
system as a user with privileges to the varlink socket (more on this later).
22-
23-
For best results, use the most recent version of MacOS
24-
25-
## Getting the Mac client
26-
The Mac client is available through [Homebrew](https://brew.sh/).
27-
```
28-
$ brew cask install podman
29-
```
30-
31-
## Setting up the client and Podman node connection
32-
33-
To use the Mac client, you must perform some setup on both the Mac and Podman nodes. In this case,
34-
the Mac node refers to the Mac on which Podman is being run; and the Podman node refers to where
35-
Podman and its storage reside.
36-
37-
### Connection settings
38-
Your Linux box must have ssh enabled, and you must copy your Mac's public key from `~/.sconf sh/id.pub` to
39-
`/root/.ssh/authorized_keys` on your Linux box using `ssh-copy-id` This allows for the use of SSH keys
40-
for remote access.
41-
42-
You may need to edit your `/etc/ssh/sshd_config` in your Linux machine as follows:
43-
```
44-
PermitRootLogin yes
45-
```
46-
47-
Use of SSH keys are strongly encouraged to ensure a secure login. However, if you wish to avoid ‘logging in’ every
48-
time you run a Podman command, you may edit your `/etc/ssh/sshd_config` on your Linux machine as follows:
49-
```
50-
PasswordAuthentication no
51-
PermitRootLogin without-password
52-
```
53-
54-
### Podman node setup
55-
The Podman node must be running a Linux distribution that supports Podman and must have Podman (not the Mac
56-
client) installed. You must also have root access to the node. Check if your system uses systemd:
57-
```
58-
$cat /proc/1/comm
59-
systemd
60-
```
61-
If it does, then simply start the Podman varlink socket:
62-
```
63-
$ sudo systemctl start io.podman.socket
64-
$ sudo systemctl enable io.podman.socket
65-
```
66-
67-
If your system cannot use systemd, then you can manually establish the varlink socket with the Podman
68-
command:
69-
```
70-
$ sudo podman --log-level debug varlink --timeout 0 unix://run/podman/io.podman
71-
```
72-
73-
### Required permissions
74-
For now, the Mac client requires that you be able to run a privileged Podman and have privileged ssh
75-
access to the remote system. This limitation is being worked on.
76-
77-
#### Running the remote client
78-
There are three different ways to pass connection information into the client: flags, conf file, and
79-
environment variables. All three require information on username and a remote host ip address. Most often,
80-
your username should be root and you can obtain your remote-host-ip using `ip addr`
81-
82-
To connect using flags, you can use
83-
```
84-
$ podman --remote-host remote-host-ip --username root images
85-
REPOSITORY TAG IMAGE ID CREATED SIZE
86-
quay.io/podman/stable latest 9c1e323be87f 10 days ago 414 MB
87-
localhost/test latest 4b8c27c343e1 4 weeks ago 253 MB
88-
k8s.gcr.io/pause 3.1 da86e6ba6ca1 20 months ago 747 kB
89-
```
90-
If the conf file is set up, you may simply use Podman as you would on the linux machine. Take a look at
91-
[podman-remote.conf.5.md](https://github.com/containers/podman/blob/master/docs/podman-remote.conf.5.md) on how to use the conf file:
92-
93-
```
94-
$ podman images
95-
REPOSITORY TAG IMAGE ID CREATED SIZE
96-
quay.io/podman/stable latest 9c1e323be87f 10 days ago 414 MB
97-
localhost/test latest 4b8c27c343e1 4 weeks ago 253 MB
98-
k8s.gcr.io/pause 3.1 da86e6ba6ca1 20 months ago 747 kB
99-
```
1+
# [Podman Mac Client tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md)
2+
This tutorial has moved! You can find out how to set up Podman on MacOS (as well as Windows) [here](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md)

Diff for: ‎docs/tutorials/mac_win_client.md

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Podman Remote clients for MacOS and Windows
2+
3+
## Introduction
4+
5+
The core Podman runtime environment can only run on Linux operating systems. But other operating systems can use the “remote client” to manage their containers to a Linux backend. This remote client is nearly identical to the standard Podman program. Certain functions that do not make sense for remote clients have been removed. For example, the “--latest” switch for container commands has been removed.
6+
7+
### Brief architecture
8+
9+
The remote client uses a client-server model. You need Podman installed on a Linux machine or VM that also has the SSH daemon running. On the local operating system, when you execute a Podman command, Podman connects to the server via SSH. It then connects to the Podman service by using systemd socket activation. The Podman commands are executed on the server. From the client's point of view, it seems like Podman runs locally.
10+
11+
## Obtaining and installing Podman
12+
13+
### Windows
14+
15+
Installing the Windows Podman client begins by downloading the Podman windows installer. The windows installer is built with each Podman release and is downloadable from its [release description page](https://github.com/containers/podman/releases/latest). You can also build the installer from source using the `podman.msi` Makefile endpoint.
16+
17+
Once you have downloaded the installer, simply double click the installer and Podman will be installed. The path is also set to put `podman` in the default user path.
18+
19+
Podman must be run at a command prompt using the Windows ‘cmd” or powershell applications.
20+
21+
### MacOS
22+
23+
The Mac Client is available through [Homebrew](https://brew.sh/). You can download homebrew via the instructions on their site. Install podman using:
24+
```
25+
$ brew install podman
26+
```
27+
28+
## Creating the first connection
29+
30+
### Enable the Podman service on the server machine.
31+
32+
Before performing any Podman client commands, you must enable the podman.sock SystemD service on the Linux server. In these examples, we are running Podman as a normal, unprivileged user, also known as a rootless user. By default, the rootless socket listens at `/run/user/${UID}/podman/podman.sock`. You can enable this socket, permanently using the following command:
33+
```
34+
$ systemctl --user enable podman.socket
35+
```
36+
You will need to enable linger for this user in order for the socket to work when the user is not logged in.
37+
38+
```
39+
$ sudo loginctl enable-linger $USER
40+
```
41+
42+
You can verify that the socket is listening with a simple Podman command.
43+
44+
```
45+
$ podman --remote info
46+
host:
47+
arch: amd64
48+
buildahVersion: 1.16.0-dev
49+
cgroupVersion: v2
50+
conmon:
51+
package: conmon-2.0.19-1.fc32.x86_64
52+
```
53+
54+
#### Enable sshd
55+
56+
In order for the client to communicate with the server you need to enable and start the SSH daemon on your Linux machine, if it is not currently enabled.
57+
```
58+
$ sudo systemctl enable -s sshd
59+
```
60+
61+
#### Setting up SSH
62+
Remote podman uses SSH to communicate between the client and server. The remote client works considerably smoother using SSH keys. To set up your ssh connection, you need to generate an ssh key pair from your client machine.
63+
```
64+
$ ssh-keygen
65+
```
66+
Your public key by default should be in your home directory under .ssh\id_rsa.pub. You then need to copy the contents of id_rsa.pub and append it into ~/.ssh/authorized_keys on the Linux server. On a Mac, you can automate this using ssh-copy-id.
67+
68+
If you do not wish to use SSH keys, you will be prompted with each Podman command for your login password.
69+
70+
## Using the client
71+
72+
The first step in using the Podman remote client is to configure a connection..
73+
74+
You can add a connection by using the `podman system connection add` command.
75+
76+
```
77+
C:\Users\baude> podman system connection add baude --identity c:\Users\baude\.ssh\id_rsa ssh://192.168.122.1/run/user/1000/podman/podman.sock
78+
```
79+
80+
This will add a remote connection to Podman and if it is the first connection added, it will mark the connection as the default. You can observe your connections with `podman system connection list`
81+
82+
```
83+
C:\Users\baude> podman system connection list
84+
Name Identity URI
85+
baude* id_rsa ssh://[email protected]/run/user/1000/podman/podman.sock
86+
```
87+
88+
Now we can test the connection with `podman info`.
89+
90+
```
91+
C:\Users\baude> podman info
92+
host:
93+
arch: amd64
94+
buildahVersion: 1.16.0-dev
95+
cgroupVersion: v2
96+
conmon:
97+
package: conmon-2.0.19-1.fc32.x86_64
98+
```
99+
100+
Podman has also introduced a “--connection” flag where you can use other connections you have defined. If no connection is provided, the default connection will be used.
101+
102+
```
103+
C:\Users\baude> podman system connection --help
104+
```
105+
106+
## Wrap up
107+
108+
You can use the podman remote clients to manage your containers running on a Linux server. The communication between client and server relies heavily on SSH connections and the use of SSH keys are encouraged. Once you have Podman installed on your remote client, you should set up a connection using `podman system connection add` which will then be used by subsequent Podman commands.
109+
110+
## History
111+
Originally published on [Red Hat Enable Sysadmin](https://www.redhat.com/sysadmin/podman-clients-macos-windows)

Diff for: ‎docs/tutorials/podman_tutorial.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Podman is a utility provided as part of the libpod library. It can be used to c
55
containers. The following tutorial will teach you how to set up Podman and perform some basic
66
commands with Podman.
77

8-
If you are running on a Mac, you should instead follow the [Mac tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_client.md)
8+
If you are running on a Mac or Windows PC, you should instead follow the [Mac and Windows tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md)
99
to set up the remote Podman client.
1010

1111
**NOTE**: the code samples are intended to be run as a non-root user, and use `sudo` where

0 commit comments

Comments
 (0)