From c35f3f8e89bc7ac643c6fe11320458a059f26f06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Thu, 17 Aug 2023 11:28:31 +0200 Subject: [PATCH] docs: added Using a proxy stories, including using a proxy requiring a custom Certificate Authorities (#1541) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP: docs: Proxy configuration - add configuration if proxy uses a custom CA certificate file fixes https://github.com/containers/podman-desktop/issues/917 Signed-off-by: Fabrice Flore-Thébault * Update website/docs/using-podman-desktop-behind-a-proxy/index.md Signed-off-by: Fabrice Flore-Thébault * Apply suggestions from code review Signed-off-by: Fabrice Flore-Thébault * Update website/docs/using-podman-desktop-behind-a-proxy/index.md Signed-off-by: Fabrice Flore-Thébault * docs: addes missing steps Signed-off-by: Fabrice Flore-Thébault * docs: added missing step Signed-off-by: Fabrice Flore-Thébault * docs: refined procedures, tested on Windows and Linux Signed-off-by: Fabrice Flore-Thébault * docs: procedure tested on Windows, and should work on macOS Signed-off-by: Fabrice Flore-Thébault * fix: typos Signed-off-by: Fabrice Flore-Thébault * fix: frontmatter Signed-off-by: Fabrice Flore-Thébault * docs: fix frontmatter, review and fix content Signed-off-by: Fabrice Flore-Thébault * fix: typo Signed-off-by: Fabrice Flore-Thébault * chore: reformatting Signed-off-by: Fabrice Flore-Thébault * Update website/docs/proxy/using-a-proxy-on-linux.md Signed-off-by: Fabrice Flore-Thébault * fix: typo that I cannot fix using GitHub web UI Signed-off-by: Fabrice Flore-Thébault --------- Signed-off-by: Fabrice Flore-Thébault --- website/docs/proxy/index.md | 16 +++++ .../proxy/using-a-proxy-in-your-containers.md | 41 ++++++++++++ website/docs/proxy/using-a-proxy-on-linux.md | 64 +++++++++++++++++++ .../using-a-proxy-requiring-a-custom-ca.md | 55 ++++++++++++++++ website/docs/proxy/using-a-proxy.md | 36 +++++++++++ 5 files changed, 212 insertions(+) create mode 100644 website/docs/proxy/index.md create mode 100644 website/docs/proxy/using-a-proxy-in-your-containers.md create mode 100644 website/docs/proxy/using-a-proxy-on-linux.md create mode 100644 website/docs/proxy/using-a-proxy-requiring-a-custom-ca.md create mode 100644 website/docs/proxy/using-a-proxy.md diff --git a/website/docs/proxy/index.md b/website/docs/proxy/index.md new file mode 100644 index 00000000000..64b81540834 --- /dev/null +++ b/website/docs/proxy/index.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 3 +title: Using behind a proxy +description: Using Podman Desktop behind a proxy requiring custom Certificate Authorities (CA). +tags: [podman-desktop, installing, windows, macos, linux] +keywords: [podman desktop, containers, podman, installing, installation, windows, macos, linux] +--- + +# Using Podman Desktop behind a proxy + +You can use Podman Desktop behind a proxy in various situations, such as: + +- [Using a proxy on Windows and macOS](proxy/using-a-proxy) +- [Using a proxy requiring a custom Certificate Authorities on macOS and Windows](proxy/using-a-proxy-requiring-a-custom-ca) +- [Using a proxy on Linux](proxy/using-a-proxy-on-linux) +- [Using a proxy in your containers](proxy/using-a-proxy-in-your-containers.md) diff --git a/website/docs/proxy/using-a-proxy-in-your-containers.md b/website/docs/proxy/using-a-proxy-in-your-containers.md new file mode 100644 index 00000000000..047d10d7733 --- /dev/null +++ b/website/docs/proxy/using-a-proxy-in-your-containers.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 3 +title: In your containers +description: Using Podman Desktop behind a proxy requiring custom Certificate Authorities (CA). +tags: [podman-desktop, installing, windows, macos, linux] +keywords: [podman desktop, containers, podman, installing, installation, windows, macos, linux] +--- + +# Using a proxy in your containers on macOS and Windows + +You can configure your Podman machine to use a proxy for your containers. + +#### Prerequisites + +- ``: Your proxy URL. + +#### Procedure + +1. Open a shell prompt on the Podman machine: + + ```shell-session + $ podman machine ssh + ``` + +1. Edit the `containers.conf` file to pass the proxy environment variables to Podman CLI. + + The file location depends on your connection mode: + + - `rootless`: `$HOME/.config/containers/containers.conf` + + - `rootful`: `/etc/containers/containers.conf` + +1. Set the proxy environment variables to pass into the containers: + + ```toml + [containers] + http_proxy = true + env = ["http_proxy=", "https_proxy="] + ``` + +1. Go to **Settings > Resources** and restart the Podman machine. diff --git a/website/docs/proxy/using-a-proxy-on-linux.md b/website/docs/proxy/using-a-proxy-on-linux.md new file mode 100644 index 00000000000..f0c0d56c9ba --- /dev/null +++ b/website/docs/proxy/using-a-proxy-on-linux.md @@ -0,0 +1,64 @@ +--- +sidebar_position: 4 +title: Linux +description: Using Podman Desktop behind a proxy on Linux. +tags: [podman-desktop, proxy, linux] +keywords: [podman desktop, containers, podman, proxy, linux] +--- + +# Using Podman Desktop behind a proxy on Linux + +You can configure Podman to run behind a proxy. + +#### Prerequisites + +- ``: Your proxy Certificate Authorities (CA), in Privacy-Enhanced Mail (PEM) format. +- ``: Your proxy URL. + +#### Procedure + +1. Edit the `containers.conf` file to pass the proxy environment variables to Podman CLI. + + The file location depends on your connection mode: + + - `rootless`: `$HOME/.config/containers/containers.conf` + + - `rootful`: `/etc/containers/containers.conf` + +1. Set the proxy environment variables to pass into the containers: + + ```toml + [containers] + http_proxy = true + env = ["http_proxy=", "https_proxy="] + ``` + +1. Set the proxy environment variables to pass into the Podman engine: + + ```toml + [engine] + env = ["http_proxy=", "https_proxy="] + ``` + +1. Add the custom Certificate Authorities (CA) for your proxy: + + ```shell-session + $ sudo cp /etc/pki/ca-trust/source/anchors/ + $ sudo update-ca-trust + ``` + +1. Restart all `podman` processes. + + ```shell-session + $ pkill podman + ``` + +1. Restart Podman Desktop: Ctrl + q. + +#### Verification + +1. Go to **Images**. +1. Click **Pull an image**. +1. **Image to Pull**: `bash` +1. Click **Pull image**. +1. Podman Desktop reports `Download complete`. diff --git a/website/docs/proxy/using-a-proxy-requiring-a-custom-ca.md b/website/docs/proxy/using-a-proxy-requiring-a-custom-ca.md new file mode 100644 index 00000000000..3759e0ea8e5 --- /dev/null +++ b/website/docs/proxy/using-a-proxy-requiring-a-custom-ca.md @@ -0,0 +1,55 @@ +--- +sidebar_position: 2 +title: Custom Certificate Authorities +description: Using Podman Desktop behind a proxy requiring custom Certificate Authorities (CA). +tags: [podman-desktop, installing, windows, macos, linux] +keywords: [podman desktop, containers, podman, installing, installation, windows, macos, linux] +--- + +# Using Podman Desktop behind a proxy requiring custom Certificate Authorities (CA) on macOS and Windows + +You can configure Podman Desktop to run behind a proxy requiring custom Certificate Authorities (CA), such as self-signed certificates. +The configuration applies to the Podman engine, but not to your containers. + +#### Prerequisites + +- Your proxy URL: `` +- Your proxy Certificate Authorities (CA) is stored in your home directory, in the `proxy_ca.pem` file, in Privacy-Enhanced Mail (PEM) format. + +#### Procedure + +1. Go to **Settings > Proxy**, and set your proxy URL: + + 1. **Proxy configuration enabled**: yes + 1. **Web Proxy (HTTP)**: `` + 1. **Secure Web Proxy (HTTPS)**: `` + 1. Click the **Update** button + +1. Copy the certificate to the Podman machine: + + ```shell-session + $ cat proxy_ca.pem | podman machine ssh podman-machine-default "cat > proxy_ca.pem" + ``` + +1. Open a shell prompt on the Podman machine: + + ```shell-session + $ podman machine ssh podman-machine-default + ``` + +1. Add the custom Certificate Authorities (CA) for your proxy: + + ```shell-session + $ sudo cp proxy_ca.pem /etc/pki/ca-trust/source/anchors/ + $ sudo update-ca-trust + ``` + +1. Go to **Settings > Resources** and restart the Podman machine. + +#### Verification + +1. Go to **Images**. +1. Click **Pull an image**. +1. **Image to Pull**: `bash` +1. Click **Pull image**. +1. Podman Desktop reports `Download complete`. diff --git a/website/docs/proxy/using-a-proxy.md b/website/docs/proxy/using-a-proxy.md new file mode 100644 index 00000000000..c409c7692d9 --- /dev/null +++ b/website/docs/proxy/using-a-proxy.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 1 +title: macOS and Windows +description: Using Podman Desktop behind a proxy on macOS and Windows. +tags: [podman-desktop, proxy, windows, macos] +keywords: [podman desktop, containers, podman, proxy, windows, macos] +--- + +# Using Podman Desktop behind a proxy on macOS and Windows + +You can configure Podman Desktop to run behind a proxy. +The configuration applies to the Podman engine, but not to your containers. + +#### Prerequisites + +- Your proxy URL: ``. +- Your proxy does not require a custom Certificate Authorities. Else see [Using a proxy requiring a custom Certificate Authorities](using-a-proxy-requiring-a-custom-ca). + +#### Procedure + +1. Go to **Settings > Proxy**, and set your proxy URL: + + 1. **Proxy configuration enabled**: yes + 1. **Web Proxy (HTTP)**: `` + 1. **Secure Web Proxy (HTTPS)**: `` + 1. Click the **Update** button + +1. Go to **Settings > Resources** and restart the Podman machine. + +#### Verification + +1. Go to **Images**. +1. Click **Pull an image**. +1. **Image to Pull**: `bash` +1. Click **Pull image**. +1. Podman Desktop reports `Download complete`.