From e39781979ef594d02ce9df6bd8ae40e17c3089d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Rod=C3=A1k?= Date: Thu, 12 Mar 2026 11:14:34 +0100 Subject: [PATCH] Improve mac_win_client tutorial structure and links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Rodák --- docs/tutorials/mac_win_client.md | 41 ++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/tutorials/mac_win_client.md b/docs/tutorials/mac_win_client.md index 5fbe3e6e56..1c439a964d 100644 --- a/docs/tutorials/mac_win_client.md +++ b/docs/tutorials/mac_win_client.md @@ -1,12 +1,12 @@ # Podman Remote clients for macOS and Windows *** -**_NOTE:_** For running Podman on Windows, refer to the [Podman for Windows](podman-for-windows.md) guide, which uses the recommended approach of a Podman-managed Linux backend. For Mac, see the [Podman installation instructions](https://podman.io/getting-started/installation). This guide covers the advanced usage of Podman with a custom Linux VM or a remote external Linux system. +**_NOTE:_** For running Podman on Windows, refer to the [Podman for Windows](podman-for-windows.md) guide, which uses the recommended approach of a Podman-managed Linux backend. For Mac, see the [Podman installation instructions](https://podman.io/docs/installation). This guide covers advanced usage of Podman as a remote client against a custom Linux VM or an external Linux system. *** ## Introduction -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. +The core Podman runtime environment can only run on Linux operating systems. But other operating systems can use the remote client to manage containers on 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. ### Brief architecture @@ -16,7 +16,9 @@ The remote client uses a client-server model. You need Podman installed on a Lin ### Windows -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). The Windows installer file is named `podman-#.#.#-setup.exe`, where the `#` symbols represent the version number of Podman. +Install the Windows Podman client by following the [installation instructions](https://podman.io/docs/installation). + +The Windows installer file is named `podman-#.#.#-setup.exe`, where the `#` symbols represent the version number of Podman. Once you have downloaded the installer to your Windows host, simply double click the installer and Podman will be installed. The path is also set to put `podman` in the default user path. @@ -24,14 +26,29 @@ Podman must be run at a command prompt using the Windows Command Prompt (`cmd.ex ### macOS -The Mac Client is available through [Homebrew](https://brew.sh/). You can download homebrew via the instructions on their site. Install podman using: -``` -$ brew install podman +Install the macOS Podman client by following the [installation instructions](https://podman.io/docs/installation). + +## Choosing a backend + +There are two common ways to use Podman on macOS and Windows: + +1. Use a Podman-managed Linux backend (`podman machine`) (recommended for most users). +2. Use Podman as a remote client to connect to your own Linux machine or VM over SSH. + +If you use `podman machine`, initialize and start it with: + +```bash +$ podman machine init +$ podman machine start ``` -## Creating the first connection +If you want your Podman machine to start automatically when you log in, see [Running Podman on macOS startup with launchd](macos_autostart.md). -### Enable the Podman service on the server machine. +The rest of this guide focuses on option 2 (remote client to an external Linux machine). + +## Creating the first connection to an external Linux server + +### Enable the Podman service on the server machine 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 and start this socket permanently, using the following commands: ``` @@ -63,17 +80,17 @@ sudo systemctl enable --now sshd ``` #### Setting up SSH -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. +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. ``` $ ssh-keygen ``` -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. +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`. If you do not wish to use SSH keys, you will be prompted with each Podman command for your login password. ## Using the client -The first step in using the Podman remote client is to configure a connection.. +When connecting to an external Linux server, the first step is to configure a connection. You can add a connection by using the `podman system connection add` command. @@ -109,7 +126,7 @@ C:\Users\baude> podman system connection --help ## Wrap up -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. +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 is 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. ## History Originally published on [Red Hat Enable Sysadmin](https://www.redhat.com/sysadmin/podman-clients-macos-windows)