Documentation/public-inbox-pop3d.pod

   1 =head1 NAME
   2
   3 public-inbox-pop3d - POP3 server for sharing public-inboxes
   4
   5 =head1 SYNOPSIS
   6
   7   public-inbox-pop3d [OPTIONS]
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-pop3d provides a POP3 daemon for public-inbox.
  12 It uses options and environment variables common to all
  13 read-only L<public-inbox-daemon(8)> implementations,
  14 but requires additional read-write storage to keep track
  15 of deleted messages on a per-user basis.
  16
  17 Like L<public-inbox-imapd(1)>, C<public-inbox-pop3d> will never
  18 require write access to the directory where the public-inboxes
  19 are stored.
  20
  21 It is designed for anonymous access, thus the password is
  22 always C<anonymous> (all lower-case).
  23
  24 Usernames are of the format:
  25
  26         C<$UUID@$NEWSGROUP_NAME>
  27
  28 Where C<$UUID> is the output of the L<uuidgen(1)> command.  Dash
  29 (C<->) characters in UUIDs are ignored, and C<[A-F]> hex
  30 characters are case-insensitive.  Users should keep their UUIDs
  31 private to prevent others from deleting unretrieved messages.
  32 Users may switch to a new UUID at any time to retrieve
  33 previously-retrieved messages.
  34
  35 Historical slices of 50K messages are available
  36 by suffixing the integer L<$SLICE>, where C<0> is the oldest.
  37
  38         C<$UUID@$NEWSGROUP_NAME.$SLICE>
  39
  40 It may be run as a different user than the user running
  41 L<public-inbox-watch(1)>, L<public-inbox-mda(1)>, or
  42 L<public-inbox-fetch(1)>.
  43
  44 To save storage, L</publicinbox.pop3state> only stores
  45 the highest-numbered deleted message
  46
  47 =head1 OPTIONS
  48
  49 See common options in L<public-inbox-daemon(8)/OPTIONS>.
  50
  51 =over
  52
  53 =item -l PROTOCOL://ADDRESS/?cert=/path/to/cert,key=/path/to/key
  54
  55 =item --listen PROTOCOL://ADDRESS/?cert=/path/to/cert,key=/path/to/key
  56
  57 In addition to the normal C<-l>/C<--listen> switch described in
  58 L<public-inbox-daemon(8)>, the C<PROTOCOL> prefix (e.g. C<pop3://> or
  59 C<pop3s://>) may be specified to force a given protocol.
  60
  61 For STARTTLS and POP3S support, the C<cert> and C<key> may be specified
  62 on a per-listener basis after a C<?> character and separated by C<,>.
  63 These directives are per-directive, and it's possible to use a different
  64 cert for every listener.
  65
  66 =item --cert /path/to/cert
  67
  68 The default TLS certificate for optional STARTTLS and POP3S support
  69 if the C<cert> option is not given with C<--listen>.
  70
  71 If using systemd-compatible socket activation and a TCP listener on port
  72 995 is inherited, it is automatically POP3S when this option is given.
  73 When a listener on port 110 is inherited and this option is given, it
  74 automatically gets STARTTLS support.
  75
  76 =item --key /path/to/key
  77
  78 The default private TLS certificate key for optional STARTTLS and POP3S
  79 support if the C<key> option is not given with C<--listen>.  The private
  80 key may be concatenated into the path used by C<--cert>, in which case this
  81 option is not needed.
  82
  83 =back
  84
  85 =head1 CONFIGURATION
  86
  87 Aside from C<publicinbox.pop3state>, C<public-inbox-pop3d> uses the
  88 same configuration knobs as L<public-inbox-nntpd(1)>,
  89 see L<public-inbox-nntpd(1)> and L<public-inbox-config(5)>.
  90
  91 =over 8
  92
  93 =item publicInbox.pop3state
  94
  95 A directory containing per-user/mailbox account information;
  96 must be writable to the C<public-inbox-pop3d> process.
  97
  98 =item publicInbox.<name>.newsgroup
  99
 100 The newsgroup name maps to a POP3 folder name.
 101
 102 =back
 103
 104 =head1 CONTACT
 105
 106 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 107
 108 The mail archives are hosted at L<https://public-inbox.org/meta/>, and
 109 L<nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta>,
 110 L<nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.mail.public-inbox.meta>
 111
 112 =head1 COPYRIGHT
 113
 114 Copyright all contributors L<mailto:meta@public-inbox.org>
 115
 116 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 117
 118 =head1 SEE ALSO
 119
 120 L<git(1)>, L<git-config(1)>, L<public-inbox-daemon(8)>,
 121 L<public-inbox-config(5)>, L<public-inbox-nntpd(1)>,
 122 L<uuidgen(1)>