From 3ee6d16b116c0fe872af38ae41d241dec697327f Mon Sep 17 00:00:00 2001 From: Kevin Yue Date: Sat, 21 Nov 2026 12:34:42 +0800 Subject: [PATCH] Refresh the installation guide for GP Connect 3.7.0 --- README.md | 271 +++++++++++++++++++++++++----------------------------- 1 file changed, 125 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index fd518a8..f76966c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # GlobalProtect-openconnect -A GlobalProtect VPN client built on OpenConnect. GP Connect runs on Windows, macOS, Linux, FreeBSD, and OpenBSD. +**GP Connect** is a GlobalProtect VPN client built on OpenConnect. The desktop app runs on Windows, macOS, Linux, FreeBSD, and OpenBSD. The command-line client is `gpclient`. -> **Disclaimer**: GP Connect is an independent third-party client for GlobalProtect VPN networks. It is not affiliated with or endorsed by Palo Alto Networks, Inc. +[Features](#features) · [Installation](#installation) · [Usage](#usage) · [Troubleshooting](#troubleshooting) · [Building from source](#building-from-source)

@@ -12,111 +12,71 @@ A GlobalProtect VPN client built on OpenConnect. GP Connect runs on Windows, mac

-> **Inspired by** [gp-saml-gui](https://github.com/dlenski/gp-saml-gui) - -## Table of Contents - -- [Features](#features) -- [Usage](#usage) - - [Command-Line Interface](#command-line-interface) - - [Graphical User Interface](#graphical-user-interface) -- [Installation](#installation) - - [Windows](#windows) - - [macOS](#macos) - - [Debian / Ubuntu](#debian--ubuntu) - - [Arch Linux / Manjaro](#arch-linux--manjaro) - - [Fedora / RHEL](#fedora--rhel) - - [openSUSE](#opensuse) - - [Alpine Linux](#alpine-linux) - - [FreeBSD](#freebsd) - - [OpenBSD](#openbsd) - - [Gentoo](#gentoo) - - [NixOS](#nixos) - - [Docker](#docker) - - [Other Distributions](#other-distributions) -- [Building from Source](#building-from-source) -- [Troubleshooting](#troubleshooting) -- [NetworkManager Integration](#networkmanager-integration) -- [Licensing](#licensing) +GP Connect is an independent project. It is not affiliated with or endorsed by Palo Alto Networks, Inc. ## Features -- **Multi-Platform** – Windows (x64 and ARM64), macOS (Apple silicon), Linux, FreeBSD, and OpenBSD -- **Dual Interfaces** – Desktop GUI (**GP Connect**) and terminal CLI (`gpclient`, on macOS, Linux, and BSD) -- **Native Shell on Linux** – Ultra-low-memory native desktop GUI alongside the webview interface -- **Flexible Routing** – Full System VPN tunnel or local SOCKS5 proxy mode -- **Modern Authentication** – SAML / SSO, MFA, FIDO2 (YubiKey), client certificates, and external browser login -- **Automated HIP Reports** – Built-in HIP report generation or custom scripts -- **Multi-Portal & Direct Gateway** – Manage multiple saved portals or connect directly to a gateway -- **Desktop Integration** – Theme-aware system tray icon, auto-connect on launch, and reconnect on wake - -## Usage - -### Command-Line Interface - -On macOS, Linux, and BSD, the open-source `gpclient` CLI handles authentication, connection lifecycle, and HIP generation: - -```bash -# Connect to a portal server -sudo gpclient connect - -# Connect using browser authentication (SSO / SAML) -sudo gpclient connect --browser - -# Connect directly to a gateway server -sudo gpclient connect --as-gateway - -# Connect with automatic HIP report generation -sudo gpclient connect --hip - -# Headless / remote server authentication (prints auth URL to open in any browser) -sudo gpclient connect --browser manual - -# Disconnect -sudo gpclient disconnect -``` - -Run `gpclient --help` or `gpclient --help` to view all available commands and options. - -### Graphical User Interface - -- **Windows**: Open **GP Connect** from the Start menu. -- **macOS**: Open **GP Connect** from Applications. -- **Linux / BSD**: Launch GP Connect from your application menu or run: - ```bash - gpclient launch-gui - ``` - -> [!TIP] -> On Linux, GP Connect uses Native Shell when your system supports it. Your saved interface choice takes priority. Switch while disconnected in **Settings → General → Interface**. -> -> If the window stays blank, fully quit GP Connect and run `gpclient launch-gui --interface tauri`. To select Native Shell, use `--interface nsh`. The choice is saved when the interface starts. +- Browser-based SSO and MFA, including security keys supported by the identity provider. Client certificates are also supported. +- System VPN tunnel or local SOCKS5 and HTTP proxies for individual applications. +- Multiple saved portals and direct gateway connections. +- Built-in host information profile (HIP) reporting and support for custom HIP scripts. +- System tray controls and automatic connection on launch. +- Native Shell, a lightweight desktop interface for supported Linux systems. ## Installation +| Platform | Installation instructions | +| --- | --- | +| Windows and macOS | [Windows](#windows) · [macOS](#macos) | +| Linux | [Alpine](#alpine-linux) · [Arch / Manjaro](#arch-linux--manjaro) · [Debian / Ubuntu](#debian--ubuntu) · [Fedora / RHEL](#fedora--rhel) · [Gentoo](#gentoo) · [NixOS](#nixos) · [openSUSE](#opensuse) · [Other distributions](#other-distributions) | +| BSD | [FreeBSD](#freebsd) · [OpenBSD](#openbsd) | +| Container | [Docker](#docker) | + ### Windows -1. Download the **x64** or **ARM64** installer for your PC from [GitHub Releases](https://github.com/yuezk/GlobalProtect-openconnect/releases/latest). -2. Run the installer and approve the administrator prompt. -3. Open **GP Connect** from the Start menu. +Download the Windows installer for [x64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/GPConnect_3.7.0_windows-x64-setup.exe) or [ARM64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/GPConnect_3.7.0_windows-arm64-setup.exe). Run it and approve the administrator prompt. ### macOS -Requires Apple silicon and macOS 13+. Includes both GP Connect and the `gpclient` CLI. +Requires Apple silicon and macOS 13+. -#### Option 1: Homebrew (Recommended) +#### Homebrew ```bash brew install --cask yuezk/gp-connect/gp-connect ``` -#### Option 2: DMG Installer +#### DMG installer -Download the `.dmg` from the [releases](https://github.com/yuezk/GlobalProtect-openconnect/releases) page and drag GP Connect into Applications. +Open the [Apple silicon DMG](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/GPConnect_3.7.0_arm64.dmg) and drag GP Connect into Applications. + +### Alpine Linux + +Download the APK for [x86_64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect-3.7.0-r1-x86_64.apk) or [ARM64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect-3.7.0-r1-aarch64.apk). + +```bash +sudo apk add --allow-untrusted globalprotect-openconnect-*.apk +``` + +Enable the Alpine `community` repository for WebKitGTK. + +### Arch Linux / Manjaro + +Install the stable package from the Extra repository. + +```bash +sudo pacman -S globalprotect-openconnect +``` + +For the development version from the main branch, use the AUR package. + +```bash +yay -S globalprotect-openconnect-git +``` ### Debian / Ubuntu -#### Option 1: PPA (Recommended) +#### Ubuntu PPA ```bash sudo add-apt-repository ppa:yuezk/globalprotect-openconnect @@ -124,24 +84,14 @@ sudo apt-get update sudo apt-get install globalprotect-openconnect ``` -#### Option 2: DEB Package +#### Debian or Ubuntu release package -Download the latest `.deb` from the [releases](https://github.com/yuezk/GlobalProtect-openconnect/releases) page: +Download the DEB for [amd64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect_3.7.0-1_amd64.deb) or [arm64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect_3.7.0-1_arm64.deb). ```bash sudo apt install ./globalprotect-openconnect_*.deb ``` -### Arch Linux / Manjaro - -```bash -# Official Extra repository -sudo pacman -S globalprotect-openconnect - -# AUR (git main) -yay -S globalprotect-openconnect-git -``` - ### Fedora / RHEL Enable the COPR repository: @@ -151,36 +101,6 @@ sudo dnf copr enable yuezk/globalprotect-openconnect sudo dnf install globalprotect-openconnect ``` -### openSUSE - -Packages are available on the [openSUSE Build Service](https://build.opensuse.org/package/show/home:yuezk/globalprotect-openconnect). Follow the [OBS instructions](https://software.opensuse.org/download.html?project=home%3Ayuezk&package=globalprotect-openconnect) for your distribution. - -### Alpine Linux - -Download the latest `.apk` package from the [releases](https://github.com/yuezk/GlobalProtect-openconnect/releases) page: - -```bash -sudo apk add --allow-untrusted globalprotect-openconnect-*.apk -``` - -*(Requires the `community` repository for WebKitGTK dependencies).* - -### FreeBSD - -Download the latest FreeBSD package from the [releases](https://github.com/yuezk/GlobalProtect-openconnect/releases) page: - -```bash -sudo pkg install ./globalprotect-openconnect-*-freebsd-*.pkg -``` - -### OpenBSD - -Download the latest OpenBSD package from the [releases](https://github.com/yuezk/GlobalProtect-openconnect/releases) page: - -```bash -doas pkg_add -D unsigned ./globalprotect-openconnect-*-openbsd-*.tgz -``` - ### Gentoo Add the overlay: @@ -191,13 +111,15 @@ sudo eselect repository add yuezk git https://github.com/yuezk/gentoo-overlay.gi sudo emerge --sync yuezk ``` -Install the prebuilt package (glibc): +On glibc systems, install the prebuilt package: ```bash sudo emerge --ask net-vpn/globalprotect-openconnect-bin::yuezk ``` -For a source build, use `net-vpn/globalprotect-openconnect::yuezk`. If Portage requests keyword or USE flag changes, review and apply them, then rerun the install command. +The source package is `net-vpn/globalprotect-openconnect::yuezk`. + +If Portage requests keyword or USE flag changes, review and apply them, then rerun the install command. ### NixOS @@ -226,38 +148,96 @@ Apply changes: sudo nixos-rebuild switch ``` +### openSUSE + +Packages are available on the [openSUSE Build Service](https://build.opensuse.org/package/show/home:yuezk/globalprotect-openconnect). Follow the [OBS instructions](https://software.opensuse.org/download.html?project=home%3Ayuezk&package=globalprotect-openconnect) for your distribution. + +### Other Distributions + +Requires glibc 2.39 or later. Download the archive for [x86_64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect_3.7.0_x86_64.bin.tar.xz) or [ARM64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect_3.7.0_aarch64.bin.tar.xz). + +```bash +tar -xJf globalprotect-openconnect_*.bin.tar.xz +cd globalprotect-openconnect_3.7.0 +sudo make install +``` + +### FreeBSD + +Download the [FreeBSD package for amd64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect-3.7.0-freebsd-amd64.pkg). + +```bash +sudo pkg install ./globalprotect-openconnect-*-freebsd-*.pkg +``` + +### OpenBSD + +Download the [OpenBSD package for amd64](https://github.com/yuezk/GlobalProtect-openconnect/releases/download/v3.7.0/globalprotect-openconnect-3.7.0-openbsd-amd64.tgz). + +```bash +doas pkg_add -D unsigned ./globalprotect-openconnect-*-openbsd-*.tgz +``` + ### Docker -Run the CLI client in an official Alpine container: +Run the CLI in the project’s Alpine container. Replace `vpn.example.com` with your portal address. ```bash docker run --rm -it --cap-add=NET_ADMIN --device=/dev/net/tun \ yuezk/globalprotect-openconnect:latest \ - connect --browser manual + connect vpn.example.com --browser manual ``` -*(Add `--network host` on Linux if VPN routes should apply to the host network).* +On Linux, add `--network host` to apply VPN routes to the host network. -### Other Distributions +## Usage -Download `globalprotect-openconnect_${version}_${arch}.bin.tar.xz` from the [releases](https://github.com/yuezk/GlobalProtect-openconnect/releases) page: +### Desktop -```bash -tar -xJf globalprotect-openconnect_*.bin.tar.xz -cd globalprotect-openconnect_* -sudo make install +Open **GP Connect**, enter your GlobalProtect portal address, and sign in. On Linux and BSD, you can also launch the app with `gpclient launch-gui`. + +### Command line + +On Linux, BSD, or macOS with Homebrew, replace `vpn.example.com` with your portal address. Use `doas` instead of `sudo` on OpenBSD. + +```sh +sudo gpclient connect vpn.example.com ``` +| Command | Action | +| --- | --- | +| `sudo gpclient disconnect` | Disconnect | +| `sudo gpclient connect vpn.example.com --browser` | Sign in with a browser | +| `sudo gpclient connect gateway.example.com --as-gateway` | Connect directly to a gateway | +| `sudo gpclient connect vpn.example.com --hip` | Connect with HIP reporting enabled | + +See `gpclient connect --help` for all connection options. + +### Connecting over SSH + +For portals that allow external-browser sign-in, run this command on the remote host: + +```sh +sudo gpclient connect vpn.example.com --browser manual +``` + +Open the printed URL in a browser that can reach the remote host. After signing in, paste the callback URL into the SSH terminal. + +## Troubleshooting + +- **Blank Linux window.** Quit GP Connect and run `gpclient launch-gui --interface tauri`. To switch back, quit and rerun with `--interface nsh`. +- **Reporting a problem.** Run `gpclient diagnostics` and include the relevant output in your issue. See the [diagnostics guide](docs/diagnostics.md) for details. + ## Building from Source ### Prerequisites (Linux) - [Rust](https://www.rust-lang.org/tools/install) 1.91 or later - Build tools: `make`, `pkg-config`, `autoconf`, `automake`, `libtool`, `gettext` -- Libraries: `gmp`, `gnutls`, `nettle`, `libxml2`, `zlib`, `lz4`, `p11-kit`, `libsecret`, and `webkit2gtk-4.1` for the embedded sign-in window and download helper. Native Shell also requires GTK 4.14 or later. The generic glibc build requires glibc 2.39 or later +- Libraries: `gmp`, `gnutls`, `nettle`, `libxml2`, `zlib`, `lz4`, `p11-kit`, `libsecret`, and `webkit2gtk-4.1` for the embedded sign-in window and download helper. Native Shell also requires GTK 4.14 or later. - Polkit (`pkexec`) for privileged tunnel setup -*(For FreeBSD and OpenBSD instructions, see [Building from Source on FreeBSD and OpenBSD](docs/bsd-source-build.md)).* +For BSD build requirements, see [Building from Source on FreeBSD and OpenBSD](docs/bsd-source-build.md). ### Build Steps @@ -274,11 +254,6 @@ sudo make install - `BUILD_WEBVIEW_AUTH=0` – Disable embedded browser authentication in both `gpclient` and `gpauth`. External-browser and manual sign-in remain available. - `BUILD_GUI_HELPER=0` – Skip building the helper UI. -## Troubleshooting - -- **Headless / Remote Login**: When running without a desktop display or over SSH, use `--browser manual`. Open the printed URL in any browser and paste the callback URL back into the terminal. -- **Diagnostics**: If you encounter issues, run `gpclient diagnostics` or follow the [diagnostics guide](docs/diagnostics.md) when opening an issue. - ## NetworkManager Integration - [WMP/GlobalProtect-SAML-NetworkManager](https://github.com/WMP/GlobalProtect-SAML-NetworkManager) – NetworkManager VPN plugin with SAML/SSO support for GNOME and KDE Plasma @@ -303,3 +278,7 @@ sudo make install | [gpclient](./apps/gpclient) | Application | [GPL-3.0](./apps/gpclient/LICENSE) | | [gpauth](./apps/gpauth) | Application | [GPL-3.0](./apps/gpauth/LICENSE) | | [gpgui-helper](./apps/gpgui-helper) | Application | [GPL-3.0](./apps/gpgui-helper/LICENSE) | + +## Acknowledgments + +Inspired by [gp-saml-gui](https://github.com/dlenski/gp-saml-gui).