jaromail

a commandline tool to easily and privately handle your e-mail
git clone git://parazyd.org/jaromail.git
Log | Files | Refs | Submodules | README

commit e22998efbc6a54e3d29ffa3505d6e6527d587525
parent ee5f947613646b480bde58198192eb68d527af88
Author: Jaromil <jaromil@dyne.org>
Date:   Sun,  3 Jun 2012 20:41:14 +0200

A start at the user manual

Diffstat:
Rdoc/postino-diagram.dia -> doc/jaromail-diagram.dia | 0
Rdoc/postino-diagram.png -> doc/jaromail-diagram.png | 0
Adoc/jaromail-manual.org | 326+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Ddoc/postino-whitepaper.org | 120-------------------------------------------------------------------------------
Ddoc/postino-whitepaper.pdf | 0
5 files changed, 326 insertions(+), 120 deletions(-)

diff --git a/doc/postino-diagram.dia b/doc/jaromail-diagram.dia Binary files differ. diff --git a/doc/postino-diagram.png b/doc/jaromail-diagram.png Binary files differ. diff --git a/doc/jaromail-manual.org b/doc/jaromail-manual.org @@ -0,0 +1,326 @@ +#+TITLE: Jaro Mail +#+AUTHOR: by Jaromil @ dyne.org +#+DATE: 2010 - 2012 + +#+LaTeX_CLASS: article +#+LaTeX_CLASS_OPTIONS: [a4,onecolumn,portrait] +#+LATEX_HEADER: \usepackage[utf8x]{inputenc} +#+LATEX_HEADER: \usepackage[T1]{fontenc} +#+LATEX_HEADER: \usepackage{hyperref} +#+LATEX_HEADER: \usepackage[pdftex]{graphicx} +#+LATEX_HEADER: \usepackage{fullpage} +#+LATEX_HEADER: \usepackage{lmodern} +#+LATEX_HEADER: \usepackage[hang,small]{caption} +#+LATEX_HEADER: \usepackage{float} + +#+LATEX: \pagebreak + +* Introduction + +Jaro Mail is an integrated suite of interoperable tools to manage +e-mail communication in a private and efficient way, without relying +too much on on-line services, in fact encouraging users to store their +email locally. + + +Rather than reinventing the wheel, this suite reuses existing free and +open source tools and protocols and is mainly targeted for +GNU/Linux/BSD desktop usage. + +** Features + + + Easy to deploy and use + + Targets intensive usage of mailinglists + + Integrates addressbook and whitelisting + + Generates Procmail and Sieve filters + + Encrypts password storage (keyrings) + + Provides advanced maildir tools + + Defers connections for off-line operations + + Checks SSL certificates over (imap, smtp) + + Supports strong encryption (GnuPG) + + Is Based on solid GNU and BSD technology + + Is Multi platform: GNU/Linux/BSD, Apple/OSX + + Old school, used by its author for the past 10 years + +#+LATEX: \pagebreak + +* Diagram + +A little diagram that clarifies a bit where do we place the components +and actions involved in managing one's email communication: + +[[file:postino-diagram.png]] + + + MUA = Mail User Agent + + MTA = Mail Transport Agent + + SMTP = Simple Mail Transport Protocol + + IMAP = Internet Message Access Protocol + + +#+LATEX: \pagebreak + +* Components + +** Client side + +To use Jaro Mail on your desktop client, you will require some +programs. These programs are ready into the Apple/OSX package, but you +will have to install them by yourself if you use GNU/Linux, preferably +using your favourite package manager. + + + [[http://www.mutt.org][Mutt]] Mail User Agent + + [[http://www.fetchmail.info/][Fetchmail]] Mail Transport Agent + + [[http://www.procmail.org/][Procmail]] Filtering Agent + + [[http://freecode.com/projects/procmail-lib][Procmail-lib]] Advanced Filtering + + [[http://msmtp.sourceforge.net/][MSmtp]] the mini SMTP + + [[http://www.spinnaker.de/lbdb][Little Brother DB]] Addressbook + + [[http://www.zsh.org/][Z Shell]] Our scripting language + +** Server side + +The software below is not necessary if you like to use Jaro Mail with +your E-Mail accounts, but it is what you need to install and configure +on your web server if you like to provide E-Mail services to you and +your friends and family. However, to describe the configuration and +administration of a E-mail server is beyond the scope of this +document. + + + [[http://www.postfix.org][Postfix]] SMTP server + + [[http://dovecot.org/][Dovecot]] IMAP server + +* Configuration + +** Build + + There are two *build-* scripts coming with the sourcecode of Jaro Mail + + One is for building it on GNU/Linux systems, the other on OSX + + A compiler and various dependencies are mandatory in order to + build this software, please look into the scripts to find out + more. + + +** Install + + Installing Jaro Mail once all dependencies are build is fairly + easy: the *install.sh* script provided will create a working + environment in your HOME/Mail directory or, if you like, you can + specify an argument. + + Every installation of Jaro Mail is fully reentrant, meaning the + directory where it is installed contains all necessary files to + operate it on the system. Hence it is possible that a single user + has multiple Jaro Mail installations, for instance to permit the + complete separation of E-Mail identities. + +** Receive mail + + The place where Jaro Mail is installed, that is the directory + $HOME/Mail by default, contains a *jaro* folder where all + configuration files are found. + + There, inside the directory *Accounts*, are some brief + instructions and some default templates which can be filled in + with Imap or Pop account configuration to fetch mail. + + There is also a file *jaro/Mutt.txt* that can be configured with + some customized settings for the mail transport agent, such as + custom headers and the default GPG key to be used when signing and + encrypting mails. + +** Send mail + + + Also inside the *jaro/Accounts* directory are found the *smtp.* + files that configure various sending accounts, it is possible to + have more than one, just give the files different names. + + When no special account is specified using the *-a* option, then + the accounts files named *.default* will be used. It is also + possible to use symbolic links. + +** Filter mail + + The file *jaro/Filters.txt* is pretty easy and self explanatory, + yet it is a powerful way to configure mailinglist filters that + will be applied to all mails that are fetched locally. + + After editing that file it is necessary to run *jaro update* so + that Jaro Mail will generate all the procmail, mutt and sieve + rules out of those. An update is issued automatically every time + *jaro fetch* is called. + + +** Examples + +*** imap.default + +#+BEGIN_EXAMPLE +# Name and values are separated by spaces or tabs +# comments start the line with a hash + +# Name appearing in From: field +name To Be Configured + +# Email address (default is same as login) +email unknown@gmail.com + +# Internet address +host imap.gmail.com + +# Username +login USERNAME@gmail.com + +# Authentication type +auth plain # or kerberos, etc + +# Identity certificate: check or ignore +cert ignore + +# Transport protocol +transport ssl + +# Service port +port 993 + +# Options when fetching +# to empty your mailbox you can also use: fetchall +# by default this is 'keep' which will not delete mails from server +options keep +# we encourage you to store emails locally, hence using a fetchall +# configuration from a machine that you keep at home and secured. + +# Imap folders +# uncommend to provide a list of folders to be fetched +# folders INBOX, known, priv, lists, ml.unsorted, unsorted +#+END_EXAMPLE + +*** smtp.default + +#+BEGIN_EXAMPLE +# Name and values are separated by spaces or tabs +# comments start the line with a hash + +# Name for this account +name To Be Configured + +# Internet address +host smtp.gmail.com + +# Username +login USERNAME@gmail.com + +# Transport protocol +transport ssl # or "tls" or "plain" + +# Service port +# port 465 +port 25 +#+END_EXAMPLE + +*** Filters.txt + +#+BEGIN_EXAMPLE +# Example filter configuration for Jaro Mail + +# mailinglist filters are in order of importance +# syntax: to <list email> save <folder> +# below some commented out examples, note the use of a prefix, +# which makes it handy when browsing with file completion. + +# to crypto@lists.dyne save dyne.crypto +# to dynebolic save dyne.dynebolic +# to freej save dyne.freej +# to frei0r-devel save dyne.frei0r +# to taccuino save ml.freaknet +# to deadpoets save ml.freaknet +# to linux-libre save gnu.linux-libre +# to foundations@lists save gnu.foundations +# to debian-mentors save debian.mentors +# to debian-blends save debian.blends +# to freedombox-discuss save debian.freedombox + +# Other filters for web 2.0 using folder names with a prefix: +# they can facilitate folder maintainance. + +from identi.ca save web.identica +from Twitter save web.twitter +from linkedin save web.linkedin +from googlealerts save web.google +from facebook save web.facebook +from FriendFeed save web.friendfeed +from academia.edu save web.academia +#+END_EXAMPLE + + + +* Flow of operation + +This section goes through a scenario of typical daily usage of Jaro +Mail + +** Fetch and read your mail at home + +As you acces your computer where Jaro Mail has been configured, you +can open a Terminal and type: +: $ jaro fetch +This will download all new mails. + +If you have configured *fetchall* among the imap account options, then +will delete them from the server, freeing online space. + +If you have configured the *keep* option, which is the default, Jaro +Mail will only download the email that you have not yet read and in +any case it won't delete anything from the server. + +: $ jaro + +This will open the first folder *known* where all mails from people +that you know or that you usually exchange mails with are shown. + +From there on, pressing *=* or *c* you can change the folder and +explore your *priv* folder, the mailinglist ones as configured by your +Filters.txt, as well your *unsorted* mails. + +** Write a new mail + +If you like to write a mail to someone, just write his/her own address +as an argument to Jaro Mail +: $ jaro friend@home.net +But if you don't remember the email of your friend, then you can just +start *jaro* without options, then press *m* and then start typing the +name or whatever you remember of it: pressing the *Tab* key a +completion will help to remind what you are looking for, offering a +list of options to choose from. + + +** Peek without downloading anything + +If you are around and like to see your new mails without downloading +them, then you can use the *peek* function: +: $ jaro peek +This will open the default configured IMAP account and folder over SSL +protocol (securing the data transfer) and show your emails. + +From peek you can reply and even delete emails, but be careful since +what you delete here will be removed from the server and won't be +there when you download it from home. + +This functionality can be also very useful if you are from a slow +connection and need to delete some email that is clogging your mailbox +and that you are not able to download because of its size. + +** Send emails whenever possible + +All the time you write an E-mail, Jaro Mail will save it into your +outbox folder, waiting for the right moment to send it. In fact you +will have to tell it the right moment by running the *send* command: +: $ jaro send + +This will authenticate with your SMTP and send all your emails to +destination. This way even if you are off-line you will always be able +to write emails and eventually bring them around for sending them +whenever possible. + + diff --git a/doc/postino-whitepaper.org b/doc/postino-whitepaper.org @@ -1,120 +0,0 @@ -#+TITLE: Postino Suite - whitepaper -#+AUTHOR: Jaromil -#+DATE: September 2010 - 2011 - -#+LaTeX_CLASS: article -#+LaTeX_CLASS_OPTIONS: [a4,onecolumn,portrait] -#+LATEX_HEADER: \usepackage[utf8x]{inputenc} -#+LATEX_HEADER: \usepackage[T1]{fontenc} -#+LATEX_HEADER: \usepackage{hyperref} -#+LATEX_HEADER: \usepackage[pdftex]{graphicx} -#+LATEX_HEADER: \usepackage{fullpage} -#+LATEX_HEADER: \usepackage{lmodern} -#+LATEX_HEADER: \usepackage[hang,small]{caption} -#+LATEX_HEADER: \usepackage{float} - - -* Introduction - -Postino is an integrated suite of interoperable tools to manage e-mail -communication in a private and efficient way, without relying on third -party services. Rather than reinventing the wheel, this suite reuses -existing free and open source tools and protocols and is mainly -targeted for GNU/Linux/BSD desktop usage. - -* Diagram - - -#+LATEX_BEGIN -\begin{figure}[htb!] - \caption{Suite diagram} - \centering - \includegraphics{postino-diagram.png} -\end{figure} -#+LATEX_END - - -* Components - -** Client side - -+ Mail User Agent[fn:mua] -+ Fetchmail -+ Procmail & Procmail-lib -+ Mini SMTP (msmtp) -+ Little Brother DB -+ Secure shell client - -[fn:mua] Can be any application supporting local maildir folders, our favourite is Mutt - -** Server side - -+ Postfix -+ Dovecot -+ Sieve -+ Secure shell server - -* Workflow - -** Configuration - -*** Configure to receive mail - -*** Configure to send mail - -*** Configure to filter mail - - - - -*** Example configuration - -**** main.conf - -#+BEGIN_EXAMPLE -# ACCEPTED EMAIL ADDRESSES -EMAIL="jaromil.rojo@gmail.com, jaromil@dyne.org, jaromil@kyuzz.org" - -# LOCAL FILES -MAIL_USER_AGENT=mutt -MAIL_TRANSPORT_AGENT=msmtp -MAILDIRS=$HOME/mail -WORKDIR=$HOME/.postino -CERTIFICATES=$HOME/.ssl/certs -REMOTE_FILTER=/var/mail/... -#+END_EXAMPLE - -**** send.conf - -#+BEGIN_EXAMPLE -# name host login -gmail smtp.gmail.com jaromil.rojo@gmail.com -dyne assata.dyne.org username@dyne.im -#+END_EXAMPLE - -**** receive.conf - -#+BEGIN_EXAMPLE -# name host login -gmail imap.gmail.com jaromil.rojo@gmail.com -#+END_EXAMPLE - -**** filters.conf - -#+BEGIN_EXAMPLE -from list@kernel.org save ml.kernel -from dynebolic.lists.dyne save ml.dynebolic -#+END_EXAMPLE - - - -** Operation - -*** Fetch mail - -*** Read and reply mail - -*** Send mail - -*** Sync backup and filters - diff --git a/doc/postino-whitepaper.pdf b/doc/postino-whitepaper.pdf Binary files differ.