[wiki:howto <- Back to the HOWTO section]

= How to set-up fetchmail =

 * Audience: Advanced E-Mail setup
 * Requires: MacPorts >= 1.6, mail/fetchmail
 * Last tested with Mac OS X 10.9.3
 * Note that below instructions have been changed to work on Mavericks

== Introduction ==

This How-to is part of the [wiki:howto/SetupFetchmail Fetchmail] ->  [wiki:howto/SetupPostfix Postfix] -> [wiki:howto/SetupDovecot Dovecot] advanced e-Mail set-up.

[wikipedia:Fetchmail fetchmail] fetchmail is program used to collect e-mail from [wikipedia:Internet_service_provider internet service provider] and transfers them to the local [wikipedia:Mail_transfer_agent mail transfer agent] for further distribution.

[wikipedia:Fetchmail fetchmail] can collect mail from various sources and for multiple users. With the setup described here the user does not need to start an [wikipedia:Email_Client] for collection to happen. In fact the user does not even need to be logged in. 

== Installation ==

First set-up a mail storage and a [wikipedia:Mail_transfer_agent mail transfer agent]  . See [wiki:howto/SetupDovecot Dovecot] and [wiki:howto/SetupPostfix Postfix] a possible set-up. Fetchmail will not work without and you can lose your mail if those components are not set-up properly.

=== Fetchmail ===

If you want to configure fetchmail with a GUI, use the below command.  Note that it requires that you have X11 installed and running.

{{{
sudo port install fetchmail +fetchmailconf +ssl 
}}}

Otherwise, use the below.  You'll have to hand edit the fetchmailrc file.
{{{
sudo port install fetchmail +ssl 
}}}


Some older OSX version may come preinstalled with fetchmail (OSX 10.5).  For this howto we will be using macports's version.

== Configuration ==

Note: Do not use any of the attached files without checking / changing them with your favorite text editor.  You will need to {{{chmod +x}}} the attached files in order to execute them.

=== Step 1: ''create user'' ===

Fetchmail does not need root or normal user privileges to run so it is suggested to create an unprivileged user and group for daemon based fetchmail configurations. You can use the [attachment:Make_Fetchmail_User.command] to do so.  This attached shell script also has instructions to view and undo all the commands.

=== Step 2: ''create directories'' ===

Dovecot need two directories to work with - one to store the run status, one for the log files. You can use the [attachment:Make_Fetchmail_Directories.command] to create the directories.

/opt/local/var/log/fetchmail
/opt/local/var/run/fetchmail

These also need to be owned by _fetchmail
{{{
sudo chown _fetchmail:_fetchmail /opt/local/var/log/fetchmail
sudo chown _fetchmail:_fetchmail /opt/local/var/run/fetchmail
}}}

=== Step 3: ''set-up configuration'' ===

Next you need to set up [attachment:fetchmailrc] and save it to {{{/opt/local/etc}}}. The file should be owned by _fetchmail:_fetchmail and only be readable to _fetchmail an no one else.
{{{
sudo chown _fetchmail:_fetchmail /opt/local/etc/fetchmailrc
sudo chmod 710 /opt/local/etc/fetchmailrc
}}}

''Note:''

 * The "ID-file" is used to store the message IDs of messages already downloaded. If you use the {{{keep}}} option with one of your mail sources to ''not'' delete messages on the server after downloading them the ID-file is used to prevent downloading these messages again on the next run of fetch mail.

 * It is highly recommended that you use the {{{keep}}} option in the fetchmailrc until you are sure everything is working O.K.  This will keep the emails on the server while downloading a copy to your system.

=== Step 4: ''starting the daemon'' ===

Fetchmail is started using {{{launchd}}} which is controlled by macport's fetchmail installed {{{/opt/local/etc/LaunchDaemons/org.macports.fetchmail/org.macports.fetchmail.plist}}}


"Note:"
 * (As of Jun 2014), the .plist uses a wrapper that denotes the fetchmailrc file as /opt/local/etc/.fetchmail so unless you want to edit this file, create a link
{{{
sudo ln -s /opt/local/etc/fetchmailrc /opt/local/etc/.fetchmail
}}}
 * (As of Jun 2014), change fetchmail.wrapper such that the Start() looks like the below.
{{{
sudo vi /opt/local/etc/LaunchDaemons/org.macports.fetchmail/fetchmail.wrapper 
}}}
{{{
Start()
{
     /opt/local/bin/fetchmail -f /opt/local/etc/.fetchmail --daemon=1200 --nodetach
}
}}}

* (As of Jun 2014), org.macports.fetchmail.plist must be edited and these 2 lines added before the </dict></plist>
{{{
sudo vi /opt/local/etc/LaunchDaemons/org.macports.fetchmail/org.macports.fetchmail.plist
}}}
{{{
<key>UserName</key>
<string>_fetchmail</string>
}}}

The attached [attachment:Restart_Fetchmail.command] command will stop and restart fetchmail which forces a re-read of the configuration files and triggers an immediate mail collection - quite helpful while debugging the system.

''Note:''

 * The logfile defined in [attachment:fetchmailrc] can only be used without {{{--nodetach}}} (see [http://www.fetchmail.info/fetchmail-man.html#24 man fetchmail]). With the configuration currently presented here everything will be logged to the system log.

=== Step 5: ''testing the deamon'' ===

'''Before using fetchmail you should collect all your mail by conventional means.'''

After starting fetchmail you should check if the start was successful by checking the syslog:

{{{
$ syslog
Thu Jun  5 21:20:42 macpro sudo[42916] <Notice>:   martin : TTY=ttys001 ; PWD=/opt/local/Applications/Utilities ; USER=root ; COMMAND=/bin/launchctl unload -w /Library/LaunchDaemons/org.macports.fetchmail.plist
Thu Jun  5 21:20:42 macpro sudo[42917] <Notice>:   martin : TTY=ttys001 ; PWD=/opt/local/Applications/Utilities ; USER=root ; COMMAND=/bin/launchctl load -w /Library/LaunchDaemons/org.macports.fetchmail.plist
Thu Jun  5 21:20:42 macpro sudo[42919] <Notice>:   martin : TTY=ttys001 ; PWD=/opt/local/Applications/Utilities ; USER=root ; COMMAND=/bin/launchctl start org.macports.fetchmail
Thu Jun  5 21:20:42 macpro org.macports.fetchmail[42918] <Notice>: fetchmail: starting fetchmail 6.3.8 daemon 
Thu Jun  5 21:20:48 macpro org.macports.fetchmail[42918] <Notice>: fetchmail: sleeping at Thu, 05 Jun 2008 21:20:48 +0200 (CEST) for 1800 seconds
}}} 

Last you send yourself a mail and trigger a mail collection with [attachment:Restart_Fetchmail.command] and then check if the mail arrived in your local mail storage.

== Simple User Configuration ==
Another possible way to setup fetchmail is to have your user run it.

* Note that the below instructions work on Mt. Lion and haven't been tested on Mavericks
* Note that you'll have to adjust the paths in the plist and sh files

Copy [attachment:myuser.fetchmail.plist] to /Library/LaunchDaemons/

Create /Users/myuser/devel/scripts/fetchmail-call.sh
{{{
#!/bin/bash

/opt/local/bin/fetchmail || [ $? -eq 1 ] 
}}}

Then, load the plist as usual.

== Optional Parts ==

[wiki:howto <- Back to the HOWTO section]