### Start NetBird Daemon

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Ensure the NetBird daemon is running before using the 'expose' command. This command starts the daemon if it's not already active.

```bash
netbird up
```

--------------------------------

### Expose Local Development Server

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Quickly expose a local development server running on port 3000 for a demo. Requires the server to be started first (e.g., with 'npm run dev').

```bash
# Start your dev server
npm run dev  # Runs on port 3000

# In another terminal, expose it
netbird expose 3000 --with-name-prefix demo
```

--------------------------------

### Start NetBird Containers

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

After modifying the database, restart all NetBird containers to apply the changes.

```bash
docker compose start
```

--------------------------------

### Common Service Bind Address Configurations

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Examples of common configuration settings for services that control the network interface they listen on. Adjusting these can resolve issues with services only accessible locally.

```properties
# Common examples across different services
bind-address = 0.0.0.0
host: 0.0.0.0
listen_addresses = '*'
server.host: "0.0.0.0"
```

--------------------------------

### Start Packet Capture with Port Filter

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Initiates a network packet capture filtered by a specific component ID and target port. Ensure you replace `<component-id>` and `<target-port>` with actual values.

```bash
pktmon start --capture --pkt-size 0 -c <component-id> -t <target-port>
```

--------------------------------

### Retrieve Proxy Events API

Source: https://docs.netbird.io/manage/reverse-proxy/access-logs

Use this GET request to programmatically retrieve access logs for your reverse proxy services. No specific setup is required beyond having access to the NetBird API.

```bash
GET /api/events/proxy
```

--------------------------------

### Wireshark Display Filters

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Examples of display filters for Wireshark to narrow down network traffic. These filters help in analyzing captured packets by specifying ports or IP addresses.

```text
tcp.port == 
ip.addr == 
```

--------------------------------

### Inspect Specific Client Status in NetBird Proxy

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Get detailed status for a specific client connected to the NetBird proxy. Allows filtering by IP, connection status, or connection type.

```bash
netbird-proxy debug status <account-id>
```

```bash
# Filter by peer IP
netbird-proxy debug status <account-id> --filter-by-ips 10.0.0.10
```

```bash
# Filter by connection status
netbird-proxy debug status <account-id> --filter-by-status connected
```

```bash
# Filter by connection type
netbird-proxy debug status <account-id> --filter-by-connection-type P2P
```

--------------------------------

### GET /api/events/proxy

Source: https://docs.netbird.io/manage/reverse-proxy/access-logs

Retrieves access logs for NetBird reverse proxy services. These logs capture details of HTTP requests and L4 connections passing through the proxy.

```APIDOC
## GET /api/events/proxy

### Description
Retrieves access logs for NetBird reverse proxy services. These logs capture details of HTTP requests and L4 connections passing through the proxy, including information like timestamp, protocol, source IP, and status codes.

### Method
GET

### Endpoint
/api/events/proxy

### Parameters
#### Query Parameters
- **startTime** (string) - Optional - Filter logs starting from this timestamp.
- **endTime** (string) - Optional - Filter logs up to this timestamp.
- **protocol** (string) - Optional - Filter by protocol (`http`, `tcp`, `udp`, `tls`).
- **status** (string) - Optional - Filter by status code (for HTTP).
- **sourceIp** (string) - Optional - Filter by client IP address.
- **limit** (integer) - Optional - Maximum number of logs to return.
- **offset** (integer) - Optional - Number of logs to skip for pagination.

### Response
#### Success Response (200)
- **logs** (array) - An array of log objects.
  - **timestamp** (string) - When the request or connection occurred.
  - **protocol** (string) - `http`, `tcp`, `udp`, or `tls`.
  - **method** (string) - HTTP method or protocol name for L4.
  - **hostUrl** (string) - Domain and path for HTTP, or host:port for L4.
  - **statusCode** (integer) - HTTP status code (for HTTP).
  - **duration** (integer) - Request or connection duration in milliseconds.
  - **bytesUploaded** (integer) - Bytes sent from client to backend.
  - **bytesDownloaded** (integer) - Bytes sent from backend to client.
  - **sourceIp** (string) - The client's IP address.
  - **location** (object) - Geolocation information (country, city, subdivision).
  - **authMethod** (string) - Authentication method used (for HTTP).
  - **user** (string) - Authenticated user's ID (for HTTP with SSO).
  - **reason** (string) - Reason for denial, if applicable.

#### Response Example
```json
{
  "logs": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "protocol": "http",
      "method": "GET",
      "hostUrl": "example.com/path",
      "statusCode": 200,
      "duration": 50,
      "bytesUploaded": 100,
      "bytesDownloaded": 500,
      "sourceIp": "192.168.1.100",
      "location": {
        "country": "USA",
        "city": "New York",
        "subdivision": "NY"
      },
      "authMethod": "SSO",
      "user": "user123",
      "reason": null
    },
    {
      "timestamp": "2023-10-27T10:01:00Z",
      "protocol": "tcp",
      "method": "tcp",
      "hostUrl": "internal-service:8080",
      "statusCode": null,
      "duration": 120000,
      "bytesUploaded": 10240,
      "bytesDownloaded": 20480,
      "sourceIp": "10.0.0.5",
      "location": {
        "country": "Canada",
        "city": "Toronto",
        "subdivision": "ON"
      },
      "authMethod": null,
      "user": null,
      "reason": "ip_restricted"
    }
  ]
}
```
```

--------------------------------

### Configure Access Log Retention (YAML)

Source: https://docs.netbird.io/manage/reverse-proxy/access-logs

Define how long access logs are kept and how often expired entries are removed using YAML format. This applies to the self-hosted NetBird setup.

```yaml
reverseProxy:
  accessLogRetentionDays: 7
  accessLogCleanupIntervalHours: 24

```

--------------------------------

### Expose Service with Name Prefix

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a service on port 8080 and prepend a readable prefix ('myapp') to the generated subdomain. This results in a domain like 'myapp-a1b2c3.proxy.example.com'. The prefix must follow specific naming rules.

```bash
netbird expose 8080 --with-name-prefix myapp

```

--------------------------------

### List Network Interfaces (Windows)

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use 'pktmon list' on Windows to identify the network adapter used by WireGuard or NetBird. This is a preliminary step before capturing traffic.

```bash
# List network interfaces to find the WireGuard/NetBird adapter
pktmon list
```

--------------------------------

### Expose Service with TLS Passthrough

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a service on port 4443 that handles its own TLS termination, using a custom domain 'tls.example.com'.

```bash
netbird expose --protocol tls --with-custom-domain tls.example.com 4443
```

--------------------------------

### Expose Service with Custom Domain

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a service on port 8080 using a custom domain you own ('app.example.com'). Ensure the custom domain is pre-configured and verified in your NetBird account.

```bash
netbird expose 8080 --with-custom-domain app.example.com

```

--------------------------------

### Test IdP Connectivity from Host Machine

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Run this command to verify that the IdP is accessible from the host machine. If this works but the containerized test fails, it indicates a reverse proxy or network issue.

```bash
curl -s https:///.well-known/openid-configuration
```

--------------------------------

### Combine Multiple Authentication Methods

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a service on port 8080 with multiple authentication options: a PIN, a backup password, and SSO group restriction. Users can choose which method to use.

```bash
netbird expose 8080 --with-pin 123456 --with-password backup-password --with-user-groups admin

```

--------------------------------

### Verifying Domain DNS Configuration

Source: https://docs.netbird.io/manage/reverse-proxy/custom-domains

Use this command to check if the wildcard CNAME record for your domain is correctly configured and has propagated. This is crucial for domain verification. Ensure the domain matches your configuration.

```bash
dig CNAME *.proxy.example.com
```

--------------------------------

### Constructing a Service URL

Source: https://docs.netbird.io/manage/reverse-proxy/custom-domains

This illustrates the format for constructing a public URL for a service by combining a subdomain and a base domain. Ensure the subdomain and base domain are correctly specified.

```plaintext
{subdomain}.{base-domain}
```

--------------------------------

### Check Management Server Logs

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Monitor the NetBird management server logs after restarting the containers to verify that the IdP connector initializes successfully.

```bash
docker logs netbird-server --tail 20
```

--------------------------------

### Expose Local Service via CLI

Source: https://docs.netbird.io/manage/reverse-proxy

Use this command to expose a local service running on a specific port. The service will be temporarily available as long as the command is running. Ensure the Peer Expose feature is enabled in NetBird settings.

```bash
netbird expose 8080
```

--------------------------------

### Expose Staging Server with Password Protection

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a staging server running on port 8080 with password protection. The password 'staging-review' is used for authentication.

```bash
netbird expose 8080 --with-password staging-review --with-name-prefix staging
```

--------------------------------

### Expose Local PostgreSQL Instance over TCP

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a local PostgreSQL database running on the default port 5432 using the TCP protocol.

```bash
netbird expose --protocol tcp 5432
```

--------------------------------

### Check Service Listening Interface

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Ensure the target service is listening on the correct network interface (0.0.0.0, NetBird IP, or destination IP), not localhost. Use `ss` for Linux or `lsof` for macOS.

```bash
# 6. Is the service listening on the right interface?
ss -tlnp | grep <port>
```

```bash
# or on macOS:
lsof -iTCP:<port> -sTCP:LISTEN
```

--------------------------------

### Expose Local UDP Game Server on Specific Port

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a local UDP game server on port 27015, mapping it to the external port 27015.

```bash
netbird expose --protocol udp --with-external-port 27015 27015
```

--------------------------------

### Home Assistant Trusted Proxies Configuration

Source: https://docs.netbird.io/manage/reverse-proxy/service-configuration

Configure Home Assistant's `configuration.yaml` to enable `use_x_forwarded_for` and list trusted proxies. This ensures Home Assistant correctly identifies client IPs when behind the NetBird Reverse Proxy.

```yaml
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 100.64.0.0/10
```

--------------------------------

### Home Assistant with Docker Bridge Network

Source: https://docs.netbird.io/manage/reverse-proxy/service-configuration

If Home Assistant runs on the same Docker bridge network as the NetBird add-on, include both the NetBird range and the Docker bridge subnet in `trusted_proxies`.

```yaml
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 100.64.0.0/10
    - 172.16.0.0/12
```

--------------------------------

### Test Local Service Reachability

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Confirm that the routing peer can reach the target service locally. Use `curl` for general testing or `wget` within a Docker container.

```bash
# 3. Can the routing peer reach the target service locally?
# From the routing peer (or inside its container):
curl -sS -o /dev/null -w "%{http_code}" http://<target-ip>:<port> --max-time 5
```

```bash
# Docker:
docker exec <routing-peer-container> wget -qO- http://<target-ip>:<port> --timeout=5
```

--------------------------------

### Expose Local HTTP Server

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Use the `netbird expose` command to expose a local HTTP server running on a specific port. The command outputs a public URL and keeps the session alive until stopped.

```bash
netbird expose 8080

```

--------------------------------

### Expose Local L4 Service (TCP)

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

To expose a TCP, UDP, or TLS service, use the `--protocol` flag with the `netbird expose` command. For L4 services, the output includes the external port on the proxy cluster.

```bash
netbird expose --protocol tcp 5432

```

--------------------------------

### Netbird Expose Command Reference

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

The `netbird expose` command allows exposing local ports with various flags for protocol, authentication, and domain customization. Authentication flags are only supported for HTTP/HTTPS protocols.

```bash
netbird expose <port> [flags]

```

--------------------------------

### Check Listening Network Address (macOS)

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use the 'lsof' command on macOS to list open files and network connections, specifically to check which address and port a service is listening on.

```bash
# macOS
lsof -iTCP:<port> -sTCP:LISTEN
```

--------------------------------

### Expose Service with Password Protection

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Secure a service on port 8080 using a password. Access is granted only to users who provide the correct password.

```bash
netbird expose 8080 --with-password mysecretpassword

```

--------------------------------

### Enable Peer Expose via API

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

An account administrator can enable the 'Peer Expose' feature and specify allowed peer groups using the NetBird API. This configuration is applied to account settings.

```bash
curl -X PUT "https://api.netbird.io/api/accounts/{account_id}" \
  -H "Authorization: Token {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "peer_expose_enabled": true,
      "peer_expose_groups": ["ch8i4ug6lnn4g9hqv7m0"]
    }
  }'

```

--------------------------------

### Check Listening Network Address (Linux)

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use the 'ss' command on Linux to check which network addresses and ports a service is listening on. This is crucial for diagnosing services bound only to localhost.

```bash
# Linux
ss -tlnp | grep <port>
```

--------------------------------

### Expose Local Webhook Endpoint

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Temporarily expose a local webhook endpoint running on port 9000 for testing purposes.

```bash
netbird expose 9000 --with-name-prefix webhooks
```

--------------------------------

### Check Listening Network Address (Windows)

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use PowerShell's Get-NetTCPConnection cmdlet on Windows to identify the local address and port a service is listening on. This helps determine if a service is only accessible locally.

```powershell
# Windows (PowerShell)
Get-NetTCPConnection -LocalPort <port> -State Listen | Select-Object LocalAddress,LocalPort
```

--------------------------------

### List Connected Clients in NetBird Proxy

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Display all connected clients to the NetBird proxy, including their service counts and status. Use the `--json` flag for structured output.

```bash
netbird-proxy debug clients
```

--------------------------------

### Management Server Log Error

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

This log entry indicates a failure in initializing the connector, often due to a 403 Forbidden error when the management server tries to reach the external identity provider.

```log
ERRO [err: failed to open connector: failed to create connector : failed to get provider: 403 Forbidden: Forbidden
] idp/dex/logrus_handler.go:83: Failed to get connector
```

--------------------------------

### Expose Service for Team Access via SSO

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Expose a service on port 8080 restricted to users in the 'engineering' group via SSO authentication.

```bash
netbird expose 8080 --with-user-groups engineering --with-name-prefix internal-api
```

--------------------------------

### Configure Nextcloud Trusted Proxies

Source: https://docs.netbird.io/manage/reverse-proxy/service-configuration

Add the NetBird CIDR range to the `trusted_proxies` array in your Nextcloud `config/config.php` file. This allows Nextcloud to correctly identify the real client IP from the `X-Forwarded-For` header when requests pass through the NetBird reverse proxy.

```php
'trusted_proxies' => ['100.64.0.0/10'],

```

--------------------------------

### Expose Service with PIN Protection

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Protect a service running on port 8080 with a 6-digit PIN. Users must enter this PIN before accessing the service.

```bash
netbird expose 8080 --with-pin 123456

```

--------------------------------

### Expose L4 Service with Custom External Port

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Specify a custom external port for an L4 service using the `--with-external-port` flag. If the proxy cluster does not support custom ports, the port will be auto-assigned and noted in the output.

```bash
netbird expose --protocol tcp --with-external-port 15432 5432

```

--------------------------------

### Check Local Service Reachability

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Verify if a service is accessible locally on the routing peer machine outside of the NetBird tunnel. This helps diagnose issues where the reverse proxy cannot reach the target service.

```bash
docker exec <routing-peer-container> wget -qO- http://10.0.0.10:32400 --timeout=5
```

--------------------------------

### Test IdP Connectivity from Management Server Container

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use this command to test if the management server container can reach the IdP's OIDC discovery endpoint through the reverse proxy. This helps diagnose geo-restriction issues.

```bash
docker run --rm --network container:netbird-server curlimages/curl -s https:///.well-known/openid-configuration
```

--------------------------------

### Set Client Log Level for NetBird Proxy Debugging

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Temporarily adjust the log level for a specific client connected to the NetBird proxy to aid in debugging. Valid levels include trace, debug, info, warn, and error.

```bash
netbird-proxy debug log level <account-id> <level>
```

--------------------------------

### Enable NetBird Proxy Debug Endpoint

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Enable the debug endpoint for self-hosted NetBird proxy deployments to facilitate deeper diagnostics. This can be done via an environment variable or a CLI flag.

```bash
# Environment variable (e.g., in Docker Compose)
NB_PROXY_DEBUG_ENDPOINT=true
```

```bash
# Or as a CLI flag
netbird-proxy --debug-endpoint
```

--------------------------------

### Capture Traffic on NetBird Interface (Linux)

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use tcpdump on Linux to capture network traffic on the NetBird WireGuard interface (e.g., wt0). This helps determine if packets are reaching the interface.

```bash
# Capture traffic on the WireGuard interface (wt0 is the default NetBird interface)
sudo tcpdump -i wt0 -n port <target-port>

# Capture on all interfaces to see where traffic arrives
sudo tcpdump -i any -n port <target-port>

# Save to a file for later analysis
sudo tcpdump -i wt0 -n port <target-port> -w /tmp/capture.pcap
```

--------------------------------

### Configure Access Log Retention (JSON)

Source: https://docs.netbird.io/manage/reverse-proxy/access-logs

Set the duration for access log retention and the interval for cleanup in JSON format. This configuration is for the self-hosted version of NetBird.

```json
{
    "ReverseProxy": {
        "AccessLogRetentionDays": 7,
        "AccessLogCleanupIntervalHours": 24
    }
}

```

--------------------------------

### Exceeding Maximum Expose Sessions

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

This message indicates that a peer has reached the limit of 10 active expose sessions. To create more, stop an existing session or use the dashboard for permanent services.

```bash
peer has reached the maximum number of active expose sessions (10)

```

--------------------------------

### Test TCP Connectivity via NetBird Proxy Client

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Test TCP connectivity from the NetBird proxy through a specific client to a target host and port. Defaults to port 80 if not specified.

```bash
netbird-proxy debug ping <account-id> <host> [port]
```

```bash
# Test if the proxy can reach a service at 10.0.0.10:32400 through the client
netbird-proxy debug ping <account-id> 10.0.0.10 32400
```

--------------------------------

### Stop Packet Capture and Convert to PCAPNG

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Stops the ongoing packet capture and converts the resulting ETL file to a PCAPNG format, which can be opened in Wireshark. The output file will be named `capture.pcapng`.

```bash
pktmon stop
pktmon etl2pcap pktmon.etl -o capture.pcapng
```

--------------------------------

### View NetBird Proxy Sync Response

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Retrieve and display the latest synchronization response for a client from the NetBird proxy. This includes service and peer configuration details received from the management server.

```bash
netbird-proxy debug sync-response <account-id>
```

--------------------------------

### Capture Traffic on macOS NetBird Interface

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

On macOS, NetBird uses utun interfaces. Use tcpdump to capture traffic on the specific utun interface identified by 'ifconfig'.

```bash
# NetBird uses utun interfaces on macOS. Find yours with ifconfig
sudo tcpdump -i utun4 -n port <target-port>
```

--------------------------------

### Check NetBird Proxy Health

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Use the `netbird-proxy debug health` command to check the management connection state and overall client health. Supports `--json` for machine-readable output.

```bash
netbird-proxy debug health
```

--------------------------------

### Identify NetBird Service ID

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Query the NetBird management database to find the ID, domain, and restrictions for your services. This is necessary to identify the correct service for modification.

```bash
docker run --rm --user root -v :/data --entrypoint sqlite3 keinos/sqlite3 /data/store.db \
  "SELECT id, domain, restrictions FROM services;"
```

--------------------------------

### Check NetBird Connection Status

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Verify if the NetBird service is connected on the routing peer. This is a fundamental step in diagnosing connectivity issues.

```bash
# 1. Is NetBird connected on the routing peer?
netbird status -d
```

--------------------------------

### Recommended NetBird Trusted Proxy Range

Source: https://docs.netbird.io/manage/reverse-proxy/service-configuration

Configure your backend to trust the entire NetBird CGNAT range for resilience against IP changes. This is safe as only authorized peers can access the service.

```text
100.64.0.0/10
```

--------------------------------

### Expose Service with SSO User Group Restriction

Source: https://docs.netbird.io/manage/reverse-proxy/expose-from-cli

Restrict access to a service on port 8080 to users belonging to specified groups ('engineering', 'devops') within your identity provider. Users must authenticate via OIDC and be in one of these groups.

```bash
netbird expose 8080 --with-user-groups engineering,devops

```

--------------------------------

### Stop NetBird Containers

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Before modifying the management database, stop all NetBird containers using Docker Compose.

```bash
cd ~/netbird
docker compose stop
```

--------------------------------

### Configure NetBird Proxy Debug Endpoint Address

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Customize the listening address for the NetBird proxy debug endpoint. This can be set using an environment variable or a CLI flag.

```bash
NB_PROXY_DEBUG_ENDPOINT_ADDRESS=localhost:9090
# Or
netbird-proxy --debug-endpoint --debug-endpoint-addr localhost:9090
```

--------------------------------

### Clear Geo-Restriction from IdP Service

Source: https://docs.netbird.io/manage/reverse-proxy/troubleshooting

Update the NetBird management database to remove geo-restrictions from a specific service by setting its restrictions to an empty JSON object. Replace with the actual service ID.

```bash
docker run --rm --user root -v :/data --entrypoint sqlite3 keinos/sqlite3 /data/store.db \
  "UPDATE services SET restrictions='{}' WHERE id='';"
```