wmbiff/wmbiff/wmbiffrc.5.in

   1 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
   2 .\" $Id: wmbiffrc.5.in,v 1.18 2004/12/12 00:01:53 bluehal Exp $
   3 .\"
   4 .\" @configure_input@
   5 .\"
   6 .\" wmbiff.1 and wmbiffrc.5 are copyright 1999-2002 by
   7 .\" Jordi Mallach <jordi@debian.org>
   8 .\"
   9 .\" This is free documentation, see the latest version of the GNU
  10 .\" General Public License for copying conditions. There is NO warranty.
  11 .TH WMBIFFRC 5 "November 11, 2002" "wmbiff"
  12
  13 .SH NAME
  14 wmbiffrc \- configuration file for
  15 .BR wmbiff (1)
  16
  17 .SH DESCRIPTION
  18 \fBWMbiff\fP is a mail notification tool for the WindowMaker and AfterStep
  19 window managers. It can handle up to 5 mailboxes, more when run using other
  20 window managers. You can define actions
  21 on mouse clicks for the different mailboxes. This manpage explains the
  22 different options which can be specified in a user's wmbiffrc.
  23
  24 .SH OPTIONS
  25 Each option takes the form
  26 .IR option[.mbox] " = " value .
  27 Comments must be preceeded by pound signs (#).
  28
  29 The supported configuration options are:
  30
  31 .TP 3
  32 \fBcertfile\fP
  33 File that holds TLS (SSL) certificates.  If specified,
  34 wmbiff will check certificates and exit on a failure, so
  35 your password is secure.  If not present, wmbiff will trust
  36 all certificates and may be vulnerable to a
  37 man-in-the-middle attack.  WMbiff's will not prompt if you
  38 want to accept new certificates.  Instead, wmbiff expects
  39 your mail client to keep certificates in a file.  For
  40 example, if mutt is your mailreader, you may add:
  41
  42 .RS
  43 certfile=/home/<me>/.muttsslcerts
  44 .RE
  45 .TP
  46 \fBtls\fP
  47 Specify cipher suite preferences on a TLS session. Can be a
  48 predefined value from gnults or a custom value. Default value
  49 is: \fINORMAL\fP.
  50
  51 gnutls predefined values:
  52 .SP
  53 .RS 8
  54 \fIPERFORMANCE\fP (gnutls >= 2.2.0)
  55 .RE
  56 .RS 8
  57 \fINORMAL\fP (gnutls >= 2.2.0)
  58 .RE
  59 .RS 8
  60 \fISECURE128\fP (gnutls >= 2.2.0)
  61 .RE
  62 .RS 8
  63 \fISECURE192\fP (gnutls >= 3.0.0)
  64 .RE
  65 .RS 8
  66 \fISECURE256\fP (gnutls >= 2.2.0)
  67 .RE
  68 .RS 8
  69 \fISUITEB128\fP (gnutls >= 3.0.0)
  70 .RE
  71 .RS 8
  72 \fISUITEB192\fP (gnutls >= 3.0.0)
  73 .RE
  74 .RS 8
  75 \fIEXPORT\fP (gnutls >= 2.2.0)
  76 .RE
  77 .RS 8
  78 \fINONE\fP (gnutls >= 2.2.0)
  79 .RE
  80 .RS
  81 .TP
  82 See \fBhttp://gnutls.org/manual/gnutls.html#Priority-Strings\fR for more details.
  83 .RE
  84 .TP
  85 \fBinterval\fP
  86 Global interval between mailbox checking. Value is the number of seconds, 5
  87 is the default.
  88 .TP
  89 \fBaskpass\fP
  90 Program run to ask for IMAP passwords, if left empty in the configuration file.
  91 The default is @DEFAULT_ASKPASS@.  Can be specified on a per-mailbox basis.
  92 .TP
  93 \fBskinfile\fP
  94 XPM pixmap file to load for the background.  If not a full
  95 path, wmbiff will search @SKINDIR@, /usr/share/wmbiff,
  96 /usr/local/share/wmbiff, and the current directory for the
  97 pixmap file.
  98 .TP
  99 \fBglobalnotify\fP
 100 Command to be executed when new mail is recieved in any mailbox. Set
 101 notify.n to override this option for mailbox n.
 102 .TP
 103 \fBlabel.n\fP
 104 Specifies the displayed label for a mailbox. It can be up to five characters
 105 long.
 106 .TP
 107 \fBpath.n\fP
 108 Path to the mailbox, local or remote one. Path lines start with a prefix,
 109 which specifies the type of wmbiff box you're setting up. The following types
 110 are supported:
 111 .RS
 112 .TP
 113 .I mbox
 114 This is a local mbox mailbox. After the prefix, you only need to put the
 115 path to the mailbox wmbiff needs to read.
 116 Local mboxes may be specified using shell commands enclosed
 117 in back-ticks. (`s.)
 118 .\"This is also the default.
 119 .RS
 120 mbox:/path/to/mail/debian-devel
 121 .RE
 122 .\"  let's stop making this available.
 123 .\" .RS
 124 .\" - or -
 125 .\" .RE
 126 .\" /path/to/mail/debian-devel
 127 .\" .RS
 128 .TP
 129 .I maildir
 130 This works just like \fImbox\fP above.
 131 .RS
 132 maildir:[:\fIflags\fP:]/path/to/mail/bugtraq/
 133 .TP
 134 \fIflags\fP can one or more of:
 135 .TP
 136 .I F
 137 Flush directory caches by creating (then deleting) a temporary file
 138 in each maildir prior to checking.  This hack speeds up checking
 139 network-mounted maildirs in cases where directory caching can cause
 140 unwanted delays (eg. SFS-mounted maildirs).
 141 .RE
 142 .TP
 143 .I pop3
 144 Using this type, WMBiff will check for mail on a pop3 server using the
 145 specified username, password, host and an optional port number (defaulting
 146 to 110).  If your password contains a special character, eg. '@' or ':',
 147 use the second path format.  See Authentication below for a description of
 148 the auth field.
 149 .RS
 150 pop3:user:passwd@server[:port] [auth]
 151 .RE
 152 .RS
 153 pop3:user passwd server[ port] [auth]
 154 .RE
 155 .TP
 156 .I pop3s
 157 Exactly like pop3, only uses TLS (SSL) when built with gnutls and defaults
 158 to port 995. @GNUTLS_MAN_STATUS@
 159 .TP
 160 .I imap
 161 These are IMAP4 boxes. As with pop3, WMBiff will report the
 162 status of an IMAP4 mbox using the given values. This type
 163 accepts user, optional password, host and optional path to
 164 mailbox and port number.  See Authentication below for a
 165 description of the auth field.  The password may be left
 166 empty: see askpass above for information on password
 167 prompting.  If your password includes a @, use the
 168 space delimited form.  If it contains a space or #, use the
 169 askpass option instead.  The mailbox field may be quoted,
 170 e.g., server/"Mail/Eggs and Spam".  Mailboxes in subfolders
 171 may be described as /INBOX.subfolder by some servers and
 172 /Mail/subfolder by others.
 173 .RS
 174 imap:user:passwd@server[/mailbox][:port] [auth]
 175 .RE
 176 .RS
 177 imap:user:@server[/mailbox][:port] [auth]
 178 .RE
 179 .RS
 180 imap:user passwd server[/mailbox][ port] [auth]
 181 .RE
 182 .RS
 183 imap:user:passwd@server[/"mail box"][:port] [auth]
 184 .RE
 185 .TP
 186 .I imaps
 187 These are IMAP4 boxes wrapped in a TLS (SSL)
 188 connection. @GNUTLS_MAN_STATUS@ Parameters are the same as
 189 those for ordinary IMAP4 boxes.  Port defaults to 993. If
 190 143 is specified, WMBiff will attempt to connect unencrypted
 191 but negotiate TLS using IMAP's STARTTLS command.  TLS
 192 support uses GNUTLS, which is under development and may be
 193 insecure.  See the imap format above
 194 for additional detail about specifying your password.
 195 .RS
 196 imaps:user:passwd@server[/mailbox][:port] [auth]
 197 .RE
 198 .RS
 199 imaps:user:@server[/mailbox][:port] [auth]
 200 .RE
 201 .RS
 202 imaps:user passwd server[/mailbox][ port] [auth]
 203 .RE
 204 .TP
 205 .I shell
 206 With this keyword, wmbiff will launch the
 207 specified shell command and read its output (STDOUT)
 208 expecting an integer message count or a three-character
 209 string.  If "new" is in the first line, the string or number
 210 will be displayed in yellow. The behavior of this
 211 experimental keyword is likely to change in future
 212 revisions.
 213 .RS
 214 shell:::/path/to/command
 215 shell:::lpq | grep Queue | awk '{print $2}'
 216 .RE
 217 .RE
 218 .TP
 219 \fBnotify.n\fP
 220 Command to be executed on new mail arrival in the given mailbox. Accepts
 221 the special keyword "beep" to use the pc speaker.
 222 .TP
 223 \fBaction.n\fP
 224 Command to be executed on left mouse click on a mailbox label.
 225 Accepts
 226 the special keyword "msglst" to pop up a window of recent message headers
 227 from IMAP or POP3 mailboxes when the left mouse button is held.
 228 .TP
 229 \fBbuttontwo.n\fP
 230 Command to be executed on middle mouse click on a mailbox level.
 231 Accepts
 232 the special keyword "msglst" to pop up a window of
 233 recent message headers from IMAP or POP3 mailboxes when the middle mouse button is held.
 234 .TP
 235 \fBinterval.n\fP
 236 Per mailbox check interval. Value is the amount of seconds between
 237 checkings, default is the global interval.
 238 .TP
 239 \fBfetchinterval.n\fP
 240 Interval between mail auto-fetching. Values accept 0 to disable, -1 for
 241 autofetching on new mail arrival, and positive values for a given interval
 242 in seconds.
 243 .TP
 244 \fBfetchcmd.n\fP
 245 Command to be executed to fetch mail. If not specified, fetching through
 246 wmbiff is disabled completely.
 247 Accepts
 248 the special keyword "msglst" to pop up a window of recent message headers
 249 from IMAP and POP3 mailboxes when the right mouse button is held down,
 250 though not when fetchinterval is nonzero.
 251 .TP
 252 \fBdebug.n\fP
 253 Show debugging messages from this mailbox.  Currently
 254 supported values are "all" and "none".  The \-debug option
 255 to wmbiff overrides this setting.  Since IMAP uses a single
 256 connection per server, per-mailbox debugging may not
 257
 258 .SH SIZING
 259
 260 WMBiff will automatically size its window to the number of
 261 configured mailboxes.  While WindowMaker's Dock and
 262 AfterStep's Wharf expect square, 64x64 applets, other window
 263 managers, such as Blackbox or Openbox do not have this
 264 limitation.  This uncharacteristic "dockapp" behavior is
 265 intended to help those users who don't have exactly five
 266 mailboxes to watch.
 267
 268 To preserve the old-style five-mailbox window even when you
 269 have only two, add
 270 .IR path.4=<space><space>
 271 to configure a blank 5th mailbox.
 272
 273 To use the new-style sizing, just configure as many
 274 mailboxes as you want.
 275
 276 .SH AUTHENTICATION
 277
 278 Authentication methods include "cram-md5", "apop" (for
 279 Pop3), and "plaintext".  "cram-md5" and "apop" are only
 280 available when wmbiff is compiled with libgcrypt.
 281 @GCRYPT_MAN_STATUS@
 282 Authentication methods are tried in the following order:
 283 cram-md5, apop, plaintext.
 284
 285 Each authentication method will be tried unless a list is
 286 included in the [auth] field.  For example, append "cram-md5
 287 apop" if you don't want your password to be sent in
 288 cleartext over the network.  Conversely, append "plaintext"
 289 if you don't want wmbiff to bother with other authentication
 290 methods.  Leaving authentication methods unspecified should
 291 be reasonably safe.  The order of entries in the [auth] list
 292 is not currently considered.
 293
 294 .SH TROUBLESHOOTING
 295
 296 For problems authenticating to servers, try specifying the
 297 authentication method explicitly as described above:
 298 sometimes a failed attempt to authenticate can cause later
 299 failures.  Some servers claim to support cram-md5 but fail:
 300 telling wmbiff not to try can help.
 301
 302 For other problems, run wmbiff with the -debug option.  See
 303 wmbiff(1) for details.
 304
 305 While editing .wmbiffrc, you may find it useful to restart
 306 wmbiff using either control-shift mouse button 1, or killall
 307 -USR1 wmbiff.
 308
 309
 310 .SH FILES
 311 .TP
 312 .I ~/.wmbiffrc
 313 per-user wmbiff configuration file.
 314
 315 .SH AUTHOR
 316 This manual page was written by Jordi Mallach <jordi@debian.org>,
 317 originally for the Debian system (but may be used by others).
 318
 319 .SH SEE ALSO
 320 .PD 0
 321 .TP
 322 \fBwmbiff\fP(1)
 323 .PP
 324 \fI/usr/share/doc/wmbiff/examples/sample.wmbiffrc\fP
 325 (or equivalent on your system)