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).

Demo • Getting started • Rest API • Configuration

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

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.

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