mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-07 21:46:42 +00:00
Add some new docs
This commit is contained in:
Owen
@@ -38,8 +38,9 @@
|
||||
},
|
||||
{
|
||||
"group": "Resources",
|
||||
"pages": ["manage/resources/tcp-udp-resources"]
|
||||
"pages": ["manage/resources/targets", "manage/resources/tcp-udp-resources", "manage/resources/client-resources"]
|
||||
},
|
||||
"manage/healthchecks-failover",
|
||||
{
|
||||
"group": "Clients",
|
||||
"pages": [
|
||||
|
||||
BIN
images/client_resource.png
Normal file
BIN
images/client_resource.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 93 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB |
@@ -83,7 +83,7 @@ gerbil:
|
||||
</Step>
|
||||
|
||||
<Step title="Configure resources">
|
||||
Create RAW TCP/UDP resources for what you would like to access through the client. For example, to SSH into a server, create a resource like `22:localhost:22`.
|
||||
Create [client resources](../resources/site-resources.mdx) for what you would like to access through the client. For example, to SSH into a server, create a resource like `22:localhost:22`.
|
||||
</Step>
|
||||
|
||||
<Step title="Verify connection">
|
||||
@@ -119,13 +119,7 @@ Sites have two operating modalities when accepting clients:
|
||||
|
||||
### Proxy Mode
|
||||
|
||||
When you run Newt with `--accept-clients` it will run fully in user space. This means you do not need to give the container or binary any special permissions. It will NOT create a virtual network interface on the host. Instead you should create raw TCP/UDP resources in Pangolin to configure what ports clients can hit and where they should go.
|
||||
|
||||
For example, if you wanted to SSH into your server you could add a resource for it:
|
||||
|
||||
<Frame caption="Pangolin UI showing example SSH resource.">
|
||||
<img src="/images/ssh_resource.png" alt="SSH Resource"/>
|
||||
</Frame>
|
||||
When you run Newt with `--accept-clients` it will run fully in user space. This means you do not need to give the container or binary any special permissions. It will NOT create a virtual network interface on the host. Instead you should create [client resources](../resources/client-resources.mdx) in Pangolin to configure what ports clients can hit and where they should go.
|
||||
|
||||
### Native Mode
|
||||
|
||||
@@ -137,26 +131,24 @@ In native mode with both `--accept-clients` and `--native`, Newt will create a n
|
||||
|
||||
#### Remote Subnets
|
||||
|
||||
Additionally, you can add remote subnets to the site settings in Pangolin to forward remote networks through Newt. This can let Newt act as a traditional VPN server to route to anything on your local network.
|
||||
In native mode, you can add remote subnets to the site settings in Pangolin to forward remote networks through Newt. This can let Newt act as a traditional VPN server to route to anything on your local network.
|
||||
|
||||
<Frame caption="Pangolin UI showing remote subnets for clients.">
|
||||
<img src="/images/remote_subnets.png" alt="Remote Subnets"/>
|
||||
</Frame>
|
||||
|
||||
This will configure a route on the Olm side of the tunnel to route this subnet down the tunnel. When it reaches the other end, can be routed to the appropriate destination by the host.
|
||||
|
||||
This may require Linux that you have forwarding enabled:
|
||||
|
||||
```bash
|
||||
sysctl -w net.ipv4.ip_forward=1
|
||||
```
|
||||
|
||||
And make it persistent:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/sysctl.conf
|
||||
|
||||
net.ipv4.ip_forward = 1
|
||||
```
|
||||
|
||||
...and [setup NAT](https://www.geeksforgeeks.org/linux-unix/using-masquerading-with-iptables-for-network-address-translation-nat/) or other routing so that destination networks can route back to the Olm client. Remember the source address of the packets will be the IP address of the Olm client in this situation and the destination will be an IP on the remote subnet network.
|
||||
|
||||
## Notes
|
||||
|
||||
- Clients require Olm to be running on the remote computer
|
||||
|
||||
216
manage/healthchecks-failover.mdx
Normal file
216
manage/healthchecks-failover.mdx
Normal file
@@ -0,0 +1,216 @@
|
||||
---
|
||||
title: "Health Checks & Failover"
|
||||
description: "Configure automated health monitoring and failover for high availability"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Health checks are only available for targets created with managed nodes or in the cloud.
|
||||
</Note>
|
||||
|
||||
## Overview
|
||||
|
||||
Pangolin provides automated health checking for [targets](./resources/targets.mdx) to ensure traffic is only routed to healthy services. When you create targets with managed nodes or in the cloud, you can optionally define health check parameters to monitor the availability and responsiveness of your services.
|
||||
|
||||
Health checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic routing and load balancing.
|
||||
|
||||
## How Health Checks Work
|
||||
|
||||
### Monitoring Process
|
||||
|
||||
Health checks operate continuously in the background:
|
||||
|
||||
1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals
|
||||
2. **Status Evaluation**: Responses are evaluated against your configured criteria
|
||||
3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded
|
||||
4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again
|
||||
|
||||
### Health Check vs Target Endpoint
|
||||
|
||||
<Card title="Flexible Monitoring">
|
||||
The health check endpoint can be the same as your target, but you can also monitor a different endpoint. This allows you to create dedicated health check endpoints that provide more detailed service status information.
|
||||
</Card>
|
||||
|
||||
## Target Health States
|
||||
|
||||
Targets can exist in three distinct states that determine how traffic is routed:
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Unknown" icon="question" color="#gray">
|
||||
**Initial State**: Targets start in this state before first health check
|
||||
|
||||
**Traffic Behavior**: Unknown targets still route traffic normally
|
||||
|
||||
**Duration**: Until first health check completes
|
||||
</Card>
|
||||
|
||||
<Card title="Unhealthy" icon="x" color="#red">
|
||||
**Failed Checks**: Target has failed health check criteria
|
||||
|
||||
**Traffic Behavior**: No traffic is routed to unhealthy targets
|
||||
|
||||
**Load Balancing**: Excluded from load balancing rotation
|
||||
</Card>
|
||||
|
||||
<Card title="Healthy" icon="check" color="#green">
|
||||
**Passing Checks**: Target is responding correctly to health checks
|
||||
|
||||
**Traffic Behavior**: Receives traffic according to load balancing rules
|
||||
|
||||
**Load Balancing**: Included in load balancing rotation
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Configuring Health Checks
|
||||
|
||||
<Steps>
|
||||
<Step title="Access Target Settings">
|
||||
In the Pangolin dashboard, navigate to your resource and locate the target in the table.
|
||||
</Step>
|
||||
|
||||
<Step title="Open Health Check Configuration">
|
||||
Click the settings wheel (⚙️) next to the health check endpoint column.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Health Check Parameters">
|
||||
Fill out the health check configuration with your desired parameters.
|
||||
</Step>
|
||||
|
||||
<Step title="Save Configuration">
|
||||
Save your settings to enable health checking for the target.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Health Check Parameters
|
||||
|
||||
### Endpoint Configuration
|
||||
|
||||
<Card title="Health Check Target">
|
||||
**Target Endpoint**: The URL or address to monitor for health status
|
||||
|
||||
**Default Behavior**: Usually the same as your target endpoint
|
||||
|
||||
**Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`)
|
||||
</Card>
|
||||
|
||||
### Timing Configuration
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Healthy Interval">
|
||||
**Purpose**: How often to check targets that are currently healthy
|
||||
|
||||
**Typical Range**: 30-60 seconds
|
||||
|
||||
**Consideration**: Less frequent checks reduce overhead
|
||||
</Card>
|
||||
|
||||
<Card title="Unhealthy Interval">
|
||||
**Purpose**: How often to check targets that are currently unhealthy
|
||||
|
||||
**Typical Range**: 10-30 seconds
|
||||
|
||||
**Consideration**: More frequent checks enable faster recovery
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Response Configuration
|
||||
|
||||
<Card title="Timeout Settings">
|
||||
**Request Timeout**: Maximum time to wait for a health check response
|
||||
|
||||
**Default Behavior**: Requests exceeding timeout are considered failed
|
||||
|
||||
**Recommended**: Set based on your service's typical response time
|
||||
</Card>
|
||||
|
||||
<Card title="HTTP Response Codes">
|
||||
**Healthy Codes**: Which HTTP status codes indicate a healthy target
|
||||
|
||||
**Common Settings**: 200, 201, 202, 204
|
||||
|
||||
**Custom Codes**: Configure based on your service's health endpoint behavior
|
||||
</Card>
|
||||
|
||||
## Failover Behavior
|
||||
|
||||
### Automatic Traffic Exclusion
|
||||
|
||||
When a target becomes unhealthy:
|
||||
|
||||
<Steps>
|
||||
<Step title="Health Check Failure">
|
||||
Target fails to meet health check criteria (response code, timeout, etc.)
|
||||
</Step>
|
||||
|
||||
<Step title="Status Update">
|
||||
Target status changes from "Healthy" to "Unhealthy"
|
||||
</Step>
|
||||
|
||||
<Step title="Traffic Removal">
|
||||
Target is immediately removed from traffic routing configuration
|
||||
</Step>
|
||||
|
||||
<Step title="Load Balancer Update">
|
||||
Load balancing configuration is updated to exclude the unhealthy target
|
||||
</Step>
|
||||
|
||||
<Step title="Continued Monitoring">
|
||||
Health checks continue at the unhealthy interval for recovery detection
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Automatic Recovery
|
||||
|
||||
When an unhealthy target recovers:
|
||||
|
||||
<Steps>
|
||||
<Step title="Successful Health Check">
|
||||
Target begins responding correctly to health checks
|
||||
</Step>
|
||||
|
||||
<Step title="Status Update">
|
||||
Target status changes from "Unhealthy" to "Healthy"
|
||||
</Step>
|
||||
|
||||
<Step title="Traffic Restoration">
|
||||
Target is automatically added back to traffic routing
|
||||
</Step>
|
||||
|
||||
<Step title="Load Balancer Update">
|
||||
Load balancing resumes including the recovered target
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## High Availability Strategies
|
||||
|
||||
### Multi-Target Redundancy
|
||||
|
||||
<Card title="Service Redundancy">
|
||||
Deploy multiple instances of your service across different targets to ensure availability even when some targets fail.
|
||||
</Card>
|
||||
|
||||
```
|
||||
Resource: web-application
|
||||
├── Target 1: web-01.local:8080 (Site A) - Healthy ✅
|
||||
├── Target 2: web-02.local:8080 (Site A) - Unhealthy ❌
|
||||
└── Target 3: web-03.local:8080 (Site B) - Healthy ✅
|
||||
|
||||
Traffic routes to: Target 1 & Target 3 only
|
||||
```
|
||||
|
||||
### Cross-Site Failover
|
||||
|
||||
<Card title="Geographic Distribution">
|
||||
Distribute targets across multiple sites to protect against site-level failures.
|
||||
</Card>
|
||||
|
||||
```
|
||||
Resource: api-service
|
||||
├── Primary Site Targets
|
||||
│ ├── api-01.primary:8443 - Healthy ✅
|
||||
│ └── api-02.primary:8443 - Healthy ✅
|
||||
└── Backup Site Targets
|
||||
├── api-01.backup:8443 - Healthy ✅
|
||||
└── api-02.backup:8443 - Healthy ✅
|
||||
|
||||
All targets receive traffic via load balancing
|
||||
```
|
||||
@@ -64,7 +64,7 @@ We're planning to add more analytics, alerting, and management tools to make you
|
||||
Ready to convert your existing self-hosted node to managed? Learn how in our [conversion guide](../self-host/convert-managed).
|
||||
|
||||
<Note>
|
||||
For detailed information about how nodes work and their advantages, see our [Nodes](/manage/nodes) documentation.
|
||||
For detailed information about how nodes work and their advantages, see our [nodes](/manage/nodes) documentation.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
|
||||
79
manage/resources/client-resources.mdx
Normal file
79
manage/resources/client-resources.mdx
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Client Resources"
|
||||
description: "Configure resources for Olm clients to access on a Newt site"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Site resources in Pangolin allow you to define specific ports and a destination that can be accessed through the VPN tunnel when using [Olm clients](../clients/add-client.mdx). This is useful for exposing internal services to your remote clients securely.
|
||||
|
||||
<Note>
|
||||
Site resources are only for exposing services on a Newt site to Olm clients running remotely and do not get proxied.
|
||||
</Note>
|
||||
|
||||
## Internal Exposure with Clients
|
||||
|
||||
Internal exposure resources are only accessible when connected via an Olm client. This approach is perfect for secure access to services without exposing them to the public internet.
|
||||
|
||||
When you run Newt with `--accept-clients`, it operates fully in user space without creating a virtual network interface on the host. This means:
|
||||
|
||||
- **No special permissions required** for the container or binary
|
||||
- **No virtual network interface** created on the host
|
||||
- **Client-only access** through Pangolin's tunnel
|
||||
- **Secure internal routing** to your services
|
||||
|
||||
## Configuring Site Resources
|
||||
|
||||
To configure site resources:
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Resources">
|
||||
Navigate to the **Resources** section in the Pangolin dashboard.
|
||||
</Step>
|
||||
<Step title="Select Site Resources">
|
||||
In the toggle at the top of the table, select "Site Resources".
|
||||
</Step>
|
||||
<Step title="Add Resource">
|
||||
Click **Add Resource**.
|
||||
</Step>
|
||||
<Step title="Choose Resource Type">
|
||||
Choose the resource type (TCP or UDP).
|
||||
</Step>
|
||||
<Step title="Configure Port and Target">
|
||||
Specify the local port and the target address.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Accessing Site Resources
|
||||
|
||||
Once configured, you can access these resources from your remote clients using the Olm tunnel.
|
||||
|
||||
### Example: SSH Access
|
||||
|
||||
Here's how to set up SSH access to your server when connected with a client:
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the resource">
|
||||
In the Pangolin dashboard, create a new client resource and set the port to `2022` (or any available port).
|
||||
|
||||
<Frame>
|
||||
<img src="/images/client_resource.png" width="400" centered/>
|
||||
</Frame>
|
||||
</Step>
|
||||
|
||||
<Step title="Connect and access">
|
||||
When connected with a Olm client, you can SSH to your server using `<site-address>:2022`.
|
||||
|
||||
```bash
|
||||
ssh user@100.90.128.0 -p 22
|
||||
```
|
||||
<Note>
|
||||
When accessing a site resource, you use the IP of the site found in the dashboard and the local port you configured for the resource.
|
||||
</Note>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
This approach is ideal for secure remote access without exposing SSH directly to the internet.
|
||||
</Note>
|
||||
|
||||
82
manage/resources/targets.mdx
Normal file
82
manage/resources/targets.mdx
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: "Targets"
|
||||
description: "Configure destination endpoints for resource routing and load balancing"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
When you create a resource in Pangolin, you define different targets that specify where traffic should be routed within your network. Each target represents a specific destination that the resource can proxy to when handling incoming requests.
|
||||
|
||||
<Note>
|
||||
Targets are created on the Newt tunnel, enabling traffic to reach destinations on the remote network without requiring additional routing configuration.
|
||||
</Note>
|
||||
|
||||
## How Targets Work
|
||||
|
||||
### Target Routing
|
||||
|
||||
Targets function as destination endpoints for your resources:
|
||||
|
||||
1. **Resource Creation**: When you create a resource, you configure one or more targets
|
||||
2. **Traffic Routing**: Incoming traffic is routed to the appropriate target based on your configuration
|
||||
3. **Network Access**: Newt proxy routes traffic to the local network through the tunnel
|
||||
4. **Direct Connection**: No additional routing is necessary on the remote network
|
||||
|
||||
## Multi-Site Targets (v1.9.0+)
|
||||
|
||||
With the introduction of update 1.9.0, targets now have sites associated with them. This enhancement provides significant benefits for reliability and load distribution.
|
||||
|
||||
### Site-Distributed Resources
|
||||
|
||||
You can now configure targets across different sites for the same resource:
|
||||
|
||||
<Card title="High Availability">
|
||||
Distribute your resources across multiple sites so that if one site goes down, traffic automatically continues to be served from other available sites.
|
||||
</Card>
|
||||
|
||||
<Card title="Load Balancing">
|
||||
Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets.
|
||||
</Card>
|
||||
|
||||
### Load Balancing Requirements
|
||||
|
||||
<Warning>
|
||||
Load balancing between different targets only works when sites are connected to the same node. In managed Pangolin instances with multiple nodes, ensure load balancing occurs on the same node.
|
||||
</Warning>
|
||||
|
||||
To ensure effective load balancing in multi-node environments:
|
||||
|
||||
```bash
|
||||
newt --prefer-endpoint <specific-endpoint> <other-args>
|
||||
```
|
||||
|
||||
<Note>
|
||||
Pangolin currently does not load balance between nodes, only between targets on the same node.
|
||||
</Note>
|
||||
|
||||
## Configuring Targets
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Resources">
|
||||
In the Pangolin dashboard, go to the **Resources** section.
|
||||
</Step>
|
||||
|
||||
<Step title="Create or Edit Resource">
|
||||
Either create a new resource or select an existing resource to edit.
|
||||
</Step>
|
||||
|
||||
<Step title="Add Target">
|
||||
Click **Add Target** to configure a new destination.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Target Details">
|
||||
Specify the target configuration:
|
||||
- **Address**: IP address or hostname of the target service
|
||||
- **Port**: Port number where the service is listening
|
||||
- **Site**: Select the site where this target is located
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Pangolin uses round-robin load balancing by default, distributing traffic evenly across all targets.
|
||||
</Note>
|
||||
@@ -80,37 +80,4 @@ Proxied resources require extra configuration to expose on the Pangolin server.
|
||||
|
||||
<Note>
|
||||
In this example, we expose port 1602 for TCP and port 1704 for UDP. You can use any available ports on your VPS.
|
||||
</Note>
|
||||
|
||||
## Internal Exposure with Clients
|
||||
|
||||
Internal exposure resources are only accessible when connected via an Olm client. This approach is perfect for secure access to services without exposing them to the public internet.
|
||||
|
||||
When you run Newt with `--accept-clients`, it operates fully in user space without creating a virtual network interface on the host. This means:
|
||||
|
||||
- **No special permissions required** for the container or binary
|
||||
- **No virtual network interface** created on the host
|
||||
- **Client-only access** through Pangolin's tunnel
|
||||
- **Secure internal routing** to your services
|
||||
|
||||
### Example: SSH Access
|
||||
|
||||
Here's how to set up SSH access to your server when connected with a client:
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the resource">
|
||||
In the Pangolin dashboard, create a new Raw TCP/UDP resource and set the port to `2022` (or any available port).
|
||||
</Step>
|
||||
|
||||
<Step title="Add the target">
|
||||
Configure the resource to target `localhost:22` (your SSH service).
|
||||
</Step>
|
||||
|
||||
<Step title="Connect and access">
|
||||
When connected with a Newt client, you can SSH to your server using `<site-address>:2022`.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
This approach is ideal for secure remote access without exposing SSH directly to the internet.
|
||||
</Note>
|
||||
</Note>
|
||||
Reference in New Issue
Block a user