Muninn/README.md

# Muninn
Muninn is a distributed consensus DNS server. It aims to make the internet more
secure and censorship resistant by distributing DNS infrastructure into the
 hands of the users. Muninn operates in tandem with the existing internet, and 
is most valuable when used alongside existing security tools like DoH clients, 
VPNs, Tor, and strict HTTPS. Muninn enables local networks of likeminded peers 
to have their own private DNS layer, individuals to have their own user 
configurable, censorship resistant DNS cache, or broad groups of people to share
 their own autonomous domain name service.

# Project State
The loose plan to implement Muninn is as follows:

1. Repo that uses NGINX subtree to build a new core module
2. DNS core module accepts requests and manages a pool lifetime
3. Client can get DNS entries directly from NGINX resolver
4. DNS records are cached in a table available to all workers
5. DNS table is directly editable by some user accessible API
6. Muninn can be configured to connect to peers and synchronize entry updates
7. Muninn traverses peers to build a DHT of peers to sync with
8. User can configure allowlists and denylists of peers in DHT
9. Muninn can identify as authoritatively owning a certain DN (and Peers abide).
10. Something other than logging is done for conflicts over who owns what DN

Currently Muninn is working on phase 3.

## Building Muninn
Muninn is implemented as a statically linked NGINX Module. The output of the
provided build process is an NGINX binary that contains Muninn functionality. To
build Muninn simply run `make`. The resulting binary will be in the build tree
at `$(pwd)/nginx/objs/nginx`.

## Running Muninn
Muninn may be ran in any way which NGINX is currently run. See the configuration
section for more details. To add Muninn to an existing running NGINX simply
compile Muninn, copy the output binary over your NGINX executable, and follow
the existing NGINX binary upgrade process.

## Configuring Muninn
Muninn uses an NGINX global configuration block similar to the existing NGINX
HTTP module. To configure Muninn begin a standard NGINX configuration and open
a Muninn block:

```nginx
error_log /dev/stdout info;
pid       /tmp/munin_pid;
daemon    off;

events {}

muninn {

}
```

To serve DNS over UDP on port 53 add a `dns_listener` directive like below.
Currently Muninn only supports UDP, but plans to provide for TCP and DoH as 
development progresses.

```nginx
error_log /dev/stdout info;
pid       /tmp/munin_pid;
daemon    off;

events {}

muninn {
    dns_listen 0.0.0.0:53;
}
```

The default Muninn DNS over UDP server provides for 1024 simultaneous 
connections. To change this add the `dns_connection_pool_count` like so:

```nginx
error_log /dev/stdout info;
pid       /tmp/munin_pid;
daemon    off;

events {}

muninn {
    dns_listen 0.0.0.0:53;
    dns_connection_pool_count 24;
}
```