Balsa E-Mail Client 2.0.x
=========================

See ChangeLog for the list of the recent changes and NEWS for highlights.

Copyright (C) 1997-2002 Stuart Parmenter and others

See 'COPYING' for licence information.  Please note linking against
OpenSSL libraries is explicitely allowed.

See 'AUTHORS' for a list of contributors


Authors:
-------
	See AUTHORS


Website:
-------
	http://balsa.gnome.org/


Description:
-----------
 	Balsa is an e-mail reader.  This client is part of the GNOME
desktop environment.  It supports local mailboxes, POP3 and IMAP.


Configuration:
-------------
	Balsa has a lot of options to its configure script; you
should run './configure --help' to get an idea of them. More
complete descriptions are here.

--enable-all
	Will turn on some features that are less than stable,
or unfinsished, such as filtering and spell-checking. This
is really use-at-your-own-risk.

--disable-more-warnings
	Balsa by default is very sensitive to compilation warnings
which often mean simply programming or configuration errors. If you
are sure this is not the case, or you cannot change your system setup
use this option to compile the code and hope for the best. 
(some Solaris setups require this).

--enable-threads
	Compile Balsa with threading for more responsiveness.
This works very well and should be enabled if possible.

--disable-system-install
	If specified, Balsa will not put files into the 
prefix of Gnome, but instead into the prefix of other Balsa
files. This allows Balsa to be installed locally if you don't
have the permissions to install into /usr or /usr/local or
wherever Gnome lives. Balsa will be able to find all the files
that it needs, but Gnome may not be able to locate certain
resources such as balsa.desktop, balsa.soundlist, etc.

--with-gpgme
        Use GPGME library for message signing and encryption. 
GPGME version more recent than  0.3.x w/ x >= 14 is required. 
Please note that all national characters in the passphrase must be
valid UTF-8 characters, see
http://home.arcor.de/dralbrecht.dress/balsa/UsingGnuPG.html#FAQ
for more details.

--with-gss[=/usr/kerberos]
	This enables GSSAPI Kerberos based authentication scheme. 
Specify the kerberos directory as the argument.

--with-ssl
	Use OpenSASL library for POP/IMAP authentication instead of
mutt's native code (in the future, the native code will most likely be
phased out in favour of SASL library).

--with-gtkhtml=version
        Choose preferred version of the GtkHtml library. Sensible
choices for the version are 2 or 3. Version 3 supports eg. printing
but does not support CSS formatting.

--with-ldap
        Use ldap libraries for a read-only address book. The read/write
address book is in the works but needs some finishing touches.


Libraries:
---------
	Balsa uses libESMTP library available at 
http://www.stafford.uklinux.net/libesmtp/
The current version is available at
http://www.stafford.uklinux.net/libesmtp/libesmtp-1.0.3r1.tar.bz2

You can grab {i386,src}.rpm that has this option enabled from
ftp://ftp.chbm.nu/pub/ (built on RH 6.2) or from
http://balsa.gnome.org/libesmtp-1.0.3r1-1.i386.rpm
http://balsa.gnome.org/libesmtp-devel-1.0.3r1-1.i386.rpm
http://balsa.gnome.org/libesmtp-1.0.3r1-1.src.rpm
	
Balsa also needs the aspell spell checking libraries.

	Make sure you have libtool installed (if you get some error 
messages during compilation or when running precompiled binaries saying that
libtdl is missing it means you need to install just that package).


Website:
-------
	Balsa CVS source comes with the Balsa website in the
directory for balsa/website/. Read balsa/website/README and
balsa/website/INSTALL for more information. If you retrieved
this source as a tarball or RPM or deb, this directory 
probably won't exist. To get it, you need to go to ....


Balsa CVS:
---------
	Balsa is hosted on the Gnome CVS servers. To get
the latest source, get the module 'balsa' from the CVS
root ':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'. 

Specifying the SMTP Server:
--------------------------

	when compiled to use libESMTP, the remote SMTP server details
are configured on the Mail Servers tab of the Preferences dialogue box
as follows:-

Remote SMTP Server:
	Specify the domain name and optionally the port for of the SMTP
	server you use for submitting mail.  Please note that the
	default port number is 587.  The syntax is hostname[:port].
	Port can be a decimal number or the name of the service as
	specified in /etc/services.  Typically you can just set this to
	localhost:25.

User:
	If the remote SMTP server requires authentication, enter your
	user name here.  Note that the exact format depends on the MTA
	in use.  For example, some systems expect a user name, others
	may require an email address.

Pass Phrase:
	If the remote SMTP server requires authentication, enter your
	pass phrase here.  Some systems refer to the pass phrase as a
	password.  Limitations on the length of the pass phrase depend
	on the SMTP server.


TLS extension in SMTP mail submission:
--------------------------------------

    If you have libESMTP 0.8.5{preX} there will be a box for entry of
    the client certificate's password.  The client certificate should
    be stored in PEM format in the file

    $HOME/.authenticate/$HOSTNAME/private/smtp-starttls.pem
    
    Both the certificate and the private key are stored in the same
    file.  The permissions on the certificate file *must* be 0600 or 0400
    otherwise libESMTP will ignore it.

    libESMTP 0.8.4 will establish an encrypted connection with servers
    supporting STARTTLS but there is no certificate support.  If the
    remote SMTP server requires a certificate, you will have to set
    "Use TLS" to "Never".

    Note that libESMTP 0.8.5 will only negotiate a TLS connection.  It
    will not use SSLv2 or SSLv3 which are subject to downgrade
    attacks.


Help System:
-----------
	In order to compile the help files, you need to have the
GNOME DocBook documentation system. Very good documentation
can be found at: http://www.gnome.org/gdp/gdp-handbook/gettingstarted.html


Balsa as mailto protocol handler:
---------------------------------
	Balsa can be used as mailto protocol handler. You have to edit
the GNOME URL handlers and add mailto protocol with command 
balsa -m "%s".

Mailbox locking:
---------------
    Balsa uses flock+dotfile for mailbox file locking. It does not
    use fcntl (although it can be enabled) since this locking method is
    very fragile and often not portable (see for example
    http://www.washington.edu/pine/tech-notes/low-level.html#locking).

    Make sure that your spool directory has drwxrwxrwt (01777) access
    privileges. Presently, dotfile locking requires this unconditionally
    In the future, we may relax this requirement and will allow you to
    shoot yourself in your leg.

POP3 mail filtering:
-------------------

    When the respective POP3 'mailbox' has the 'filter' box checked, the
    downloaded mail is passed on to procmail which will use
    ~/.procmailrc file as its configuration, so you can share it between
    balsa and fetchmail and get consistent behavior no matter you use
    balsa or fetchmail for downloading.

Simple example ~/.procmailrc file:
--------- cut here ----------------
:0H:
* ^Subject:.*balsa
mail/balsa-related-mail
--------- cut here ----------------

It is recommended to read procmail(1) and procmailrc(1) for more
real-life examples and syntax explanation.


Alternative browsers:
--------------------
Start from checking settings in your Gnome Control Center. If your
version of gnomecc does provide option to change the default browser,
you will need to create a file named gnome-moz-remote in your .gnome
directory. It should contain the following:

[Mozilla]
filename=/path/to/your/browser


Reporting Bugs:
--------------
	See http://balsa.gnome.org/bugs.html for instructions.  Do not
report bugs with GtkHTML - it is quite unstable. Patches are welcome.



Known issues:
------------

*	When dotlocking is not possible (Wrong access privilieges for
	the mailbox file) balsa will open mailbox for reading only.
	Verify that balsa can create dot file in the mailbox directory.
	Recommended access privileges to /var/spool/mail are rwxrwxrwxt (01777)

*	Some versions of libgnome is known to have bugs that lead to 
	balsa crash on startup. Read for details
	http://mail.gnome.org/archives/balsa-list/2000-October/msg00101.html
	and make sure you have at least /usr/lib/libgnome.so.32.3.11.

*       Experimental gcc 2.96 distributed with RedHat 7.0 generates 
	spurious warning messages. You have to configure balsa with 
	--disable-more-warnings option.

