{"id":27185185,"url":"https://github.com/xavieralpha/derper","last_synced_at":"2025-04-09T17:11:49.474Z","repository":{"id":262706182,"uuid":"886847547","full_name":"XavierAlpha/derper","owner":"XavierAlpha","description":"Tailscale custom derper image build","archived":false,"fork":false,"pushed_at":"2025-04-09T00:54:27.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T17:11:45.279Z","etag":null,"topics":["derp","derper","tailscale"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/camllia/derper","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XavierAlpha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-11T17:59:23.000Z","updated_at":"2025-04-09T00:54:30.000Z","dependencies_parsed_at":"2024-12-07T01:26:40.029Z","dependency_job_id":"ad3593ea-e51f-43d0-b4dd-2034ce955dcc","html_url":"https://github.com/XavierAlpha/derper","commit_stats":null,"previous_names":["xavieralpha/derper"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XavierAlpha%2Fderper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XavierAlpha%2Fderper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XavierAlpha%2Fderper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XavierAlpha%2Fderper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XavierAlpha","download_url":"https://codeload.github.com/XavierAlpha/derper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074964,"owners_count":21043490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["derp","derper","tailscale"],"created_at":"2025-04-09T17:11:48.716Z","updated_at":"2025-04-09T17:11:49.442Z","avatar_url":"https://github.com/XavierAlpha.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DERP in Docker\n\n## How To Use\n\u003e Image Source: camllia/derper:latest OR ghcr.io/xavieralpha/derper:latest\n\n\n```sh\n# install tailscale if VERIFY_CLIENTS=true; otherwise, ignore it.\ncurl -fsSL https://tailscale.com/install.sh | sh\n\n# if /bin/sh\ndocker pull camllia/derper:latest\ndocker run --rm -it camllia/derper /bin/sh\n```\n\n### DERP Server Environment Variables and Parameter Comparison Table\n\nThis table provides a detailed comparison and command-line parameters for the `derper` server, making it easier to configure and understand each feature.\n\n| **Environment Variable**   | **derper Command Parameter**             | **Default Value**                     |\n|----------------------------|------------------------------------------|---------------------------------------|\n| DEV                        | `-dev`                                   | `false`                               |\n| VERSION_FLAG               | `-version`                               | `false`                               |\n| ADDR                       | `-a`                                     | `:443`                                |\n| HTTP_PORT                  | `-http-port`                             | `80`                                  |\n| STUN_PORT                  | `-stun-port`                             | `3478`                                |\n| CONFIG_PATH                | `-c`                                     | `\"\"`                                  |\n| CERT_MODE                  | `-certmode`                              | `manual`                              |\n| CERT_DIR                   | `-certdir`                               | `derper-certs`                        |\n| HOSTNAME                   | `-hostname`                              | `127.0.0.1`                           |\n| RUN_STUN                   | `-stun`                                  | `true`                                |\n| RUN_DERP                   | `-derp`                                  | `true`                                |\n| FLAGHOME                   | `-home`                                  | `\"\"`                                  |\n| MESH_PSKFILE               | `-mesh-psk-file`                         | `\"\"`                                  |\n| MESH_WITH                  | `-mesh-with`                             | `\"\"`                                  |\n| SECRETS_URL                | `-secrets-url`                           | `\"\"`                                  |\n| SECRETS_PREFIX             | `-secrets-path-prefix`                   | `prod/derp`                           |\n| SECRETS_CACHEDIR           | `-secrets-cache-dir`                     | `derper-secrets`                      |\n| BOOTSTRAP_DNS              | `-bootstrap-dns-names`                   | `\"\"`                                  |\n| UNPUBLISHED_DNS            | `-unpublished-bootstrap-dns-names`       | `\"\"`                                  |\n| VERIFY_CLIENTS             | `-verify-clients`                        | `true`                                |\n| VERIFY_CLIENT_URL          | `-verify-client-url`                     | `\"\"`                                  |\n| VERIFY_FAIL_OPEN           | `-verify-client-url-fail-open`           | `true`                                |\n| SOCKET                     | `-socket`                                | `\"\"`                                  |\n| ACCEPT_CONNECTION_LIMIT    | `-accept-connection-limit`               | `+Inf`                                |\n| ACCEPT_CONNECTION_BURST    | `-accept-connection-burst`               | `9223372036854775807`                 |\n| TCP_KEEPALIVE_TIME         | `-tcp-keepalive-time`                    | `10m0s`                               |\n| TCP_USER_TIMEOUT           | `-tcp-user-timeout`                      | `15s`                                 |\n| TCP_WRITE_TIMEOUT          | `-tcp-write-timeout`                     | `2s`                                  |\n\n### RUN DERPER\n```sh\n# avoid SNI checks: Make sure certmode=manual and hostname is ip\ndocker run --restart=unless-stopped \\\n--name derper \\\n# -p 80:80 -p 443:443 -p 3478:3478/udp \\\n# -e CERT_MODE=manual \\\n# -e HOSTNAME=127.0.0.1 \\\n# -e ADDR=:443 \\\n# -e STUN_PORT=3478 \\\n# -e VERIFY_CLIENTS=true \\\n# -e CERT_DIR=derper-certs \\\n-v \"$(pwd)\"/derper-certs/:/root/derper-certs/ \\\n-v /var/run/tailscale/:/var/run/tailscale/ \\\n-d camllia/derper:latest\n# '-v /var/run/tailscale/:/var/run/tailscale/' Not necessary if VERIFY_CLIENTS=false\n```\n\n```yml\n# avoid SNI checks: Make sure certmode=manual and hostname is ip\nservices:\n  derper:\n    image: camllia/derper\n    container_name: derper\n    restart: unless-stopped\n    environment:\n    #   - CERT_DIR=derper-certs   # default\n    #   - CERT_MODE=manual        # default\n    #   - HOSTNAME=127.0.0.1      # default\n    #   - ADDR=:443               # default\n    #   - STUN_PORT=3478          # default\n    #   - VERIFY_CLIENTS=true     # default\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n      - \"3478:3478/udp\"\n    volumes:\n      - ./derper-certs/:/root/derper-certs/ # Match env \"CERT_DIR\"\n      - /var/run/tailscale/:/var/run/tailscale/ # (tailscaled.sock in linux) Not necessary if VERIFY_CLIENTS=false\n```\n\n\u003e **THEN** Run `docker logs derper`, copy the displayed \"CertName\":\"sha256-raw:xxx...xxx\", and add it to the `Nodes` section within the `derpMap` in ACL policy.\n\u003e \n\u003e ~~**NOTICE**: It is not yet available. You still need to set `\"InsecureForTests\": true` in the `Nodes` section of the `derpMap` within the ACL policy if you are **using a self-signed certificate**.~~\n\u003e\n\n### Custom tailscaled socket path (When VERIFY_CLIENTS=true)\nIf `-socket=\"\"`, the system will search for the socket based on the default location defined by the operating system.\n\n\u003e FROM [DefaultTailscaledSocket in tailscale.](https://github.com/tailscale/tailscale/blob/e80d2b4ad1e427c7700264a05d4bc8a6d95e29d7/paths/paths.go#L23)\n```go\n// DefaultTailscaledSocket returns the path to the tailscaled Unix socket\n// or the empty string if there's no reasonable default.\nfunc DefaultTailscaledSocket() string {\n\tif runtime.GOOS == \"windows\" {\n\t\treturn `\\\\.\\pipe\\ProtectedPrefix\\Administrators\\Tailscale\\tailscaled`\n\t}\n\tif runtime.GOOS == \"darwin\" {\n\t\treturn \"/var/run/tailscaled.socket\"\n\t}\n\tif runtime.GOOS == \"plan9\" {\n\t\treturn \"/srv/tailscaled.sock\"\n\t}\n\tswitch distro.Get() {\n\tcase distro.Synology:\n\t\tif distro.DSMVersion() == 6 {\n\t\t\treturn \"/var/packages/Tailscale/etc/tailscaled.sock\"\n\t\t}\n\t\t// DSM 7 (and higher? or failure to detect.)\n\t\treturn \"/var/packages/Tailscale/var/tailscaled.sock\"\n\tcase distro.Gokrazy:\n\t\treturn \"/perm/tailscaled/tailscaled.sock\"\n\tcase distro.QNAP:\n\t\treturn \"/tmp/tailscale/tailscaled.sock\"\n\t}\n\tif fi, err := os.Stat(\"/var/run\"); err == nil \u0026\u0026 fi.IsDir() {\n\t\treturn \"/var/run/tailscale/tailscaled.sock\"\n\t}\n\treturn \"tailscaled.sock\"\n}\n```\nOtherwise, the `SOCKET` environment variable needs to be set manually in docker.\n\n# DERP\n\u003e This section is from Tailscale's README file.\n\u003e\n\u003e BSD 3-Clause License\n\u003e \n\u003e Copyright (c) 2020 Tailscale Inc \u0026 AUTHORS.\n\nThis is the code for the [Tailscale DERP server](https://tailscale.com/kb/1232/derp-servers).\n\nIn general, you should not need to or want to run this code. The overwhelming\nmajority of Tailscale users (both individuals and companies) do not.\n\nIn the happy path, Tailscale establishes direct connections between peers and\ndata plane traffic flows directly between them, without using DERP for more than\nacting as a low bandwidth side channel to bootstrap the NAT traversal. If you\nfind yourself wanting DERP for more bandwidth, the real problem is usually the\nnetwork configuration of your Tailscale node(s), making sure that Tailscale can\nget direction connections via some mechanism.\n\nIf you've decided or been advised to run your own `derper`, then read on.\n\n## Caveats\n\n* Node sharing and other cross-Tailnet features don't work when using custom\n  DERP servers.\n\n* DERP servers only see encrypted WireGuard packets and thus are not useful for\n  network-level debugging.\n\n* The Tailscale control plane does certain geo-level steering features and\n  optimizations that are not available when using custom DERP servers.\n\n## Guide to running `cmd/derper`\n\n* You must build and update the `cmd/derper` binary yourself. There are no\n  packages. Use `go install tailscale.com/cmd/derper@latest` with the latest\n  version of Go. You should update this binary approximately as regularly as\n  you update Tailscale nodes. If using `--verify-clients`, the `derper` binary\n  and `tailscaled` binary on the machine must be built from the same git revision.\n  (It might work otherwise, but they're developed and only tested together.)\n\n* The DERP protocol does a protocol switch inside TLS from HTTP to a custom\n  bidirectional binary protocol. It is thus incompatible with many HTTP proxies.\n  Do not put `derper` behind another HTTP proxy.\n\n* The `tailscaled` client does its own selection of the fastest/nearest DERP\n  server based on latency measurements. Do not put `derper` behind a global load\n  balancer.\n\n* DERP servers should ideally have both a static IPv4 and static IPv6 address.\nBoth of those should be listed in the DERP map so the client doesn't need to\nrely on its DNS which might be broken and dependent on DERP to get back up.\n\n* A DERP server should not share an IP address with any other DERP server.\n\n* Avoid having multiple DERP nodes in a region. If you must, they all need to be\n  meshed with each other and monitored. Having two one-node \"regions\" in the\n  same datacenter is usually easier and more reliable than meshing, at the cost\n  of more required connections from clients in some cases. If your clients\n  aren't mobile (battery constrained), one node regions are definitely\n  preferred. If you really need multiple nodes in a region for HA reasons, two\n  is sufficient.\n\n* Monitor your DERP servers with [`cmd/derpprobe`](../derpprobe/).\n\n* If using `--verify-clients`, a `tailscaled` must be running alongside the\n  `derper`, and all clients must be visible to the derper tailscaled in the ACL.\n\n* If using `--verify-clients`, a `tailscaled` must also be running alongside\n  your `derpprobe`, and `derpprobe` needs to use `--derp-map=local`.\n\n* The firewall on the `derper` should permit TCP ports 80 and 443 and UDP port\n  3478.\n\n* Only LetsEncrypt certs are rotated automatically. Other cert updates require a\n  restart.\n\n* Don't use a firewall in front of `derper` that suppresses `RST`s upon\n  receiving traffic to a dead or unknown connection.\n\n* Don't rate-limit UDP STUN packets.\n\n* Don't rate-limit outbound TCP traffic (only inbound).\n\n## Diagnostics\n\nThis is not a complete guide on DERP diagnostics.\n\nRunning your own DERP services requires exeprtise in multi-layer network and\napplication diagnostics. As the DERP runs multiple protocols at multiple layers\nand is not a regular HTTP(s) server you will need expertise in correlative\nanalysis to diagnose the most tricky problems. There is no \"plain text\" or\n\"open\" mode of operation for DERP.\n\n* The debug handler is accessible at URL path `/debug/`. It is only accessible\n  over localhost or from a Tailscale IP address.\n\n* Go pprof can be accessed via the debug handler at `/debug/pprof/`\n\n* Prometheus compatible metrics can be gathered from the debug handler at\n  `/debug/varz`.\n\n* `cmd/stunc` in the Tailscale repository provides a basic tool for diagnosing\n  issues with STUN.\n\n* `cmd/derpprobe` provides a service for monitoring DERP cluster health.\n\n* `tailscale debug derp` and `tailscale netcheck` provide additional client\n  driven diagnostic information for DERP communications.\n\n* Tailscale logs may provide insight for certain problems, such as if DERPs are\n  unreachable or peers are regularly not reachable in their DERP home regions.\n  There are many possible misconfiguration causes for these problems, but\n  regular log entries are a good first indicator that there is a problem.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavieralpha%2Fderper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxavieralpha%2Fderper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxavieralpha%2Fderper/lists"}