← Back to branch summary

~ubuntu-branches/ubuntu/maverick/mpop/maverick

« back to all changes in this revision

Viewing changes to doc/mpop.texi

  • Committer: Bazaar Package Importer
  • Author(s): Emmanuel Bouthenot
  • Date: 2009-08-14 18:08:48 UTC
  • mfrom: (1.1.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20090814180848-f31eii74n1dnzimr
Tags: 1.0.17-1
http://bugs.debian.org/513223
* New upstream release (Closes: #513223)
* Adopting the package: setting me as maintainer.
* Add a Homepage field.
* Bump Standards-Version to 3.8.2.
* Update debian/copyright:
  - point to the GPLv3 licence from /usr/share/common-licences
    instead of including the whole licence.
  - Add new copyright holders.
  - Cleaning and refactoring.
* Add Vcs-Git and Vcs-Browser fields.
* Switch packaging from CDBS to "plain debhelper".
* Update debian/compat to version 7.
* New binary package mpop-gnome (mpop with GNOME keyring support)
  which depends on "standard" mpop package and diverts /usr/bin/mpop.
* Update patch which fixes lintian warnings about hyphens in mpop
  manpage.
* Add DM-Upload-Allowed field.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/mpop.texi
1
1
\input texinfo   @c -*-texinfo-*-
2
2
@setfilename mpop.info
3
 
@set UPDATED August 1, 2007
4
 
@set UPDATED-MONTH August 2007
5
 
@set EDITION 1.0.11
6
 
@set VERSION 1.0.11
 
3
@set UPDATED March 7, 2009
 
4
@set VERSION 1.0.17
7
5
@settitle mpop @value{VERSION}
8
6
 
9
7
@c Define new indices: for options (op) and commands (cm)
15
13
This manual was last updated @value{UPDATED} for version
16
14
@value{VERSION} of mpop.
17
15
 
18
 
Copyright (C) 2005, 2006, 2007  Martin Lambers
 
16
Copyright (C) 2005, 2006, 2007, 2008, 2009  Martin Lambers
19
17
 
20
18
@quotation
21
19
Permission is granted to copy, distribute and/or modify this document
54
52
* Introduction::                        Basic concepts.
55
53
* Configuration file::                  Configuration file commands.
56
54
* Invocation::                          Command line options.
57
 
* POP3 features::                       Explanation of various POP3 features.
 
55
* Transport Layer Security::            How to use TLS/SSL.
 
56
* Authentication::                      How to use authentication.
 
57
* Pipelining::                          How to use POP3 pipelining.
 
58
* Defective POP3 servers::              Common defects of POP3 servers.
58
59
* Mail retrieval mode::                 How to retrieve mail.
59
60
* Filtering::                           How to filter mails.
60
61
* Server information mode::             How to obtain information about 
196
197
Set your password for POP3 authentication. An empty argument unsets the
197
198
password.
198
199
If no password is set but one is needed during authentication, mpop will try to
199
 
find it in @code{~/.netrc}, and if that fails, will prompt you for it.
 
200
find it in @code{~/.netrc}. If that fails, it will try to find it in 
 
201
@code{SYSCONFDIR/netrc} (use @code{--version} to find out what @code{SYSCONFDIR}
 
202
is on your platform). If that fails, it will try to get it from a system 
 
203
specific keychain (if available). If that fails, mpop will prompt you for it.
200
204
@xref{Authentication}.
201
205
@anchor{ntlmdomain}
202
206
@item ntlmdomain [@var{ntlmdomain}]
237
241
use the file @file{/etc/ssl/certs/ca-certificates.crt}.@*
238
242
An empty argument disables this feature.
239
243
@xref{Transport Layer Security}.
 
244
@anchor{tls_crl_file}
 
245
@item tls_crl_file [@var{file}]
 
246
@cmindex tls_crl_file
 
247
This command sets or unsets a certificate revocation list (CRL) file for TLS,
 
248
to be used during strict server certificate verification as enabled by the
 
249
@ref{tls_trust_file} command. This allows the verification procedure to detect
 
250
revoked certificates.
 
251
@xref{Transport Layer Security}.
240
252
@anchor{tls_key_file}
241
253
@item tls_key_file [@var{file}]
242
254
@cmindex tls_key_file
266
278
Force TLS/SSL version SSLv3. This might be needed to use SSL with some old and
267
279
broken servers. Do not use this unless you have to.
268
280
@xref{Transport Layer Security}.
 
281
@anchor{tls_min_dh_prime_bits}
 
282
@item tls_min_dh_prime_bits [@var{bits}]
 
283
@cmindex tls_min_dh_prime_bits
 
284
Set or unset the minimum number of Diffie-Hellman (DH) prime bits that mpop
 
285
will accept for TLS sessions. The default is set by the TLS library and can be
 
286
selected by using an empty argument to this command. Only lower the default
 
287
(for example to 512 bits) if there is no other way to make TLS work with the
 
288
remote server.
 
289
@xref{Transport Layer Security}.
 
290
@anchor{tls_priorities}
 
291
@item tls_priorities [@var{priorities}]
 
292
@cmindex tls_priorities
 
293
Set the priorities for TLS sessions. The default is set by the TLS library and
 
294
can be selected by using an empty argument to this command.  Currently this 
 
295
command only works with sufficiently recent GnuTLS releases. See the GnuTLS
 
296
documentation of the @samp{gnutls_priority_init} function for a description of 
 
297
the @var{priorities} string.
 
298
@xref{Transport Layer Security}.
269
299
@end table
270
300
 
271
301
@section Commands specific to mail retrieval mode
297
327
(This is what fetchmail does by default.)
298
328
@item delivery maildir @var{directory}@*
299
329
Deliver the mails to the given maildir directory. The directory must exist and 
300
 
it must be a valid maildir directory; mpop will not create directories.
 
330
it must be a valid maildir directory; mpop will not create directories. This 
 
331
delivery type only works on file systems that support hard links.
301
332
@item delivery mbox @var{mbox-file}@*
302
333
Deliver the mails to the given file in mbox format. The file will be locked 
303
334
with @code{fcntl(2)}. mpop uses the MBOXRD mbox format variant; see the
338
369
keep command is used, in which case they will just be skipped). The size 
339
370
argument must be zero or greater. If it is followed by a 'k' or an 'm', the 
340
371
size is measured in kilobytes/megabytes instead of bytes. Note that some POP3 
341
 
servers report slightly incorrect sizes for mails. @xref{Filtering}.
 
372
servers report slightly incorrect sizes for mails. @xref{Filtering}.@*
 
373
When @samp{killsize} is set to 0 and @samp{keep} is set to on, then all mails
 
374
are marked as retrieved, but no mail gets deleted from the server. This can be
 
375
used to synchronize the UID list on the client to the UID list on the server.
342
376
@anchor{skipsize}
343
377
@item skipsize (off|@var{size})
344
378
@cmindex skipsize
400
434
The default user configuration file.
401
435
@item @code{~/.mpop_uidls}
402
436
Default directory to store UIDLs files in.
403
 
@item @code{~/.netrc}
404
 
The @code{.netrc} file contains login information. If a password is not found 
405
 
in the configuration file, msmtp will search it in @code{.netrc} before 
406
 
prompting the user for it. The syntax of @code{.netrc} is described in the 
407
 
@code{netrc(5)} or @code{ftp(1)} manual page.
 
437
@item @code{~/.netrc} and @code{SYSCONFDIR/netrc}
 
438
The @code{netrc} file contains login information. If a password is not found 
 
439
in the configuration file, mpop will search it in @code{~/.netrc} and 
 
440
@code{SYSCONFDIR} before prompting the user for it. The syntax of @code{netrc}
 
441
files is described in the @code{netrc(5)} or @code{ftp(1)} manual page.
408
442
@item @code{$USER}, @code{$LOGNAME}
409
443
These variables override the user's login name. @code{$LOGNAME} is only used if
410
444
@code{$USER} is unset. The user's login name is used for @code{Received} 
505
539
@itemx --tls-trust-file=[@var{file}]
506
540
@opindex --tls-trust-file
507
541
Set or unset a trust file for TLS encryption. @xref{tls_trust_file}.
 
542
@anchor{--tls-crl-file}
 
543
@itemx --tls-crl-file=[@var{file}]
 
544
@opindex --tls-crl-file
 
545
Set or unset a certificate revocation list (CRL) file for TLS. 
 
546
@xref{tls_crl_file}.
508
547
@anchor{--tls-key-file}
509
548
@itemx --tls-key-file=[@var{file}]
510
549
@opindex --tls-key-file
522
561
@itemx --tls-force-sslv3=(on|off)]
523
562
@opindex --tls-force-sslv3
524
563
Force TLS/SSL version SSLv3. @xref{tls_force_sslv3}.
 
564
@anchor{--tls-min-dh-prime-bits}
 
565
@itemx --tls-min-dh-prime-bits=[@var{bits}]
 
566
@opindex --tls-min-dh-prime-bits
 
567
Set or unset minimum bit size of the Diffie-Hellman (DH) prime.
 
568
@xref{tls_min_dh_prime_bits}.
 
569
@anchor{--tls-priorities}
 
570
@itemx --tls-priorities=[@var{priorities}]
 
571
@opindex --tls-priorities
 
572
Set or unset TLS priorities. @xref{tls_priorities}.
525
573
@end table
526
574
 
527
575
@subsection Options specific to mail retrieval mode
591
639
File to store UIDLs in. @xref{uidls_file}.
592
640
@end table
593
641
 
594
 
@node POP3 features
595
 
@chapter POP3 features
596
 
 
597
 
@menu
598
 
* Transport Layer Security::            How to use TLS/SSL
599
 
* Authentication::                      How to use authentication
600
 
* Pipelining::                          How to use POP3 pipelining
601
 
* Defective POP3 servers::              Common defectives of POP3 servers
602
 
@end menu
603
642
 
604
643
@node Transport Layer Security
605
 
@section Transport Layer Security
 
644
@chapter Transport Layer Security
606
645
 
607
646
Transport Layer Security (TLS) is a new name for Secure Socket Layer (SSL).
608
647
The TLS 1.0 protocol is an updated version of the SSL 3.0 protocol. TLS and
683
722
CAs advertised by the server. If you set a client certificate but it is not send
684
723
to the server, probably does not match any CA that the server trusts.
685
724
 
 
725
If you need to fine tune TLS parameters or have problems connecting to your
 
726
server, have a look at the @ref{tls_force_sslv3}, @ref{tls_min_dh_prime_bits},
 
727
and @ref{tls_priorities} commands.
 
728
 
686
729
 
687
730
@node Authentication
688
 
@section Authentication
 
731
@chapter Authentication
689
732
 
690
733
POP3 servers require a client to authenticate itself before it is allowed to
691
734
retrieve mail. 
755
798
Authentication data can be set with the @samp{user} and @samp{password} commands
756
799
or with the @samp{--user} option. See @ref{user}, @ref{password}, @ref{--user}.
757
800
If no password is set but one is needed during authentication, mpop will try to
758
 
find it in @code{~/.netrc}, and if that fails, mpop will prompt you for it.
 
801
find it in @code{~/.netrc}. If that fails, it will try to find it in 
 
802
@code{SYSCONFDIR/netrc} (use @code{--version} to find out what @code{SYSCONFDIR}
 
803
is on your platform). If that fails, it will try to get it from a system 
 
804
specific keychain (if available). If that fails, mpop will prompt you for it.
 
805
 
 
806
Currently the only supported keychain is the Mac OS X keychain. 
 
807
@xref{Using the Mac OS X Keychain}.
759
808
 
760
809
The authentication method can be chosen with the @samp{auth} command or 
761
810
@samp{--auth} option, but it is usually sufficient to just use the @samp{on} 
770
819
If you really want to risk your authentication data, you have to force mpop to
771
820
do that by manually setting the authentication method while TLS is off.
772
821
 
 
822
@section Using the Mac OS X Keychain
 
823
@anchor{Using the Mac OS X Keychain}
 
824
 
 
825
A Mac OS X user can store a password in a keychain item using the Keychain
 
826
Access GUI application. The @samp{account name} is simply the value of the
 
827
mpopop @samp{user} argument. However, the @samp{keychain item name} is
 
828
@code{smtp://<hostname>} where @code{<hostname>} matches the mpop @samp{host}
 
829
argument. Using @code{smtp://} is needed so that the item is created of kind
 
830
@samp{internet password}.  For example, selecting @samp{File->Get Info} on a
 
831
keychain item that corresponds to @samp{host smtp.freemail.example} and
 
832
@samp{user joe.smith} will show:
 
833
 
 
834
@example
 
835
   Name: smtp.freemail.example
 
836
   Kind: Internet password
 
837
Account: joe.smith
 
838
  Where: smtp://smtp.freemail.example
 
839
@end example
 
840
 
 
841
 
773
842
@node Pipelining
774
 
@section Pipelining
 
843
@chapter Pipelining
775
844
 
776
845
A POP3 client that sends multiple POP3 commands at once to a POP3 server before
777
846
starting to read the server's answers is using POP3 pipelining. Since the client
793
862
always safe to disable pipelining. It is not recommended to force pipelining
794
863
for servers that are not known to support it.
795
864
 
 
865
 
796
866
@node Defective POP3 servers
797
 
@section Defective POP3 servers
 
867
@chapter Defective POP3 servers
798
868
 
799
869
Some POP3 servers still do not support the UIDL command. In this case, mpop 
800
870
cannot recognize messages that were already successfully retrieved, and will
985
1055
POP3 server since they cannot know the actual size in advance. Thus you cannot
986
1056
rely on @emph{exact} size filtering.
987
1057
 
988
 
 
989
1058
@node Examples
990
1059
@chapter Examples
991
1060