Files
GlobalProtect-openconnect/README.md
T

10 KiB
Raw Permalink Blame History

GlobalProtect-openconnect

A GlobalProtect VPN client built on OpenConnect. GP Connect runs on Windows, macOS, Linux, FreeBSD, and OpenBSD. Command-line tools (gpclient) are available on macOS, Linux, and BSD.

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.

GP Connect Desktop

Inspired by gp-saml-gui

Table of Contents

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:

# Connect to a portal server
sudo gpclient connect <portal>

# Connect using browser authentication (SSO / SAML)
sudo gpclient connect <portal> --browser

# Connect directly to a gateway server
sudo gpclient connect <gateway> --as-gateway

# Connect with automatic HIP report generation
sudo gpclient connect <portal> --hip

# Headless / remote server authentication (prints auth URL to open in any browser)
sudo gpclient connect <portal> --browser manual

# Disconnect
sudo gpclient disconnect

Run gpclient --help or gpclient <command> --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:
    gpclient launch-gui
    

Tip

On Linux, try Native Shell for lower memory usage. Switch between Native Shell and Tauri in Settings → General → Interface.

Installation

Windows

Download the matching EXE installer from GitHub Releases:

  • x64: Windows 10 version 2004 (build 19041) or later.
  • ARM64: Windows 11.

Run the installer and confirm installation. It installs GP Connect and its background VPN service for all users; administrator access is required. Open GP Connect from the Start menu as your normal user.

The installer and application executables are signed by Tangramly, LLC. Embedded sign-in uses Microsoft Edge WebView2 Runtime. You can also use your system browser from Settings.

GP Connect checks for updates in the app. Uninstall it from Windows Settings; your app settings are kept. The Windows package contains the desktop app and service, without the gpclient command-line tool.

macOS

Requires Apple silicon and macOS 13+. Includes both GP Connect and the gpclient CLI.

brew install --cask yuezk/gp-connect/gp-connect

Option 2: DMG Installer

Download the .dmg from the releases page and drag GP Connect into Applications.

Debian / Ubuntu

sudo add-apt-repository ppa:yuezk/globalprotect-openconnect
sudo apt-get update
sudo apt-get install globalprotect-openconnect

Option 2: DEB Package

Download the latest .deb from the releases page:

sudo apt install ./globalprotect-openconnect_*.deb

Arch Linux / Manjaro

# Official Extra repository
sudo pacman -S globalprotect-openconnect

# AUR (git main)
yay -S globalprotect-openconnect-git

Fedora / RHEL

Enable the COPR repository:

sudo dnf copr enable yuezk/globalprotect-openconnect
sudo dnf install globalprotect-openconnect

openSUSE

Packages are available on the openSUSE Build Service. Follow the OBS instructions for your distribution.

Alpine Linux

Download the latest .apk package from the releases page:

sudo apk add --allow-untrusted globalprotect-openconnect-*.apk

(Requires community repository enabled for WebKitGTK and AppIndicator dependencies).

FreeBSD

Download the latest FreeBSD package from the releases page:

sudo pkg install ./globalprotect-openconnect-*-freebsd-*.pkg

OpenBSD

Download the latest OpenBSD package from the releases page:

doas pkg_add -D unsigned ./globalprotect-openconnect-*-openbsd-*.tgz

Gentoo

Available via the guru repository:

sudo eselect repository enable guru
sudo emerge --sync guru
sudo emerge --ask net-vpn/GlobalProtect-openconnect

NixOS

Add the flake to your flake.nix:

{
  inputs.globalprotect-openconnect.url = "github:yuezk/GlobalProtect-openconnect";

  outputs = { self, nixpkgs, globalprotect-openconnect, ... }: {
    nixosConfigurations.<hostname> = nixpkgs.lib.nixosSystem {
      modules = [
        globalprotect-openconnect.nixosModules.default
        {
          programs.globalprotect-openconnect.enable = true;
        }
      ];
    };
  }
}

Apply changes:

sudo nixos-rebuild switch

Docker

Run the CLI client in an official Alpine container:

docker run --rm -it --cap-add=NET_ADMIN --device=/dev/net/tun \
  yuezk/globalprotect-openconnect:latest \
  connect <portal> --browser manual

(Add --network host on Linux if VPN routes should apply to the host network).

Other Distributions

Download globalprotect-openconnect_${version}_${arch}.bin.tar.xz from the releases page:

tar -xJf globalprotect-openconnect_*.bin.tar.xz
cd globalprotect-openconnect_*
sudo make install

Building from Source

Prerequisites (Linux)

  • Rust 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 (or GTK 4 for Native Shell)
  • Polkit (pkexec) for privileged tunnel setup

(For FreeBSD and OpenBSD instructions, see Building from Source on FreeBSD and OpenBSD).

Build Steps

git clone --recursive https://github.com/yuezk/GlobalProtect-openconnect.git
cd GlobalProtect-openconnect
make build
sudo make install

Build Options:

  • INCLUDE_GUI=1 – Download and install the matching desktop application bundle.
  • BUILD_WEBVIEW_AUTH=0 – Build gpauth without embedded browser authentication (uses external browser or manual mode).
  • 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 when opening an issue.

NetworkManager Integration

Licensing

  • CLI (gpclient): Free and open source (GPL-3.0).
  • GUI (GP Connect): Commercial desktop application with a free trial.

Open Source Components

Component Type License
gpapi Crate MIT
openconnect Rust wrapper crate MIT
upstream OpenConnect C library LGPL-2.1
common Crate MIT
browser-launcher Crate MIT
auth Crate GPL-3.0
gpservice Application GPL-3.0
gpclient Application GPL-3.0
gpauth Application GPL-3.0
gpgui-helper Application GPL-3.0