diff --git a/development/system-architecture.mdx b/development/system-architecture.mdx index 1cdffc9..8ff3564 100644 --- a/development/system-architecture.mdx +++ b/development/system-architecture.mdx @@ -64,7 +64,7 @@ The control plane writes certificates, Traefik router definitions, and WireGuard A **site connector** runs on a remote network (server, VM, container, or appliance) and is the bridge between your private LAN and the platform. For public resources it maintains persistent **outbound** connections to a Pangolin node so ingress can reverse-proxy into the LAN. For private resources, clients form a **peer-to-peer** path to the connector; the node is only in that data path as a relay when hole punching fails. -The primary connector is a **Pangolin Site**. In engineering contexts it is referred to as Newt. The site opens: +The primary connector is a **Pangolin Site**. The site opens: 1. A **WebSocket** to the control plane for configuration, health, and coordination 2. A **WireGuard** tunnel to the node's tunnel manager (Gerbil) for encrypted data traffic diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 120244b..ff89a0a 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -114,32 +114,18 @@ Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. Pangolin CLI supports running as user device with authentication or a machine client. - -### Quick Install (Recommended) — Linux and macOS +### Install Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always pulls the latest version, adding `pangolin` to your PATH: ```bash curl -fsSL https://static.pangolin.net/get-cli.sh | bash ``` -### Windows -Go to [GitHub releases](https://github.com/fosrl/cli/releases) and download the latest **MSI installer** or **EXE** for Windows. - -### Manual Download +On Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi), or choose to install the CLI from menu bar of the desktop app by choosing the "Install Pangolin CLI" option. Binaries for all platforms are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures. -Download and install manually: - -```bash -wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin -``` - - -Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information. - - ### Installation Steps 1. **Download and install the Pangolin client** @@ -178,6 +164,33 @@ Replace `{version}` with the desired version and `{architecture}` with your arch Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups. +## Machine Clients + +Machine clients don't require a login and are built for machines like services to be able to connect to private resources. Like sites, they have an ID and a secret. + +### Run as a Service + +The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host. + +```bash +sudo pangolin service install client \ +--id 31frd0uzbjvp721 \ +--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ +--endpoint https://app.pangolin.net +``` + +Check the service status: + +```bash +sudo pangolin service status client +``` + +And to get the logs: + +```bash +sudo pangolin service logs client +``` + ### Systemd Service (Pangolin CLI) Create a basic systemd service for Pangolin CLI: diff --git a/manage/sites/install-site.mdx b/manage/sites/install-site.mdx index 9a3d922..7786a15 100644 --- a/manage/sites/install-site.mdx +++ b/manage/sites/install-site.mdx @@ -5,13 +5,9 @@ description: "Install the site connector as a binary or Docker container" The site connector can be installed as either a static binary executable or a Docker container via the CLI. You must first create a site and copy the ID and secret config from Pangolin before running it. - -Deploying a site in Kubernetes? See the dedicated [Kubernetes](/manage/sites/kubernetes/helm) docs - install guides for [Helm](/manage/sites/kubernetes/helm) and [Kustomize](/manage/sites/kubernetes/kustomize), a full [Configuration](/manage/sites/kubernetes/configuration) reference, and [Troubleshooting](/manage/sites/kubernetes/troubleshooting). - - ## Binary Installation -### Quick Install (Recommended) +### Install Use this command to automatically install the CLI. It detects your system architecture automatically and always pulls the latest version, adding the CLI to your PATH: @@ -19,11 +15,7 @@ Use this command to automatically install the CLI. It detects your system archit curl -fsSL https://static.pangolin.net/get-cli.sh | bash ``` -#### Windows - -To run a site on Windows, use the latest installer from [GitHub releases](https://github.com/fosrl/cli/releases/latest). - -### Manual Download +To run a site on Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi). Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/cli/releases/latest) for ARM and AMD64 (x86_64) architectures. @@ -38,9 +30,9 @@ pangolin up site \ --endpoint https://app.pangolin.net ``` -### Systemd Service (Recommended) +### Run as a Service -The CLI can install and manage the systemd service for you: +The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host. ```bash sudo pangolin service install site \ @@ -55,6 +47,12 @@ Check the service status: sudo pangolin service status site ``` +And to get the logs: + +```bash +sudo pangolin service logs site +``` + ### Manual Systemd Service Create `/etc/pangolin/pangolin-site.env` with the initial values from your Pangolin site configuration: @@ -98,11 +96,7 @@ WantedBy=multi-user.target ``` -Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service: - -```bash -which pangolin -``` +Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service: `~$ which pangolin` Reload systemd and enable the service: @@ -256,41 +250,6 @@ Newt is available in the Unraid Community Applications store. Search for "Newt" Newt on CA -### Portainer and Other UIs - -Container management UIs like Portainer typically allow passing commands and environment variables to containers similar to Docker Compose. Look for a commands or arguments configuration section and follow the relevant guides. - -### Windows Service - -On Windows, the site connector can be run as a service or normally as a binary in a session. - -When running as a binary and not installing the service, you can use the same CLI arguments as you would on any other platform. - -If you are installing the service, we recommend writing the config into the config file location first, following the [config file format](/manage/sites/install-site#config-file-injected-as-compose-secret), with the provisioning key. Since the service runs under the `SYSTEM` account, its config lives under that account's profile at `C:\WINDOWS\system32\config\systemprofile\.config\pangolin\site.json`. Alternatively, you can install the service and start it with CLI args, which will also work. For example: - -``` -pangolin.exe service install site -pangolin.exe service start site --endpoint https://app.pangolin.net --provisioning-key -``` - -This will provision a new service, start it, and create the config file for future starts. - -#### Service Management Commands - -``` -# Install the service -pangolin.exe service install site --id --secret --endpoint https://app.pangolin.net - -# Stop the service -pangolin.exe service logs site - -# Check service status -pangolin.exe service status site - -# Remove the service -pangolin.exe service uninstall site -``` - ### Advantech Router App Download the correct version of the router app for your device from the [GitHub releases](https://github.com/fosrl/newt/releases/latest). You can find more information about router apps along with the right version information for your hardware on the the [Advantech engineering portal](https://icr.advantech.com/products/software/router-apps). diff --git a/manage/sites/understanding-sites.mdx b/manage/sites/understanding-sites.mdx index 869e9cd..c175b9a 100644 --- a/manage/sites/understanding-sites.mdx +++ b/manage/sites/understanding-sites.mdx @@ -17,7 +17,7 @@ A Pangolin Site is the software connector that establishes this connection and r Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios. -### Newt Site (Recommended) +### Site Connector (Recommended) This site type exposes resources on a remote network through a managed tunnel and websocket connection. It requires the Pangolin Site connector on the remote network. This is the easiest setup and does not require NAT configuration. @@ -54,4 +54,4 @@ Basic WireGuard sites do not support: - Using LAN-style addresses as targets - Private resources - Health checking -- Docker socket scanning +- Docker socket scanning \ No newline at end of file