opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2026-03-13 08:01:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #28247 from Honny1/lunchd-podman-machine

Browse Source 
Add tutorial for running podman machine on macOS startup
This commit is contained in:
Matt Heon
2026-03-12 13:26:13 -04:00
committed by GitHub
parent faa9b02d8f e39781979e
commit ec78353a63
3 changed files with 188 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/tutorials/README.md
View File

@@ -16,6 +16,10 @@ The steps required to set up rootless Podman are enumerated.
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.
**[Running Podman on macOS startup with launchd](macos_autostart.md)**
How to automatically start a Podman machine at login on macOS using launchd LaunchAgents.
**[Remote Client](remote_client.md)**
A brief how-to on using the Podman remote-client.

41
docs/tutorials/mac_win_client.md
View File

@@ -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)

155
docs/tutorials/macos_autostart.md Normal file
View File

@@ -0,0 +1,155 @@
# Running Podman on macOS startup with launchd
On macOS, Podman requires a virtual machine to run containers. By default, you must manually start this VM with `podman machine start` each time you log in. This tutorial shows how to use macOS's `launchd` service manager to automatically start your Podman machine at login.
## Prerequisites
- macOS with Podman installed (see the [installation instructions](https://podman.io/docs/installation))
- A fully working Podman machine: initialized (`podman machine init`) and able to start manually (`podman machine start`)
## Overview
macOS uses `launchd` to manage services. User-level services are defined by property list (plist) files placed in `~/Library/LaunchAgents/`. These `LaunchAgents` run when you log in and stop when you log out.
## Step 1: Find your Podman binary path
launchd does not inherit your shell's `PATH`, so the plist must use the full path to the `podman` binary. Determine it with:
```
$ which podman
/opt/podman/bin/podman
```
If you installed Podman with Homebrew, the path is typically `/opt/homebrew/bin/podman`. If you installed Podman using the installer from the [release page](https://github.com/containers/podman/releases), the path is `/opt/podman/bin/podman`.
## Step 2: Create the LaunchAgent plist
Create the file `~/Library/LaunchAgents/com.podman.machine.default.plist` with the following content. Replace `/opt/podman/bin/podman` with the path from Step 1 if it differs on your system.
> **Note:** Running `podman machine start` without specifying a machine name will automatically start the default machine. The example below explicitly uses `podman-machine-default`; replace it with the name of your machine if you are not using the default.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.podman.machine.default</string>
<key>ProgramArguments</key>
<array>
<string>/opt/podman/bin/podman</string>
<string>machine</string>
<string>start</string>
<string>podman-machine-default</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>AbandonProcessGroup</key>
<true/>
</dict>
</plist>
```
### Explanation of the plist keys
| Key | Purpose |
|-----|---------|
| `Label` | A unique identifier for the service. |
| `ProgramArguments` | The command and arguments to run. Each argument is a separate array element. |
| `RunAtLoad` | Start the command as soon as the agent is loaded (at login). |
| `AbandonProcessGroup` | When the main process (`podman machine start`) exits, launchd leaves its child processes (e.g., the VM and networking) running instead of killing them. **Required** for this use case because `podman machine start` is a one-shot command that starts the VM and then exits. Do **not** use `KeepAlive` here: that would make launchd restart the process after it exits, find the machine already running, and create a restart loop. |
## Step 3: Load the LaunchAgent
Load the agent so it takes effect without logging out and back in. The recommended commands (since macOS 10.10) are `bootstrap` and `bootout`; the older `load` and `unload` subcommands are deprecated.
```
$ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.podman.machine.default.plist
```
The Podman machine should start. You can verify with:
```
$ podman machine list
NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE
podman-machine-default applehv 2 days ago Currently running 4 2GiB 100GiB
```
## Managing the LaunchAgent
### Stop the machine from auto-starting
To prevent the Podman machine from starting at login, boot out the agent:
```
$ launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.podman.machine.default.plist
```
### Re-enable auto-starting
```
$ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.podman.machine.default.plist
```
### Remove the LaunchAgent entirely
```
$ launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.podman.machine.default.plist
$ rm ~/Library/LaunchAgents/com.podman.machine.default.plist
```
### Graceful stop before shutdown or logout
When you log out or shut down, the system will terminate the VM processes. If you prefer to stop the Podman machine gracefully (e.g. to avoid a hard kill), run before shutting down or logging out:
```
$ podman machine stop
```
> **Note:** There is no built-in way to run actions on logout, shutdown, or restart in macOS. The [`LogoutHook`](https://superuser.com/questions/295924/how-to-run-a-script-at-login-logout-in-os-x) can be used, but it is deprecated.
## Troubleshooting
### The machine does not start or exits immediately
1. Ensure `AbandonProcessGroup` is set to `true` in the plist. Without it, launchd kills the process group when `podman machine start` exits, which stops the VM and related processes.
2. Check that the `podman` path in the plist is correct (`which podman`).
3. Verify the machine starts correctly when running `podman machine start` manually in a terminal.
4. Ensure the machine has been initialized with `podman machine init`.
### The machine enters a restart loop
This typically occurs when `KeepAlive` is set to `true` in the plist. Edit the plist file, remove the `KeepAlive` key and its value, then boot out and bootstrap again:
```
$ launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.podman.machine.default.plist
$ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.podman.machine.default.plist
```
### Debugging with logs
To capture stdout and stderr from the launchd job, add these keys to the plist (create the log paths if needed):
```xml
<key>StandardOutPath</key>
<string>/tmp/podman-machine-start.log</string>
<key>StandardErrorPath</key>
<string>/tmp/podman-machine-start.err.log</string>
```
Then inspect the files:
```
$ cat /tmp/podman-machine-start.log
$ cat /tmp/podman-machine-start.err.log
```
## SEE ALSO
**[podman-machine-start(1)](../source/markdown/podman-machine-start.1.md.in)**, **[podman-machine(1)](../source/markdown/podman-machine.1.md)**
Apple's [launchd documentation](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)