<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link = "/proj/en/infrastructure/dev-email.xml">
<title>Gentoo E-mail System for developers</title>
<author title="Author">
    <mail link="swift">Sven Vermeulen</mail>
</author>
<author title="Editor">
    <mail link="klieber">Kurt Lieber</mail>
</author>
<author title="Editor">
    <mail link="ramereth">Lance Albertson</mail>
</author>
<author title="Editor">
    <mail link="dostrow">Daniel Ostrow</mail>
</author>
<author title="Editor">
    <mail link="kingtaco">Mike Doty</mail>
</author>
<author title="Editor">
    <mail link="solar">Ned Ludd</mail>
</author>
<author title="Editor">
    <mail link="robbat2">Robin H. Johnson</mail>
</author>
<abstract>
This document describes what you, as a Gentoo Developer, can expect from our
e-mail system, and provides configuration details you require.
</abstract>
<version>1.12</version>
<date>2011-12-03</date>

<!-- This doesn't look good, can be handy though. Commenting out
     untill someone wants it. How's that for anticipation :)

<chapter>
<title>Content</title>
<section>
<title>Gentoo Developer E-mail Possibilities</title>
<body>
<ul>
<li><uri link="#doc_chap2_sect1">Introduction</uri></li>
<li><uri link="#doc_chap2_sect2">Forwarding E-mails</uri></li>
<li><uri link="#doc_chap2_sect3">Using the mailbox on dev.gentoo.org</uri></li>
</ul>
</body>
</section>
<section>
<title>Using dev.gentoo.org for your e-mails</title>
<body>
<ul>
<li><uri link="#doc_chap3_sect1">Accessing dev.gentoo.org using POP3S</uri></li>
<li><uri link="#doc_chap3_sect2">Accessing dev.gentoo.org using IMAPS</uri></li>
<li><uri link="#doc_chap3_sect3">Using dev.gentoo.org as a mail relay server</uri></li>
</ul>
</body>
</section>
<section>
<title>Frequently Asked and/or Anticipated Questions</title>
<body>
<ul>
<li><uri link="#doc_chap4_sect1">What happens when dev.gentoo.org goes down?</uri></li>
<li><uri link="#doc_chap4_sect2">Can I use procmail on dev.gentoo.org?</uri></li>
<li><uri link="#doc_chap4_sect3">Are my e-mails or the contents of my home directory backed up regularly?</uri></li>
</ul>
</body>
</section>
</chapter>

-->

<chapter>
<title>Gentoo Developer E-mail Possibilities</title>
<section>
<title>Introduction</title>
<body>
<p>
This document describes the various options for checking your gentoo.org email address.
You can opt for having the e-mails forwarded to a specific e-mail
address, or let them stay on the dev.gentoo.org server to which you can
connect using your favorite e-mail client with POP3S or IMAPS (the
secure implementations of POP3 and IMAP respectively).
</p>
</body>
</section>
<section>
<title>Forwarding E-mails</title>
<body>
<p>
If you want to have your e-mails forwarded to another e-mail address, you
should log on to dev.gentoo.org and put the e-mail address in 
<path>~/.forward</path>. Logging on to dev.gentoo.org is similar to
cvs.gentoo.org: you'll be using the same keys.
</p>
<pre caption = "Forwarding e-mails to another e-mail address">
$ <i>ssh  username@dev.gentoo.org</i>
username@woodpecker username $ <i>echo new.e-mail@address.com &gt; ~/.forward</i>
username@woodpecker username $ <i>exit</i>
</pre>
<p>
If you at some point want to change the e-mail address to which the
e-mails should be forwarded, change the content of the
<path>~/.forward</path> file to the new e-mail address.
</p>
<note>
If you use a forward please make sure that it is reliable. If the queue on
dev.gentoo.org starts to grow due to bouncing e-mail Infra will be forced to
remove you forward. All e-mail will then be delivered locally until you fix it.
</note>
</body>
</section>
<section>
<title>Using the mailbox on dev.gentoo.org</title>
<body>
<p>
If you want to use the mailbox on dev.gentoo.org, you must make sure
that there is no <path>.forward</path> in your home directory. Doing this
requires access to dev.gentoo.org (duh). Accessing dev.gentoo.org is no
different than accessing cvs.gentoo.org: you'll be using the same keys.
</p>
<!-- The single quotes are needed else their username is expended on the client side -->
<pre caption = "Removing ~/.forward">
$ <i>ssh -l username dev.gentoo.org 'rm ~/.forward'</i>
</pre>
<p>
There are some things you must know about your mailbox on
dev.gentoo.org:
</p>
<ul>
<li>You can only access it using POP3S or IMAPS (see the following
chapter).</li>
<li>There are some local e-mail clients installed on
dev.gentoo.org (<c>mutt</c> and <c>pine</c> to be exact). Only use those
if you know how to use them :)</li>
<li>The password to access the mailbox is the same password you can set
on dev.gentoo.org using <c>passwd</c>.</li>
</ul>
</body>
</section>
</chapter>
<chapter>
<title>Using dev.gentoo.org for your e-mails</title>
<section>
<body>
<note>
As of 2009/06/29, we use CACert as the Certificate Authority for all of the
following SSL certificates.
</note>
<note>
Prior to 2011/12/, Gentoo Infrastructure only supported the pure SSL variants
of the protocols, which provided a complete SSL wrapper around the POP3 or IMAP
protocols. While POP3S and IMAPS is still supported, we encourage users to
migrate to using STARTTLS instead, as it is easier to debug by being able to
see the initial plaintext on tcpdump. Users behind aggressive firewalls that
conduct deep-packet inspection to block based on plaintext headers should still
use the pure SSL variants.
</note>
</body>
</section>
<section>
<title>Accessing dev.gentoo.org using POP3 &amp; STARTTLS or POP3S</title>
<body>
<p>
POP3 is a pull-protocol, meaning that e-mails are pulled from the server
to your local disk. 
</p>
<p>
To set up your favorite e-mail client for POP3 &amp; STARTTLS or POP3S, use the
following settings:
</p>
<ul>
<li><e>POP3 server</e>: dev.gentoo.org</li>
<li><e>Use SSL</e>: yes</li>
<li><e>Account</e>: your username</li>
<li><e>Password</e>: your dev.gentoo.org password</li>
</ul>
<warn>
POP3 without SSL/TLS is <e>not</e> supported! It is insecure because it
transmits the password in plain text, which is a Bad Thing (TM).
</warn>
<p>
For instance, if you are using <c>fetchmail</c> to fetch your e-mails,
your <path>.fetchmailrc</path> should read something like this:
</p>
<pre caption="fetchmailrc">
poll dev.gentoo.org proto pop3 
    user <i>username</i> 
	pass <i>password</i> 
	nokeep sslcertck
	sslfingerprint "34:D0:1D:0D:08:0A:39:D1:A7:46:E4:E9:4F:33:FF:58"
	sslcertfile /usr/share/ca-certificates/cacert.org/cacert.org.crt
	sslproto TLS1
</pre>
<note>
The above will have fetchmail using POP3 with STARTTLS. If you need POP3S
instead, add the keyword <c>ssl</c> before the <c>sslcertck</c> keyword.
</note>
<p>
If you are using <c>sylpheed</c> for your e-mails, create a new account
and make sure that the <e>Receive</e> tab uses POP3 and the <e>SSL</e>
tab has the <e>Use SSL for POP3 connection</e> selected.
</p>
<p>
If you are using <c>mutt</c>, you're smart enough to figure this one out
yourself.
</p>
<pre caption="dev.gentoo.org POP3 SSL fingerprints">
MD5    = 34:D0:1D:0D:08:0A:39:D1:A7:46:E4:E9:4F:33:FF:58
SHA1   = C7:79:6B:C9:D5:C8:02:D6:D4:72:EA:7C:DB:F3:BD:29:A3:F5:FF:72
SHA256 = F2:7E:E0:B7:D4:CE:43:6A:BF:42:12:51:5B:95:84:7E:0E:10:70:AD:F6:11:90:B6:72:9C:3E:59:BB:1B:FA:A4
</pre>
</body>
</section>
<section>
<title>Accessing dev.gentoo.org using IMAP &amp; STARTTLS or IMAPS</title>
<body>
<p>
IMAP is a push-protocol, meaning that e-mails stay on the remote server and you
can manage seperate mailboxes on that server.
</p>
<p>
To set up your favorite e-mail client for IMAP &amp; STARTTLS or IMAPS, use the
following settings:
</p>
<ul>
<li><e>IMAP server</e>: dev.gentoo.org</li>
<li><e>Use SSL</e>: yes</li>
<li><e>Account</e>: your username</li>
<li><e>Password</e>: your dev.gentoo.org password</li>
</ul>
<warn>
IMAP without SSL/TLS is <e>not</e> supported! It is insecure because it
uses static authentication, which is a Bad Thing (TM).
</warn>
<note>
Your *.gentoo.org LDAP password is the same as the one used on
all Gentoo infrastructure you have access to. If you don't know your
password anymore, ask infra to reset your password.
</note>
<p>
For instance, if you are using <c>fetchmail</c> to fetch your e-mails,
your <path>.fetchmailrc</path> should read something like this:
</p>
<pre caption = "fetchmailrc">
poll dev.gentoo.org proto imap
    user <i>username</i>
	pass <i>password</i>
	nokeep sslcertck
	sslfingerprint "34:D0:1D:0D:08:0A:39:D1:A7:46:E4:E9:4F:33:FF:58"
	sslcertfile /usr/share/ca-certificates/cacert.org/cacert.org.crt
	sslproto TLS1
</pre>
<note>
The above will have fetchmail using IMAP with STARTTLS. If you need IMAPS
instead, add the keyword <c>ssl</c> before the <c>sslcertck</c> keyword.
</note>
<p>
If you are using <c>mutt</c>, you're smart enough to figure this one out
yourself.
</p>
<pre caption="dev.gentoo.org IMAP SSL fingerprints">
MD5    = 34:D0:1D:0D:08:0A:39:D1:A7:46:E4:E9:4F:33:FF:58
SHA1   = C7:79:6B:C9:D5:C8:02:D6:D4:72:EA:7C:DB:F3:BD:29:A3:F5:FF:72
SHA256 = F2:7E:E0:B7:D4:CE:43:6A:BF:42:12:51:5B:95:84:7E:0E:10:70:AD:F6:11:90:B6:72:9C:3E:59:BB:1B:FA:A4
</pre>
</body>
</section>
<section>
<title>Using dev.gentoo.org as a mail relay server</title>
<body>
<p>
If you would like to reduce the SRF spam scoring against your email, or do not
wish to use your ISP's relay, you may relay your email through dev.gentoo.org.
</p>
<note>
For devs unable to use port 25 to send mail, dev.gentoo.org also accepts
inbound SMTP connections on TCP port 587.
</note>
<p>
Now setup your e-mail client to use dev.gentoo.org as the SMTP server.
Select <e>yes</e> when asked if the server uses authentication. Also enable
<e>STARTTLS</e>. If you get the choice, select <e>plain</e> as the hash-method.
Use your username and your LDAP password for authentication. The certificate
is also signed by CACert as of 2010/05/25.</p>
<pre caption="dev.gentoo.org SMTP SSL fingerprints">
MD5    = B5:E9:21:AF:8C:97:03:A3:2D:B4:73:80:19:8C:9B:82
SHA1   = E1:B3:FC:AD:DF:D3:A4:72:8B:2D:BB:3E:2F:90:91:15:49:39:61:F9
SHA256 = 2B:98:39:5D:21:D5:79:F1:87:ED:F8:9D:72:48:FB:F3:8C:BC:32:BC:B3:3A:DE:94:35:5E:74:13:13:AB:6C:98
</pre>
</body>
</section>
<section>
<title>Setting up procmail rules for Spam Checking</title>
<body>
<p>
All email coming into dev.gentoo.org is scanned for spam and viruses. Viruses
are automatically deleted so there is no need to check for them yourself. To 
check for spam use something like the following procmail recipie.
</p>
<pre caption = "~/.procmailrc">
 :0:
 * ^X-Spam-Status: Yes
 .maildir/.spam/
</pre>
<p>
If you wish to check your spam based on spam level a recipie like the following
can be used (adjust the number of '\*' to the level that fits you best, the more
stars the greater the possibilty that what you are filtering is spam).
</p>
<pre caption = "~/.procmailrc">
 :0:
 * ^X-Spam-Level: \*\*\*
 .maildir/.spam/
</pre>
<note>
Mail placed into ~/.maildir/.spam is auto cleaned every 14 days. If you wish to
save your potential spam for an extended period of time please place it in another
directory. The usage of ~/.maildir/.spam is strongly encouraged.
</note>
</body>
</section>
</chapter>
<chapter>
<title>Frequently Asked and/or Anticipated Questions</title>
<section>
<title>What happens when dev.gentoo.org goes down?</title>
<body>
<p>
When dev.gentoo.org goes down, e-mails
will stay in the mailqueue on mail.gentoo.org and will be delivered
whenever dev.gentoo.org is up again.
</p>
</body>
</section>
<section>
<title>Can I use procmail on dev.gentoo.org?</title>
<body>
<p>
Yes you can. You need to create a <path>~/.forward</path> file thought with the
following content:
</p>
<pre caption="~/.forward for procmail usage">
| /usr/bin/procmail
</pre>
</body>
</section>
<section>
	<title>Can I use sieve/managesieve on dev.gentoo.org?</title>
	<body>
		<p>
			You need to create a <path>~/.forward</path> file thought with the
			following content:
		</p>
		<pre caption="~/.forward for sieve/managesieve usage">
| "/usr/libexec/dovecot/deliver"
		</pre>
		<note>
			Using the dovecot LDA also improves the performance/speed for IMAP
			and POP3.
		</note>
	</body>
</section>
<section>
<title>Can I use SpamAssassin on dev.gentoo.org?</title>
<body>
<p>
Spam is automatically marked for you. There is no need to run your mail through
any additional filters just check for the appropriate headers.
</p>
</body>
</section>
<section>
<title>Why don't you set up a system-wide (spam|virus) filter?</title>
<body>
<p>
Due to the rapid spread of e-mail bourne viruses we have had to filter all of
these despite the risk of loosing legitimate e-mail. Spam filtering is not 100%
accurate so although we tag all e-mail with Spam level headers we do not filter
it. We leave that option to the developers to do so if they choose.
</p>
</body>
</section>
<section>
<title>How can I exempt myself from Sender Address Verification?</title>
<body>
<p>
By default all @gentoo.org users get Sender Address Verification 
enabled for them for free. We recognize that there are times when this 
is less than ideal and put a system in place for you to exempt yourself 
from it. You can simply <c>touch ~/.permissive</c> and wait about an 
hour for the recipient_filtering to be rechecked. Note however that 
when you opt for permissive mode that no spam or virus filtering is 
done for your account.
</p>
</body>
</section>
<section>
<title>Are my e-mails or the contents of my home directory backed up 
regularly?</title>
<body>
<p>
No, it's the responsibility of the individual to back up their own important 
files and mail.
</p>
</body>
</section>
<section>
<title>How can I copy over files from/to dev.gentoo.org?</title>
<body>
<p>
Use <c>scp</c>.
</p>
</body>
</section>
</chapter>
</guide>
