# TunnelSats: Support & Troubleshooting Guide

<a id="official-support-channels"></a>
## 1. Official Support & Community Channels

Whether you are setting up your first hybrid Lightning node, migrating to our native Umbrel or StartOS 0.4 packages, or diagnosing a routing issue, our engineering team and fellow node runners are here to help:

- **Armada Nostr Community (Recommended - Encrypted & Scam-Resistant):** [Join TunnelSats on Armada](https://tunnelsats.com/join-armada)
  - Real-time community channels (`#general`), NIP-17 end-to-end encrypted direct messages, and interactive slash commands powered by the official **TunnelSats Bot** (`npub1n9z4y3xjramqes8fp9rl96x5e4nl0hff57ynw7vqnjpq370tq78sljsp8y`).
- **Telegram Community:** [Join Tunnel⚡Sats on Telegram](https://tunnelsats.com/join-telegram)
  - Active group chat with node operators and [@TunnelSatsBot](https://t.me/TunnelSatsBot) for quick clearnet `/ping` verification.
- **GitHub Issue Tracker:** [github.com/tunnelsats/tunnelsats/issues](https://github.com/tunnelsats/tunnelsats/issues)
  - Report bugs in `tunnelsats.sh`, request platform features, or review open-source scripts and firewall rules.
- **Amboss Community:** [TunnelSats Amboss Community](https://amboss.space/community/29db5f25-24bb-407e-b752-be69f9431071)
  - Connect with verified hybrid routing peers. Active subscribers can post their node link in Armada or Telegram (or run `/pendingqueue`) to receive the 3 required community approvals.
- **Direct Email & X:**
  - **Email:** [info@tunnelsats.com](mailto:info@tunnelsats.com) (for billing, payment hash inquiries, or private support)
  - **X (Twitter):** [@TunnelSats](https://x.com/TunnelSats)
- **Self-Service Documentation & Live Health:**
  - **[Setup Guide](/guide):** Step-by-step installation for Umbrel, StartOS 0.4, RaspiBlitz, RaspiBolt, myNode, and Bare Metal.
  - **[FAQ](/faq):** Answers on privacy, pricing, 100GB bandwidth resets, NWC auto-renewal, and server migration.
  - **[System Status](/status):** Real-time WireGuard gateway health and Globalping latency across all regions.

---

<a id="armada-nostr-community"></a>
## 2. What is Armada & How to Sign Up in 60 Seconds

### Why We Use Armada (`armada.buzz`)
**Armada** is a modern, Discord-style encrypted community platform built on **Nostr** (using the Concord V2 encrypted group protocol and NIP-17 private messages). Because it is relatively new, many node runners have not tried it yet - here is why we recommend it for support:

1. **Zero Personal Data Required:** Unlike Telegram or Discord, you **never** need to provide a phone number, email address, or SIM card to join.
2. **Cryptographic Anti-Scam Protection:** On Telegram and Discord, scammers frequently clone admin display names and avatars to DM users. On Armada, every moderator and our official **TunnelSats Bot** is verified by a cryptographic public key (`npub`), making impersonation mathematically impossible.
3. **Built-In Bot Autocomplete (`/`):** Type `/` in the chat input to run live node diagnostics (`/ping`, `/info`, `/servers`) or manage encrypted subscription expiry reminders (`/link`, `/tunnelsats`).

### How to Join TunnelSats on Armada (Step-by-Step)
1. **Open the Invite Link:** Click **[Join TunnelSats on Armada](https://tunnelsats.com/join-armada)** in any desktop or mobile browser.
2. **Create or Connect Your Nostr Key (Under 60 Seconds):**
   - **New to Nostr?** Click **Create Account / Generate Keys** directly inside Armada. Your browser generates a cryptographic keypair locally in one click - no signup form, email, or phone number required. *(Tip: Copy and save your secret key `nsec1...` in your password manager so you can log back in from any device).*
   - **Already have a Nostr identity?** Sign in with one click using your NIP-07 browser extension (**Alby**, **nos2x**, **Aca**) or NIP-46 remote signer.
3. **Accept the Community Invite:** Click **Join Community** to enter the encrypted TunnelSats space and say hello in `#general`!

### Official TunnelSats Bot Commands on Armada
Once inside Armada, type `/` in the message box (or open an encrypted DM with `npub1n9z4y3xjramqes8fp9rl96x5e4nl0hff57ynw7vqnjpq370tq78sljsp8y`) to use our interactive bot:

| Scope | Command | Description |
| :--- | :--- | :--- |
| **Channel or DM** | `/ping <pubkey>` | Probe clearnet TCP reachability and latency to your Lightning node's advertised VPN endpoint |
| **Channel or DM** | `/info <pubkey>` | Inspect your node's alias, capacity, channel count, and advertised Clearnet / Tor sockets |
| **Channel or DM** | `/servers` | View live status and load across all TunnelSats WireGuard gateways |
| **Channel or DM** | `/faq [topic]` | Search FAQ topics directly inside chat |
| **Channel or DM** | `/pendingqueue` | Check nodes waiting for Amboss Community approval |
| **Encrypted DM Only** | `/link <wgPublicKey>` | Privately link your WireGuard public key to receive automated DM alerts at **7, 3, and 1 days** before expiry |
| **Encrypted DM Only** | `/tunnelsats` | Check your linked subscription's active server, forwarded port, and exact expiration date |
| **Encrypted DM Only** | `/mute` / `/unmute` | Pause or resume automated DM expiration reminders |
| **Encrypted DM Only** | `/unlink [wgPublicKey]` | Remove a linked WireGuard public key from your Nostr identity |

---

<a id="troubleshooting-checklist"></a>
## 3. What We Need for Fast Troubleshooting

When asking for help in **Armada**, **Telegram**, or on **GitHub**, including the 4 details below allows our engineers to pinpoint the issue immediately:

### 1. Node Platform & OS Version
Tell us which platform you are running:
- **Umbrel:** e.g., `umbrelOS 1.3` or `1.4` (and whether you installed from the **Community App Store** or **Official App Store Secure Mode**)
- **StartOS:** e.g., `StartOS v0.4.0` (native TunnelSats package version)
- **RaspiBlitz / RaspiBolt / myNode / Bare Metal:** e.g., `RaspiBlitz v1.11.0` or `Ubuntu 22.04` (output of `uname -r` and `nft -v`)

### 2. Lightning Implementation & Version
- **LND** (e.g., `v0.18.5-beta` or `v0.21.3-beta`), **Core Lightning (CLN)** (e.g., `v24.11`), or **Eclair**

### 3. VPN Server Region & Forwarded Port
- Which TunnelSats server you are connected to (e.g., `de2.tunnelsats.com`, `us3.tunnelsats.com`, `sg1.tunnelsats.com`) and your assigned forwarding port (or your **WireGuard Public Key** `# myPubKey` so we can check server-side peer state).

### 4. Diagnostic Output from Your Node
Run the health check for your platform and share the output (after verifying no private keys are included):

- **RaspiBlitz / RaspiBolt / myNode / Bare Metal (`tunnelsats.sh`):**
  ```bash
  sudo bash tunnelsats.sh status
  sudo wg show
  ```
- **Umbrel App:**
  Open the TunnelSats App on your Umbrel -> click the **Health Check** tab -> share which checks pass or fail.
- **StartOS 0.4 Native Package:**
  Check the **Check inbound reachability** indicator in the TunnelSats web dashboard, or attach to your node container (`start-cli package attach lnd`) and run:
  ```bash
  wg show wg0
  ip rule
  ip route show table 51820
  ```

### Copy-Paste Support Request Template
```text
Platform & OS: [e.g. umbrelOS 1.4 / StartOS 0.4 / RaspiBlitz v1.11]
Lightning Node: [e.g. LND v0.18.5 / CLN v24.11]
VPN Server: [e.g. de2.tunnelsats.com]
Issue Summary: [e.g. Handshake succeeds in wg show, but inbound /ping times out]
Diagnostic Output:
[Paste output of `sudo bash tunnelsats.sh status` or App Health Check here]
```

---

<a id="common-quick-fixes"></a>
## 4. Common Quick Fixes & Self-Service Checks

Before opening a ticket, check these four most common issues:

1. **WireGuard Handshake Works (`wg show`), But Inbound `/ping` Times Out:**
   - Verify your Lightning node is listening on `0.0.0.0:9735` (`listen=0.0.0.0:9735` in `lnd.conf` or `bind-addr=0.0.0.0:9735` in CLN `config`) and that `externalhosts` / `announce-addr` matches your exact assigned `{vpnDNS}:{vpnPort}`.
   - On **Umbrel Official Store (Secure Mode)**, confirm you saved the `lnd.conf` / `config` changes and **restarted** the Lightning Node app from the Umbrel dashboard.
   - On **StartOS 0.4**, confirm you accepted the pending **clearnet-vpn** task on your Lightning node service after purchasing or importing your subscription.
2. **Outbound Connections Still Use Tor or Fail to Connect to Clearnet Peers:**
   - For **LND**, ensure both `tor.streamisolation=false` and `tor.skip-proxy-for-clearnet-targets=true` are set under `[Tor]` in `lnd.conf`.
   - For **CLN**, ensure `always-use-proxy=false` is set in `config`.
3. **Tunnel Stopped Passing Traffic Mid-Month (100GB Bandwidth Cap):**
   - Check your usage in **My Dashboard** on [tunnelsats.com](https://tunnelsats.com). If your node hit the 100GB monthly limit, you can reset your current month's counter back to `0` immediately for **$1** (**Reset bandwidth** button in Dashboard or StartOS package). Also ensure LND is updated to `v0.18.4+`.
4. **Still Using a Retiring Server (`de1.tunnelsats.com` or `de3.tunnelsats.com`):**
   - Open the **Renew** tab on [tunnelsats.com](https://tunnelsats.com), enter your WireGuard Public Key, and click **Review Consolidation Offer** to claim a free replacement `de2.tunnelsats.com` config (+30 bonus days and 7-day grace period).

---

<a id="security-anti-scam-policy"></a>
## 5. Security & Anti-Scam Policy

> **Critical Security Rule:** TunnelSats engineers, moderators, and bots will **NEVER** message you first asking for payments, seed phrases, SSH credentials, or your WireGuard `PrivateKey`.

- **What IS Safe to Share with Support:**
  - Your **WireGuard Public Key** (`# myPubKey` in `tunnelsats_<server>.conf` or `public key` in `sudo wg show`)
  - Your **Lightning Node Public Key** (`identity_pubkey`)
  - Your assigned server hostname (e.g., `de2.tunnelsats.com`) and forwarded TCP port
  - Output of `sudo bash tunnelsats.sh status`
- **What You Must NEVER Share (Publicly or in DMs):**
  - Your WireGuard **`PrivateKey`** or **`PresharedKey`** (anyone with your `PrivateKey` can hijack your tunnel port or claim your server consolidation offer)
  - Your full unredacted `tunnelsats_<server>.conf` file
  - Your Nostr secret key (`nsec1...`) or Lightning wallet seed words

*Automated Protection on Armada:* If someone accidentally pastes a WireGuard key or runs `/link <wgPublicKey>` in a public Armada channel, the TunnelSats Bot automatically issues a Nostr `Kind 5` deletion request to redact the message and sends a safety warning.