rgap

Redundancy Group Announcement Protocol

RGAP allows one group of hosts to be aware about IP addresses of another group of hosts. For example, it is useful for updating load balancers on dynamic IP addresses of backend servers.

Announcements are propagated in short HMAC-signed UDP messages using unicast or multicast.

This implementation defines two primary parts: agent and listener.

Agent periodically sends unicast or broadcast UDP message to announce it's presense in particular redundancy group.

Listener accepts announces, verifies them and maintains the list of active IP addresses for each redundancy group. At the same time it exposes current list of IP addresses through its output plugins.

Usage

Agent example

RGAP_ADDRESS=127.1.2.3 \
RGAP_PSK=8f1302643b0809279794c5cc47f236561d7442b85d748bd7d1a58adfbe9ff431 \
rgap agent -g 1000 -i 5s

where RGAP_ADDRESS is actual IP address which node exposes to the redundancy group.

Listener

rgap listener -c /etc/rgap.yaml

See also configuration example.

PSK Generator

rgap genpsk

Reference

Listener confiruration

The file is in YAML syntax with following elements

• listen (list)
  • (string) listen port addresses. Accepted formats: host:port or host:port@interface or host:port@IP/prefixlen. In later case rgap will find an interface with IP address which belongs to network specified by IP/prefixlen. Examples: 239.82.71.65:8271, 239.82.71.65:8271@eth0, 239.82.71.65:8271@192.168.0.0/16.
• groups (list)
  • (dictionary)
    • id (uint64) redundancy group identifier.
    • psk (string) hex-encoded pre-shared key for message authentication.
    • expire (duration) how long announced address considered active past the timestamp specified in the announcement.
    • clock_skew (duration) allowed skew between local clock and time in announcement message.
    • readiness_delay (duration) startup delay before group is reported as READY to output plugins. Useful to supress uninitialized group output after startup.
• outputs (list)
  • (dictionary)
    • kind (string) name of output plugin
    • spec (any) YAML config of corresponding output plugin

Output plugins reference

noop

Dummy plugin which doesn't do anything.

log

Periodically dumps groups contents to the application log.

Configuration:

• interval (duration) interval between dumps into log.

eventlog

Logs group membership changes to the application log.

Configuration:

• only_groups (list or null) list of group identifiers to subscribe to. All groups are logged if this list is null or this key is not specified.
  • (uint64) group ID.

hostsfile

Periodically dumps group contents into hosts file.

Configuration:

• interval (duration) interval between periodic dumps.
• filename (string) path to hosts file
• mappings (list)
  • (dictionary)
    • group (uint64) group which addresses should be mapped to given hostname in hosts file
    • hostname (string) hostname specified for group addresses in hosts file
    • fallback_addresses (list)
      • (string) addresses to use instead of group addresses if group is empty
• prepend_lines (list)
  • (string) lines to prepend before output. Useful for comment lines.
• append_lines (list)
  • (string) lines to append after output. Useful for comment lines.

dns

Runs DNS server responding to queries for names mapped to group addresses.

Configuration:

• bind_address (string)
• mappings (dictionary)
  • *DOMAIN NAME* (dictionary)
    • group (uint64) group ID which addresses whould be returned in response to DNS queries for hostname *DOMAIN NAME*.
    • fallback_addresses (list)
      • (string) addresses to use instead of group addresses if group is empty
• compress (boolean) compress DNS response message
• non_authoritative (boolean) if true, do not set AA bit for DNS response messages

command

Pipes active addresses of group into stdin of external command after each membership change. Redirects stdout and stderr of external command to output into application log.

Configuration:

• group (uint64) identifier of group.
• command (list of strings) command and arguments.
• timeout (duration) execution time limit for the command.
• retries (int) attempts to retry failed command. Default is 1.
• wait_delay (duration) delay to wait for I/O to complete after process termination. Zero value disables I/O cancellation logic. Default is 100ms.

Configuration example

listen:
- 239.82.71.65:8271 # or "239.82.71.65:8271@eth0" or "239.82.71.65:8271@192.168.0.0/16"
- 127.0.0.1:8282groups:
- id: 1000psk: 8f1302643b0809279794c5cc47f236561d7442b85d748bd7d1a58adfbe9ff431expire: 15sclock_skew: 10sreadiness_delay: 15soutputs:
- kind: noopspec:
- kind: logspec:
interval: 60s
- kind: eventlogspec: # or skip spec at allonly_groups: # or specify null for all groups
- 1000
- kind: hostsfilespec:
interval: 5sfilename: hostsmappings:
- group: 1000hostname: workerfallback_addresses:
- 1.2.3.4
- 5.6.7.8prepend_lines:
- "# Auto-generated hosts file"
- "# Do not edit manually, changes will be overwritten by RGAP"append_lines:
- "# End of auto-generated file"
- kind: dnsspec:
bind_address: :8253mappings:
worker.example.com:
group: 1000fallback_addresses:
- 1.2.3.4
- 5.6.7.8worker.example.org:
group: 1000fallback_addresses:
- 1.2.3.4
- 5.6.7.8
- kind: commandspec:
group: 1000command:
- "/home/user/sync.sh"
- "--group"
- "1000"timeout: 5sretries: 3

CLI synopsis

Run rgap help to see details of command line interface.