README.md

mosdns-opnsense-deploy

A generic guide to deploy mosdns to OPNSense

Introduction

This repo provides a generic guide to deploy mosdns to OPNSense with ease. However, it requires users to have some fundamental knowledge about OPNSense and mosdns.

Documentation

Mosdns Official Wiki: https://irine-sistiana.gitbook.io/mosdns-wiki/

Know DNS Providers: https://adguard-dns.io/kb/general/dns-providers/

Project Owner

Copyright 2023-2024 @TechProber. All rights reserved.

Maintainer: Kevin Yu (@yqlbu)

Table of Contents

• Related Projects
• Steps to deploy
  • Preparation
  • Download binary from GitHub release page
  • Create log file
  • Download geodata artifacts
  • Disable and stop Unbound service
  • Create mosdns rc service
  • Create mosdns config
  • Enable mosdns service
  • Verify running status
  • Check journal logs
• Cronjobs
  • Set up cron job
    • Create cron action
    • Clean up logs
    • Update geodata artifacts
  • Add a new cron command available under OPNsense GUI
• Forward requests to designated gateways
• Maintenance
  • Force stop mosdns
• Appendix

Related Projects

• techprober/mosdns-lxc-deploy - Deploy mosdns in Proxmox LXC Container
• IrineSistiana/mosdns - A self-hosted DNS resolver
• tteck/Proxmox - Proxmox Helper Scripts
• Loyalsoldier/v2ray-rules-dat - Enhanced edition of V2Ray rules dat files, compatible with Xray-core, Shadowsocks-windows, Trojan-Go and leaf.
• Loyalsoldier/geoip - Enhanced edition of GeoIP files for V2Ray, Xray-core, Trojan-Go, Clash and Leaf, with replaced CN IPv4 CIDR available from ipip.net, appended CIDR lists and more.

Steps to deploy

Preparation

Create a new directory for mosdns

sudo mkdir -p /etc/usr/local/mosdns

Create sub directories

sudo mkdir -p /usr/local/etc/mosdns/{ips,domains,downloads,custom}

Make sure you have the following file structure present on your host:

# /usr/local/etc/mosdns
./
|-- config.yml
|-- custom
|-- domains
|-- downloads
|-- scripts
`-- ips

5 directories, 1 file

Install Vim (Optional)

sudo pkg install vim

Download binary from GitHub release page

https://github.com/IrineSistiana/mosdns/releases

cd /usr/local/etc/mosdns/downloads
curl -o mosdns.zip https://github.com/IrineSistiana/mosdns/releases/download/{VERSION}/mosdns-freebsd-amd64.zip
unzip mosdns.zip
sudo install -Dm755 mosdns /usr/bin/

Create log file

sudo touch /var/log/mosdns.log

Download geodata artifacts

Reference: https://github.com/techprober/mosdns-lxc-deploy

Artifacts Source: https://github.com/techprober/v2ray-rules-dat/releases

Note

You may selectively download the rule lists you need from the release branch from @techprober/v2ray-rules-dat.

set MOSDNS_PATH=/usr/local/etc/mosdns
curl --progress-bar -JL -o $MOSDNS_PATH/downloads/geoip.zip https://github.com/techprober/v2ray-rules-dat/raw/release/geoip.zip
curl --progress-bar -JL -o $MOSDNS_PATH/downloads/geosite.zip https://github.com/techprober/v2ray-rules-dat/raw/release/geosite.zip
unzip -o $MOSDNS_PATH/downloads/geoip.zip -d $MOSDNS_PATH/ips
unzip -o $MOSDNS_PATH/downloads/geosite.zip -d $MOSDNS_PATH/domains

Note

Alternatively, you may use a dedicated script to automatically download and extract the geodata artifacts. See ./scripts/geodata-update.sh

Disable and stop Unbound service

Warning

Doing so will free port 53 for mosdns to use

# stop unbound service
# /usr/local/opnsense/service/conf/actions.d/actions_unbound.conf
configctl unbound stop
/usr/local/sbin/pluginctl dns stop
/usr/local/sbin/pluginctl dns disable

Create mosdns rc service

Paste the content from ./rc.d/mosdns in this repo to /usr/local/etc/rc.d/mosdns in OPNSense.

sudo chmod +x /usr/local/etc/rc.d/mosdns

Create mosdns config

Note

You may start with the recommended config, which provides out-of-the-box ip leak prevent feature.

Warning

Please take a look at the content of config-{VERSION}.yml before you copy it to /usr/local/etc/mosdns. It is a boilerplate template which intends to provide users a reference to start with customizing their own config.

Enable mosdns service

echo 'mosdns_enable="YES"' >> /etc/rc.conf
sudo service mosdns start
sudo service mosdns enable

Verify running status

ps -aux | grep mosdns
sudo service mosdns status

Check journal logs

Important

To write logs to a file, you need to specify the log file destination in your config as shown in the following:

## -- Log Config -- ##
log:
  level: debug # ["debug", "info", "warn", and "error"], default is set to "info"
  production: true
  file: "/var/log/mosdns.log"

sudo tail -f /var/log/mosdns.log

Cronjobs

Set up cron job

Create cron action

Create a .conf file in /usr/local/opnsense/service/conf/actions.d/ (your file must start with actions_) vi /usr/local/opnsense/service/conf/actions.d/actions_mosdns-logs-cleanup.conf

Available in ./actions.d/actions_mosdns.conf

Restart and reload

sudo service configd restart

Clean up logs

sudo configctl mosdns logs-cleanup

---

Update geodata artifacts

Add geodata-update script

The script is available in ./scripts/geodata-update.sh.

Download save it in /usr/local/etc/mosdns/scripts/

curl -L -o /usr/local/etc/mosdns/scripts/geodata-update.sh https://github.com/techprober/mosdns-opnsense-install/raw/master/scripts/geodata-update.sh

Set permission

sudo chmod +x /usr/local/etc/mosdns/scripts/geodata-update.sh

Run the action

sudo configctl mosdns geodata-update

---

Add a new cron command available under OPNsense GUI

Go to System > Settings > Cron and Add a Job You can show your cron command in dropdown Command. Plan your cron schedule as you wish.

Forward requests to designated gateways

Note

For those who would like to further forward DNS requests to designated gateways, depending on the DNS provider of choice, you may achieve so following the route setting below.

Maintenance

Force stop mosdns

# force stop
ps -aux | grep mosdns
kill -9 <mosdns pid>
# restart
service mosdns start

Appendix

• Auto-generate geoip.txt, geosites.txt (since *.dat are deprecated in v5) - https://github.com/techprober/v2dat
• Available Rules - https://github.com/techprober/v2ray-rules-dat/releases