Skip to content

DESIGN.md

Latest commit

 

History

History
103 lines (75 loc) · 3.69 KB

DESIGN.md

File metadata and controls

103 lines (75 loc) · 3.69 KB
Raw

Hashy Design

Key Features

  • Accepts DNS requests for devices
    • Host name is synthetic and contains the device name (e.g. MAC)
  • Provides a custom binary interface for bulk checks
    • Hashy's groups can be updated dynamically
  • Static configuration of groups
    • A group is a list of host names (i.e. talaria servers)

Concepts

DNS for devices

Hashy's DNS server understands hostnames with the following form:

[{prefix}-]{deviceName}[-{ignored text}].endpoint.{subdomain}

{prefix}

An optional prefix can be used before the deviceName. This allows device names to be used in host names where they would otherwise be illegal per RFC 1035. For example, 112233445566.endpoint.hashy.net is not a valid host name, since labels cannot start with a number. To hash the mac address 112233445566, put any prefix you like in front of it, e.g. mac-112233445566.endpoint.hashy.net.

{deviceName}

The deviceName is the string that is hashed. It can only contain characters that are valid for a hostname. The meaning of the deviceName is opaque to Hashy. It can be a MAC address, UUID, or any arbitrary identifier. The list of servers returned via DNS is solely determined by the deviceName.

{ignored text}

Anything that comes after the deviceName, separated by a hyphen (-), is ignored. This allows devices to incorporate nonce values or other information for debugging and to ensure hostnames are not cached by intermediaries.

{subdomain}

The subdomain is a domain that Hashy will respond to. By default, hashy.net is the subdomain (zone) for all DNS requests sent to hashy.

Groups

Hashy organizes servers into groups. A group is simply a list of servers with a unique name. A group can be a datacenter, but it can also be any arbitrary list of servers. A server may belong to multiple groups (might need to change?). Groups are supplied to Hashy via configuration or (TODO) dynamically at runtime.

Hashy computes a hash of each group so that clients can determine if a group's members have changed.

Flows

CPE uses Hashy (instead of Petasos) to find a Talaria

sequenceDiagram
  participant CPE
  participant Hashy
  participant Talaria@{"type" : "collections"}

  CPE->>Hashy:DNS request
  Hashy->>Hashy:produces a hash, one per group
  Hashy->>CPE:DNS response containing a list of one IP or CNAME per group
  CPE->>CPE:chooses an IP or CNAME at random
  CPE->>Talaria:connects
Loading

Talaria checks devices upon connection

sequenceDiagram
  participant CPE
  participant Talaria
  participant Hashy

  CPE->>Talaria:connects
  Talaria->>Talaria:Queues new connection for verification
  loop Submits queued connections to Hashy
    critical Verifies each CPE
      Talaria->>Hashy:queued device names
      Hashy->>Talaria:which device names hash to that talaria
      option Device is incorrectly connected
        Talaria->>CPE:disconnect with reason
    end
  end
Loading

Talaria enforces device hashing

sequenceDiagram
  participant Talaria
  participant Hashy

  Talaria->>Hashy:(on startup) the host name for this talaria
  Hashy->>Talaria:groups for that host name, along with a hash for each group
  loop On a configurable interval, check Hashy for changes
    critical Check for updates
      Talaria->>Hashy:list of groups and hashes
      Hashy->>Talaria:updated groups and hashes
      option No changes
        Talaria->>Talaria:update TTLs (possibly)
      option Change detected
        Talaria->>Hashy:list of devices (possibly batched)
        Hashy->>Talaria:which devices must be relocated
        Talaria->>Talaria:remove devices which no longer belong
    end
  end
Loading