Skip to content

Update docs #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Snawoot merged 1 commit into from
Apr 25, 2024
Merged

Update docs #12

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 93 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,9 @@ rgap

Redundancy Group Announcement Protocol

RGAP allows one group of hosts to be aware about IP addresses of another group of hosts.
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.

It is useful to inform load balancers about ever-changing IP addresses of worker servers.

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

This implementation defines two primary parts: *agent* and *listener*.

Expand All @@ -20,7 +18,9 @@ Listener accepts announces, verifies them and maintains the list of active IP ad
### Agent example

```sh
RGAP_ADDRESS=127.1.2.3 RGAP_PSK=8f1302643b0809279794c5cc47f236561d7442b85d748bd7d1a58adfbe9ff431 rgap agent -g 1000 -i 5s
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.
Expand All @@ -31,7 +31,91 @@ where RGAP\_ADDRESS is actual IP address which node exposes to the redundancy gr
rgap listener -c /etc/rgap.yaml
```

Configuration example:
See also [configuration example](#configuration-example).

### PSK Generator

```sh
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:[email protected]/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

### Configuration example

```yaml
listen:
Expand Down Expand Up @@ -86,13 +170,7 @@ outputs:
- 5.6.7.8

```

### CLI synopsis

### PSK Generator

```sh
rgap genpsk
```

## Synopsys

See `rgap help` for details of command line interface.
Run `rgap help` to see details of command line interface.