diff --git a/docs/tutorials/podman-for-windows.md b/docs/tutorials/podman-for-windows.md index 10d82cfb2a..dfe88f956e 100644 --- a/docs/tutorials/podman-for-windows.md +++ b/docs/tutorials/podman-for-windows.md @@ -1,4 +1,6 @@ -![](https://raw.githubusercontent.com/containers/common/main/logos/podman-logo-full-vert.png) + + +![The Podman logo](https://raw.githubusercontent.com/containers/common/main/logos/podman-logo-full-vert.png) Podman for Windows ================== @@ -6,23 +8,55 @@ Podman for Windows While "containers are Linux," Podman also runs on Mac and Windows, where it provides a native CLI and embeds a guest Linux system to launch your containers. This guest is referred to as a Podman machine and is managed with -the `podman machine` command. On Windows, each Podman machine is backed by a -virtualized Windows Subsystem for Linux (WSLv2) distribution. The podman command -can be run directly from your Windows PowerShell (or CMD) prompt, where it -remotely communicates with the podman service running in the WSL environment. -Alternatively, you can access Podman directly from the WSL instance if you -prefer a Linux prompt and Linux tooling. In addition to command-line access, -Podman also listens for Docker API clients, supporting direct usage of -Docker-based tools and programmatic access from your language of choice. +the `podman machine` command. + +On Windows, each Podman machine is backed by a virtualized Windows Subsystem for +Linux (WSLv2) distribution or an Hyper-V virtual machine. + +The podman command can be run directly from your Windows PowerShell (or CMD) +prompt, where it remotely communicates with the podman service running in the +guest environment. In addition to command-line access, Podman also listens for +Docker API clients, supporting direct usage of Docker-based tools and +programmatic access from your language of choice. + +Table of Contents +------------------ + +- [Prerequisites](#prerequisites) +- [Installing Podman](#installing-podman) + - [Directories, files and registry keys used by Podman on Windows](#directories-files-and-registry-keys-used-by-podman-on-windows) +- [Machine Init Process](#machine-init-process) +- [Starting Machine](#starting-machine) +- [First Podman Command](#first-podman-command) +- [Port Forwarding](#port-forwarding) +- [Using API Forwarding](#using-api-forwarding) +- [Rootful & Rootless](#rootful--rootless) +- [Configuring the Machine Provider](#configuring-the-machine-provider) +- [Volume Mounting](#volume-mounting) +- [Listing Podman Machine(s)](#listing-podman-machines) +- [Accessing the Podman Linux Environment](#accessing-the-podman-linux-environment) +- [Using SSH](#using-ssh) +- [Using the WSL Command](#using-the-wsl-command) +- [Using Windows Terminal Integration](#using-windows-terminal-integration) +- [Stopping a Podman Machine](#stopping-a-podman-machine) +- [Removing a Podman Machine](#removing-a-podman-machine) +- [Uninstalling Podman](#uninstalling-podman) +- [Troubleshooting](#troubleshooting) + - [Installing WSL Manually](#installing-wsl-manually) +- [Install Certificate Authority](#install-certificate-authority) Prerequisites ------------- -Since Podman uses WSL, you need a recent release of Windows 10 or Windows 11. -On x64, WSL requires build 18362 or later, and 19041 or later is required for -arm64 systems. Internally, WSL uses virtualization, so your system must -support and have hardware virtualization enabled. If you are running Windows -on a VM, you must have a VM that supports nested virtualization. +Because Podman uses WSLv2 or Hyper-V, you need a recent release of Windows 10 or +later. On x64, WSLv2 requires build 18362 or later, and 19041 or later is +required for arm64 systems. Internally, WSL and Hyper-V use virtualization, so +your system must support and have hardware virtualization enabled. If you are +running Windows on a VM, you must have a VM that supports nested virtualization. + +Hyper-V is only available on Windows Enterprise, Pro, or Education editions (not +Home). The `podman machine` sub-commands (init, start, stop, rm, etc...) require +administrator privileges. It is also recommended to install the modern "Windows Terminal," which provides a superior user experience to the standard PowerShell and CMD @@ -33,61 +67,91 @@ You can install it by searching the Windows Store or by running the following `winget install Microsoft.WindowsTerminal` - Installing Podman ----------------- Installing the Windows Podman client begins by downloading the Podman Windows installer. The Windows installer is built with each Podman release and can be downloaded from the official - [GitHub release page](https://github.com/containers/podman/releases). -Be sure to download a 4.1 or later release for the capabilities discussed +[GitHub release page](https://github.com/containers/podman/releases). +Be sure to download a Podman 5.6 or later release for the capabilities discussed in this guide. -![Installing Podman 4.1.0](podman-win-install.jpg) +The Windows installer is provided as an installation bundle (e.g., +`podman-installer-windows-arm64.exe`). It only supports machine-scope +installations: it requires administrator privileges. Files are installed in +`%PROGRAMFILES%\RedHat\Podman`, and the PATH is updated for all users. -Once downloaded, simply run the EXE file, and relaunch a new terminal. After -this point, podman.exe will be present on your PATH, and you will be able to run -the `podman machine init` command to create your first machine. +During installation, you can select the virtualization provider (WSL or Hyper-V) +that Podman will use for machines. The installer will create a configuration +file at `%PROGRAMDATA%\containers\containers.conf.d\99-podman-machine-provider.conf` +with the selected provider. -`PS C:\Users\User> podman machine init` +![Installing Podman 5.6.2](podman-win-install.jpg) -Automatic WSL Installation --------------------------- +Once installed, relaunch a new terminal. After this point, `podman.exe` will be +present on your PATH, and you will be able to run the `podman machine init` +command to create your first machine. -If WSL has not been installed on your system, the first machine init command -will prompt a dialog to begin an automated install. If accepted, this process -will install the necessary Windows components, restart the system, and after -login, relaunch the machine creation process in a terminal window. Be sure to -wait a minute or two for the relaunch to occur, as Windows has a delay before -executing startup items. Alternatively, you can decline automatic installation -and install WSL manually. However, this will require additional download and -setup time. +**Note:** WSLv2 or Hyper-V must be installed before creating Podman machines. If +WSL is not installed, you can install it manually by running `wsl --install` +from an administrator PowerShell prompt. The Podman installer no longer +automatically installs WSL. If the Hyper-V feature is not enabled, you can +enable it by running +`Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All` from +an administrator PowerShell prompt. + +### Directories, files and registry keys used by Podman on Windows + +The following tables list the directories, files and registry keys used by +Podman on Windows. + +| Directory or file | Description | +|------------------------------------------------------------------------------|---------------------------------------| +| `%PROGRAMFILES%\RedHat\Podman` | Installation directory | +| `%PROGRAMDATA%\containers\containers.conf.d\99-podman-machine-provider.conf` | Installer created configuration file | +| `%APPDATA%\containers\containers.conf` | Client main configuration file | +| `%APPDATA%\containers\podman-connections.json` | Client connections configuration file | +| `%USERPROFILE%\.local\share\containers\podman\machine` | Machines data directory | +| `%USERPROFILE%\.config\containers\podman\machine\` | Machines configuration directory | +| `%USERPROFILE%\.local\share\containers\storage\podman\` | Containers and images storage layers | + +Table: Directories and files used by Podman on Windows + +| Key | Description | +|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| +| `HKLM:\SOFTWARE\Red Hat\Podman` | Installation directory path | +| `HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\GuestCommunicationServices` | Hyper-V socket registry entries (`{PORT_HEX}-FACB-11E6-BD58-64006A7986D3` pattern) | + +Table: Registry keys used by Podman on Windows Machine Init Process -------------------- -After WSL is installed, the init command will install a minimal installation -of Fedora, customizing it to run podman. +The `podman machine init` command will pull a custom Fedora OCI image (Fedora +CoreOS when using Hyper-V) as an OCI artifact from `quay.io/podman/machine-os`. +The image is customized to run Podman. -``` +```powershell PS C:\Users\User> podman machine init -Extracting compressed file -Importing operating system into WSL (this may take 5+ minutes on a new WSL install)... -Installing packages (this will take a while)... -Complete! +Looking up Podman Machine image at quay.io/podman/machine-os:5.6 to create VM +Getting image source signatures +Copying blob 26cff917a2a5 done | +Copying config 44136fa355 done | +Writing manifest to image destination +26cff917a2a5c6a194472f8cd1ae3b7a21efe0d80cce6ddc4e621ee64c080dc1 +Extracting compressed file: podman-machine-default-arm64: done +Importing operating system into WSL (this may take a few minutes on a new WSL install)... +The operation completed successfully. Configuring system... -Generating public/private ed25519 key pair. -Your identification has been saved in podman-machine-default -Your public key has been saved in podman-machine-default.pub -The key fingerprint is: -SHA256:RGTGg2Q/LX7ijN+mzu8+BzcS3cEWP6Hir6pYllJtceA root@WINPC Machine init complete To start your machine run: podman machine start ``` +**Note:** Hyper-V requires administrator privileges to manage the +podman machine. Starting Machine ---------------- @@ -95,7 +159,7 @@ Starting Machine After the machine init process completes, it can then be started and stopped as desired: -``` +```powershell PS C:\Users\User> podman machine start Starting machine "podman-machine-default" @@ -121,8 +185,8 @@ Linux. For a quick working example with a small image, you can run the Linux date command on PowerShell. -``` -PS C:\Users\User> podman run ubi8-micro date +```powershell +PS C:\Users\User> podman run ubi9-micro date Thu May 5 21:56:42 UTC 2022 ``` @@ -130,12 +194,14 @@ Port Forwarding --------------- Port forwarding also works as expected; ports will be bound against localhost -(127.0.0.1). Note: When running as rootless (the default), you must use a port +(127.0.0.1). + +**Note:** When running as rootless (the default), you must use a port greater than 1023. See the Rootful and Rootless section for more details. To launch httpd, you can run: -``` +```powershell PS C:\Users\User> podman run --rm -d -p 8080:80 --name httpd docker.io/library/httpd f708641300564a6caf90c145e64cd852e76f77f6a41699478bb83a162dceada9 ``` @@ -143,7 +209,7 @@ f708641300564a6caf90c145e64cd852e76f77f6a41699478bb83a162dceada9 A curl command against localhost on the PowerShell prompt will return a successful HTTP response: -``` +```powershell PS C:\Users\User> Invoke-WebRequest -UseBasicParsing http://localhost:8080/ StatusCode : 200 @@ -156,15 +222,14 @@ As with Linux, to stop, run: `podman stop httpd` - Using API Forwarding -------------------- -API forwarding allows Docker API tools and clients to use podman as if it was +API forwarding allows Docker API tools and clients to use Podman as if it was Docker. Provided there is no other service listening on the Docker API pipe; no special settings will be required. -``` +```powershell PS C:\Users\User> docker run -it fedora echo "Hello Podman!" Hello Podman! ``` @@ -174,8 +239,7 @@ variable you can set for tools to point to podman. Alternatively, you can shut down both the conflicting service and podman, then finally run `podman machine start` to restart, which should grab the Docker API address. - -``` +```powershell Another process was listening on the default Docker API pipe address. You can still connect Docker API clients by setting DOCKER HOST using the following PowerShell command in your terminal session: @@ -197,25 +261,27 @@ Podman Engine Rootful & Rootless ------------------ -On the embedded WSL Linux distro, podman can either be run under the root user +On the embedded guest environment, Podman can either be run under the root user (rootful) or a non-privileged user (rootless). For behavioral consistency with -Podman on Linux, rootless is the default. Note: Rootful and Rootless -containers are distinct and isolated from one another. Podman commands against -one (e.g., podman ps) will not represent results/state for the other. +Podman on Linux, rootless is the default. + +**Note:** Rootful and Rootless containers are distinct and isolated from one +another. Podman commands against one (e.g., podman ps) will not represent +results/state for the other. While most containers run fine in a rootless setting, you may find a case where the container only functions with root privileges. If this is the case, you can switch the machine to rootful by stopping it and using the set command: -``` +```powershell podman machine stop podman machine set --rootful ``` To restore rootless execution, set rootful to false: -``` +```powershell podman machine stop podman machine set --rootful=false ``` @@ -225,41 +291,87 @@ less than 1024. However, future versions of podman will likely drop this to a lower number to improve compatibility with defaults on system port services (such as MySQL) +Configuring the Machine Provider +-------------------------------- + +Podman on Windows supports two virtualization providers: WSL and Hyper-V. The +provider can be configured in several ways: + +1. **During installation**: The installer allows you to select the provider + during installation and creates a configuration file automatically. + +2. **Via configuration file**: You can manually create or edit the configuration + file at: + + - User scope: `%APPDATA%\containers\containers.conf` + - Machine scope: `%PROGRAMDATA%\containers\containers.conf` + + Add the following content: + + ```toml + [machine] + provider = "wsl" + ``` + + or + + ```toml + [machine] + provider = "hyperv" + ``` + +3. **Via environment variable**: Set `CONTAINERS_MACHINE_PROVIDER` to `wsl` or + `hyperv`. + +**Note:** WSL and Hyper-V machines cannot run simultaneously. You must stop +machines using one provider before starting machines with the other. + Volume Mounting --------------- -New in Podman v4.1 is the ability to perform volume mounts from Windows paths into a -Linux container. This supports several notation schemes, including: +Podman supports volume mounts from Windows paths into Linux containers. This +supports several notation schemes, including: Windows Style Paths: -`podman run --rm -v c:\Users\User\myfolder:/myfolder ubi8-micro ls /myfolder` +`podman run --rm -v c:\Users\User\myfolder:/myfolder ubi9-micro ls /myfolder` Unixy Windows Paths: -`podman run --rm -v /c/Users/User/myfolder:/myfolder ubi8-micro ls /myfolder` +`podman run --rm -v /c/Users/User/myfolder:/myfolder ubi9-micro ls /myfolder` Linux paths local to the WSL filesystem: -`podman run --rm -v /var/myfolder:/myfolder ubi-micro ls /myfolder` +`podman run --rm -v /var/myfolder:/myfolder ubi9-micro ls /myfolder` All of the above conventions work, whether running on a Windows prompt or the WSL Linux shell. Although when using Windows paths on Linux, appropriately quote or escape the Windows path portion of the argument. - Listing Podman Machine(s) ------------------------- To list the available podman machine instances and their current resource usage, use the `podman machine ls` command: -``` +```powershell PS C:\Users\User> podman machine ls -NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE -podman-machine-default wsl 2 hours ago Currently running 4 331.1MB 768MB +NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE +wsl-default wsl 2 hours ago Currently running 12 16G 768MB +``` + +The command lists the machines of the configured provider. In the example above, +the configured provider is WSL, so the command lists the WSL machines. In the +example below, the configured provider is Hyper-V: + +```powershell +PS C:\Users\User> podman machine ls + + +NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE +hyperv-default* hyperv 16 minutes ago Never 6 2GiB 100GiB ``` Since WSL shares the same virtual machine and Linux kernel across multiple @@ -267,7 +379,10 @@ distributions, the CPU and Memory values represent the total resources shared across running systems. The opposite applies to the Disk value. It is independent and represents the amount of storage for each individual distribution. - +The CPU, memory and disk size values for an Hyper-V machines instead, represent +the number of vCPUs, memory and disk size allocated to the machine. Those values +can be configured when creating the machine using the `--cpus`, `--memory` and +`--disk-size` options. Or edited later using the `podman machine set` command. Accessing the Podman Linux Environment -------------------------------------- @@ -277,12 +392,13 @@ seamless native experience supporting the usage of local desktop tools and APIs, there are a few scenarios in which you may wish to access the Linux environment: -+ Updating to the latest stable packages on the embedded Fedora instance -+ Using Linux development tools directly -+ Using a workflow that relies on EXT4 filesystem performance or behavior +- Updating to the latest stable packages on the embedded Fedora instance +- Using Linux development tools directly +- Using a workflow that relies on EXT4 filesystem performance or behavior semantics There are three mechanisms to access the embedded WSL distribution: + 1. SSH using `podman machine ssh` 2. WSL command on the Windows PowerShell prompt 3. Windows Terminal Integration @@ -301,16 +417,11 @@ latest OS bugfixes: ### Using the WSL Command -The `wsl` command provides direct access to the Linux system but enters the -shell as root first. This is due to design limitations of WSL, where running -systemd (Linux's system services) requires the usage of a privileged process -namespace. +The `wsl` command provides direct access to the Linux system. Unless you have no +other distributions of WSL installed, it's recommended to use the `-d` option +with the name of your podman machine (podman-machine-default is the default): -Unless you have no other distributions of WSL installed, it's recommended to -use the `-d` option with the name of your podman machine (podman-machine-default -is the default) - -``` +```powershell PS C:\Users\User> wsl -d podman-machine-default ``` @@ -318,43 +429,30 @@ You will be automatically entered into a nested process namespace where systemd is running. If you need to access the parent namespace, hit `ctrl-d` or type exit. This also means to log out, you need to exit twice. -``` -[root@WINPC /]# podman --version -podman version 4.1.0 +```bash +[user@WINPC /]$ podman --version +podman version 6.0.0 ``` +To access commands that require root privileges, you can prefix the `wsl` +command with `sudo` (the default user is sudoer): -To access commands as the non-privileged user (rootless podman), you must -first type `su user`. Alternatively, you can prefix the `wsl` command to use the -special `enterns`: - -``` -wsl -d podman-machine-default enterns su user -[user@WINPC /]$ id -uid=1000(user) gid=1000(user) groups=1000(user),10(wheel) +```bash +wsl -d podman-machine-default sudo systemctl status ``` -Likewise, running commands as root without entering a prompt should also be -prefixed with `enterns`. - -`wsl -d podman-machine-default enterns systemctl status` - -Accessing the WSL instance as a specific user using `wsl -u` or using inline -commands without `enterns` is not recommended since commands will execute -against the incorrect namespace. +Accessing the WSL instance as a specific user using `wsl -u` is not recommended +since commands will execute against the incorrect namespace. ### Using Windows Terminal Integration -Entering WSL as root is a 2-click operation. Simply click the drop-down tag, -and pick 'podman-machine-default,' where you will be entered directly as root. +Entering WSL is a 2-click operation. Simply click the drop-down tag, and pick +'podman-machine-default,' where you will be entered directly as the default +user. ![Using WSL in Windows Terminal](podman-wsl-term.jpg) -As before, to switch to a non-privileged user for rootless podman commands, -type `su user`. - -``` -[root@WINPC /]# su user +```powershell [user@WINPC /]$ podman info --format '{{.Store.RunRoot}}' /run/user/1000/containers ``` @@ -364,7 +462,7 @@ Stopping a Podman Machine To stop a running podman machine, use the `podman machine stop` command: -``` +```powershell PS C:\Users\User> podman machine stop Machine "podman-machine-default" stopped successfully ``` @@ -374,7 +472,7 @@ Removing a Podman Machine To remove a machine, use the `podman machine rm` command: -``` +```powershell PS C:\Users\User> podman machine rm The following files will be deleted: @@ -389,34 +487,66 @@ C:\Users\User\.local\share\containers\podman\machine\wsl\wsldist\podman-machine- Are you sure you want to continue? [y/N] y ``` +Uninstalling Podman +------------------- +Podman can be uninstalled from the Windows Control Panel. Administrator +privileges are required if Podman was installed for the machine, rather than for +a user. + +The uninstaller does not clean up Podman data an configuration resources. These +must be cleaned up manually. Troubleshooting --------------- -Recovering from a failed auto-installation of WSL +### Installing WSL Manually -If auto-install fails and retrying is unsuccessful, you can attempt to reset -your WSL system state and perform a manual WSL installation using the `wsl ---install` command. To do so, perform the following steps: +If WSL is not installed on your system, you must install it manually before +creating Podman machines. To install WSL: 1. Launch PowerShell as administrator - ``` + + ```powershell Start-Process powershell -Verb RunAs ``` -2. Disable WSL Features + +2. Run the WSL install command + + ```powershell + wsl --install ``` + +3. Reboot your system if prompted +4. After reboot, continue with `podman machine init` + +If you encounter issues with WSL installation, you can attempt to reset your +WSL system state: + +1. Launch PowerShell as administrator + + ```powershell + Start-Process powershell -Verb RunAs + ``` + +2. Disable WSL Features + + ```powershell dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart ``` + 3. Reboot 4. Run manual WSL install - ``` + + ```powershell wsl --install ``` -5. Continue with podman machine init + +5. Continue with `podman machine init` Install Certificate Authority -============================= +------------------------------ -Instructions for installing a CA certificate can be found [here](podman-install-certificate-authority.md). +Instructions for installing a CA certificate can be found [in the dedicated +article](podman-install-certificate-authority.md). diff --git a/docs/tutorials/podman-win-install.jpg b/docs/tutorials/podman-win-install.jpg index cf1b3ca862..66a5db52cc 100644 Binary files a/docs/tutorials/podman-win-install.jpg and b/docs/tutorials/podman-win-install.jpg differ diff --git a/docs/tutorials/podman-wsl-term.jpg b/docs/tutorials/podman-wsl-term.jpg index a01bea84e7..cdb807a2fd 100644 Binary files a/docs/tutorials/podman-wsl-term.jpg and b/docs/tutorials/podman-wsl-term.jpg differ