Jason's Home Page - Linux HOWTOs

cyrus-imap-2.5 - IMAP/POP3/Sieve server created at Carnegie Mellon University ChangeLog

Web site:	https://www.cyrusimap.org/
Repository:	https://github.com/cyrusimap/cyrus-imapd
Wikipedia:	https://en.wikipedia.org/wiki/Cyrus_IMAP_server

HOWTO

# Cyrus IMAP 2.5.17 (GitHub release date: 2021-03-08)
# =================
# Below is the latest of the 2.5.x (legacy) tree.  Installation and
# configuration between major release branches can vary greatly, so we cover
# each one separately.  Go to the main Cyrus IMAP HOWTO to see other covered
# major releases: 2.5, 3.0, etc.

# Cyrus IMAP 2.5.x does NOT support OpenSSL 3.0, so make sure you've got nothing
# newer than 1.1.1 installed if you will be using it.  1.1.1 is an LTS one, but
# even then it will only be supported until 2023-09-11.  If you have existing
# mailboxes, you may want to consider upgrading Cyrus IMAP from 2.5.x to 3.0,
# then 3.2, then 3.4, then 3.6 where you'll be able to run OpenSSL 3.0
#
# (or set up a new server with Cyrus IMAP 3.8, then remote copy everything or
#  sync between them or something else like that...)

# Releases used to be located at ftp.cyrusimap.org, they are not handle at
# GitHub.  If you try to download it as shown below and it is not found,
# look through GitHub Releases:
# https://github.com/cyrusimap/cyrus-imapd/releases

# You can read about new releases on the web site or the cyrus-announce
# mailing list:
# https://www.cyrusimap.org/2.5/feedback-mailing-lists.html
#
# The old cyrus-announce mailing list archives are here, they are no longer updated:
# https://lists.andrew.cmu.edu/pipermail/cyrus-announce/
#
# Cyrus IMAP 2.5.17 (and 2.4.22, 3.0.15) announcement:
# https://cyrus.topicbox.com/groups/announce/T65d466b174f8d001

# If you have trouble, look at the mailing lists (see above) and the GitHub issue tracker:
# GitHub Issues

# This HOWTO is an example of installing or upgrading Cyrus IMAP to be
# configured a particular way.  There are MANY different ways to set it up.
# If you are upgrading from an older version, see doc/install-upgrade.html and
# release notes for the one you're upgrading to.

# GitHub release cyrus-imapd-2.5.17
#
# Release notes for 2.5.0 through 2.5.17:
# Cyrus IMAP 2.5 Releases
#
# Cyrus IMAP 2.5 documentation:
# Cyrus IMAP 2.5 Installation Guide
# - Do It Yourself Build Dependencies
# Cyrus IMAP 2.5 Configuration Guide
# Cyrus IMAP 2.5 Administrator Guide
# Cyrus IMAP 2.5 Features
# Cyrus IMAP 2.5 FAQ

# If you're about to upgrade Cyrus, I would highly suggest backing up
# everything.  If you use tarballs and have lots of e-mails with lots of
# attachments, the files could end up being massive, and could take a long
# time to compress everything.
#
# A good idea to shut it down before backing it up if possible.  You will
# need to start/restart it after the upgrade is complete.  Possibly something
# like this below to back it up.  Ideally you would want to be running rsync
# to copy the files off site periodically or using some other backup procedure.
# [ newer versions include backup and server sync features ]
su
cd
mkdir -p -m 0700 backup/cyrus/$(date +%Y%m%d)
chown cyrus backup/cyrus/$(date +%Y%m%d)
cd backup/cyrus/$(date +%Y%m%d)
test -d /usr/cyrus &&
tar cJvf usr-cyrus.tar.xz /usr/cyrus
test -d /usr/local/cyrus &&
tar cJvf usr-local-cyrus.tar.xz /usr/local/cyrus
tar cJvf usr-sieve.tar.xz /usr/sieve
tar cJvf var-imap.tar.xz /var/imap
tar cJvf var-spool-imap.tar.xz /var/spool/imap
test -d /usr/cyrus/bin &&
su cyrus -c "/usr/cyrus/bin/ctl_mboxlist -d > mailboxes.db.txt"
test -d /usr/local/cyrus/bin &&
su cyrus -c "/usr/local/cyrus/bin/ctl_mboxlist -d > mailboxes.db.txt"
cp -a /etc/cyrus.conf /etc/imapd.conf .
chown -R cyrus:root .
chmod -R o-rwx .
exit

# Prerequisites:
# If you run autoreconf:
#   autoconf
#   automake
#   libtool
# bison
# Cyrus SASL (compiled with the same version of bdb)
# flex
# pcre
# gperf
# libcap (if you pass --with-libcap)
# Jansson (optional; for the Cyrus httpd service)
# util-linux's libuuid
# OpenSSL >= 0.9.4 or LibreSSL (if you want imaps, pop3s)
# pkg-config >= 0.9.0
# Used with 'make check' (optional):
#   CUnit
#   Cyrus SASL's plain
#   Cyrus SASL's md5
# Berkeley DB >= 3.0.55 (optional)
# groff (optional)
# ClamAV (optional)
# Kerberos (optional)
# libical >= 0.48 (optional; for the Cyrus httpd service)
# libxml 2.x (optional; for the Cyrus httpd service)
# If using the "sql" backend for cyrusdb:
#   MySQL or MariaDB (optional; --with-mysql)
#   PostgreSQL (optional; --with-pgsql)
#   SQLite (optional; --with-sqlite)
# Net-SNMP >= 4.2 (optional)
# OpenLDAP (optional; --with-ldap)
# Perl >= 5.x (optional; --with-perl; needed for cyradm and some installation scripts)
# tcp wrappers (optional)
# transfig (...or the Slackware package in 't')
# valgrind
# INN (to export newsgroups with IMAP)
# A MTA: sendmail or Postfix

# If you upgrade from one minor Berkeley DB release to another, you may
# need to run 'db_recover /var/imap/db' before starting Cyrus IMAP again.
#
# FYI, Berkeley DB's use is discouraged and support will be removed from
# 3.x  In 2.4.18, the defaults are skiplist or flat for all databases.

# Get the source
cd
test -f installed/cyrus-imapd-2.5.17.tar.gz &&
mv installed/cyrus-imapd-2.5.17.tar.gz .
test ! -f cyrus-imapd-2.5.17.tar.gz &&
  wget https://github.com/cyrusimap/cyrus-imapd/releases/download/\
cyrus-imapd-2.5.17/cyrus-imapd-2.5.17.tar.gz

# Verify tarball w/ sha256sum:
# (this came from my gpg-verified tarball;
#  no sha256sum - this is an alternative: openssl sha256 cyrus-imapd-2.5.17.tar.gz)
echo "9a160aadbf980f17d5d2b146e999abe2bff9266bbf0cf5b3a4013ed8302bef\
6a  cyrus-imapd-2.5.17.tar.gz" | sha256sum -c

# Verify tarball w/ gpg:
( gpg --list-keys B36378E0 > /dev/null 2>&1 ||
  gpg --keyserver pgp.mit.edu --recv-keys B36378E0 ) &&
wget -nc https://github.com/cyrusimap/cyrus-imapd/releases/download/\
cyrus-imapd-2.5.17/cyrus-imapd-2.5.17.tar.gz.sig &&
  gpg --verify cyrus-imapd-2.5.17.tar.gz.sig &&
   rm cyrus-imapd-2.5.17.tar.gz.sig

# Extract the source
mkdir -p -m 0700 ~/src
cd ~/src
find -maxdepth 1 -type d -name "cyrus-imapd-*" -exec rm -r {} \;
tar xzvf ~/cyrus-imapd-2.5.17.tar.gz
cd cyrus-imapd-2.5.17
test $UID = 0 && chown -R root:root .

## Before you actually install it, make sure you read (at least) this, and
## there is lots of additional information on the web site.
## IMAP Installation Guide
# lynx ./doc/install.html

# If your OpenSSL is from a distribution package, you probably do not need
# to specify a prefix path with --with-ssl.

# If you have NetSNMP installed but do not want to compile-in support for
# it, use --without-snmp

# --enable-http and --with-sqlite are for the Cyrus httpd service
# See ./doc/install-http.html
#
# I have only compiled, but not implemented this in the past, but with 2.5.12
# I did not even compile it after some ld errors about libical.

# If you do not need IMAP IDLE support via idled, leave off --enable-idled

# See the documentation under ./doc/ and the output of
# './configure --help' for other configure flags

# Configure the build
LIB=lib
test $(uname -m) = 'x86_64' && LIB=lib64
./configure --libdir=/usr/local/${LIB} --mandir=/usr/local/man \
--without-snmp --with-openssl=/usr/local/ssl --with-sqlite --enable-idled \
--enable-http --enable-replication
unset LIB

# Build it
make all CFLAGS=-O2 LDFLAGS="-s"

# Test the build if you passed --enable-unit-tests to configure (CUnit)
make check

# Become root to install it
su

# The Perl bits may put man pages in /usr/local/share/man/, instead of
# whatever configure told it to do, so if that does not exist, create a
# symlink to /usr/local/man/ so 'man' can find the man pages in there.
# ...or update MANPATH in /etc/profile or your non-root user's
# ~/.bash_login
test -d /usr/local/man && test ! -e /usr/local/share/man &&
ln -s /usr/local/man /usr/local/share/man

# If your Perl does not use /usr/local/lib*/perl5/, create a symlink there
# so it will know about Cyrus' modules:
test -d /usr/lib64/perl5 && test ! -e /usr/local/lib64/perl5 &&
ln -sf /usr/lib64/perl5 /usr/local/lib64/perl5
test -d /usr/lib/perl5 && test ! -e /usr/local/lib/perl5 &&
ln -sf /usr/lib/perl5 /usr/local/lib/perl5

# Install it
make install
ldconfig

# If you are upgrading and have fulldirhash enabled in /etc/imapd.conf,
# run tools/rehash:
egrep -q "^fulldirhash: 1$" /etc/imapd.conf &&
su cyrus -c "tools/rehash /etc/imapd.conf"

# If this is an upgrade (not a new installation), you should be OK
# to restart Cyrus IMAP now.  Cross your fingers:
test -x /etc/rc.d/rc.cyrus && /etc/rc.d/rc.cyrus start

## If you are upgrading from 2.4 to 2.5:
#
# Run this to upgrade index files - it is safe to run while Cyrus IMAP is
# running:
/usr/local/cyrus/bin/reconstruct -V max
#
# Run this to update/check quotas:
/usr/local/cyrus/bin/quota -f
#
# Now look for config file entries that you may need to update, like these:
# autocreatequota -> autocreate_quota
# tls_ca_file -> tls_client_ca_file
# tls_cert_file -> tls_server_cert
# tls_key_file -> tls_server_key

# Make sure your non-root user can remove the source later
chown -R $(logname) .
chmod -R u+w .

# Become yourself again
exit

# Save the source for later
cd
mkdir -p -m 0700 installed
rm -f installed/cyrus-imapd-*.tar.*
mv cyrus-imapd-2.5.17.tar.gz installed/

# Skip down to the "Configuration" section near the bottom

# 2.5.x from Git:
# ===============
# Prerequisites:
# Git
# autoconf
# automake
# libtool

# Get it
mkdir -p -m 0700 ~/src
cd ~/src
test -d ./cyrus-imapd-2.5.x && git pull
test ! -d ./cyrus-imapd-2.5.x &&
git clone -b cyrus-imapd-2.5 --single-branch \
https://github.com/cyrusimap/cyrus-imapd.git cyrus-imapd-2.5.x

# Generate configure, etc.
cd cyrus-imapd-2.5.x
test $UID = 0 && chown -R root:root .
test -f config.status && make distclean
test ! -f configure && autoreconf -f -i

# Then continue with the 2.5.17 tarball instructions above
# from the part where you run configure

# Configuration
# =============
# Become root
# Use -p to keep $USER set
su -p

# Add a cyrus user that is a member of the mail group:
id cyrus > /dev/null 2>&1 ||
useradd -c "Cyrus IMAP" -d /var/imap -g mail -s /bin/bash -r cyrus

## Add these to /etc/services if they're not in there already:
# pop3      110/tcp
# nntp      119/tcp # If you built IMAPd with INN support
# imap      143/tcp
# nntps     563/tcp # If you built IMAPd with INN and OpenSSL support
# imaps     993/tcp # If you built IMAPd with OpenSSL support
# pop3s     995/tcp # If you built IMAPd with OpenSSL support
# kpop      1109/tcp # If you built SASL with Kerberos support
# lmtp      2003/tcp    # If you use lmtp over tcp (not a unix socket)
# smmap     2004/tcp    # If you use smmapd
# csync     2005/tcp    # If you use replication
# mupdate   3905/tcp    # If you use mupdate
# sieve     4190/tcp
# fud       4201/udp

# Create a /etc/cyrus.conf
# Read 'man cyrus.conf', look over the samples in master/conf/, and/or check
# out my sample:
( cd /etc
  test ! -f cyrus.conf &&
   wget http://englanders.us/pub/linux/misc/cyrus.conf )

# Create a /etc/imapd.conf
# Read 'man imapd.conf', and/or check out my sample:
( cd /etc
  test ! -f imapd.conf &&
   wget http://englanders.us/pub/linux/misc/imapd.conf )

# Create the required directories:
mkdir -p /var/imap /var/spool/imap /usr/sieve
chown cyrus /var/imap /var/spool/imap /usr/sieve
chgrp mail /var/imap /var/spool/imap /usr/sieve
chmod 750 /var/imap /var/spool/imap /usr/sieve

# Make sure you're still in ~nonrootuser/src/cyrus-imapd-* when you run
# this part
cd $(eval echo ~$USER)/src/cyrus-imapd-*

# As the cyrus user, create the Cyrus directory structure
su cyrus
tools/mkimap
tools/rehash /etc/imapd.conf
exit

# Make sure these directories have correct ownership & permissions:
chown cyrus:mail /var/imap/db /var/imap/socket
chmod 750 /var/imap/db /var/imap/socket

# If the filesystem is ext2 (not ext3, ext4, reiserfs, xfs, jfs, ...):
cd /var/imap
mkdir -p /var/spool/mqueue
chattr +S . user quota user/* quota/*
chattr +S /var/spool/imap /var/spool/imap/* /var/spool/mqueue

## Setting up SSL/TLS in Cyrus IMAP

## Relevant lines in /etc/imapd.conf:
##
# tls_server_ca_dir: /usr/local/ssl/certs
## -or-
# tls_server_ca_dir: /etc/ssl/certs
## -or-
# tls_server_ca_file: /var/imap/abcdefg.pem
## -and-
# tls_server_cert: /var/imap/cert.pem
# tls_server_key: /var/imap/key.pem

## To use existing Let's Encrypt certificates:
##
## Copy certificate files in place (you can automate this with certbot's
## --deploy-hook option):
# cd /etc/letsencrypt/live/imap.example.com
# cp fullchain.pem /var/imap/cert.pem
# cp privkey.pem /var/imap/key.pem
# chown cyrus:mail /var/imap/cert.pem /var/imap/key.pem
# chmod 640 /var/imap/cert.pem /var/imap/key.pem

# You can also use CAcert certificates cacert.org, though
# those are only going to be seen as valid on the other end
# if the remote server has the CAcert CA certificate

## To create SSL/TLS certs for Cyrus, become yourself again (run 'exit'), go
## to the bottom of the OpenSSL howto to create SSL certs, then come back here
## and become root again (run 'su')
## If you create them yourself, they will be self-signed and
## not seen as valid on the other end if verification is done
## and they do not have your CA certificate
##
## While su'd to root, cd in to your non-root user home directory and put
## them in place:
# cd $(egrep "^$(logname):" /etc/passwd | awk -F: '{ print $6 }')
# cp demoCA/cacert.pem /var/imap/CAcert.pem
# cp newcert.pem /var/imap/cert.pem
# cp newkey.pem /var/imap/key.pem
# chown cyrus:mail /var/imap/*.pem
# chmod 640 /var/imap/*.pem

## If you're using sendmail, add these to the bottom of your sendmail.mc to
## make sendmail use Cyrus IMAP as your local mailer:
# MAILER(cyrusv2)dnl
# define(`confLOCAL_MAILER', `cyrusv2')dnl

# If you need a startup script, try this sample.  Make sure you start cyrus
# before sendmail.
cd /etc/rc.d
test -f rc.cyrus && ( mv -f rc.cyrus rc.cyrus.old ; chmod 600 rc.cyrus.old )
wget https://englanders.us/pub/linux/misc/rc.cyrus && chmod 755 rc.cyrus
test -f rc.cyrus.old && diff -q rc.cyrus.old rc.cyrus && rm rc.cyrus.old

## To have syslog log info from cyrus to /var/log/cyrus, add this line to
## /etc/syslog.conf and HUP syslogd:
# local6.debug /usr/log/cyrus
#
## To have syslog-ng log info crom cyrus to /var/log/cyrus, add these lines
## to your syslog-ng.conf and HUP syslog-ng:
# filter cyrus { facility(local6) and level(debug); };
# destination cyrus { file("/var/log/cyrus"); };
# log { source(local); filter(cyrus); destination(cyrus); };

## If you built in libwrap (tcp wrappers) support and want to restrict
## access to Cyrus with /etc/hosts.allow and /etc/hosts.deny, use service
## names 'imap', 'pop', and 'sieve'.  See 'man 5 hosts_access' for more info
## about those files.  Here's an example hosts.deny:
# imap: PARANOID, bad.evil.server.org, 1.2.3.4/255.255.255.0

# If you have a bad user that you want to deny, see 'man cyr_deny'
# (>= 2.5.x)

# If you want to maintain Sieve scripts from a web GUI, try these:
# Roundcube (a webmail with Sieve support)
# SmartSieve
# Squirrelmail (a webmail with a Sieve plugin)
# Websieve
# clients - Sieve.Info

# There is lots of info in the doc subdirectory under the source tree.
# Read through doc/install-perf.html for performance hints, read
# doc/install-virtdomains.html for info about setting up Cyrus for
# virtual domains, etc.

# To clean up old files that were left behind after an upgrade, if you
# didn't do the uninstall part at the bottom, look in these directories for
# files that have a date that doesn't match the rest:
# /usr/cyrus/bin
# /usr/local/include/cyrus

## Cyrus IMAP 3.x does not support Berkeley DB at all, so this only applies
## to 2.5 and older versions, and even them may not apply if you use
## skiplist or other non-BDB formats:
##
## If you have any Berkeley-DB format database files, you can run something
## like this from a cron job to remove old, unused log files:
# test -d /var/imap/db -a -x /usr/bin/db_archive &&
#  /usr/bin/db_archive -d -h /var/imap/db

## If you want telemetry logging for a user who logs in with username foo,
## create a directory like so, writable by the user that runs Cyrus IMAP.
## As soon as the user opens a new connection a file with detailed logging
## info will appear.  The file name will be something like imap-1234 where
## 1234 is the PID of the imapd process that is handling them.  To stop it,
## remove the directory.  If you want time stamps in these logs, add
## "logtimestamps: 1" (without the quotes) to /etc/imapd.conf and restart.
## https://cyrusimap.org/imap/faqs/o-telemetry.html
# mkdir /var/imap/log/foo
# chown cyrus /var/imap/log/foo
# chmod 700 /var/imap/log/foo

# If you ever want to uninstall Cyrus IMAP, this should do it.
#
# You should definitely back up everything first just in case, 'make
# uninstall' (as root) may be enough, the rest is just in case you have old
# files from previous versions.
cd
su
test -x /etc/rc.d/rc.cyrus && /etc/rc.d/rc.cyrus stop
sleep 3
killall $(find /usr/cyrus/bin -type f -exec basename {} \; | grep -v master)
sleep 3
killall $(find /usr/local/cyrus/bin -type f -exec basename {} \; | grep -v master)
sleep 3
test -d src/cyrus-imapd-* && ( cd src/cyrus-imapd-* ; make uninstall )
test -d /usr/cyrus && rm -r /usr/cyrus
test -d /usr/local/cyrus && rm -r /usr/local/cyrus
for pfx in /usr /usr/local;
do
  ( cd ${pfx}/bin
    rm -f imtest installsieve sieveshell
    test -L pop3test && rm pop3test
    test -L nntptest && rm nntptest
    test -L lmtptest && rm lmtptest
    test -L smtptest && rm smtptest
    test -L mupdatetest && rm mupdatetest
    test -L sivtest && rm sivtest
    test -L synctest && synctest )
  test -d ${pfx}/include/cyrus && rm -r ${pfx}/include/cyrus
  ( cd ${pfx}/lib
    rm -f libcyrus.* libcyrus_min.* libcyrus_imap.* libcyrus_sieve.* )
  test -d ${pfx}/lib/pkgconfig &&
   ( cd ${pfx}/lib/pkgconfig
     rm -f libcyrus.pc libcyrus_imap.pc libcyrus_min.pc libcyrus_sieve.pc )
libcyrus_min.pc libcyrus.pc libcyrus_sieve.pc
  test -d ${pfx}/lib64 &&
   ( cd ${pfx}/lib64
     rm -f libcyrus.* libcyrus_min.* libcyrus_imap.* libcyrus_sieve.*
  test -d ${pfx}/lib64/pkgconfig &&
   ( cd ${pfx}/lib64/pkgconfig
     rm -f libcyrus.pc libcyrus_min.pc libcyrus_sieve.pc )
  find ${pfx}/lib/perl5/site_perl -type d -name Cyrus -exec rm -r {} \;
  for mandir in ${pfx}/man ${pfx}/share/man;
  do
    ( cd ${mandir}/man1
      rm -f imtest.1 installsieve.1 lmtptest.1 mupdatetest.1 nntptest.1 \
       pop3test.1 sieveshell.1 sivtest.1 smtptest.1 )
    ( cd ${mandir}/man3 ; rm -f Cyrus::*.3 imclient.3 )
    ( cd ${mandir}/man5
      rm -f cyrus.conf.5 imapd.conf.5 krb.equiv.5 )
    ( cd ${mandir}/man8
      rm -f arbitron.8 chk_cyrus.8 ctl_cyrusdb.8 ctl_deliver.8 \
       ctl_mboxlist.8 cvt_cyrusdb.8 cyr_dbtool.8 cyr_deny.8 cyr_df.8 \
       cyr_expire.8 cyr_info.8 cyr_synclog.8 \
       deliver.8 fetchnews.8 fud.8 idled.8 imapd.8 ipurge.8 lmtpd.8 \
       make_md5.8 make_sha1.8 master.8 mbexamine.8 mbpath.8 nntpd.8 \
       notifyd.8 pop3d.8 quota.8 reconstruct.8 rmnews.8 smmapd.8 squatter.8 \
       sync_client.8 sync_reset.8 sync_server.8 syncnews.8 timsieved.8 \
       tls_prune.8 unexpunge.8 )
  done
done
test -f /etc/rc.d/rc.cyrus && rm /etc/rc.d/rc.cyrus
exit
find ~/src -maxdepth 1 -type d -name "cyrus-imapd-*" -exec rm -r {} \;
rm -f ~/installed/cyrus-imapd-*.tar.*