------------------------------------------------------------ revno: 3626 committer: Jonathan Jesse <[EMAIL PROTECTED]> branch nick: ubuntu-hardy timestamp: Sat 2007-11-10 07:04:04 -0500 message: adding adam's patch added: generic/server/c/ generic/server/c/mail.xml
=== added directory 'generic/server/c' === added file 'generic/server/c/mail.xml' --- a/generic/server/c/mail.xml 1970-01-01 00:00:00 +0000 +++ b/generic/server/c/mail.xml 2007-11-10 12:04:04 +0000 @@ -0,0 +1,1107 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [ +<!ENTITY % globalent SYSTEM "../../../libs/global.ent"> +%globalent; +<!ENTITY % genericent SYSTEM "../../libs/generic.ent"> +%genericent; +<!ENTITY % cdo-C SYSTEM "../../../libs/cdo-C.ent"> +%cdo-C; +<!ENTITY % gnome-menus-C SYSTEM "../../../ubuntu/libs/gnome-menus-C.ent"> +%gnome-menus-C; +<!ENTITY % xinclude SYSTEM "../../../libs/xinclude.mod"> +%xinclude; +<!ENTITY language "&EnglishAmerican;"> +]> + <chapter id="email-services" status="complete"> + <title>Email Services</title> + <para> + The process of getting an email from one person to another over a network or + the Internet involves many systems working together. Each of these systems + must be correctly configured for the process to work. The sender uses a <emphasis>Mail + User Agent</emphasis> (MUA), or email client, to send the message through one or more + <emphasis>Mail Transfer Agents</emphasis> (MTA), the last of which will hand it off to a <emphasis>Mail Delivery Agent</emphasis> (MDA) for delivery to the + recipient's mailbox, from which it + will be retrieved by the recipient's email client, usually via a POP3 or IMAP server. + </para> + <sect1 id="postfix" status="complete"> + <title>Postfix</title> + <para> + <application>Postfix</application> is the default Mail Transfer Agent (MTA) in Ubuntu. It + attempts to be fast and easy to administer and secure. It is + compatible with the MTA <application>sendmail</application>. This section explains how + to install and configure <application>postfix</application>. It also explains how to + set it up as an SMTP server using a secure connection (for sending emails securely). + </para> + <sect2 id="postfix-installation" status="complete"> + <title>Installation</title> + <para> + To install <application>postfix</application> run the following command: + </para> +<screen> +<command>sudo apt-get install postfix</command> +</screen> + <para> + Simply press return when the installation process asks questions, the configuration will be done in greater detail in the next stage. + </para> + </sect2> + <sect2 id="postfix-configuration" status="complete"> + <title>Basic Configuration</title> + <para> + To configure <application>postfix</application>, run the following command: + </para> +<screen> +<command>sudo dpkg-reconfigure postfix</command> +</screen> + <para> + The user interface will be displayed. On each screen, select the following + values: + <itemizedlist spacing="compact"> + <listitem><para>Ok</para></listitem> + <listitem><para>Internet Site</para></listitem> + <listitem><para>NONE</para></listitem> + <listitem><para>mail.example.com</para></listitem> + <listitem><para>mail.example.com, localhost.localdomain, localhost</para></listitem> + <listitem><para>No</para></listitem> + <listitem><para>127.0.0.0/8</para></listitem> + <listitem><para>Yes</para></listitem> + <listitem><para>0</para></listitem> + <listitem><para>+</para></listitem> + <listitem><para>all</para></listitem> + </itemizedlist> + </para> + <note> + <para> + Replace mail.example.com with your mail server hostname. + </para> + </note> + <para> + Now is a good time to decide which mailbox format you want to use. By default + Postifx will use <emphasis role="strong">mbox</emphasis> for the mailbox format. + Rather than editing the configuration file directly, + you can use the <command>postconf</command> command to configure + all <application>postfix</application> parameters. The + configuration parameters will be stored in + <filename>/etc/postfix/main.cf</filename> file. Later if you + wish to re-configure a particular parameter, you can either + run the command or change it manually in the file. + </para> + <para> + To configure the mailbox format for <emphasis role="strong">Maildir:</emphasis> + </para> +<screen> +<command>sudo postconf -e 'home_mailbox = Maildir/'</command> +</screen> + <note> + <para> + This will place new mail in /home/<emphasis role="italic">username</emphasis>/Maildir so + you will need to configure your Mail Delivery Agent (MDA) to use the same path. + </para> + </note> + </sect2> + <sect2 id="postfix-smtp-authentication" status="complete"> + <title>SMTP Authentication</title> + <para> + SMTP-AUTH allows a client to identify itself through an authentication mechanism (SASL). + Transport Layer Security (TLS) should be used to encrypt the authentication process. + Once authenticated the SMTP server will allow the client to relay mail. + </para> + <procedure> + <step> + <para> + Configure Postfix for SMTP-AUTH using SASL (Dovecot SASL): + </para> +<screen> +sudo postconf -e 'smtpd_sasl_type = dovecot' +sudo postconf -e 'smtpd_sasl_path = private/auth-client' +sudo postconf -e 'smtpd_sasl_local_domain =' +sudo postconf -e 'smtpd_sasl_security_options = noanonymous' +sudo postconf -e 'broken_sasl_auth_clients = yes' +sudo postconf -e 'smtpd_sasl_auth_enable = yes' +sudo postconf -e 'smtpd_recipient_restrictions = permit_sasl_authenticated,permit_mynetworks,reject_unauth_destination' +sudo postconf -e 'inet_interfaces = all' +</screen> + <note> + <para> + The <emphasis>smtpd_sasl_path</emphasis> configuration is a path relative to the Postfix queue directory. + </para> + </note> + </step> + <step> + <para> + Next, configure the digital certificate for TLS. When asked questions, follow + the instructions and answer appropriately: + </para> +<screen> +openssl genrsa -des3 -rand /etc/hosts -out smtpd.key 1024 +chmod 600 smtpd.key +openssl req -new -key smtpd.key -out smtpd.csr +openssl x509 -req -days 365 -in smtpd.csr -signkey smtpd.key -out smtpd.crt +openssl rsa -in smtpd.key -out smtpd.key.unencrypted +mv -f smtpd.key.unencrypted smtpd.key +openssl req -new -x509 -extensions v3_ca -keyout cakey.pem -out cacert.pem -days 3650 +sudo mv smtpd.key /etc/ssl/private/ +sudo mv smtpd.crt /etc/ssl/certs/ +sudo mv cakey.pem /etc/ssl/private/ +sudo mv cacert.pem /etc/ssl/certs/ +</screen> + <note> + <para> + You can get the digital certificate from a certificate authority. Alternatively, you + can create the certificate yourself. Refer to + <ulink url="./web-servers.xml#creating-a-self-signed-certificate">Creating + a self Signed Certification</ulink> sub-section for more + details. + </para> + </note> + </step> + <step> + <para> + Configure Postfix to provide TLS encryption for both incoming and outgoing mail: + </para> +<screen> +sudo postconf -e 'smtpd_tls_auth_only = no' +sudo postconf -e 'smtp_use_tls = yes' +sudo postconf -e 'smtpd_use_tls = yes' +sudo postconf -e 'smtp_tls_note_starttls_offer = yes' +sudo postconf -e 'smtpd_tls_key_file = /etc/ssl/private/smtpd.key' +sudo postconf -e 'smtpd_tls_cert_file = /etc/ssl/certs/smtpd.crt' +sudo postconf -e 'smtpd_tls_CAfile = /etc/ssl/certs/cacert.pem' +sudo postconf -e 'smtpd_tls_loglevel = 1' +sudo postconf -e 'smtpd_tls_received_header = yes' +sudo postconf -e 'smtpd_tls_session_cache_timeout = 3600s' +sudo postconf -e 'tls_random_source = dev:/dev/urandom' +sudo postconf -e 'myhostname = mail.example.com' +</screen> + </step> + </procedure> + <note> + <para> + After running all the commands, <application>Postfix</application> is configured for SMTP-AUTH + and a self-signed cerficiate has been created for TLS encryption. + </para> + </note> + <para> + Now, the file <filename>/etc/postfix/main.cf</filename> + should look like <ulink url="../sample/postfix_configuration">this</ulink>. + </para> + <para> + The postfix initial configuration is complete. Run + the following command to start the postfix daemon: + </para> +<screen> +<command>sudo /etc/init.d/postfix start</command> +</screen> + <para> + <application>Postfix</application> supports SMTP-AUTH as defined in + <ulink + url="ftp://ftp.isi.edu/in-notes/rfc2554.txt";>RFC2554</ulink>. + It is based on <ulink + url="ftp://ftp.isi.edu/in-notes/rfc2222.txt";>SASL</ulink>. However it is still necessary + to set up SASL authentication before you can use SMTP-AUTH. + </para> + </sect2> + <sect2 id="sasl"> + <title>Configuring SASL</title> + <para> + Postfix supports two SASL implementations Cyrus SASL and Dovecot SASL. To enable Dovecot SASL + the <application>dovecot-common</application> package will need to be installed. From a terminal prompt + enter the following: + </para> +<screen> +<command>sudo apt-get install dovecot-common</command> +</screen> + <para> + Next you will need to edit <filename>/etc/dovecot/dovecot.conf</filename>. In the <emphasis>auth default</emphasis> + section uncomment the <emphasis>socket listen</emphasis> option and change the following: + </para> +<programlisting> + socket listen { + #master { + # Master socket provides access to userdb information. It's typically + # used to give Dovecot's local delivery agent access to userdb so it + # can find mailbox locations. + #path = /var/run/dovecot/auth-master + #mode = 0600 + # Default user/group is the one who started dovecot-auth (root) + #user = + #group = + #} + client { + # The client socket is generally safe to export to everyone. Typical use + # is to export it to your SMTP server so it can do SMTP AUTH lookups + # using it. + path = /var/spool/postfix/private/auth-client + mode = 0660 + user = postfix + group = postfix + } + } +</programlisting> + <para> + Once you have <application>Dovecot</application> configured start it with: + </para> +<screen> +<command>sudo /etc/init.d/dovecot start</command> +</screen> + </sect2> + <sect2 id="postfix-testing" status="complete"> + <title>Testing</title> + <para> + SMTP-AUTH configuration is complete. Now it is time to test the setup. + </para> + <para> + To see if SMTP-AUTH and TLS work properly, run the following + command: + </para> +<screen> +<command>telnet mail.example.com 25</command> +</screen> + <para> + After you have established the connection to the postfix mail + server, type: + </para> +<screen> +ehlo mail.example.com +</screen> + <para> + If you see the following lines among others, then everything + is working perfectly. Type <command>quit</command> to exit. + </para> +<programlisting> +250-STARTTLS +250-AUTH LOGIN PLAIN +250-AUTH=LOGIN PLAIN +250 8BITMIME +</programlisting> + </sect2> + + <sect2 id="postfix-troubleshooting"> + <title>Troubleshooting</title> + <para> + This section introduces some common ways to determine the cause if problems arise. + </para> + <sect3 id="postfix-chroot"> + <title>Escaping chroot</title> + <para> + The Ubuntu <application>postfix</application> package will by default install into a <emphasis>chroot</emphasis> + environment for security reasons. This can add greater complexity when troubleshooting problems. + </para> + <para> + To turn off the chroot operation locate for the following line in the + <filename>/etc/postfix/master.cf</filename> configuration file: + </para> +<screen> +smtp inet n - - - - smtpd +</screen> + <para> + and modify it as follows: + </para> +<screen> +smtp inet n - n - - smtpd +</screen> + <para> + You will then need to restart Postfix to use the new configuration. From a terminal prompt enter: + </para> +<screen> +<command>sudo /etc/init.d/postfix restart</command> +</screen> + </sect3> + <sect3 id="postfix-logs"> + <title>Log Files</title> + <para> + <application>Postfix</application> sends all log messages to <filename>/var/log/mail.log</filename>. + However error and warning messages can sometimes get lost in the normal log output so they are also logged to + <filename>/var/log/mail.err</filename> and <filename>/var/log/mail.warn</filename> respectivley. + </para> + <para> + To see messages entered into the logs in real time you can use the <application>tail -f</application> + command: + </para> +<screen> +<command>tail -f /var/log/mail.err</command> +</screen> + <para> + The amount of detail that is recorded in the logs can be increased. Below are some configuration options for increasing the log level + for some of the areas covered above. + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + To increase <emphasis>TLS</emphasis> activity logging set the <emphasis>smtpd_tls_loglevel</emphasis> option to a value from 1 to 4. + </para> +<screen> +<command>sudo postconf -e 'smtpd_tls_loglevel = 4'</command> +</screen> + </listitem> + <listitem> + <para> + If you are having trouble sending or receiving mail from a specific domain you can add the domain to the <emphasis>debug_peer_list</emphasis> + parameter. + </para> +<screen> +<command>sudo postconf -e 'debug_peer_list = problem.domain'</command> +</screen> + </listitem> + <listitem> + <para> + You can increase the verbosity of any <application>Postfix</application> daemon process by editing the <filename>/etc/postfix/master.cf</filename> + and adding a <emphasis>-v</emphasis> after the entry. For example edit the <emphasis>smtp</emphasis> entry: + </para> +<programlisting> +smtp unix - - - - - smtp -v +</programlisting> + </listitem> + </itemizedlist> + <note> + <para> + It is important to note that after making one of the logging changes above the <application>Postfix</application> process will need to be reloaded + in order to recognize the new configuration: <command>sudo /etc/init.d/postfix reload</command> + </para> + </note> + <itemizedlist spacing="compact"> + <listitem> + <para> + To increase the amount of information logged when troubleshooting <emphasis>SASL</emphasis> issues you can set the following options in + <filename>/etc/dovecot/dovecot.conf</filename> + </para> +<programlisting> +auth_debug=yes +auth_debug_passwords=yes +</programlisting> + </listitem> + </itemizedlist> + <note> + <para> + Just like <application>Postfix</application> if you change a <application>Dovecot</application> configuration the process will need to be + reloaded: <command>sudo /etc/init.d/dovecot reload</command>. + </para> + </note> + <note> + <para> + Some of the options above can drastically increase the amount of information sent to the log files. Remember to return the log level + back to normal after you have corrected the problem. Then reload the appropriate daemon for the new configuration to take affect. + </para> + </note> + </sect3> + <sect3 id="postfix-help"> + <title>Where to get Help</title> + <para> + Administering a <application>Postfix</application> server can be a very complicated task. At some point you may + need to turn to the Ubuntu community for more experienced help. + </para> + <para> + A great place to ask for <application>Postfix</application> assistance, and get involved with the Ubuntu Server community, + is the <emphasis>#ubuntu-server</emphasis> IRC channel on <ulink url="http://freenode.net";>freenode</ulink>. You + can also post a message to one of the <ulink url="http://www.ubuntu.com/support/community/webforums";>Web Forums</ulink>. + </para> + <para> + For in depth <application>Postfix</application> information Ubuntu developers highly recommend: + <ulink url="http://www.postfix-book.com/";>The Book of Postfix</ulink>. + </para> + <para> + Finally, the <ulink url="http://www.postfix.org/documentation.html";>Postfix</ulink> website also has great documentaion on all + the different configuration options available. + </para> + </sect3> + </sect2> + </sect1> + + <sect1 id="exim4" status="complete"> + <title>Exim4</title> + <para> + <application>Exim4</application> is another Message Transfer + Agent (MTA) developed at the University of Cambridge for use + on Unix systems connected to the internet. Exim can be + installed in place of <application>sendmail</application>, + although the configuration of + <application>exim</application> is quite different to + that of <application>sendmail</application>. + </para> + <sect2 id="exim4-installation" status="complete"> + <title>Installation</title> + <para> + To install <application>exim4</application>, run the following command: +<screen> +<command>sudo apt-get install exim4</command> +</screen> + </para> + </sect2> + <sect2 id="exim4-configuration" status="complete"> + <title>Configuration</title> + <para> + To configure <application>exim4</application>, run the following command: + </para> +<screen> +<command>sudo dpkg-reconfigure exim4-config</command> +</screen> + <para> + The user interface will be displayed. The user interface + lets you configure many parameters. For example, In + <application>exim4</application> the configuration files are + split among multiple files. If you wish to have them in one + file you can configure accordingly in this user interface. + </para> + + <para> + All the parameters you configure in the user interface are + stored in + <filename>/etc/exim4/update-exim4.conf.conf</filename> file. + If you wish to re-configure, either you re-run the + configuration wizard or manually edit this file + using your favourite editor. Once you configure, you can run + the following command to generate the master configuration + file: + </para> +<screen> +<command>sudo update-exim4.conf</command> +</screen> + <para> + The master configuration file, is generated and + it is stored in + <filename>/var/lib/exim4/config.autogenerated</filename>. + </para> + <warning> + <para> + At any time, you should not edit the master configuration + file, + <filename>/var/lib/exim4/config.autogenerated</filename> + manually. It is updated automatically every time you run + <command>update-exim4.conf</command> + </para> + </warning> + <para> + You can run the following command to start + <application>exim4</application> daemon. + </para> +<screen> +<command>sudo /etc/init.d/exim4 start</command> +</screen> + </sect2> + <sect2> + <title>SMTP Authentication</title> + <para> + In this section we'll configure Exim4 to use SMTP-AUTH using TLS and SASL. + </para> + <para> + The first step is to create a certificate for use with TLS. Enter the following into a terminal prompt: + </para> +<screen> +<command>sudo /usr/share/doc/exim4-base/examples/exim-gencert</command> +</screen> + <para> + Now Exim4 needs to be configured for TLS by editing <filename>/etc/exim4/conf.d/main/03_exim4-config_tlsoptions</filename> + add the following: + </para> +<programlisting> +MAIN_TLS_ENABLE = yes +</programlisting> + <para> + Next you need to configure <application>Exim4</application> to use the <application>saslauthd</application> + for authentication. Edit <filename>/etc/exim4/conf.d/auth/30_exim4-config_examples</filename> and uncomment + the <emphasis>plain_saslauthd_server</emphasis> and <emphasis>login_saslauthd_server</emphasis> sections: + </para> +<programlisting> + plain_saslauthd_server: + driver = plaintext + public_name = PLAIN + server_condition = ${if saslauthd{{$auth2}{$auth3}}{1}{0}} + server_set_id = $auth2 + server_prompts = : + .ifndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS + server_advertise_condition = ${if eq{$tls_cipher}{}{}{*}} + .endif +# + login_saslauthd_server: + driver = plaintext + public_name = LOGIN + server_prompts = "Username:: : Password::" + # don't send system passwords over unencrypted connections + server_condition = ${if saslauthd{{$auth1}{$auth2}}{1}{0}} + server_set_id = $auth1 + .ifndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS + server_advertise_condition = ${if eq{$tls_cipher}{}{}{*}} + .endif +</programlisting> + <para> + Finally, update the Exim4 configuration and restart the service: + </para> +<screen> +<command>sudo update-exim4.conf</command> +<command>sudo /etc/init.d/exim4 restart</command> +</screen> + </sect2> + <sect2> + <title>Configuring SASL</title> + <para> + This section provides details on configuring the saslauthd to provide authentication for <application>Exim4</application>. + </para> + <para> + The first step is to install the sasl2-bin package. From a terminal prompt enter the following: + </para> +<screen> +<command>sudo apt-get install sasl2-bin</command> +</screen> + <para> + To configure saslauthd edit the /etc/default/saslauthd configuration file and set START=no to: + </para> +<programlisting> +START=yes +</programlisting> + <para> + Next the <emphasis>Debian-exim</emphasis> user needs to be part of the <emphasis>sasl</emphasis> group in + order for Exim4 to use the saslauthd service: + </para> +<screen> +<command>sudo adduser Debian-exim sasl</command> +</screen> + <para> + Now start the <application>saslauthd</application> service: + </para> +<screen> +<command>sudo /etc/init.d/saslauthd start</command> +</screen> + <para> + <application>Exim4</application> is now configured with SMTP-AUTH using TLS and SASL authentication. + </para> + </sect2> + </sect1> + <sect1 id="dovecot-server" status="complete"> + <title>Dovecot Server</title> + <para> + <application>Dovecot</application> is a Mail Delivery Agent, written with security + primarily in mind. It supports the major mailbox formats: mbox + or Maildir. This section explain how to set it up as an imap or + pop3 server. + </para> + <sect2 id="dovecot-installation" status="complete"> + <title>Installation</title> + <para> + To install <application>dovecot</application>, run the following command in the + command prompt: + </para> +<screen> +<command>sudo apt-get install dovecot-common dovecot-imapd dovecot-pop3d</command> +</screen> + </sect2> + <sect2 id="dovecot-configuration" status="complete"> + <title>Configuration</title> + <para> + To configure <application>dovecot</application>, you can edit the file + <filename>/etc/dovecot/dovecot.conf</filename>. You can + choose the protocol you use. It could be pop3, pop3s (pop3 + secure), imap and imaps (imap secure). A description of these protocols is beyond the scope of this guide. For further information, refer to the wikipedia articles on <ulink + url="http://en.wikipedia.org/wiki/POP3";>POP3</ulink> and + <ulink + url="http://en.wikipedia.org/wiki/Internet_Message_Access_Protocol";>IMAP</ulink>. + </para> + + <para> + IMAPS and POP3S are more secure that the simple IMAP and + POP3 because they use SSL encryption to connect. Once you + have chosen the protocol, amend the following line in the file + <filename>/etc/dovecot/dovecot.conf</filename>: + </para> +<programlisting> +protocols = pop3 pop3s imap imaps +</programlisting> + <para> + It enables the protocols when <application>dovecot</application> is started. Next, add the following line in the pop3 section of the file <filename>/etc/dovecot/dovecot.conf</filename>: + </para> +<programlisting> +pop3_uidl_format = %08Xu%08Xv +</programlisting> + <para> + Next, choose the mailbox you use. <application>Dovecot</application> supports + <emphasis role="strong">maildir</emphasis> and <emphasis + role="strong">mbox</emphasis> formats. These are the most + commonly used mailbox formats. They both have their own + benefits and they are discussed on <ulink + url="http://wiki.dovecot.org/MailboxFormat";>the dovecot website</ulink>. + </para> + <para> + Once you have chosen your mailbox type, edit the file + <filename>/etc/dovecot/dovecot.conf</filename> and change + the following line: + </para> +<programlisting> +mail_location = maildir:~/Maildir # (for maildir) +or +mail_location = mbox:~/mail:INBOX=/var/spool/mail/%u # (for mbox) +</programlisting> + <note> + <para> + You should configure your Mail Transport Agent (MTA) to transfer the + incoming mail to this type of mailbox if it is different from the one + you have configured. + </para> + </note> + <para> + Once you have configured dovecot, start the <application>dovecot</application> daemon + in order to test your setup: + </para> + <screen><command>sudo /etc/init.d/dovecot start</command></screen> + <para> + If you have enabled imap, or pop3, you can also try to log in + with the commands <command>telnet localhost pop3</command> or + <command>telnet localhost imap2</command>. If you see + something like the following, the installation has been + successful: + </para> +<programlisting> [EMAIL PROTECTED]:~$ telnet localhost pop3 +Trying 127.0.0.1... +Connected to localhost.localdomain. +Escape character is '^]'. ++OK Dovecot ready. +</programlisting> + </sect2> + <sect2 id="dovecot-ssl" status="complete"> + <title>Dovecot SSL Configuration</title> + <para> + To configure <application>dovecot</application> to use SSL, you can edit the file + <filename>/etc/dovecot/dovecot.conf</filename> and amend + following lines: + </para> +<programlisting> +ssl_cert_file = /etc/ssl/certs/ssl-cert-snakeoil.pem +ssl_key_file = /etc/ssl/private/ssl-cert-snakeoil.key +ssl_disable = no +disable_plaintext_auth = no +</programlisting> + <para> + You can get the SSL certificate from a Certificate Issuing + Authority or you can create self signed SSL certificate. Please + refer to <xref linkend="creating-a-self-signed-certificate"/> + for details about how to create self signed SSL certificate. Once + you create the certificate, you will have a key file and a + certificate file. Please copy them to the location pointed + in the <filename>/etc/dovecot/dovecot.conf</filename> + configuration file. + </para> + </sect2> + <sect2> + <title>Firewall Configuration for an Email Server</title> + <para> + To access your mail server from another computer, you must + configure your firewall to allow connections to the server on + the necessary ports. + <itemizedlist> + <listitem><para>IMAP - 143</para></listitem> + <listitem><para>IMAPS - 993</para></listitem> + <listitem><para>POP3 - 110</para></listitem> + <listitem><para>POP3S - 995</para></listitem> + </itemizedlist> + </para> + </sect2> + </sect1> + <sect1 id="mailman" status="complete"> + <title>Mailman</title> + <para> + Mailman is an open source program for managing electronic mail + discussions and e-newsletter lists. Many open source mailing + lists (including all the <ulink + url="http://lists.ubuntu.com";>Ubuntu mailing lists</ulink>) use + Mailman as their mailing list software. It is powerful and easy + to install and maintain. + </para> + <sect2 id="mailman-installation" status="complete"> + <title>Installation</title> + <para> + Mailman provides a web interface for the administrators + and users. So, it requires Apache with mod_perl support. + Mailman uses an external mail server to send and receive + emails. It works perfectly with the following mail servers: + </para> + <para> + <itemizedlist spacing="compact"> + <listitem> + <para><application>Postfix</application></para> + </listitem> + <listitem> + <para><application>Exim</application></para> + </listitem> + <listitem> + <para><application>Sendmail</application></para> + </listitem> + <listitem> + <para><application>Qmail</application></para> + </listitem> + </itemizedlist> + </para> + + <para> + We will see how to install and configure Mailman with, the Apache web server, + and either the Postfix or Exim mail server. If you wish to install Mailman + with a different mail server, please refer to the references + section. + </para> + <note> + <para> + You only need to install one mail server and <application>Postfix</application> is the default Ubuntu Mail Transfer Agent. + </para> + </note> + <sect3 id="mailman-apache2"> + <title>Apache2</title> + <para> + To install apache2 you refer to <ulink + url="./web-servers.xml#http-installation">HTTPD + Installation</ulink> section for details. + </para> + </sect3> + <sect3 id="mailman-postfix"> + <title>Postfix</title> + <para> + For instructions on installing and configuring Postfix refer to <xref linkend="postfix"/> + </para> + </sect3> + <sect3 id="mailman-exim4"> + <title>Exim4</title> + <para> + To install Exim4 refer to <xref linkend="exim4"/>. + </para> + <para> + Once exim4 is installed, the configuration files are stored in + the <filename>/etc/exim4</filename> directory. In Ubuntu, by default, the exim4 configuration files are + split across different files. You can change this behavior by changing + the following variable in the <filename>/etc/exim4/update-exim4.conf</filename> file: + + <itemizedlist spacing="compact"> + <listitem> + <para><application>dc_use_split_config='true'</application></para> + </listitem> + </itemizedlist> + </para> + </sect3> + <sect3 id="mailman-mailman"> + <title>Mailman</title> + <para> + To install <application>Mailman</application>, run following command at a terminal prompt: + </para> +<screen> +<command>sudo apt-get install mailman</command> +</screen> + <para> + It copies the installation files in + <application>/var/lib/mailman</application> directory. It installs the + CGI scripts in <application>/usr/lib/cgi-bin/mailman</application> + directory. It creates <emphasis>list</emphasis> linux + user. It creates the <emphasis>list</emphasis> linux + group. The mailman process will be owned by this user. + </para> + </sect3> + </sect2> + <sect2 id="mailman-configuration" status="complete"> + <title>Configuration</title> + <para> + This section assumes you have successfully installed + <application>mailman</application>, + <application>apache2</application>, and + <application>postfix</application> or <application>exim4</application>. Now you just need + to configure them. + </para> + <sect3 id="mailman-conf-apache2"> + <title>Apache2</title> + <para> + An example Apache configuration file comes with <application>Mailman</application> and is placed + in <filename>/etc/mailman/apache.conf</filename>. In order for Apache to use the config file it needs + to be copied to <filename>/etc/apache2/sites-available</filename>: + </para> +<screen> +<command>sudo cp /etc/mailman/apache.conf /etc/apache2/sites-available/mailman.conf</command> +</screen> + <para> + This will setup a new Apache <emphasis>VirtualHost</emphasis> for the Mailman administration site. + Once you have copied the new configuration file you will need to enable it and restart Apache: + </para> +<screen> +<command>sudo a2ensite mailman.conf</command> +<command>sudo /etc/init.d/apache2 restart</command> +</screen> + <para> + Mailman uses apache2 to render its CGI scripts. The mailman CGI scripts + are installed in the <application>/usr/lib/cgi-bin/mailman</application> + directory. So, the mailman url will be + http://hostname/cgi-bin/mailman/. You can make changes to the + <filename>/etc/apache2/sites-available/mailman.conf</filename> file if you wish to + change this behavior. + </para> + </sect3> + <sect3 id="mailman-conf-postfix"> + <title>Postfix</title> + <para> + For <application>Postfix</application> integration, we will associate the domain lists.example.com with the mailing lists. + Please replace <emphasis>lists.example.com</emphasis> with the domain of your choosing. + </para> + <para> + You can use the postconf command to add the necessary configuration to <filename>/etc/postfix/main.cf</filename>: + </para> +<screen> +<command>sudo postconf -e 'relay_domains = lists.example.com'</command> +<command>sudo postconf -e 'transport_maps = hash:/etc/postfix/transport'</command> +<command>sudo postconf -e 'mailman_destination_recipient_limit = 1'</command> +</screen> + <para> + In <filename>/etc/postfix/master.cf</filename> double check that you have the following transport: + </para> +<programlisting> +mailman unix - n n - - pipe + flags=FR user=list argv=/usr/lib/mailman/bin/postfix-to-mailman.py + ${nexthop} ${user} +</programlisting> + <para> + It calls the <emphasis>postfix-to-mailman.py</emphasis> script when a mail is delivered to a list. + </para> + <para> + Associate the domain lists.example.com to the Mailman transport with the transport map. Edit the file <filename>/etc/postfix/transport</filename>: + </para> +<programlisting> +lists.example.com mailman: +</programlisting> + <para> + Now have <application>Postfix</application> build the transport map by entering the following from a terminal prompt: + </para> +<screen> +<command>sudo postmap -v /etc/postfix/transport</command> +</screen> + <para> + Then restart Postfix to enable the new configurations: + </para> +<screen> +<command>sudo /etc/init.d/postfix restart</command> +</screen> + </sect3> + <sect3 id="mailman-conf-exim4"> + <title>Exim4</title> + <para> + Once Exim4 is installed, you can start the Exim server using the following + command from a terminal prompt: + </para> +<screen> +<command>sudo apt-get /etc/init.d/exim4 start</command> +</screen> + <para> +In order to make mailman work with exim4, you need to configure exim4. +As mentioned earlier, by default, exim4 uses multiple configuration +files of different types. For details, please refer to the <ulink +url="http://www.exim.org";>Exim</ulink> website. To run mailman, we +should add new a configuration file to the following configuration +types: + <itemizedlist spacing="compact"> + <listitem> + <para>Main</para> + </listitem> + <listitem> + <para>Transport</para> + </listitem> + <listitem> + <para>Router</para> + </listitem> + </itemizedlist> + Exim creates a master configuration file by sorting all + these mini configuration files. So, the order of these + configuration files is very important. + </para> + </sect3> + <sect3 id="mailman-conf-main"> + <title>Main</title> + <para> + All the configuration files belonging to the main type are + stored in the + <filename>/etc/exim4/conf.d/main/</filename> directory. You can add + the following content to a new file, named <filename>04_exim4-config_mailman</filename>: + +<programlisting> +# start +# Home dir for your Mailman installation -- aka Mailman's prefix +# directory. +# On Ubuntu this should be "/var/lib/mailman" +# This is normally the same as ~mailman +MM_HOME=/var/lib/mailman +# +# User and group for Mailman, should match your --with-mail-gid +# switch to Mailman's configure script. Value is normally "mailman" +MM_UID=list +MM_GID=list +# +# Domains that your lists are in - colon separated list +# you may wish to add these into local_domains as well +domainlist mm_domains=hostname.com +# +# -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +# +# These values are derived from the ones above and should not need +# editing unless you have munged your mailman installation +# +# The path of the Mailman mail wrapper script +MM_WRAP=MM_HOME/mail/mailman +# +# The path of the list config file (used as a required file when +# verifying list addresses) +MM_LISTCHK=MM_HOME/lists/${lc::$local_part}/config.pck +# end +</programlisting> + </para> + </sect3> + <sect3 id="mailman-conf-transport"> + <title>Transport</title> + <para> +All the configuration files belonging to transport type are stored in +the <filename>/etc/exim4/conf.d/transport/</filename> directory. You +can add the following content to a new file named <filename> +40_exim4-config_mailman</filename>: + +<programlisting> + mailman_transport: + driver = pipe + command = MM_WRAP \ + '${if def:local_part_suffix \ + {${sg{$local_part_suffix}{-(\\w+)(\\+.*)?}{\$1}}} \ + {post}}' \ + $local_part + current_directory = MM_HOME + home_directory = MM_HOME + user = MM_UID + group = MM_GID +</programlisting> + </para> + </sect3> + <sect3 id="mailman-conf-router"> + <title>Router</title> + <para> +All the configuration files belonging to router type are stored in the +<filename>/etc/exim4/conf.d/router/</filename> directory. You can add the following content +in to a new file named <filename>101_exim4-config_mailman</filename>: +<programlisting> + mailman_router: + driver = accept + require_files = MM_HOME/lists/$local_part/config.pck + local_part_suffix_optional + local_part_suffix = -bounces : -bounces+* : \ + -confirm+* : -join : -leave : \ + -owner : -request : -admin + transport = mailman_transport +</programlisting> + + </para> +<warning> +<para> +The order of main and transport configuration files can be in any order. +But, the order of router configuration files must be the same. +This particular file must appear before the +<application>200_exim4-config_primary</application> file. +These two configuration files contain same type of information. The +first file takes the precedence. For more details, please refer to the +references section. +</para> +</warning> + </sect3> + <sect3 id="mailman-conf-mailman"> + <title>Mailman</title> + <para> + Once mailman is installed, you can run it using the following command: + </para> +<screen> +<command>sudo /etc/init.d/mailman start</command> +</screen> + <para> + Once mailman is installed, you should create the default mailing list. + Run the following command to create the mailing list: + </para> + +<screen> +<command>sudo /usr/sbin/newlist mailman</command> +</screen> + +<programlisting> + Enter the email address of the person running the list: bhuvan at ubuntu.com + Initial mailman password: + To finish creating your mailing list, you must edit your <filename>/etc/aliases</filename> (or + equivalent) file by adding the following lines, and possibly running the + `newaliases' program: + + ## mailman mailing list + mailman: "|/var/lib/mailman/mail/mailman post mailman" + mailman-admin: "|/var/lib/mailman/mail/mailman admin mailman" + mailman-bounces: "|/var/lib/mailman/mail/mailman bounces mailman" + mailman-confirm: "|/var/lib/mailman/mail/mailman confirm mailman" + mailman-join: "|/var/lib/mailman/mail/mailman join mailman" + mailman-leave: "|/var/lib/mailman/mail/mailman leave mailman" + mailman-owner: "|/var/lib/mailman/mail/mailman owner mailman" + mailman-request: "|/var/lib/mailman/mail/mailman request mailman" + mailman-subscribe: "|/var/lib/mailman/mail/mailman subscribe mailman" + mailman-unsubscribe: "|/var/lib/mailman/mail/mailman unsubscribe mailman" + + Hit enter to notify mailman owner... + + # +</programlisting> + <para> + We have configured either Postfix or Exim4 to recognize all emails from mailman. So, it is + not mandatory to make any new entries in + <filename>/etc/aliases</filename>. If you have made any changes + to the configuration files, please ensure that you restart those + services before continuing to next section. + </para> + </sect3> + </sect2> + <sect2 id="mailman-admin" status="complete"> + <title>Administration</title> +<para> +We assume you have a default installation. The +mailman cgi scripts are still in the +<application>/usr/lib/cgi-bin/mailman/</application> directory. Mailman +provides a web based administration facility. To access this page, point +your browser to the following url: + +</para> +<para> +http://hostname/cgi-bin/mailman/admin +</para> + +<para> +The default mailing list, <emphasis>mailman</emphasis>, +will appear in this screen. If you click the mailing list name, it +will ask for your authentication password. If you enter the correct +password, you will be able to change administrative settings of this +mailing list. + +You can create a new mailing list using the command line utility +(<command>/usr/sbin/newlist</command>). +Alternatively, you can create a new mailing list using the web interface. +</para> + </sect2> + <sect2 id="mailman-users" status="complete"> + <title>Users</title> +<para> +Mailman provides a web based interface for users. To access this page, +point your browser to the following url: +</para> + +<para> +http://hostname/cgi-bin/mailman/listinfo +</para> + +<para> +The default mailing list, <emphasis>mailman</emphasis>, +will appear in this screen. If you +click the mailing list name, it will display the subscription form. You +can enter your email address, name (optional), and password to subscribe. +An email invitation will be sent to you. You can follow the +instructions in the email to subscribe. +</para> + </sect2> + <sect2 id="mailman-references" status="complete"> + <title>References</title> +<para> +<ulink url="http://www.list.org/mailman-install/index.html";> GNU Mailman +- Installation Manual</ulink> +</para> +<para> +<ulink url="http://www.exim.org/howto/mailman21.html";>HOWTO - Using Exim +4 and Mailman 2.1 together</ulink> +</para> + </sect2> + </sect1> + </chapter> + -- https://code.launchpad.net/~ubuntu-core-doc/ubuntu-doc/ubuntu-hardy You are receiving this branch notification because you are subscribed to it. To unsubscribe from this branch go to https://code.launchpad.net/~ubuntu-core-doc/ubuntu-doc/ubuntu-hardy/+subscription/ubuntu-core-doc. -- ubuntu-doc-commits mailing list ubuntu-doc-commits@lists.ubuntu.com https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc-commits
