mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-09-17 11:29:09 +02:00
Updating information
This commit is contained in:
@@ -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.
|
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
|
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
|
2. A **WireGuard** tunnel to the node's tunnel manager (Gerbil) for encrypted data traffic
|
||||||
|
|||||||
@@ -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.
|
Pangolin CLI supports running as user device with authentication or a machine client.
|
||||||
|
|
||||||
|
### Install
|
||||||
### Quick Install (Recommended) — Linux and macOS
|
|
||||||
|
|
||||||
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:
|
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
|
```bash
|
||||||
curl -fsSL https://static.pangolin.net/get-cli.sh | 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.
|
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.
|
||||||
|
|
||||||
### Manual Download
|
|
||||||
|
|
||||||
Binaries for all platforms are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures.
|
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
|
|
||||||
```
|
|
||||||
|
|
||||||
<Note>
|
|
||||||
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.
|
|
||||||
</Note>
|
|
||||||
|
|
||||||
### Installation Steps
|
### Installation Steps
|
||||||
|
|
||||||
1. **Download and install the Pangolin client**
|
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.
|
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)
|
### Systemd Service (Pangolin CLI)
|
||||||
|
|
||||||
Create a basic systemd service for Pangolin CLI:
|
Create a basic systemd service for Pangolin CLI:
|
||||||
|
|||||||
@@ -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.
|
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.
|
||||||
|
|
||||||
<Note>
|
|
||||||
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).
|
|
||||||
</Note>
|
|
||||||
|
|
||||||
## Binary Installation
|
## 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:
|
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
|
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Windows
|
To run a site on Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi).
|
||||||
|
|
||||||
To run a site on Windows, use the latest installer from [GitHub releases](https://github.com/fosrl/cli/releases/latest).
|
|
||||||
|
|
||||||
### Manual Download
|
|
||||||
|
|
||||||
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.
|
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
|
--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
|
```bash
|
||||||
sudo pangolin service install site \
|
sudo pangolin service install site \
|
||||||
@@ -55,6 +47,12 @@ Check the service status:
|
|||||||
sudo pangolin service status site
|
sudo pangolin service status site
|
||||||
```
|
```
|
||||||
|
|
||||||
|
And to get the logs:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo pangolin service logs site
|
||||||
|
```
|
||||||
|
|
||||||
### Manual Systemd Service
|
### Manual Systemd Service
|
||||||
|
|
||||||
Create `/etc/pangolin/pangolin-site.env` with the initial values from your Pangolin site configuration:
|
Create `/etc/pangolin/pangolin-site.env` with the initial values from your Pangolin site configuration:
|
||||||
@@ -98,11 +96,7 @@ WantedBy=multi-user.target
|
|||||||
```
|
```
|
||||||
|
|
||||||
<Warning>
|
<Warning>
|
||||||
Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service:
|
Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service: `~$ which pangolin`
|
||||||
|
|
||||||
```bash
|
|
||||||
which pangolin
|
|
||||||
```
|
|
||||||
</Warning>
|
</Warning>
|
||||||
|
|
||||||
Reload systemd and enable the service:
|
Reload systemd and enable the service:
|
||||||
@@ -256,41 +250,6 @@ Newt is available in the Unraid Community Applications store. Search for "Newt"
|
|||||||
<img src="/images/unraid_store.png" alt="Newt on CA" />
|
<img src="/images/unraid_store.png" alt="Newt on CA" />
|
||||||
</Frame>
|
</Frame>
|
||||||
|
|
||||||
### 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 <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 <id> --secret <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
|
### 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).
|
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).
|
||||||
|
|||||||
@@ -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.
|
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.
|
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
|
- Using LAN-style addresses as targets
|
||||||
- Private resources
|
- Private resources
|
||||||
- Health checking
|
- Health checking
|
||||||
- Docker socket scanning
|
- Docker socket scanning
|
||||||
Reference in New Issue
Block a user