{{Todo|This material has been re-organized..., but grouping should be checked: '''Howtos are smaller articles''' and '''tutorials are more detailed document'''}}

[[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.'''

'''The 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.

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions.

'''IMPORTANT:''' contributions on those pages must be complete articles as well as requesting topics to be covered, don't override already made contributions. If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].

{{Clear}}

= Howtos =

== Applications ==

=== Miscellaneous ===

* [[Ansible]] ''(Configuration management)''

=== 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)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[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)'' 
* [[Setting up lm_sensors]]
* [[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]]

=== Networking ===

* 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]]

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

== Backup and data migration ==

* [[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]]
* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

== Desktop ==
* [[Daily driver guide]]
* [[Alpine and UEFI]]
* [[Default applications]]
* Desktop cloud
** [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Desktop environments and Window managers]] (overall information only)
* [[Gaming on Alpine]]
* [[Printer Setup]]
* [[Remote Desktop Server]]
* Sound Systems
** [[ALSA]]
** [[PipeWire]]
** [[PulseAudio]]

== 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]]

== 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]]

== Post-Install ==

* [[CPU frequency scaling]]
* [[Repositories#Enabling_the_community_repository|Enable Community repository]] ''(Providing additional packages)''
* [[Enable Serial Console on Boot]]
* [[Alpine Linux Init System|Init System (OpenRC)]] ''(Configure a service to automatically boot at next reboot)''
** [[Multiple Instances of Services|Init System - Multiple Instances of Services]]
** [[Writing Init Scripts|Init System - Writing Init Scripts]]
* [[Installing Oracle Java|Oracle Java (installation)]]
* [[IGMPproxy]]
* [[Alpine Package Keeper|Package Management (apk)]] ''(How to add/remove packages on your Alpine)''
** [[Comparison with other distros|Package Management - Comparison with other distros]]
* [[Running glibc programs]]
* [[Setting up a new user]]
* [[Upgrading Alpine]]

== 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)''

== Server ==

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Setting up unbound DNS server]]
* [[TinyDNS Format]]

=== HTTP ===

* [[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]]
* [[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]]

==== Hostable Content ====

* [[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)''

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* 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]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Other Servers ===

* [[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]]
* [[Setting up an NFS server|nfs-server]]
* [[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 a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[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)''

== Storage ==

* [[Setting up disks manually|Disk setup (manual)]]
* [[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]]

= Tutorials =

== Miscellaneous ==

* [[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)''
* [[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]]

== Newbie corner ==

* [[How to get regular stuff working]] ''some notes on need-to-know topics''

== Servers ==

* [[Alpine production deploy]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
** [[MySQL|Production database: MySQL]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎]]
* Alpine production monitoring
** [[Cacti: traffic analysis and monitoring network]]
** [[Zabbix|Zabbix - the professional complete manager]]
* Kubernetes
** [[K8s]] Building a K8s Cluster on Alpine Linux

== Security ==

* [[Securing Alpine Linux]] How to Secure Alpine Linux using Security Technical Implementation Guides (STIGs)

Small-Time Email with Exim and Dovecot

2024-05-12T00:51:33Z

Dhorton: fixed group name

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /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.

The Dovecot package for Alpine comes with twenty configuration files in /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 /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 = 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

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 /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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"

Configure OpenLDAP

2023-04-28T16:11:40Z

Dhorton: Removing the link to stackoverflow, but keeping the reference. I didn't source the script from there. This is the original. I'm the same guy who asked the question on S.O.

Lightweight Directory Access Protocol (LDAP) is often employed as an authentication mechanism, providing a common username and password across many different applications. This tutorial shows how to install and configure the OpenLDAP package on Alpine Linux.

== Installing Packages ==

There is an Alpine package for OpenLDAP. However, simply adding the openldap apk is not enough to get you up and running. You'll also need to install a backend database and some LDAP command-line tools.

Here's how:

apk add openldap openldap-back-mdb openldap-clients

But, before you start up the slapd service and go, there's a bit of configuration to do.

== Customizing Configuration for OpenLDAP 2.3+ ==

The Alpine OpenLDAP package can use either a configuration directory (slapd.d) or a configuration file (slapd.conf). Since OpenLDAP version 2.3, the preferred method is to use the slapd.d configuration directory. Any official OpenLDAP documentation, including their [https://www.openldap.org/doc/admin26/quickstart.html quickstart guide], will use this configuration method.

First, create the slapd.d directory with the proper ownership and permissions.

install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d

Next, edit the slapd startup configuration to use the directory instead of the file.

# Open up /etc/conf.d/slapd in your favorite editor
# Comment out cfgfile="/etc/openldap/slapd.conf"
# Uncomment cfgdir="/etc/openldap/slapd.d"

Finally, get rid of the included slapd.conf file.

rm /etc/openldap/slapd.conf

== Updating Shared Libraries File Names ==

Open up /etc/openldap/slapd.ldif in your favorite editor. Search for the file names ending with <code>.la</code> and change the extension to <code>.so</code>

== Customizing Configuration for Your Domain ==

Your LDAP domain can be the same as your DNS domain or it can be completely different. Whatever you choose, be sure to use the LDAP naming convention of <code>dc=domain,dc=tld</code> rather than the dot separated DNS style of <code>domain.tld</code>

# Edit slapd.ldif again.
# Find the <code>olcSuffix:</code> keyword.
# Change the value to match your domain
# Find <code>olcRootDN:</code>
# Change the value to match your domain

Later, this document will assume the domain is <code>dc=home</code> or <code>dc=contoso,dc=com</code>, reflecting a domain of <code>home</code> or <code>contoso.com</code> respectively.

== Adding Schema for Linux User Accounts ==

The basic OpenLDAP configuration does not include anything other than core schema definitions. To be useful for Linux systems, the inetOrgPerson schema and NIS schema are often included. The schema files are provided with the OpenLDAP package. All that needs to be done is to include them in the slapd.ldif configuration along with the cosine.ldif dependency.

# Edit slapd.ldif again.
# Find the line <code>include: file:///etc/openldap/schema/core.ldif</code>
# Append similar lines referencing ''cosine.ldif'', ''inetorgperson.ldif'', and ''nis.ldif''.

It should look like this when you're done:

include: file:///etc/openldap/schema/core.ldif
include: file:///etc/openldap/schema/cosine.ldif
include: file:///etc/openldap/schema/inetorgperson.ldif
include: file:///etc/openldap/schema/nis.ldif

== Importing the Configuration ==
Verify slapd.ldif one last time and use the <code>slapadd</code> command to import it into the backend database.

slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif

There should be no errors, only a "Closing DB..." message.

Next, change ownership on the resulting files in /etc/openldap/slapd.d

'''If you skip this step, the slapd service will refuse to start.'''

chown -R ldap:ldap /etc/openldap/slapd.d/*

== Configuring the slapd Service ==

The pid directory is missing. We'll need to create it or the service won't start, so this needs to be done first.

install -m 755 -o ldap -g ldap -d /var/lib/openldap/run

Next, you can start the service and enable it at boot.

service slapd start
rc-update add slapd

== Testing ==

The OpenLDAP quickstart guide uses the <code>ldapsearch</code> utility to test the configuration.

ldapsearch -x -b "" -s base '(objectclass=*)' namingContexts

You should see your domain.

You can also test with <code>slapcat</code>

slapcat -n 0

This will dump the entire config database in LDIF format. You can also pipe to grep and specify your domain name to verify everything looks correct. When using grep, remember LDAP uses the format dc=domain,dc=com and not the more familiar domain.com.

Later, when you begin populating your LDAP database, you can use <code>slapcat -n 1</code> to see your information. (Zero is the config database. Numbers above zero are user-defined databases.)

Finally, you can run <code>netstat -tln</code> and look for LDAP port 389 in the output.

== Scripted Installation ==

If you want to automate the steps above, use the following script. Be sure to adjust the DOMAIN value to fit your needs.

export DOMAIN="dc=home"

echo "Installing packages..."
apk add openldap openldap-back-mdb openldap-clients

echo "Configuring for v2.3+ style slapd.d config directory..."
install -m 755 -o ldap -g ldap -d /etc/openldap/slapd.d
sed -i~ \
-e 's/^cfgfile=/#cfgfile=/' \
-e 's/^#cfgdir=.*/cfgdir=\"\/etc\/openldap\/slapd.d\"/' \
/etc/conf.d/slapd
rm /etc/openldap/slapd.conf

echo "Customizing for domain: ${DOMAIN}..."
sed -i~ \
-e 's/\.la$/.so/' \
-e "s/dc=my-domain,dc=com/${DOMAIN}/" /etc/openldap/slapd.ldif

echo "Adding schema for Linux user accounts..."
cp /etc/openldap/slapd.ldif /etc/openldap/slapd.ldif~1
awk '{ print } /^include:/ { sub("core", "cosine", $0); print $0; sub("cosine", "inetorgperson"); print $0; sub("inetorgperson", "nis"); print }' /etc/openldap/slapd.ldif~1 >/etc/openldap/slapd.ldif

echo "Importing configuration..."
slapadd -n 0 -F /etc/openldap/slapd.d -l /etc/openldap/slapd.ldif
chown -R ldap:ldap /etc/openldap/slapd.d/*

echo "Configuring slapd service..."
install -m 755 -o ldap -g ldap -d /var/lib/openldap/run
service slapd start
rc-update add slapd

== Creating an Organizational Structure ==

Now that the installation is done, you can start using your LDAP database. At a minimum, you'll need to create an organization within your LDAP directory. This is covered as step 11 in the OpenLDAP [https://openldap.org/doc/admin26/quickstart.html quickstart] document.

Here is an example using the contoso.com domain as the organization and <code>home</code>/<code>dc=home</code> as the base DN (update the baseDN if yours differs):

cat <<EOF >org.ldif
dn: dc=contoso,dc=com
objectclass: dcObject
objectclass: organization
o: Fictional Company
dc: contoso

dn: cn=Manager,dc=contoso,dc=com
objectclass: organizationalRole
cn: Manager
EOF

ldapadd -x -D "cn=Manager,dc=home" -w secret -f org.ldif

You may also want to create organizational units (OUs) to help keep your directory tidy.

Here's an LDIF to create ''People'' and ''Groups'' as OUs:

# Organizational unit for users
dn: ou=People,dc=home
changetype: add
objectClass: organizationalUnit
ou: People

# Organizational unit for groups.
dn: ou=Groups,dc=home
changetype: add
objectClass: organizationalUnit
ou: Groups

Import the OUs with an ldapadd command similar to the one used to create the organization.

Now that this is done, you're ready to connect to the LDAP server with the administration tool of your choice and begin populating users, groups, etc. [http://ldapadmin.org/ LDAPAdmin] is an oldie, but a goodie for Windows users.

== Next Steps ==

The configuration presented here does not include provisions for TLS (encrypted) communication. It should not be used on an untrusted network. Refer to the official OpenLDAP docs for instructions on setting up encrypted LDAP connections.

== Reference ==

https://openldap.org/doc/admin26/quickstart.html

https://stackoverflow.com/questions/72132704/did-i-import-inetorgperson-schema-correctly-for-openldap-on-alpine-linux/

[[Category:Networking]]

Small-Time Email with Exim and Dovecot

2022-05-15T13:36:30Z

Dhorton: /* Creating Credentials for Dovecot Users */

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /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.

The Dovecot package for Alpine comes with twenty configuration files in /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 /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 = 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

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 /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-15T13:31:31Z

Dhorton: /* Creating a Dovecot User and Password */

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /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.

The Dovecot package for Alpine comes with twenty configuration files in /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 /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 = 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

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 /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T23:10:50Z

Dhorton: /* Troubleshooting Mail Delivery */

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /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.

The Dovecot package for Alpine comes with twenty configuration files in /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot will use /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T23:09:17Z

Dhorton: /* Troubleshooting Mail Delivery */

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /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 mailboxes 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.

The Dovecot package for Alpine comes with twenty configuration files in /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot will use /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T16:46:52Z

Dhorton: /* 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot will use /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T16:46:27Z

Dhorton: /* 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot will use /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T16:44:41Z

Dhorton: /* Creating a Dovecot User and Password */

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot will use /etc/passwd for looking up user information, but not authentication. Technically, /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 /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T15:40:50Z

Dhorton: /* Using and Enjoying Your Small-Time Email 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T15:34:40Z

Dhorton: /* Scripted Installation and Configuration */

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 send 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.

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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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

2022-05-11T15:31:29Z

Dhorton:

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 send 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.

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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /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 user passwords with: doveadm pw -s sha512-crypt"

Tutorials and Howtos

2022-05-11T15:25:28Z

Dhorton: /* Mail */

{{Todo|This material needs to be re-organized .. as '''Howtos are smaller articles''' and '''tutorials are more detailed document''' both need to be reordered as independent sections }}

[[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.'''

'''The 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.

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions.

'''IMPORTANT:''' contributions on those pages must be complete articles as well as requesting topics to be covered, don't override already made contributions. If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].

{{Clear}}

=== Postinstall ===

* [[Post installation|Post installation notes]]

==== Postinstall: desktops and applications ====

* [[Desktop environments and Window managers]] (overall information only)
** [[Xfce]]
** [[LXQt]]
** [[Openbox]]
** [[MATE]]
* [[Alpine and UEFI|Alpine and UEFI Support Status and related topics]]

==== Developers: compilers, IDEs and tools ====

* [[Alpine newbie developer]]
** [[Alpine newbie developer: gitea|Alpine newbie developer: Git management web frontend gitea]]
** [[Alpine newbie developer: full stack web]]

==== Servers: deploy in production ====

* [[Alpine production deploy]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
** [[Production DataBases : mysql|Production database: MySql]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎]]
* Alpine production monitoring
** [[Cacti: traffic analysis and monitoring network]]
** [[Zabbix|Zabbix - the professional complete manager]]
* Kubernetes
** [[K8s]] Building a K8s Cluster on Alpine Linux

== Storage ==

* [[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]]

* [[Setting up disks manually]] 
* [[Setting up a software RAID array]]

* [[Raid Administration]]
* [[Setting up encrypted volumes with LUKS]]
* [[Setting up LVM on LUKS]]
* [[Setting up Logical Volumes with LVM]]
** [[Setting up LVM on GPT-labeled disks]]
** [[Installing on GPT LVM]]
* [[Filesystems|Formatting HD/Floppy/Other]] 

* [[Setting up iSCSI]]
** [[iSCSI Raid and Clustered File Systems]]
* [[Setting up NBD]]
* [[Setting up ZFS on LUKS]]
* [[Setting up ZFS with native encryption]]
* [[High performance SCST iSCSI Target on Linux software Raid]] ''(deprecated)'' 
* [[Linux iSCSI Target (TCM)]]
* [[Disk Replication with DRBD]] 

* [[Burning ISOs]] 
* [[Partitioning and Bootmanagers]]
* [[Migrating data]]
* [[Create a bootable SDHC from a Mac]]
* [[Alpine on ARM]]

== Networking ==

* [[Configure Networking]]
* [[Connecting to a wireless access point]]
* [[Bonding]]
* [[Vlan]]
* [[Bridge]]
* [[Bridge wlan0 to eth0]]
* [[OpenVSwitch]]
* [[How to configure static routes]]
* [[Configure a Wireguard interface (wg)]]

* [[Alpine Wall]] - [[How-To Alpine Wall]] - [[Alpine Wall User's Guide]] ''(a new firewall management framework)''

* [[PXE boot]]

* [[Using serial modem]]
* [[Using HSDPA modem]]
* [[Setting up Satellite Internet Connection]]
* [[Using Alpine on Windows domain with IPSEC isolation]]

* [[Setting up a SSH server]] ''(Using SSH is the preferred way to administer your box remotely)'' 
** [[HOWTO OpenSSH 2FA with password and Google Authenticator]] ''(A simple two factor setup for OpenSSH)''
* [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* [[How to set up Alpine as a wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''
* [[Setting up a OpenVPN server with Alpine]] ''(Allowing single users or devices to remotely connect to your network)''

* [[Experiences with OpenVPN-client on ALIX.2D3]] 

* [[Generating SSL certs with ACF]] 
* [[Setting up unbound DNS server]]
* [[Setting up nsd DNS server]]
* [[TinyDNS Format]]
* [[Fault Tolerant Routing with Alpine Linux]] 
* [[Freeradius Active Directory Integration]]
* [[Multi_ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[OwnCloud]] ''(Installing OwnCloud)''

* [[Seafile: setting up your own private cloud]]

* [[GNUnet]]

== Post-Install ==


* [[Setting up a new user]]
* [[Enable Community Repository]] ''(Providing additional packages)''
* [[Alpine Linux package management|Package Management (apk)]] ''(How to add/remove packages on your Alpine)''

** [[Comparison with other distros]]
* [[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]]
* [[Alpine Linux Init System|Init System (OpenRC)]] ''(Configure a service to automatically boot at next reboot)''
** [[Multiple Instances of Services]]

* [[Alpine setup scripts#setup-xorg-base|Setting up Xorg]]
* [[Upgrading Alpine]]


* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator]] ''(A simple two factor setup for OpenSSH)''
* [[setup-acf]] ''(Configures ACF (webconfiguration) so you can manage your box through https)''
* [[Changing passwords for ACF|Changing passwords]]
* [[Ansible]] ''(Configuration management)''

* [[Enable Serial Console on Boot]]

* [[How to get regular stuff working]] ''some notes on need-to-know topics''
* [[Installing Oracle Java]]
* [[Rsnapshot|Setting up periodic backups with <samp>rsnapshot</samp>]]

== Virtualization==

* [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
* [[Xen Dom0 on USB or SD]]
* [[Create Alpine Linux PV DomU]]
* [[Xen PCI Passthrough]]
* [[Xen LiveCD]]
* [[QEMU]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[Docker]]
* [[Install Alpine on VirtualBox]]
* [[Install Alpine on VMWare]]

== Desktop Environment ==

* [[AwesomeWM]]
* [[dwm]]
* [[EyeOS]] ''(Cloud Computing Desktop)''
* [[Gnome]]
* [[KDE]]
* [[MATE]]
* [[Oneye]] ''(Cloud Computing Desktop - Dropbox Alternative)''
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Remote Desktop Server]]
* [[River]]
* [[Suspend on LID close]]
* [[Sway]]
* [[Xfce]]
* [[Sound Setup]]
* [[PipeWire]]
* [[Printer Setup]]
* [[Default applications]]

== Raspberry Pi ==

* [[Raspberry Pi|Raspberry Pi (Installation)]]
* [[Raspberry Pi - Headless Installation]]
* [[Classic install or sys mode on Raspberry Pi]]
* [[RPI Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Linux Router with VPN on a Raspberry Pi]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi Zero W - Installation]]
* [[Raspberry Pi Bluetooth Speaker]]

== PowerPC ==

* [[Ppc64le|Powerpc64le (Installation)]]

== IBM Z (IBM z Systems) ==

* [[s390x|s390x (Installation)]]

== Applications ==

=== Telephony ===
* [[Setting up Zaptel/Asterisk on Alpine]]
** [[Setting up Streaming an Asterisk Channel]]
* [[Freepbx on Alpine Linux]]
* [[FreePBX_V3]] ''(FreeSWITCH, Asterisk GUI web acces tool)''
* [[2600hz]] ''(FreeSWITCH, Asterisk GUI web access tool)''
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== Mail ===
* [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
** [[Hosting Web/Email services on Alpine]]
* [[ISP Mail Server HowTo]] 
** [[ISP Mail Server Upgrade 2.x]]
** [[ISP Mail Server 2.x HowTo]] ''(Beta, please test)''
** [[ISP Mail Server 3.x HowTo]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* [[Protecting your email server with Alpine]]
* [[Setting up clamsmtp]]
* [[Setting up dovecot with imap and ssl]]
* [[relay email to gmail (msmtp, mailx, sendmail]]

=== HTTP ===
* [[Lighttpd]]
** [[Lighttpd Https access]]
** [[Setting Up Lighttpd with PHP]]
** [[Setting Up Lighttpd With FastCGI]]
* [[Cherokee]]
* [[Nginx]]
** [[Nginx_with_PHP#Nginx_with_PHP|Nginx with PHP]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]

* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)'' 

* [[Setting up Transparent Squid Proxy]] 
** [[SqStat]] ''(Script to look at active squid users connections)''
** [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[Setting up Explicit Squid Proxy]]

* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[DokuWiki]]
* [[Darkhttpd]]
* [[Tomcat]]
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''

=== Other Servers ===
* [[Setting up a ssh-server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator]] ''(A simple two factor setup for OpenSSH)''

* [[Configure OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a nfs-server]]
* [[Setting up a samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc]] ''(Active Directory compatible domain controller)''
* [[Phpizabi]] ''(Social Networking Platform)''
* [[Statusnet]] ''(Microblogging Platform)''
* [[Pastebin]] ''(Pastebin software application)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system)''
* [[Request-Tracker]] ''(Ticket system)''
* [[OsTicket]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''

* [[Alpine_newbie_developer: gitea|Setting up Git management web frontend gitea]]
* [[Cgit]]
** [[Setting up a git repository server with gitolite and cgit]] 
* [[Roundcube]] ''(Webmail system)''
* [[Glpi]] ''(Manage inventory of technical resources)''

* [[How to setup a Alpine Linux mirror]]
* [[Cups]]
* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''
* [[How To Setup Your Own IRC Network]] ''(Using {{Pkg|charybdis}} and {{Pkg|atheme-iris}})''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[Chrony and GPSD | Using chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Sending SMS using gnokii]]
* [[IPTV How To|Internet Protocol television (IPTV)]]
* [[UniFi_Controller]]
* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Odoo]]

=== Monitoring ===
* Setting up [[collectd]]
* [[Traffic monitoring]] 
* [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Setting up monitoring using rrdtool (and rrdcollect)]]
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[LTTng]] ''(Kernel and userspace tracing)''
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting up Smokeping|Smokeping]] ''(Network latency monitoring)'' 
** [[Setting up MRTG and Smokeping to Monitor Bandwidth Usage and Network Latency]]
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance)'' 
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 

* [[IP Accounting]] 
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''

* [[Piwik]] ''(A real time web analytics software program)''
* [[Awstats]] ''(Free log file analyzer)''
* [[Intrusion Detection using Snort]]
** [[Intrusion Detection using Snort, Sguil, Barnyard and more]]
* [[Dglog]] ''(Log analyzer for the web content filter DansGuardian)''

* [[Webmin]] ''(A web-based interface for Linux system)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Linfo]]

* [[Setting up lm_sensors]]

* [[ZoneMinder video camera security and surveillance]]

== Misc ==

* [[:Category:Shell]]
* [[:Category:Programming]]
* [[Running glibc programs]]
* [[:Category:Drivers]]
* [[:Category:Multimedia]]
* [[Kernel Modesetting]]
* [[CPU frequency scaling]]

== Complete Solutions ==
* [[Unattended Boot and Install]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [https://codeberg.org/AVG7/alpine-sway-x86_64 DIY Live-USB-Stick with Sway]
* [[Alpine on the Aopen Chromebase or Chromebox Mini with Mainline Kernel]]
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[High performance SCST iSCSI Target on Linux software Raid]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[Experiences with OpenVPN-client on ALIX.2D3]]
* [[Building a cloud with Alpine Linux]]

* [[ISP Mail Server HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-serivce ISP mail server)''
** [[ISP Mail Server Upgrade 2.x]]
** [[ISP Mail Server 2.x HowTo]] ''(Beta, please test)''
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
* [[Streaming Security Camera Video with VLC]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small_Office_Services]]



== Newbies ==

* [[Alpine_newbie]] (for overall information in funny sections)

[[Category:System_Administration]]
[[Category:Installation]]

Small-Time Email with Exim and Dovecot

2022-05-11T15:23:05Z

Dhorton:

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 send 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.

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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /etc/mail/aliases. The format is the same as Sendmail.

Small-Time Email with Exim and Dovecot

2022-05-11T15:21:58Z

Dhorton: /* Why would you do this? */

{{ draft }}

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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 send 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.

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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /etc/mail/aliases. The format is the same as Sendmail.

Small-Time Email with Exim and Dovecot

2022-05-11T15:21:07Z

Dhorton:

{{ draft }}

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 you 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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 send 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.

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 /etc/aliases for mail delivery, you should be aware that Exim puts this file in /etc/mail/aliases. The format is the same as Sendmail.

Small-Time Email with Exim and Dovecot

2022-05-11T15:08:27Z

Dhorton:

{{ draft }}

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 you 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 typo 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!

Small-Time Email with Exim and Dovecot

2022-05-11T14:58:05Z

Dhorton: /* Configuring Dovecot */

{{ draft }}

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 you 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 from a typo in the Dovecot config file.

''Work in progress. More to come.''

Small-Time Email with Exim and Dovecot

2022-05-11T14:57:40Z

Dhorton: /* Configuring Dovecot */

{{ draft }}

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 you 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 /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 = 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

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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 from a typo in the Dovecot config file.

''Work in progress. More to come.''

Small-Time Email with Exim and Dovecot

2022-05-11T14:56:36Z

Dhorton: /* Testing the Dovecot Setup */

{{ draft }}

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 you 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 exim dovecot mailx

== 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 /etc/exim/exim.conf
# Open /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 exim, 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 int the directory /var/spool/exim/msglog. If there are files in here, 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 /var/mail directory.

== 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 /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 13 lines.

First, make a backup copy of /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 = passwd-file
args = scheme=sha512-crypt username_format=%n /etc/dovecot/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 a Dovecot User and Password ==

As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this 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 and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /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.

== 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 from a typo in the Dovecot config file.

''Work in progress. More to come.''