rynDNS/README.md

rynDNS

A simplistic Dynamic DNS-ish server.

rynDNS is a simple REST-API for name to ip resolving in the spirit of Dynamic DNS. Clients can PUT their ipv4 address up to be read by other clients. Access is controlled via api_key and permissions (read, write, admin). No special client side application needed, just something to do a POST request like wget, curl or httpie.

Demo • Getting started • Rest API • Configuration • Roadmap

Getting Started

This repo includes a Dockerfile with an accompanying docker-compose.yml. To build and launch the container simply run:

docker-compose up

Once the container is build and running it will create a default admin account and post its randomly generated api key to the console:

ryndns | No admin accounts in Database, adding default: admin
ryndns | Created default admin with api_key: 3NJbP4tS.39b92576.062...

The API is now accessible at http://localhost:3000/rynDNS.

# using httpie
API_SERVER=http://localhost:3000/rynDNS
API_KEY=X-API-Key:3NJbP4tS.39b92576.062142e6451df545d5034ca8f6050b80ff3e9689f20d5e45d72d160fa7e1cf32

# list all clients
http get $API_SERVER/admin/clients $API_KEY

# creating a client
JSON_REQUEST_BODY='{                                      
  "name": "clientA",
  "description": "Client across the river",
  "permission": "rw",
  "public_ip": false
}'
http post $API_SERVER/admin/client $API_KEY <<< $JSON_REQUEST_BODY

# Alternatively using query strings (be sure to encode special characters in the param values)
API_KEY='X-API-Key=MdSUxrQQ.d5d40cd9.e2s1BsQEqmSE5MqyHYbDBVxGr/KY4BYIV5QkdjiCOF0='
CLIENT_PARAMS='name=clientA&description=Client+across+the+river&permission=rw&public_ip=false'
http post "$API_SERVER/admin/client?$API_KEY&$CLIENT_PARAMS"

Updating a write client's ipv4:

# using httpie
API_SERVER=http://localhost:3000/rynDNS
API_KEY=X-API-Key:zW3If4s5.3d6129cc.48d41d2a28b16a9a274d3f407026aee2b82cddbb3c11a5496ffe329c78e5d54b

# automatically set ip based on request itself
http put $API_SERVER/client $API_KEY

# set a custom ip for the client
JSON_REQUEST_BODY='{
  "ipv4": "115.16.0.99"
}'
http put $API_SERVER/client $API_KEY <<< $JSON_REQUEST_BODY

Reading a write client's ipv4 with a read client:

# using httpie
API_SERVER=http://localhost:3000/rynDNS
API_KEY=X-API-Key:zW3If4s5.28aef5cb.d502cb94ba0802c6363f95ecb3a70de7e2e4b889779e435b7c033f2c72ed4f20
CLIENT_NAME=write_client

http get $API_SERVER/clients/$CLIENT_NAME $API_KEY

# returns clients name and ipv4  as json
#{
#  "name": "write_client",
#  "ipv4": "115.16.0.99"
#}

REST API

A detailed and interactive specification can be found in the demo which is a render of the OpenAPI specification api.yml with swager-ui.

All requests except for /public/* require a valid X-API-Key header with appropriate permission.

Experimental: All parameters (including X-API-Key) can be passed as query string.

The following is a quick overview of the available commands.

Admin

Permission x

• POST /admin/client - Create or update a client and retrieve a new API key
• PUT /admin/client - Update an existing client
• GET /admin/clients - Retrieve all clients information
• GET /admin/clients/{client_name} - Retrieve client information
• DELETE /admin/clients/{client_name} - Delete an existing client

Client (write)

Permission w

• PUT /client - Update ipv4 client information based on request IP or body if present
• DELETE /client - Delete the requesting client's ipv4 information

Client (read)

Permission r

• GET /clients/{client_name} - Get ipv4 client information

Public

Client attribute public_ip: true

• GET /public/{client_name} - Get ipv4 client information

Configuration

The rynDNS server can be configured with environment variables, these can also be set in the docker environment:

# set to run app in subdirectory [default: /]
RAILS_RELATIVE_URL_ROOT: /rynDNS
# set maximum number of clients in db [default: 250]
RAILS_MAX_CLIENTS: 250
# set custom api key prefix [default: randomly generated (saved and restored if using docker)]
API_KEY_PREFIX: zW3If4s5
# set custom header name for api key [default: X-API-Key]
API_KEY_HEADER: X-API-Key
# set to reset the admin account, this will output a new api key on the console when starting the server [default: 0]
RAILS_RESET_ADMIN: 1
# set app to run as demo [default: 0]
RAILS_API_DEMO: 1
# [DOCKER only] set cycle to reset demo data [default: 60m]
RAILS_DEMO_RESET: 60m

Roadmap

• Public Mode - to allow for quick deployment without having to create clients/api-keys in a trusted environment (see #1)
• Support Query Strings - as alternative to api key in header and json body (merged 297016e799)
  • add full test coverage for query strings (considered experimental until then)
  • add query strings to api.yml and additional examples
• DNS Server in Docker container - resolve client_names via DNS server