mirror of
https://github.com/containers/podman.git
synced 2026-03-13 08:01:19 +08:00
Merge pull request #27648 from l0rd/win-tutorial-update
Update the Podman on Windows tutorial
This commit is contained in:
Miloslav Trmač
@@ -1,4 +1,6 @@
|
||||
|
||||
<!-- markdownlint-configure-file { "heading-style": { "style": "setext_with_atx" } } -->
|
||||
<!-- markdownlint-disable MD041 -->
|
||||
|
||||
|
||||
Podman for Windows
|
||||
==================
|
||||
@@ -6,23 +8,56 @@ 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 recent features, you need Windows 11 or
|
||||
later. 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 command to initialize the first Hyper-V Podman machine, and the command
|
||||
to remove the last one, both require administrator privileges. Other commands for
|
||||
machine management (start, stop, etc...) require that the current user is a member
|
||||
of the Hyper-V administrators group.
|
||||
|
||||
It is also recommended to install the modern "Windows Terminal," which
|
||||
provides a superior user experience to the standard PowerShell and CMD
|
||||
@@ -33,61 +68,118 @@ 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 6.0 or later release for the capabilities discussed
|
||||
in this guide.
|
||||
|
||||
|
||||
The Windows installer is provided as an MSI package (e.g.,
|
||||
`podman-installer-windows-arm64.msi`). The installer supports both user-scope
|
||||
and machine-scope installations:
|
||||
|
||||
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.
|
||||
- **User scope (per-user)**: No administrator privileges required. Files are
|
||||
installed in the user's profile directory (`%LOCALAPPDATA%\Programs\Podman`),
|
||||
and the PATH is updated only for the current user. This is the default scope.
|
||||
|
||||
`PS C:\Users\User> podman machine init`
|
||||
- **Machine scope (per-machine)**: Requires administrator privileges. Files are
|
||||
installed in `%PROGRAMFILES%\Podman`, and the PATH is updated for all users.
|
||||
|
||||
Automatic WSL Installation
|
||||
--------------------------
|
||||
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 `%APPDATA%\containers\containers.conf.d\99-podman-machine-provider.conf`
|
||||
(for user scope) or `%PROGRAMDATA%\containers\containers.conf.d\99-podman-machine-provider.conf`
|
||||
(for machine scope) with the selected provider.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
**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 |
|
||||
|------------------------------------------------------------------------------|--------------------------------------------|
|
||||
| `%LocalAppData%\Programs\Podman\` | Installation directory |
|
||||
| `%APPDATA%\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 |
|
||||
| `%ProgramFiles%\Podman\` | Machine-scope installation directory |
|
||||
| `%ProgramData%\containers\containers.conf.d\99-podman-machine-provider.conf` | Machine-scope installer created conf file |
|
||||
| `%ProgramData%\containers\containers.conf` | Machine-scope client configuration file |
|
||||
|
||||
Table: Directories and files used by Podman on Windows
|
||||
|
||||
| Key | Description |
|
||||
|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
|
||||
| `HKCU:\SOFTWARE\Podman` | Installation directory path |
|
||||
| `HKLM:\SOFTWARE\Podman` | Machine-scope 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:6.0 to create VM
|
||||
Getting image source signatures
|
||||
Copying blob 24c97bc42489 done |
|
||||
Copying config 44136fa355 done |
|
||||
Writing manifest to image destination
|
||||
24c97bc424897b38d15d0e229b7a27487a1f8ed8ec8c019ccf2bb18add970db5
|
||||
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
|
||||
```
|
||||
|
||||
You can also specify the virtualization provider when initializing a machine:
|
||||
|
||||
```powershell
|
||||
PS C:\Users\User> podman machine init --provider wsl
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```powershell
|
||||
PS C:\Users\User> podman machine init --provider hyperv
|
||||
```
|
||||
|
||||
**Note:** Hyper-V requires administrator privileges to initialize the first
|
||||
podman machine. Similarly it requires administrator privileges to remove the
|
||||
last machine. That's because these operation create and delete
|
||||
machine-scope registry keys, required to support the communication between the
|
||||
guest OS and the host. Other commands such as machine start and stop require
|
||||
that the current user is a member of the Hyper-V Administrator group.
|
||||
|
||||
Starting Machine
|
||||
----------------
|
||||
@@ -95,7 +187,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 +213,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 +222,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 +237,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 +250,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 +267,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,69 +289,112 @@ 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
|
||||
```
|
||||
|
||||
Another case in which you may wish to use rootful execution is binding a port
|
||||
less than 1024. However, future versions of podman will likely drop this to a
|
||||
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 MSI 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`.
|
||||
|
||||
4. **Via command line**: Specify the provider when initializing a machine:
|
||||
|
||||
```powershell
|
||||
podman machine init --provider wsl
|
||||
```
|
||||
|
||||
**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
|
||||
hyperv-default* hyperv 16 minutes ago Never 6 2GiB 100GiB
|
||||
```
|
||||
|
||||
Since WSL shares the same virtual machine and Linux kernel across multiple
|
||||
@@ -267,7 +402,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 +415,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 +440,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 +452,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.
|
||||
|
||||
|
||||
|
||||
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 +485,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 +495,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 +510,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 and 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).
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 505 KiB After Width: | Height: | Size: 195 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 143 KiB After Width: | Height: | Size: 49 KiB |
Reference in New Issue
Block a user