# Linum

A simple DNS recursive resolver written in Golang. Linum supports both
recursive resolution from root hints and forwarding to upstream resolvers with
built-in hosts blocking.

## Features

- UDP, TCP, DoT listeners
- Recursive & foreward modes
- Host blocking

## Requirements

- Go 1.26+
- Linux
- Root to bind port 53 / 853

## Quickstart

```bash
git clone https://codeberg.org/radhitya/linum.git
cd linum
make
./build/linum -config linum.toml
```

Test with dig:

```bash
dig @127.0.0.1 -p 5353 example.com
```

### Build & Install

From source

```bash
make
sudo make install
sudo make install-config
```

and install systemd service

```bash
sudo make install-service
sudo systemctl enable --now linum
```

## Config Reference

Save as /etc/linum/linum.toml

```
[server]
listen_udp = ":5353"
listen_tcp = ":5353"
listen_doh = ":8443"
listen_dot = ":853"

[cache]
max_entries = 100000
db_path = "/var/cache/linum/cache.db"

[resolver]
mode = "recursive"        # "recursive" or "forward"
timeout = "2s"
max_delegations = 30
# forwarders = ["1.1.1.1", "8.8.8.8"]  # only used when mode = "forward"

[blocklist]
response = "zero_ip"      # "zero_ip" or "nxdomain"
files = ["etc/blocklist/*.txt"]
# urls = [
#     "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts",
# ]

[acl]
allow = ["127.0.0.1/8", "::1/128"]
rate_limit_qps = 50
rate_limit_burst = 10

[admin]
listen = "127.0.0.1:8080"

[tls]
cert = "/etc/linum/linum-cert.pem"
key = "/etc/linum/linum-key.pem"

[log]
level = "info"
```

## Blocklist Format

Linum supports several rule formats:

```txt
# hosts format
0.0.0.0 example.com
# AdGuard format
||example.com^

# Exception / whitelist
@@||example.com^
```

Set response = "zero_ip" to return 0.0.0.0 / ::, or response = "nxdomain" to return NXDOMAIN.

- [codeberg.org/miekg/dns](https://codeberg.org/miekg/dns)
- [github.com/BurntSushi/toml](https://github.com/BurntSushi/toml)
- [modernc.org/sqlite](https://modernc.org/sqlite)