Gravity

Scopes

Mon, 01 Jan 0001 00:00:00 +0000

The scope for any particular request is found in the following way:

Checking if the DHCP Peer address is within any of the scopes CIDR, or
Checking if the Address of the interface the request was received on is within any of the scopes CIDR, or
Checking if the Scope has the default flag set to true.

Afterwards, all matching scopes are sorted by the length of the Scope’s CIDR Prefix, and the longest prefix match is chosen.

Zones

Mon, 01 Jan 0001 00:00:00 +0000

Handlers

The order of handler matters; Gravity will send a query to each handler in the order they are configured until a response is returned.

The handler configuration consists of a list of individual handler configurations. All list entries require a type attribute which must match one of the headers listed below. For example:

- type: forward_blocky
 to:
 - 8.8.8.8
 cache_ttl: 3600
- type: forward_ip
 to:
 - 8.8.8.8

- type: memory
- type: etcd

`etcd`

Attempt to reply to query by looking for records in etcd. Keep in mind that because this is configured on zone level, this handler will only look for matching records in the current zone.

Options

Mon, 01 Jan 0001 00:00:00 +0000

Reference

Mon, 01 Jan 0001 00:00:00 +0000

`gravity` Object

`log(msg: any)`

Logs a message to the stdout of the Gravity node this hook is run on.

`node: string`

The identifier of the node this hook is run on.

`version: string`

The version of Gravity on the node this hook is run on.

`role`

A reference to the Role instance this hook was triggered by.

`net` Object

`parseIP(ip: string, family: string)`

Parse an IP address from the string ip and return it as an array of bytes. family determines if the IP should be parsed as IPv4 or IPv6.

Migration as a proxy

Mon, 01 Jan 0001 00:00:00 +0000

A universal method of migrating DNS records to Gravity is to setup a Zone to forward requests to an existing DNS Server and save the results into Gravity.

This can be done by using the following handler configuration on a zone:

- type: memory
- type: etcd
- type: forward_ip
 to:
 - <IP Address of the existing DNS Server(s)>
 cache_ttl: -2

With this configuration, Gravity can be configured as the default DNS Server for a domain, and it will forward requests to the configured upstream DNS servers and permanently write the results into its database.

Clustering

Mon, 01 Jan 0001 00:00:00 +0000

Any number of Gravity instances can be clustered together. This has the following advantages:

High availability of DNS
Failover
Multi-site with a central source of truth

Because Gravity is based on etcd, it is recommended to use an odd number of nodes (see etcd). With 2 nodes in a cluster, you’ll have the same quorum as with one node. Hence with 2 nodes, if any node goes down, the other node cannot access etcd either. Gravity works around this issue with caching objects in memory, and as such even when etcd is not accessible, DNS resolution still works (as long as either forward_* or memory handlers are enabled).

Migrating from Bind

Mon, 01 Jan 0001 00:00:00 +0000

(requires Gravity v0.24+)

Gravity can import DNS records from Bind zonefiles.

Retrieving the zone file

Retrieving the zone file will depend on the setup of your Bind server. In most cases, this file will be in /etc/bind/.

Some other DNS servers also provide the option of exporting records as DNS, these files are also compatible with Gravity.

Import data into Gravity

Web

Click on the Create button on the DNS Zones page and enter the domain for the new zone. On the next page select Import and continue. Select the zone file from above. Gravity will import all records into the new scope.

Migrating from Microsoft DHCP

Mon, 01 Jan 0001 00:00:00 +0000

Gravity can import DHCP leases from Microsoft’s DHCP server.

Export leases and reservations

Run the following command on the server running Microsoft DHCP, or another server with management tools installed:

Export-DhcpServer -Leases -File C:\dhcp_export.xml

This file contains information about all scopes, their leases and reservations, and any extra options.

Import data into Gravity

Web (requires Gravity v0.24+)

Click on the Create button on the DHCP Scopes page and enter the name for a new scope. On the next page select Import and continue. Select the XML file exported above. Gravity will import all leases and reservations into the new scope.

Migrating from Opensense

Mon, 01 Jan 0001 00:00:00 +0000

(requires Gravity v0.24+)

Gravity can import DNS records from Opnsense backups.

Exporting records

In the Opnsense web interface, export a backup under System -> Configuration -> Backups. Make sure to not include RRD data (default) and not encrypt the configuration file.

Import data into Gravity

Web

Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Hook Methods

`onDHCPRequestBefore(request)`

Called before the DHCP response is generated.

request: See https://pkg.go.dev/beryju.io/gravity/pkg/roles/dhcp#Request4

`onDHCPRequestAfter(request, response)`

Called after the DHCP response is generated.

request: See https://pkg.go.dev/beryju.io/gravity/pkg/roles/dhcp#Request4
response: See https://pkg.go.dev/github.com/insomniacslk/dhcp/dhcpv4#DHCPv4

Environment

`gravity` Object

`log(msg: any)`

Logs a message to the stdout of the Gravity node this hook is run on.

`node: string`

The identifier of the node this hook is run on.

`version: string`

The version of Gravity on the node this hook is run on.

Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Hook Methods

`onDNSRequestBefore(request)`

Called before the DNS response is generated.

request: See https://pkg.go.dev/beryju.io/gravity/pkg/roles/dns/utils#DNSRequest

`onDNSRequestAfter(request, response)`

Called after the DNS response is generated.

request: See https://pkg.go.dev/beryju.io/gravity/pkg/roles/dns/utils#DNSRequest
response: See https://pkg.go.dev/github.com/miekg/dns#Msg

Environment

`gravity` Object

`log(msg: any)`

Logs a message to the stdout of the Gravity node this hook is run on.

`node: string`

The identifier of the node this hook is run on.

`version: string`

The version of Gravity on the node this hook is run on.

Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Gravity can be run in Kubernetes, either as a single node or as a cluster.

Single node

For a single node instance, the Gravity container can be deployed as-is.

Note that to use DHCP when running in Kubernetes, it is recommended to deploy a DHCP on the router and have it forward requests to Gravity’s LoadBalancer IP.

See the example deployment below:

apiVersion: v1
kind: Namespace
metadata:
 name: gravity
---
apiVersion: v1
kind: Service
metadata:
 name: gravity
 namespace: gravity
 labels:
 app.kubernetes.io/name: gravity
spec:
 selector:
 app.kubernetes.io/name: gravity
 ports:
 - protocol: UDP
 port: 53
 targetPort: 53
 name: dns
 - protocol: TCP
 port: 53
 targetPort: 53
 name: dnstcp
 - port: 67
 targetPort: 67
 name: dhcp
 protocol: UDP
 - port: 69
 targetPort: 69
 name: tftp
 protocol: UDP
 - port: 8008
 targetPort: 8008
 name: http
 protocol: TCP
 type: LoadBalancer
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: gravity
 namespace: gravity
spec:
 selector:
 matchLabels:
 app.kubernetes.io/name: gravity
 spec:
 containers:
 - name: gravity
 image: ghcr.io/beryju/gravity:stable
 env:
 - name: BOOTSTRAP_ROLES
 value: dns;dhcp;api;discovery;backup;monitoring;tsdb;tftp
 - name: INSTANCE_IP
 value: <insert loadbalancer IP of gravity>
 - name: INSTANCE_LISTEN
 value: 0.0.0.0
 livenessProbe:
 httpGet:
 path: /healthz/live
 port: http-metrics
 readinessProbe:
 httpGet:
 path: /healthz/ready
 port: http-metrics
 ports:
 - containerPort: 53
 name: dns-tcp
 - containerPort: 53
 protocol: UDP
 name: dns-udp
 - containerPort: 67
 protocol: UDP
 name: dhcp
 - containerPort: 68
 protocol: UDP
 name: dhcp-alt
 - containerPort: 69
 protocol: UDP
 name: tftp
 - containerPort: 8008
 name: http
 - containerPort: 8009
 name: http-metrics
 volumeMounts:
 - name: data
 mountPath: /data
 volumeClaimTemplates:
 - metadata:
 name: data
 spec:
 accessModes: ["ReadWriteOnce"]
 resources:
 requests:
 storage: 1Gi

Multi-node cluster

When running a multi-node Gravity cluster in Kubernetes, it is recommended to not use the built-in etcd server in Gravity. This is because the built-in cluster management is optimized for static nodes and simplicity and as such doesn’t offer enough dynamic options that Kubernetes requires.

Permissions

Mon, 01 Jan 0001 00:00:00 +0000

Starting with Gravity 0.16, users can have permissions assigned to them. Permissions are assigned based on HTTP URL paths and methods. For example, to give a user permissions to read all resources, permissions can be set to this:

[
 {
 "path": "/*",
 "methods": ["get", "head"]
 }
]

To give users permissions to view DNS zones and records, you can set the permissions to

[
 {
 "path": "/api/v1/dns/zones",
 "methods": ["get"]
 },
 {
 "path": "/api/v1/dns/zones/records",
 "methods": ["get"]
 },
]

To give a user admin permissions, set the permissions to

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

port: The port the API server listens on (defaults to 8008).
oidc: Optional OpenID Connect config.
- clientID: OpenID Client Identifier.
- clientSecret: OpenID Client Secret.
- issuer: OpenID Issuer, sometimes also called “Configuration URL”. Ensure .well-known/openid-configuration suffix is removed.
- redirectURL: Redirect URL Gravity is reachable under. Should end in /auth/oidc/callback.
  
  The placeholder $INSTANCE_IDENTIFIER will be replaced by the instance’s name and $INSTANCE_IP will be replaced by the instances IP.
- scopes: Array of scopes that are requested. Should contain openid and email.

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

Cron Schedule (cronExpr): Cron expression for backup frequency (defaults to 0 */24 * * *, once every 24 hours).

Gravity only uploads files to the S3 bucket and as such only needs the PutObject permission.

Bucket (bucket): S3 bucket.
Path (path): S3 path prefix.
Endpoint (endpoint): S3 endpoint.
Access key (accessKey): S3 access key for backups.
Secret key (secretKey): S3 secret key for backups.

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

port: The port the DHCP server listens on (defaults to 67).
leaseNegotiateTimeout: The timeout a lease is reserved after a DHCP Discover request (defaults to 30 seconds).

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

enabled: Enable discovery (defaults to true).

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

port: The port the DNS server listens on (defaults to port 53).

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

port: The port the monitoring server listens on (defaults to 8009).

Role configuration

Mon, 01 Jan 0001 00:00:00 +0000

port: The port the TFTP server listens on (defaults to 69).
enableLocal: Enable reading of Node-local files stored in data/tftp via TFTP

Gravity

Scopes

Zones

Handlers

etcd

Options

Tag

tagName:

tag:

Reference

gravity Object

log(msg: any)

node: string

version: string

role

net Object

parseIP(ip: string, family: string)

Migration as a proxy

Clustering

Migrating from Bind

Retrieving the zone file

Import data into Gravity

Web

Migrating from Microsoft DHCP

Export leases and reservations

Import data into Gravity

Web (requires Gravity v0.24+)

Migrating from Opensense

Exporting records

Import data into Gravity

Web

Hooks

Hook Methods

onDHCPRequestBefore(request)

onDHCPRequestAfter(request, response)

Environment

gravity Object

log(msg: any)

node: string

version: string

Hooks

Hook Methods

onDNSRequestBefore(request)

onDNSRequestAfter(request, response)

Environment

gravity Object

log(msg: any)

node: string

version: string

Kubernetes

Single node

Multi-node cluster

Permissions

Role configuration

Role configuration

Local and S3 related settings

S3 related settings

Role configuration

Role configuration

Role configuration

Role configuration

Role configuration

`etcd`

`tagName`:

`tag`:

`gravity` Object

`log(msg: any)`

`node: string`

`version: string`

`role`

`net` Object

`parseIP(ip: string, family: string)`

`onDHCPRequestBefore(request)`

`onDHCPRequestAfter(request, response)`

`gravity` Object

`log(msg: any)`

`node: string`

`version: string`

`onDNSRequestBefore(request)`

`onDNSRequestAfter(request, response)`

`gravity` Object

`log(msg: any)`

`node: string`

`version: string`