Alpine Linux - User contributions [en]

Small-Time Email with Exim and Dovecot

2025-09-22T21:54:08Z

DavesCodeMusings: /* Creating Mail Directories for Users */ using root shell prompt to show the command requiring root privs

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

$ mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1.2 01/15/2001. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l /var/mail
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of just over twenty lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like what's shown below.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22. It is not compatible with Dovecot 2.3 used in earlier versions of Alpine.}}

dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Creating Mail Directories for Users ==
The IMAP server will use the user's home directory to store mail folders. These are configured to go in ~/mail. You'll need to make sure this directory exists with the proper permissions for each user accessing email via IMAP.

The following command shows how you can create ~/mail for the user dave:

# install -d -o dave -g dave -m770 ~dave/mail

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows, [https://alpineapp.email/ Alpine Mail] on Linux, and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# ssl_server {
# cert_file = /etc/ssl/dovecot/server.pem
# key_file = /etc/ssl/dovecot/server.key
# }

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt and add to {{path|/etc/dovecot/passwd}}"
echo "Create user mail directories with: install -d -o username -g dave -m770 ~username/mail"

Small-Time Email with Exim and Dovecot

2025-09-22T21:52:14Z

DavesCodeMusings: /* Configuring Dovecot */ update conf file line count for new Dovecot version 2.4

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

$ mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1.2 01/15/2001. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l /var/mail
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of just over twenty lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like what's shown below.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22. It is not compatible with Dovecot 2.3 used in earlier versions of Alpine.}}

dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Creating Mail Directories for Users ==
The IMAP server will use the user's home directory to store mail folders. These are configured to go in ~/mail. You'll need to make sure this directory exists with the proper permissions for each user accessing email via IMAP.

The following command shows how you can create ~/mail for the user dave:

install -d -o dave -g dave -m770 ~dave/mail

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows, [https://alpineapp.email/ Alpine Mail] on Linux, and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# ssl_server {
# cert_file = /etc/ssl/dovecot/server.pem
# key_file = /etc/ssl/dovecot/server.key
# }

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt and add to {{path|/etc/dovecot/passwd}}"
echo "Create user mail directories with: install -d -o username -g dave -m770 ~username/mail"

Small-Time Email with Exim and Dovecot

2025-09-22T21:49:43Z

DavesCodeMusings: /* Testing the Exim Setup */ include shell prompt for consistency with other example screen output

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

$ mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1.2 01/15/2001. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l /var/mail
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like what's shown below.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22. It is not compatible with Dovecot 2.3 used in earlier versions of Alpine.}}

dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Creating Mail Directories for Users ==
The IMAP server will use the user's home directory to store mail folders. These are configured to go in ~/mail. You'll need to make sure this directory exists with the proper permissions for each user accessing email via IMAP.

The following command shows how you can create ~/mail for the user dave:

install -d -o dave -g dave -m770 ~dave/mail

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows, [https://alpineapp.email/ Alpine Mail] on Linux, and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# ssl_server {
# cert_file = /etc/ssl/dovecot/server.pem
# key_file = /etc/ssl/dovecot/server.key
# }

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt and add to {{path|/etc/dovecot/passwd}}"
echo "Create user mail directories with: install -d -o username -g dave -m770 ~username/mail"

Small-Time Email with Exim and Dovecot

2025-09-22T17:35:33Z

DavesCodeMusings: /* Configuring Dovecot */ fix proper name casing typo

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1.2 01/15/2001. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l /var/mail
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like what's shown below.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22. It is not compatible with Dovecot 2.3 used in earlier versions of Alpine.}}

dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Creating Mail Directories for Users ==
The IMAP server will use the user's home directory to store mail folders. These are configured to go in ~/mail. You'll need to make sure this directory exists with the proper permissions for each user accessing email via IMAP.

The following command shows how you can create ~/mail for the user dave:

install -d -o dave -g dave -m770 ~dave/mail

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows, [https://alpineapp.email/ Alpine Mail] on Linux, and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# ssl_server {
# cert_file = /etc/ssl/dovecot/server.pem
# key_file = /etc/ssl/dovecot/server.key
# }

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt and add to {{path|/etc/dovecot/passwd}}"
echo "Create user mail directories with: install -d -o username -g dave -m770 ~username/mail"

Small-Time Email with Exim and Dovecot

2025-09-22T17:34:34Z

DavesCodeMusings: Update to reflect breaking changes in dovecot.conf starting with Dovecot version 2.4

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1.2 01/15/2001. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l /var/mail
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like what's shown below.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22. It is not compatible with dovecot 2.3 used in earlier versions of Alpine.}}

dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Creating Mail Directories for Users ==
The IMAP server will use the user's home directory to store mail folders. These are configured to go in ~/mail. You'll need to make sure this directory exists with the proper permissions for each user accessing email via IMAP.

The following command shows how you can create ~/mail for the user dave:

install -d -o dave -g dave -m770 ~dave/mail

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows, [https://alpineapp.email/ Alpine Mail] on Linux, and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# ssl_server {
# cert_file = /etc/ssl/dovecot/server.pem
# key_file = /etc/ssl/dovecot/server.key
# }

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
dovecot_config_version = 2.4.0
auth_allow_cleartext = yes
dovecot_storage_version = 2.4.0
first_valid_uid = 8
log_path = /var/log/dovecot.log
mail_driver = mbox
mail_gid = mail
mail_home = /home/%{user}
mail_inbox_path = /var/mail/%{user}
mail_path = /home/%{user}/mail
mail_privileged_group = mail
mail_uid = %{user}
protocols {
imap = yes
}
passdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl_server {
cert_file = /etc/ssl/dovecot/server.pem
key_file = /etc/ssl/dovecot/server.key
}
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt and add to {{path|/etc/dovecot/passwd}}"
echo "Create user mail directories with: install -d -o username -g dave -m770 ~username/mail"

Small-Time Email with Exim and Dovecot

2025-09-21T15:51:28Z

DavesCodeMusings: /* Testing the Dovecot Setup */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.3 used in Alpine Linux 3.21 and earlier. It is not compatible with dovecot 2.4 used in Alpine 3.22.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = ldap
args = /etc/dovecot/ldap-auth.ext
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_cert=</etc/ssl/dovecot/server.pem
#ssl_key=</etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time Email with Exim and Dovecot

2025-09-21T15:50:06Z

DavesCodeMusings: /* Configuring Dovecot */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.3 used in Alpine Linux 3.21 and earlier. It is not compatible with dovecot 2.4 used in Alpine 3.22.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = ldap
args = /etc/dovecot/ldap-auth.ext
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_server_cert_file = /etc/ssl/dovecot/server.pem
#ssl_server_key_file = /etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time Email with Exim and Dovecot

2025-09-21T15:11:27Z

DavesCodeMusings: /* Configuring Dovecot */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22 and later. It is not compatible with older versions.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0
listen = *
log_path = /var/log/dovecot.log
protocols = imap
auth_allow_cleartext = yes
mail_privileged_group = mail
mail_driver = maildir
mail_path = ~/mail
mail_inbox_path = /var/mail/%u
first_valid_uid = 8
mail_uid = mail
mail_gid = mail
userdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}
# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_server_cert_file = /etc/ssl/dovecot/server.pem
ssl_server_key_file = /etc/ssl/dovecot/server.key

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_server_cert_file = /etc/ssl/dovecot/server.pem
#ssl_server_key_file = /etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time Email with Exim and Dovecot

2025-09-21T14:31:05Z

DavesCodeMusings: /* Testing the Dovecot Setup */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22 and later. It is not compatible with older versions.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0
listen = *
log_path = /var/log/dovecot.log
protocols = imap
auth_allow_cleartext = yes
mail_privileged_group = mail
mail_driver = maildir
mail_path = ~/mail
mail_inbox_path = /var/mail/%u
userdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}
# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_server_cert_file = /etc/ssl/dovecot/server.pem
ssl_server_key_file = /etc/ssl/dovecot/server.key

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_server_cert_file = /etc/ssl/dovecot/server.pem
#ssl_server_key_file = /etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time Email with Exim and Dovecot

2025-09-21T14:28:53Z

DavesCodeMusings: /* Configuring Dovecot */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22 and later. It is not compatible with older versions.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0
listen = *
log_path = /var/log/dovecot.log
protocols = imap
auth_allow_cleartext = yes
mail_privileged_group = mail
mail_driver = maildir
mail_path = ~/mail
mail_inbox_path = /var/mail/%u
userdb passwd {
driver = passwd-file
passwd_file_path = /etc/dovecot/passwd
}
# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_server_cert_file = /etc/ssl/dovecot/server.pem
ssl_server_key_file = /etc/ssl/dovecot/server.key

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_cert=</etc/ssl/dovecot/server.pem
#ssl_key=</etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time Email with Exim and Dovecot

2025-09-21T14:01:45Z

DavesCodeMusings: /* Configuring Dovecot */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22 and later. It is not compatible with older versions.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0
listen = *
log_path = /var/log/dovecot.log
protocols = imap
auth_allow_cleartext = yes
mail_privileged_group = mail
mail_driver = maildir
mail_path = ~/mail
mail_inbox_path = /var/mail/%u
userdb passwd {
driver = passwd
}
# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_server_cert_file = /etc/ssl/dovecot/server.pem
ssl_server_key_file = /etc/ssl/dovecot/server.key

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_cert=</etc/ssl/dovecot/server.pem
#ssl_key=</etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time Email with Exim and Dovecot

2025-09-21T13:58:29Z

DavesCodeMusings: /* Configuring Dovecot */

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

== Why would anyone do this? ==

My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

== Why Exim and Dovecot? ==

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

== Installing the Packages ==
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}

== Configuring Exim ==

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

# Make a backup of {{path|/etc/exim/exim.conf}}
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.

Find the lines that look like this:

# group = mail
# mode = 0660

They'll be under the heading of <code>local_delivery:</code>

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

local_delivery:
driver = appendfile
file = /var/mail/$local_part_data
delivery_date_add
envelope_to_add
return_path_add
group = mail
mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

== Fixing Ownership and Permissions on /var/mail ==

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

chgrp mail /var/mail
chmod 2775 /var/mail

When you're done, verify it with <code>ls -ld /var/mail</code>. It should look something like this:

$ ls -ld /var/mail/
drwxrwsr-x 3 root mail 4096 May 11 12:58 /var/mail/

Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.

== Starting the Exim Service ==

Start Exim and configure it to start at boot time with the usual commands.

service exim start
rc-update add exim

== Testing the Exim Setup ==

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

mail -s Testing dave
This is a test.
.

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running <code>mail</code> with no command-line parameters. If everything went well, it should look like the example below.

$ mail
Mail version 8.1 6/6/93. Type ? for help.
"/var/mail/dave": 1 messages
> 1 dave@myserver.home Wed May 11 03:51 27/847 "Testing"
&

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

== Troubleshooting Mail Delivery ==

If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.

The directory permissions should look like this:

# ls -ld /var/mail
drwxrwsr-x 3 root mail

The permissions on mailbox files inside should look like this:

# ls -l
-rw-rw---- 1 dave mail

== Configuring Dovecot ==

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

{{Note| The example configuration below is for Dovecot version 2.4 used in Alpine Linux 3.22 and later. It is not compatible with older versions.}}

The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.

Next, create a new dovecot.conf that looks like this:

dovecot_config_version = 2.4.0
dovecot_storage_version = 2.4.0
listen = *
log_path = /var/log/dovecot.log
protocols = imap
auth_allow_cleartext = yes
mail_privileged_group = mail
mail_driver = maildir
mail_path = ~/mail
mail_inbox_path = /var/mail/%u
userdb passwd {
driver = passwd
}

This config does not have the <code>!include conf.d/*.conf</code> that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

== Starting the Dovecot Service ==

Start Dovecot and configure it to start at boot time with the usual commands.

service dovecot start
rc-update add dovecot

== Creating Credentials for Dovecot Users ==

As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.

The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:

dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the <code>doveadm</code> command, like this:

# doveadm pw -s sha512-crypt
Enter new password:
Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

ls -l /etc/dovecot/passwd
-rw-r----- 1 root dovecot

== Testing the Dovecot Setup ==

To test IMAP, you'll need an email client. Personally, I've used [https://www.thunderbird.net Thunderbird] on Windows and [https://k9mail.app/ K-9 Mail] on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

Disconnected: TLS initialization failed.
Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

# These are self-signed certs generated when the dovecat apk was installed.
#ssl=yes
#ssl_cert=</etc/ssl/dovecot/server.pem
#ssl_key=</etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

== Using and Enjoying Your Small-Time Email Setup ==

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

== A Word About Aliases ==

If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.

== Scripted Installation and Configuration ==

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

chgrp mail /var/mail
chmod 2775 /var/mail

apk add exim mailx

sed -i~ \
-e 's/# group = mail/ group = mail/' \
-e 's/# mode = 0660/ mode = 0660/' \
/etc/exim/exim.conf

ln -s mail/aliases /etc/aliases

rc-update add exim
service exim start

apk add dovecot

mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~

cat <<EOF > /etc/dovecot/dovecot.conf
listen = *
log_path = /var/log/dovecot.log
protocols = imap
disable_plaintext_auth = no
mail_privileged_group = mail
mail_location = mbox:~/mail:INBOX=/var/mail/%u
userdb {
driver = passwd
}
passdb {
driver = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
}

# These are self-signed certs generated when the dovecat apk was installed.
ssl=yes
ssl_cert=</etc/ssl/dovecot/server.pem
ssl_key=</etc/ssl/dovecot/server.key
EOF

touch /etc/dovecot/passwd
chown root:dovecot /etc/dovecot/passwd
chmod 640 /etc/dovecot/passwd

service dovecot start
rc-update add dovecot

echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Small-Time DNS with BIND9

2025-09-12T13:54:05Z

DavesCodeMusings: /* Blocking Ads */ Typo fix

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

allow-query { any; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# chown named /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable the RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~
mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.
[[Category:Networking]]

Small-Time DNS with BIND9

2025-03-07T00:46:48Z

DavesCodeMusings: /* Configure as a Forwarding DNS Server */ allow queries from anywhere after recent versions of BIND9 now block by default

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

allow-query { any; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# chown named /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~
mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.
[[Category:Networking]]

Small-Time DNS with BIND9

2025-02-10T17:24:33Z

DavesCodeMusings: /* Maintaining the RPZ File */ Stop script from failing on first run

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# chown named /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~
mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.
[[Category:Networking]]

Small-Time DNS with BIND9

2025-02-03T19:53:47Z

DavesCodeMusings: /* Next Steps */ Removed encryption. DNSSEC is not actually encryption, it's cryptographic signing.

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# chown named /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

Small-Time DNS with BIND9

2025-02-03T18:42:10Z

DavesCodeMusings: /* Create the Zone File */ Remove uninteded line break

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# chown named /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC encryption

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

Small-Time DNS with BIND9

2025-02-03T18:41:24Z

DavesCodeMusings: /* Create the Zone File */ Add step to fix dir ownership to allow automatic dnssec signing if desired

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# chown named /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC encryption

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

User:DavesCodeMusings

2025-02-03T02:07:11Z

DavesCodeMusings:

I've been using Alpine for a few years as a lightweight OS on barebones NUC mini-PCs. My current approach is to run basic services like: email, DNS, LDAP, and system monitoring installed from APKs. Everything else runs in Docker containers. Whenever I figure out how to do something that takes more than a few commands, I tend to write it down. And since I'm writing it down, I might as well share.

I also like to do stuff with ESP microcontrollers and MicroPython. You can find more on that at my GitHub page https://davescodemusings.github.io/

User:DavesCodeMusings

2025-02-02T23:00:24Z

DavesCodeMusings:

I've been using Alpine for a few years as a lightweight OS on barebones NUC mini-PCs. My current approach is to run basic services like: email, DNS, LDAP, and system monitoring at the OS level. Everything else runs in Docker containers. Whenever I figure out how to do something that takes more than a few commands, I tend to write it down. And since I'm writing it down, I might as well share.

I also like to do stuff with ESP microcontrollers and MicroPython. You can find more on that at my GitHub page https://davescodemusings.github.io/

User:DavesCodeMusings

2025-02-02T22:58:50Z

DavesCodeMusings: Created page with "I've been using Alpine for a few years as a lightweight OS on barebones NUC mini-PCs. My current approach is to run basic services like: email, DNS, LDAP, and system monitoring at the OS level. Everything else runs in Docker containers. Whenever I figure out how to do something that takes more than a few commands, I tend to write it down. And since I'm writing it down, I might as well share."

Small-Time DNS with BIND9

2025-02-02T17:35:49Z

DavesCodeMusings: Remove redundant title heading

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC encryption

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

Small-Time DNS with BIND9

2025-02-02T17:02:14Z

DavesCodeMusings: substitute primary in place of master

= Small-Time DNS Server with BIND9 =

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type primary;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type primary;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type primary;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type primary;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC encryption

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

Small-Time DNS with BIND9

2025-02-02T16:32:32Z

DavesCodeMusings:

= Small-Time DNS Server with BIND9 =

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

# apk update
# apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

# service named start
# rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type master;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type master;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type master;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type master;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC encryption

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

Small-Time DNS with BIND9

2025-02-02T15:48:50Z

DavesCodeMusings: Created page with "= Small-Time DNS Server with BIND9 = This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like dependin..."

= Small-Time DNS Server with BIND9 =

This document shows how to configure a basic installation of the ISC DNS server, BIND9, for Alpine Linux. This is useful when you want to have a DNS server for your home or home office network. The instructions start with a basic caching, forwarding DNS server. It continues on with adding lookup zones for your LAN hosts. Finally, it gives a peek at setting up ad blocking. You can work through as much or as little as you like depending on your DNS needs.

It should be noted, this document focuses on quick deployment and ease of use for a ''trusted network behind a firewall''. Do not deploy this configuration on a host that allows DNS queries from the internet.

== Install the Package ==

The usual Alpine apk installation method can be used to install bind9. This will install the named DNS server as well as nslookup and other utilities.

apk update
apk add bind

== Configure as a Forwarding DNS Server ==

When configured as a forwarding server, the local DNS server will cache the results of query replies. Queries not found in cache are forwarded to a public DNS server (or your ISP).

The example below uses public DNS servers 1.1.1.1 and 8.8.8.8. You may substitute your ISP’s DNS servers or any other trusted DNS server.

# cd /etc/bind

# cat << EOF > named.conf

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;
};
EOF

After writing the configuration, run named-checkconf to verify it’s correct. Fix any errors before moving on.

=== Start the DNS Server ===

service named start
rc-update add named

=== Test Queries Locally ===

First, run nslookup on your Alpine host and set the server to your Alpine host’s IP address. Then, query some internet DNS name and IP addresses. You should see IP addresses and domain names in the reply.

If you see an error, like ''** server can’t find example.com: NXDOMAIN'', check the configuration in named.conf.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> 1.1.1.1
1.1.1.1.in-addr.arpa name = one.one.one.one.

Note: Output has been truncated for brevity.

If the test is successful, you’ll want to configure your host’s /etc/resolv.conf to use its own IP address for DNS lookups.

=== Test Queries from a LAN Client ===

Repeat the test, but from another machine on your network. Be sure to use the Alpine host’s IP address for the nslookup server.

If you see an error like ''*** [192.168.1.100] can’t find example.com: Query refused'', check your named.conf. Verify there is a line for ''recursion yes;''

Here’s a sample of a successful test on a Windows client.

C:\> nslookup
> server 192.168.1.100

> example.com
Server: [192.168.1.100]
Address: 192.168.1.100

Non-authoritative answer:
Name: example.com
Addresses: 2600:1406:bc00:53::b81e:94ce
23.215.0.136

Note: Output has been truncated for brevity.

If the test is successful, you can configure your DHCP server to use the Alpine host’s IP address for primary DNS.

== Optionally Add LAN Hosts ==

So far, only well-known internet hosts are able to be queried. Sometimes it’s useful to have hosts on your own network be available in DNS as well. This requires setting up a zone file.

Creatig a zone file is a little more complex than the configuration thus far, but not insurmountable. There are many examples of zone files to be found on the internet, including [https://bind9.readthedocs.io/en/latest/chapter3.html#example-com-base-zone-file the BIND9 documentation], [https://en.wikipedia.org/wiki/Zone_file#Example_file a Wikipedia article], and [https://wiki.alpinelinux.org/wiki/Setting_up_nsd_DNS_server#Configure another Alpine Wiki DNS howto]. All these can be used as references.

=== Create the Zone File ===

The example below is for a simple home network using the reserved private top-level domain name of ''.home''. The top half of the file contains details about the domain itself. The bottom half is where individual hosts and their addresses are listed. You will need to adjust names and IP addresses for your network configuration.

# mkdir /etc/bind/zones

# cat << EOF > /etc/bind/zones/home

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101
EOF

Be sure to check the file using named-checkzone and fix any errors before continuing. The positional parameters are ''zone name'' and ''file name''.

# named-checkzone home /etc/bind/zone/home
zone home/IN: loaded serial 1
OK

If you do encounter errors in the output, there is a line number included that will help you track it down.

=== Reference the Zone File in named.conf ===

Edit /etc/bind/named.conf and append the following lines:

zone "home" {
type master;
file "/etc/bind/zones/home";
};

Validate the configuration with the command: named-checkconf. Fix any errors before continuing.

=== Inform the DNS Server of the New Configuration ===

Use the usual Alpine service command to reload the configuration.

service named reload

If there are errors, use the named-checkconf and named-checkzone commands to help narrow down the cause.

=== Do Some Test Queries ===

As a final check, revisit the tests using nslookup that were used to verify the forwarding DNS server. This time, in addition to looking up internet hosts, try some queries for the hosts in your zone file.

Here’s an example of a successful test.

$ nslookup
> server 192.168.1.100
Default server: 192.168.1.100
Address: 192.168.1.100#53

> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

Non-authoritative answer:
Name: example.com
Address: 23.215.0.136

> router.home
Server: 192.168.1.100
Address: 192.168.1.100#53

Name: router.home
Address: 192.168.1.1

Note: Output has been truncated for brevity.

== Add Zones for localhost ==

To make the configuration complete, there should be a zone for the localhost name so the DNS server will return the familiar 127.0.0.1 address when queried. The DNS server should also respond with ''localhost'' when queried for the IP address ''127.0.0.1''

The process for creating the forward lookup zone is the same as is was for creating the ''home'' zone. What’s new in this step is the concept of reverse lookup zones. This is simply the DNS server returning a name when asked about an IP address.

Here are the steps:
# Create the zone file
# Reference the zone in named.conf
# Reload the configuration

Don’t forget to test with named-checkzone, named-checkconf, and nslookup as you go.

=== Create the Forward Lookup Zone File ===

The zone file for localhost is fairly simple, with only one A record. An example is show below. Create a new file with the path /etc/bind/zones/localhost and copy the contents of the example into it.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
@ IN A 127.0.0.1

=== Create the Reverse Lookup Zone File ===

The reverse lookup zone file is nearly the same as the forward lookup, but has a PTR record instead of an A record on the last line. Create a new file with the path /etc/bind/zones/1.0.0.127.in-addr.arpa and copy the contents from below.

$TTL 3600
@ IN SOA localhost. root.localhost. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS localhost.
1 IN PTR localhost.

The rather strange looking naming convention of the file (and the zone itself) is simply the IP address of the reverse zone with its octets in reverse order and the suffix .in-addr.arpa tacked on the end. You can actually name it whatever you want provided it matches the configuration in named.conf. Some examples will use localhost.rev for the reverse lookup filename.

=== Reference the Zone Files in named.conf ===

After checking the new zone files with named-checkzone, append a reference to them in the named.conf file. The configuration to be added is shown below.

zone "localhost" {
type master;
file "/etc/bind/zones/localhost";
};

zone "1.0.0.127.in-addr.arpa" {
type master;
file "/etc/bind/zones/1.0.0.127.in-addr.arpa";
};

If named-checkconf does not raise any errors, the next step is to reload the configuration with service named reload

== Reverse Lookup Zone for LAN Hosts ==

If you created a zone file for hosts on your local network, you should create a reverse lookup zone for completeness. The process is very similar to the creation of the localhost reverse lookup zone. A shortcut method is to copy the forward lookup zone file to a new filename of the IP of your LAN and then replace the A records with their corresponding PTR records.

Following the example given in the forward lookup, the reverse zone would look like what’s shown below.

$TTL 3600
@ IN SOA ns1.home. root.home. (
1 ; Serial - increment after modifying
604800 ; Refresh
86400 ; Retry
2419200 ; Expire
604800 ) ; Negative Cache TTL
;

@ IN NS ns1
@ IN A 192.168.1.1
router IN A 192.168.1.1
ns1 IN A 192.168.1.100
alpine IN A 192.168.1.100
media IN A 192.168.1.101

=== On-Going Maintenance of LAN Hosts ===

When using DNS for your own network’s hosts, there are a few steps to keep in mind when you add or remove hosts.

# Increment the serial number on the zone file.
# Test the zone file with named-checkzone
# Test the configuration with named-checkconf
# Reload the named service to make the changes active.

== Blocking Ads ==

The Response Policy Zone (RPZ) feature of BIND9 makes it easy to block access to an unwanted domain by returning a domain not found response instead of an IP address. Three steps are required to get this working.

# Enable to RPZ feature in the options section of named.conf
# Create a zone file lising unwanted domains.
# Reference the zone file in named.conf

=== Enable RPZ in named.conf options ===

Below is the options section of named.conf used in all the examples so far, but with the addition of response policy zones. New lines for RPZ appear following the ''recursion yes;'' directive. The remainder of named.conf has been omitted for brevity.

options {
directory "/var/bind";

listen-on { any; };
listen-on-v6 { none; };

dnssec-validation no;

forwarders {
1.1.1.1;
8.8.8.8;
};

recursion yes;

response-policy {
zone "rpz";
};
};

After making the changes, run named-checkconf to ensure there are no problems with the file.

=== Create an RPZ File ===

The RPZ zone file looks a lot like a regular zone file. One way to create it quickly is to start by copying the localhost zone file and then appending the hosts to be blocked.

For example:

# cd /etc/bind/zones

# cp localhost rpz

# cat << EOF >> rpz
example.com CNAME .
*.example.com CNAME .
EOF

The CNAME . record instructs BIND9 to return an NXDOMAIN (domain not found) response when the listed domain is queried. You probably wont want to block example.com, but it works well for demonstration purposes.

Check the file for errors by running named-checkzone rpz /etc/bind/zone/rpz and fix any errors before moving on to the next step.

=== Reference the RPZ file in named.conf ===

Just like the instructions for adding localhost and LAN host zones, adding the RPZ zone file involves appending a few lines to named.conf and running named-checkconf before reloading the service.

The format for a new zone should be familiar by now. It looks like what’s shown below.

zone "rpz" {
type master;
file "/etc/bind/zones/rpz";
};

After appending this to named.conf, be sure to run named-checkconf. Then reload the configuration with service named reload

=== Test RPZ Blocking ===

To test, use nslookup just like before when testing the forwarding configuration, LAN hosts, etc. Except this time, you’re hoping to see an error message.

Below an example showing the successful configuration to block example.com.

$ nslookup
> example.com
Server: 192.168.1.100
Address: 192.168.1.100#53

** server can't find example.com: NXDOMAIN

Continue testing with some other domains that should be allowed just to make sure it’s being blocked by the RPZ policy and not because the server is misconfigured.

=== Maintaining the RPZ File ===

Manually adding blocked domains to the RPZ zone file can quickly become tedious, but with this simple test involving example.com, you can see how it’s done. There are some folks on the internet who curate and maintain blocklists. One such source is https://github.com/hagezi/dns-blocklists

To use an ad blocking RPZ you’ll want to perform the following steps:

# Download the file from the source location.
# Check the file’s validity with named-checkzone
# Replace the existing /etc/bind/zones/rpz file with the downloaded one.
# Reload the configuration by running service named reload

New ad domains pop up all the time. The trick is automating the download of new block lists when they come out. A shell script like the one below can help.

#! /bin/sh

cd /etc/bind/zones || exit 1
curl -Os https://raw.githubusercontent.com/hagezi/dns-blocklists/main/rpz/multi.txt || exit 2
named-checkzone rpz ./multi.txt || exit 3
cp rpz rpz~ && mv multi.txt rpz
service named reload

== Next Steps ==

This document has taken you through the basics of setting up BIND9 on your Alpine server. There are many more features that haven’t been covered. Some of the interesting ones include:

* Wildcard subdomains
* IPv6 domains
* Secondary DNS servers
* DNSSEC encryption

Whichever you choose to pursue is up to you. See the [https://bind9.readthedocs.io BIND9 documentation] for more information.

Tutorials and Howtos

2025-02-02T15:00:57Z

DavesCodeMusings: /* DNS */

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}
=== Power management ===

* [[Configure action when power-button is pressed]]
* [[Suspend on LID close]]
* [[Configure Wake-on-LAN]]

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* [[VLAN]]

=== Security ===

* [[Securing Alpine Linux]] How to Secure Alpine Linux using Security Technical Implementation Guides (STIGs)
* Understand [[UEFI]] and enable [[UEFI Secure Boot]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Raspberry Pi|Raspberry Pi - Installation]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''
* [[RPI Video Receiver]]

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]]
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''

=== Database ===

* [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Setting up unbound DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall and VPN ===

* Alpine Wall ''(a new firewall management framework)''
** [[Alpine Wall]]
** [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[How-To Alpine Wall]]
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[IGMPproxy]]

=== HTTP and web services ===

* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system)''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* ZFS
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
** [[Setting up ZFS with native encryption]]
** [[ZFS scrub and trim]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]