{"id":13558343,"url":"https://github.com/WebThingsIO/registration_server","last_synced_at":"2025-04-03T13:31:01.337Z","repository":{"id":55920665,"uuid":"86094492","full_name":"WebThingsIO/registration_server","owner":"WebThingsIO","description":"The registration server for WebThings Gateway.","archived":false,"fork":false,"pushed_at":"2024-10-27T19:13:45.000Z","size":2156,"stargazers_count":79,"open_issues_count":9,"forks_count":34,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-04T09:37:11.284Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebThingsIO.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2017-03-24T17:34:24.000Z","updated_at":"2024-10-27T19:13:49.000Z","dependencies_parsed_at":"2024-11-04T09:31:23.954Z","dependency_job_id":"b13a8395-d34c-4056-bf39-138fcae6f73b","html_url":"https://github.com/WebThingsIO/registration_server","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fregistration_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fregistration_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fregistration_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebThingsIO%2Fregistration_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebThingsIO","download_url":"https://codeload.github.com/WebThingsIO/registration_server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247009519,"owners_count":20868565,"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":["hacktoberfest"],"created_at":"2024-08-01T12:04:53.682Z","updated_at":"2025-04-03T13:31:01.330Z","avatar_url":"https://github.com/WebThingsIO.png","language":"Rust","funding_links":[],"categories":["Rust","others"],"sub_categories":[],"readme":"# Registration Server\n\n[![Build Status](https://github.com/WebThingsIO/registration_server/workflows/Rust%20application/badge.svg)](https://github.com/WebThingsIO/registration_server/workflows/Rust%20application)\n[![license](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSE)\n\nThis server exposes an HTTP API that lets you register a WebThings Gateway for\ntunneling support.\n\nWhen combined with a [PowerDNS](https://www.powerdns.com/auth.html) server and\na [PageKite](https://pagekite.net) server, this acts as an all-in-one dynamic\nDNS or tunneling solution, with distributed GeoIP support. This is not only\nuseful for WebThings, but could also be used by a variety of other stacks.\n\n## Usage\n\n```\nUSAGE:\n    main [OPTIONS]\n\nFLAGS:\n    -h, --help       Prints help information\n    -V, --version    Prints version information\n\nOPTIONS:\n        --config-file \u003cpath\u003e         Path to a toml configuration file.\n```\n\nSee `config/config.toml` for an example configuration file.\n\n\n## Building \u0026 Testing\n\n* First, select the database type you'd like: `mysql` | `postgres` | `sqlite`\n* Run `cargo build --features \u003cdb_type\u003e` to build.\n* Run `./run_tests.sh` to test.\n\n## Docker build\n\nBuild the Docker image with `docker build -t registration-server .` from\nthe source directory.\n\nYou can add the following build args:\n* `--build-arg \"db_type=\u003cdb-type\u003e\"`\n    * `\u003cdb-type\u003e` should be one of: mysql, sqlite, postgres\n\n## Deploying\n\nThe setup relies on 3 components:\n* The registration server\n* A [PowerDNS](https://powerdns.com/) server\n* [PageKite](https://pagekite.net/)\n\nGetting a full setup ready involves the following:\n* Build a Docker image.\n* Install nginx on the container's host.\n* Configure your DNS zone for the domain you want to use. The NS records need\n  to point to your registration server, i.e. the same IP address that will end\n  up serving `api.mydomain.org`. This will need to be done through your DNS\n  host or domain registrar.\n\n    ```\n    $ dig +short NS mozilla-iot.org\n    ns2.mozilla-iot.org.\n    ns1.mozilla-iot.org.\n    ```\n\n* Run the Docker image with the proper configuration.\n\n## Configuration files\n\n### Nginx\n\nIf you're using Nginx as your reverse proxy on the host, you'll need to add the\nfollowing server directives to your `nginx.conf`:\n\n```\n# HTTP version of the main registration server. We redirect to TLS port 8443 to\n# avoid conflicting with tunneled domains.\nserver {\n    listen 80;\n    listen [::]:80;\n    server_name api.mydomain.org;\n    return 301 https://$server_name:8443$request_uri;\n}\n\n# This default server handles tunneled domains, i.e. myhost.mydomain.org.\nserver {\n    listen 80 default_server;\n    listen [::]:80 default_server;\n    return 301 https://$host$request_uri;\n}\n\n# This is the main registration server.\n#\n# This section assumes you're using Let's Encrypt to generate a host\n# certificate. Adjust accordingly if necessary.\nserver {\n    listen 8443 ssl http2 default_server;\n    listen [::]:8443 ssl http2 default_server;\n    server_name api.mydomain.org;\n\n    ssl_certificate \"/etc/letsencrypt/live/api.mydomain.org/fullchain.pem\";\n    ssl_certificate_key \"/etc/letsencrypt/live/api.mydomain.org/privkey.pem\";\n    # It is *strongly* recommended to generate unique DH parameters\n    # Generate them with: openssl dhparam -out /etc/pki/nginx/dhparams.pem 2048\n    ssl_dhparam \"/etc/pki/nginx/dhparams.pem\";\n    ssl_session_cache shared:SSL:1m;\n    ssl_session_timeout  10m;\n    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;\n    ssl_ciphers HIGH:SEED:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!RSAPSK:!aDH:!aECDH:!EDH-DSS-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA:!SRP;\n    ssl_prefer_server_ciphers on;\n\n    location / {\n        proxy_set_header Host $http_host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_pass http://127.0.0.1:81;\n    }\n}\n```\n\n### PageKite\n\nThe `$CONFIG_DIR/pagekite.conf` file is used to set any options for PageKite,\nwhere `$CONFIG_DIR` is the directory you'll end up sharing into your Docker\ncontainer at `/home/user/config`. Here's a full example:\n\n```\n--isfrontend\n--ports=4443\n--protos=https\n--authdomain=mydomain.org\n--nullui\n# Uncomment the following to quiet logging:\n#--logfile=/dev/null\n```\n\n### PowerDNS\n\nThe `$CONFIG_DIR/pdns.conf` is the PowerDNS configuration file, where\n`$CONFIG_DIR` is the directory you'll end up sharing into your Docker container\nat `/home/user/config`. It needs to be consistent with the registration\nconfiguration to connect on the correct socket for the remote queries:\n\n```ini\ndaemon=no\nlocal-port=53\nlocal-address=0.0.0.0\nsocket-dir=/run/\nlaunch=remote\nremote-connection-string=unix:path=/tmp/pdns_tunnel.sock\nwrite-pid=no\nlog-dns-details=no\nlog-dns-queries=no\nloglevel=4\n\n# If using geoip in the registration server, uncomment the following:\n#query-cache-ttl=0\n#cache-ttl=0\n```\n\n### Registration Server\n\nThe `$CONFIG_DIR/config.toml` file holds the registration server\nconfiguration, where `$CONFIG_DIR` is the directory you'll end up sharing into\nyour Docker container at `/home/user/config`. You should take a look at each\nline and ensure that the values are proper for your domain. In particular, you\nshould look at anything with `mydomain.org` or an IP address. Here's a sample\nconsistent with the `pdns.conf` shown above:\n\n```toml\n[general]\nhost = \"0.0.0.0\"\nhttp_port = 81\ndomain = \"mydomain.org\"\n\n# For SQLite: db_path should just be a file path.\n# For MySQL: db_path should be of the form: mysql://[user[:password]@]host[:port][/database_name]\n# For PostgreSQL: db_path should be of the form: postgres://[user[:password]@]host[:port][/database_name]\ndb_path = \"/home/user/data/domains.sqlite\"\n\n[pdns]\napi_ttl = 1\ndns_ttl = 86400\ntunnel_ttl = 60\nsocket_path = \"/tmp/pdns_tunnel.sock\"\ncaa_records = [\n  \"0 issue \\\"letsencrypt.org\\\"\",\n]\nmx_records = []\nns_records = [\n  [ \"ns1.mydomain.org.\", \"5.6.7.8\" ],\n  [ \"ns2.mydomain.org.\", \"4.5.6.7\" ],\n]\ntxt_records = []\n# Check your DNS configuration to fill in this field.\nsoa_record = \"ns1.mydomain.org. dns-admin.mydomain.org. 2018082801 900 900 1209600 60\"\n# Uncomment to set an IP address to resolve www.mydomain.org and domain.org to.\n# www_address = \"\"\n\n  [pdns.geoip]\n  default = \"5.6.7.8\"\n\n  # If you're not using geoip, you should comment out the next line.\n  database = \"/var/lib/GeoIP/GeoLite2-Country.mmdb\"\n\n    # If you're not using geoip, you should comment out all of the continents,\n    # but keep the section header.\n    [pdns.geoip.continent]\n    AF = \"1.2.3.4\"\n    AN = \"2.3.4.5\"\n    AS = \"3.4.5.6\"\n    EU = \"4.5.6.7\"\n    NA = \"5.6.7.8\"\n    OC = \"6.7.8.9\"\n    SA = \"9.8.7.6\"\n\n[email]\nserver = \"mail.gandi.net\"\nuser = \"accounts@mydomain.org\"\npassword = \"******\"\nsender = \"accounts@mydomain.org\"\nreclamation_title = \"Reclaim your WebThings Gateway Domain\"\nreclamation_body = \"\"\"Hello,\n\u003cbr\u003e\n\u003cbr\u003e\nYour reclamation token is: {token}\n\u003cbr\u003e\n\u003cbr\u003e\nIf you did not request to reclaim your gateway domain, you can ignore this email.\"\"\"\nconfirmation_title = \"Welcome to your WebThings Gateway\"\nconfirmation_body = \"\"\"Hello,\n\u003cbr\u003e\n\u003cbr\u003e\nWelcome to your WebThings Gateway! To confirm your email address, navigate to \u003ca href=\"{link}\"\u003e{link}\u003c/a\u003e.\n\u003cbr\u003e\n\u003cbr\u003e\nYour gateway can be accessed at \u003ca href=\"https://{domain}\"\u003ehttps://{domain}\u003c/a\u003e.\"\"\"\nsuccess_page = \"\"\"\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\u003ctitle\u003eEmail Confirmation Successful!\u003c/title\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eThank you for verifying your email.\u003c/h1\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\"\"\"\nerror_page = \"\"\"\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\u003ctitle\u003eEmail Confirmation Error!\u003c/title\u003e\u003c/head\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eAn error happened while verifying your email.\u003c/h1\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\"\"\"\n```\n\n### geoipupdate\n\nThe `$CONFIG_DIR/GeoIP.conf` file holds the configuration for geoipupdate,\nwhere `$CONFIG_DIR` is the directory you'll end up sharing into your Docker\ncontainer at `/home/user/config`. This is only necessary if you're using geoip\nin the registration server.\n\n```\n# GeoIP.conf file for `geoipupdate` program, for versions \u003e= 3.1.1.\n# Used to update GeoIP databases from https://www.maxmind.com.\n# For more information about this config file, visit the docs at\n# https://dev.maxmind.com/geoip/geoipupdate/.\n\n# `AccountID` is from your MaxMind account.\nAccountID \u003cyour id\u003e\n\n# `LicenseKey` is from your MaxMind account\nLicenseKey \u003cyour key\u003e\n\n# `EditionIDs` is from your MaxMind account.\nEditionIDs GeoLite2-Country\n```\n\n## Running the Docker image\n\nYou will have to mount a couple of directories and relay some ports for the\nDocker image to run properly:\n* Mount `$CONFIG_DIR` (which was used above) to `/home/user/config`. This is\n  where all of the configuration files live.\n* If using SQLite as your database, you should also mount another directory to\n  `/home/user/data`, or wherever else you specified your database to live in\n  the `db_path` option.\n\nPort 53 over TCP and UDP needs to be forwarded for PowerDNS. The ports used for\nthe HTTP server and the tunnel also need to be forwarded.\n\nExample:\n\n```bash\ndocker run \\\n    -d \\\n    -v /opt/docker/registration-server/config:/home/user/config \\\n    -v /opt/docker/registration-server/data:/home/user/data \\\n    -p 127.0.0.1:81:81 \\\n    -p 443:4443 \\\n    -p 53:53 \\\n    -p 53:53/udp \\\n    --log-opt max-size=1m \\\n    --log-opt max-file=10 \\\n    --restart unless-stopped \\\n    --name registration-server \\\n    webthingsio/registration-server:sqlite\n```\n\n## Configuring the Gateway\n\nTo configure the WebThings Gateway to use your custom registration server,\nafter doing all the steps above, you can modify your gateway's configuration in\n`~/.mozilla-iot/config/local.json` as follows:\n\n```json\n{\n  \"ssltunnel\": {\n    \"registration_endpoint\": \"https://api.mydomain.org:8443\",\n    \"domain\": \"mydomain.org\",\n    \"certemail\": \"certificate@mydomain.org\"\n  }\n}\n```\nA Docker image has been provided\n[here](https://hub.docker.com/r/webthingsio/registration-server), containing\nthis server, a PowerDNS server, a PageKite server, and geoipupdate.\n\n## API\n\nThe API is documented [here](doc/api.md). Its usage within the WebThings\necosystem is described in [this document](doc/flow.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebThingsIO%2Fregistration_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWebThingsIO%2Fregistration_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebThingsIO%2Fregistration_server/lists"}