NAME

appjail-dns — DNS information for AppJail users

SYNOPSIS

DESCRIPTION

The appjail-dns utility is a command to generate a hosts(5)-like file to be used by scripts and services, such as a DNS server.

appjail-dns can read one or more hosts(5)-like files by removing any comments. After reading and displaying all the specified files, appjail-dns will generate a list of DNS hostnames for each jail in each virtual network.

The syntax of each line is exactly as specified in hosts(5)-like, but the jail's hostname follows a particular syntax: “<Jail Name>.<Virtual Network>HOST_DOMAIN”. The virtual network host name syntax is “<Virtual Network>HOST_DOMAIN”. See appjail.conf(5) for a description of the HOST_DOMAIN parameter, but as you can see, it is used exactly as is, assuming it is prefixed with a dot.

This document also explains how to use the rc(8) script to implement appjail-dns with a DNS server, in this case DNSMasq.

The rc(8) script checks the current hosts(5)-like (appjail_dns_hosts: /var/tmp/appjail-hosts) file against the output of appjail-dns at intervals (appjail_dns_interval: 60) using a checksum; if it detects a change it will write the new content to the hosts(5)-like file and execute the hook (appjail_dns_hook: /usr/local/share/appjail/scripts/dnsmasq-hook.sh) only if it has the execution bit set.

A hook is simply an external program that has two responsibilities: filtering the hosts(5)-like file and restarting the DNS server. These responsibilities depend entirely on the DNS server, as it may not need to be restarted, or even the hook may not need to modify the hosts(5)-like file for the DNS server to interpret it correctly.

For example, if we use the following file for DNSMasq:

/usr/local/share/appjail/files/dnsmasq.conf:

addn-hosts=/var/tmp/appjail-hosts
no-resolv
server=208.67.222.222
server=208.67.220.220

With the necessary parameters in our rc.conf(5):

dnsmasq_enable="YES"
dnsmasq_conf="/usr/local/share/appjail/files/dnsmasq.conf"

We are configuring DNSMasq to use /var/tmp/appjail-hosts as our hosts(5). Since it can perfectly interpret a hosts(5) file, it is not necessary to modify it.

The hosts(5)-like file is passed to the hook as the first argument, but we don't need it, since the only thing our hook needs to do is restart DNSMasq.

/usr/local/share/appjail/scripts/dnsmasq-hook.sh:

#!/bin/sh

service dnsmasq reload

AppJail uses the above hook in its rc(8) script, but you can change to any other hook by changing the value of the appjail_dns_hook parameter in your rc.conf(5):

appjail_dns_enable="YES"
appjail_dns_hook="/usr/local/share/appjail/scripts/dnsmasq-hook.sh"

Once everything is done, we can start the rc(8) scripts:

# touch /var/tmp/appjail-dns
# service dnsmasq start
# service appjail-dns start

Since every time the rc(8) script is restarted, it checks if there are any changes between the output of appjail-dns and the current hosts(5)-like file, we should have the file with content, assuming that there are already jails created and that are in an existing virtual network.

# cat /var/tmp/appjail-dns
10.0.0.1        ajnet.appjail
10.0.0.2        filebrowser filebrowser.ajnet.appjail
10.0.0.3        jtest jtest.ajnet.appjail

In my case, I have enabled SHORTEN_DOMAIN_NAMES, so a shorter domain name is available in that file, as you can see.

EXIT STATUS

The appjail-dns utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

appjail-network(1) hosts(5) appjail-tutorial(7)

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>