Skip to content
This repository has been archived by the owner on Jul 22, 2024. It is now read-only.

Commit

Permalink
update readme with latest changes
Browse files Browse the repository at this point in the history
  • Loading branch information
mfuentesg committed Jun 11, 2022
1 parent d4686ee commit a85114f
Showing 1 changed file with 43 additions and 31 deletions.
74 changes: 43 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,94 +1,106 @@
## localDNS Server
## localdns Server

`localDNS` is a simple DNS server built to handle local records and thought to be easy, fast and small. It is able to handle local and external DNS queries,
it means, if the record is not available in the `localDNS` database it will forward the query to some known public DNS server like `8.8.8.8` or `1.1.1.1`.
`localdns` is a simple DNS server built to handle local records and thought to be easy, fast and small. It is able to
handle local and external DNS queries,
it means, if the record is not available in the `localdns` database it will forward the query to some known public DNS
server like `8.8.8.8` or `1.1.1.1`.

## Motivation

I just wanted to have a custom DNS on my home to handle custom domains, I tried `Pi-Hole`, but it was too much for what I really wanted, just `dns`.
I just wanted to have a custom DNS on my home to handle custom domains, I tried `Pi-Hole`, but it was too much for what
I really wanted, just `dns`.

But, the most powerful reason is **Just for fun**.

## Development

`localdns` uses [sqlite](https://www.sqlite.org/index.html) as storage layer.

If you want to run your own instance of `localDNS`, go to the [releases page](https://github.com/mfuentesg/localdns/releases) and download the most convenient binary for you, or, clone this repo and execute `go run main.go` and the magic will start.
If you want to run your own instance of `localdns`, go to
the [releases page](https://github.com/mfuentesg/localdns/releases) and download the most convenient binary for you, or,
clone this repo and execute `go run main.go` and the magic will start.

### Config file

`localdns` is fully configurable, just edit the autogenerated `.localdns.yaml` file and change it as your convenience.

## Migrations

`localdns` uses [golang-migrate](https://github.com/golang-migrate/migrate) for the migration system, all sql files will
be included as part of the final binary.
Migrations can be found at [`./migrations`](https://github.com/mfuentesg/localdns/tree/master/migrations) folder, and
them are applied once you start the `localdns` server.

### gRPC

`localDNS` exposes a gRPC server in order, it brings you the flexibility to develop something awesome, like a custom UI to add/remove/edit records.
`localdns` exposes a gRPC server in order, it brings you the flexibility to develop something awesome, like a custom UI
to add/remove/edit records or a CLI.

## Systemd

This service can be installed as systemd service. Use the following snippets as base for your own configuration.
These files assume that you have installed `localDNS` at `/opt/localdns/` directory and them will check for `/opt/localdns/localdns` binary file.
These files assume that you have installed `localdns` at `/opt/localdns/` directory and them will check
for `/opt/localdns/localdns` binary file.

**/etc/systemd/system/localdns.service**

```ini
[Unit]
Description=localDNS service
ConditionPathExists=/opt/localdns/localdns
After=network.target
Description = localdns service
ConditionPathExists = /opt/localdns/localdns
After = network.target

[Service]
Type=simple
ExecStart=/opt/localdns/localdns
WorkingDirectory=/opt/localdns/
Restart=on-failure
User=root
Group=root
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=localdns
Type = simple
ExecStart = /opt/localdns/localdns
WorkingDirectory = /opt/localdns/
Restart = on-failure
User = root
Group = root
RestartSec = 10
StandardOutput = syslog
StandardError = syslog
SyslogIdentifier = localdns

[Install]
WantedBy=multi-user.target
WantedBy = multi-user.target
```

**/etc/systemd/system/localdns-watcher.service**

```ini
[Unit]
Description=localDNS watcher to restart localdns service on config changes
After=network.target
Description = localdns watcher to restart localdns service on config changes
After = network.target

[Service]
Type=oneshot
ExecStart=/usr/bin/systemctl restart localdns.service
Type = oneshot
ExecStart = /usr/bin/systemctl restart localdns.service

[Install]
WantedBy=multi-user.target
WantedBy = multi-user.target
```

**/etc/systemd/system/localdns-watcher.path**

```ini
[Path]
PathModified=/opt/localdns/.localdns.yaml
PathModified = /opt/localdns/.localdns.yaml

[Install]
WantedBy=multi-user.target
WantedBy = multi-user.target
```

## ToDo

- [x] Add persistent layer
- [x] Add support for A records
- [x] Support for IPv4
- [ ] Prometheus metrics
- [x] go-releaser binary creation
- [x] GitHub actions pipeline
- [x] Add gRPC API
- [x] Logging strategy
- [x] Configuration layer
- [ ] Provide a UI for easy management
- [ ] User access and permissions for UI
- [ ] Prometheus metrics
- [ ] DNS over https support
- [ ] DNS over tls support

0 comments on commit a85114f

Please sign in to comment.