From ca3977270ff8dc4ce7df026321d6533b5b708241 Mon Sep 17 00:00:00 2001 From: Ghassan Yusuf Date: Wed, 25 Feb 2026 10:58:25 +0300 Subject: [PATCH] Add readme.md --- readme.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 readme.md diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..1600e19 --- /dev/null +++ b/readme.md @@ -0,0 +1,189 @@ +# Tailscale in Proxmox LXC + +This document describes how to run **Tailscale** inside a Proxmox LXC container, including enabling `/dev/net/tun` and optionally using the container as a subnet router. [tailscale](https://tailscale.com/docs/features/containers/lxc/lxc-unprivileged) + +## Prerequisites + +- Proxmox VE 7 or newer. [github](https://github.com/mossc001/Tailscale-LXC/blob/main/Guide) +- An LXC container (Debian/Ubuntu or similar; examples assume Debian/Ubuntu). [nihalatwal](https://nihalatwal.com/projects/tailscale-subnet-router-proxmox/) +- Access to the Proxmox host shell and the container shell. [github](https://github.com/mossc001/Tailscale-LXC/blob/main/Guide) + +*** + +## 1. Create the LXC container + +Create an LXC container from a standard Debian/Ubuntu template (e.g. `debian-12-standard` or `ubuntu-22.04-standard`). Keep resources minimal unless you plan to route a lot of traffic. [nihalatwal](https://nihalatwal.com/projects/tailscale-subnet-router-proxmox/) + +Example (GUI): + +- Download Debian/Ubuntu CT template from Proxmox templates. +- Click **Create CT**, choose the template, set hostname (e.g. `tailscale-lxc`), disk ~8–16 GB, RAM 512–2048 MB, and assign a static IP if desired. [github](https://github.com/mossc001/Tailscale-LXC/blob/main/Guide) + +Start the container when finished. + +*** + +## 2. Enable `/dev/net/tun` for the container + +On the Proxmox **host**, edit the container config: + +```bash +nano /etc/pve/lxc/.conf +``` + +Append the following lines (for Proxmox 7+ with cgroup2): [github](https://github.com/tailscale/tailscale/issues/825) + +```ini +lxc.cgroup2.devices.allow: c 10:200 rwm +lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file +``` + +For older Proxmox with cgroup v1, the key name differs: [github](https://github.com/mossc001/Tailscale-LXC/blob/main/Guide) + +```ini +lxc.cgroup.devices.allow: c 10:200 rwm +lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file +``` + +Restart the container to apply the changes: + +```bash +pct stop +pct start +``` + +Inside the container, verify TUN exists: + +```bash +ls -l /dev/net/tun +# Expect: character device with major 10, minor 200 +``` + +*** + +## 3. Install Tailscale inside the LXC + +Inside the container: + +```bash +apt update && apt upgrade -y +apt install -y curl +``` + +Install Tailscale using the official Linux installer: [tailscale](https://tailscale.com/docs/install/linux) + +```bash +curl -fsSL https://tailscale.com/install.sh | sh +``` + +Enable and start the service: + +```bash +systemctl enable --now tailscaled +``` + +You can check status with: + +```bash +systemctl status tailscaled +``` + +*** + +## 4. Bring the node onto your tailnet + +On the container: + +```bash +tailscale up +``` + +Follow the URL printed in the terminal to authenticate the node in your Tailscale admin console. [tailscale](https://tailscale.com/docs/install/linux) + +After that, verify it has a Tailscale IP: + +```bash +tailscale ip +tailscale status +``` + +You should see an IP in the `100.x.y.z` range and the node listed as connected. [tailscale](https://tailscale.com/docs/install/linux) + +*** + +## 5. Enable IP forwarding (for subnet router use) + +If you want this LXC to act as a **subnet router** for your LAN, enable IP forwarding inside the container: [imoize.github](https://imoize.github.io/getstart/docs/proxmox/lxc/tailscale-subnet-router) + +```bash +echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.conf +echo 'net.ipv6.conf.all.forwarding = 1' | sudo tee -a /etc/sysctl.conf +sudo sysctl -p /etc/sysctl.conf +``` + +Alternatively, use a dedicated sysctl drop-in such as `/etc/sysctl.d/99-tailscale.conf` with similar content. [imoize.github](https://imoize.github.io/getstart/docs/proxmox/lxc/tailscale-subnet-router) + +*** + +## 6. Configure Tailscale as a subnet router (optional) + +Decide which LAN subnets behind the LXC you want to advertise, e.g. `192.168.1.0/24`. [imoize.github](https://imoize.github.io/getstart/docs/proxmox/lxc/tailscale-subnet-router) + +Run: + +```bash +sudo tailscale up --advertise-routes=192.168.1.0/24 +``` + +If you are using a local DNS (Pi-hole etc.) and do **not** want Tailscale to override DNS, you can add: [github](https://github.com/mossc001/Tailscale-LXC/blob/main/Guide) + +```bash +sudo tailscale up \ + --advertise-routes=192.168.1.0/24 \ + --accept-dns=false +``` + +Then, in the Tailscale admin console: + +1. Go to **Machines**. +2. Find this LXC node. +3. Click the three-dot menu → **Edit route settings**. +4. Approve the advertised subnet routes. [imoize.github](https://imoize.github.io/getstart/docs/proxmox/lxc/tailscale-subnet-router) + +After approval, devices on your tailnet can reach the advertised subnet via this container. [nihalatwal](https://nihalatwal.com/projects/tailscale-subnet-router-proxmox/) + +*** + +## 7. Userspace networking mode (no TUN, optional) + +If you cannot or do not want to expose `/dev/net/tun`, you can run Tailscale in **userspace networking** mode inside the LXC: [tailscale](https://tailscale.com/docs/containers-and-virtualization) + +```bash +tailscaled --tun=userspace-networking & +tailscale up --tun=userspace-networking +``` + +This avoids needing a TUN device but may have limitations and different performance characteristics compared to kernel TUN mode. [tailscale](https://tailscale.com/docs/features/containers/lxc/lxc-unprivileged) + +*** + +## 8. Troubleshooting + +- **`failed to connect to local tailscaled`** + - Ensure `tailscaled` is running: `systemctl status tailscaled`. + - Confirm `/dev/net/tun` exists and the Proxmox config lines were added correctly. [github](https://github.com/tailscale/tailscale/issues/825) + +- **Container starts but no Tailscale traffic** + - Check IP forwarding and firewall rules inside the LXC. + - For subnet router scenarios, verify routes are approved in the Tailscale admin console. [nihalatwal](https://nihalatwal.com/projects/tailscale-subnet-router-proxmox/) + +- **Unprivileged LXC specifics** + - The `/dev/net/tun` configuration in the Proxmox LXC config is enough for kernel TUN even in unprivileged LXCs starting with Proxmox 7, as shown in the official LXC + Tailscale guidance. [youtube](https://www.youtube.com/watch?v=JC63OGSzTQI) + +*** + +## References + +- Tailscale LXC / unprivileged guide. [tailscale](https://tailscale.com/docs/features/containers/lxc/lxc-unprivileged) +- Example Proxmox LXC + Tailscale setup. [nihalatwal](https://nihalatwal.com/projects/tailscale-subnet-router-proxmox/) +- Containers and virtualization notes for Tailscale. [tailscale](https://tailscale.com/docs/containers-and-virtualization) \ No newline at end of file