.\" Man page generated from reStructuredText.
.
.TH "ISBG" "1" "Aug 17, 2020" "2.3.1" "isbg"
.SH NAME
isbg \- scans an IMAP Inbox and runs every entry against SpamAssassin.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
isbg \fB\-\-imaphost\fP \fI<hostname>\fP \fB\-\-imapuser\fP \fI<username>\fP [\fIoptions\fP]
.sp
isbg \fB\-\-imaphost\fP \fI<hostname>\fP \fB\-\-imapuser\fP \fI<username>\fP \fB\-\-imaplist\fP
[\fIoptions\fP]
.sp
isbg (\fB\-h\fP | \fB\-\-help\fP)
.sp
isbg \fB\-\-usage\fP
.sp
isbg \fB\-\-version\fP
.SH DESCRIPTION
.sp
isbg scans an IMAP Inbox and runs every entry against SpamAssassin. For
any entries that match, the message is copied to another folder, and the
original marked or deleted.
.sp
Works with all common IMAP servers, can do IMAP over SSL, can remember
your password, will work painlessly against multiple IMAP accounts and
servers, is not involved in the mail delivery process, and so can run on
any machine that can contact your IMAP server and has the possibility to
skip spam detection to stick only to the teach feature.
.SH OPTIONS
.INDENT 0.0
.TP
\fB\-\-imaphost\fP \fIhostname\fP
IMAP server name
.TP
\fB\-\-imapuser\fP \fIusername\fP
Who you login as
.TP
\fB\-\-imaplist\fP
List imap directories
.TP
\fB\-h\fP, \fB\-\-help\fP
Show the help screen
.TP
\fB\-\-usage\fP
Show usage information
.TP
\fB\-\-version\fP
Show version information
.TP
\fB\-\-dryrun\fP
Do not actually make any changes
.TP
\fB\-\-delete\fP
The spams will be marked for deletion from your inbox
.TP
\fB\-\-deletehigherthan\fP \fI#\fP
Delete any spam with a score higher than \fI#\fP
.TP
\fB\-\-exitcodes\fP
Use exitcodes to detail what happened
.TP
\fB\-\-expunge\fP
Cause marked for deletion messages to also be deleted (only useful
if \fB\-\-delete\fP is specified)
.TP
\fB\-\-flag\fP
The spams will be flagged in your inbox
.TP
\fB\-\-gmail\fP
Delete by copying to \(aq\fI[Gmail]/Trash\fP\(aq folder
.TP
\fB\-\-ignorelockfile\fP
Don\(aqt stop if lock file is present
.TP
\fB\-\-imappasswd\fP \fIpasswd\fP
IMAP account password. This however is a really bad idea since any
user on the system can run \fBps\fP and see the command line arguments
.TP
\fB\-\-imapport\fP \fIport\fP
Use a custom port
.TP
\fB\-\-imapinbox\fP \fImbox\fP
Name of your inbox folder [Default: \fIINBOX\fP]
.TP
\fB\-\-learnspambox\fP \fImbox\fP
Name of your learn spam folder
.TP
\fB\-\-learnhambox\fP \fImbox\fP
Name of your learn ham folder
.TP
\fB\-\-learnthendestroy\fP
Mark learnt messages for deletion
.TP
\fB\-\-learnthenflag\fP
Flag learnt messages
.TP
\fB\-\-learnunflagfed\fP
Only learn if unflagged (for \fB\-\-learnthenflag\fP)
.TP
\fB\-\-lockfilegrace\fP=<min>
Set the lifetime of the lock file to [Default: \fI240.0\fP]
.TP
\fB\-\-lockfilename\fP \fIfile\fP
Override the lock file name
.TP
\fB\-\-maxsize\fP \fInumbytes\fP
Messages larger than this will be ignored as they are unlikely to be
spam
.TP
\fB\-\-movehamto\fP \fImbox\fP
Move ham to folder
.TP
\fB\-\-noninteractive\fP
Prevent interactive requests
.TP
\fB\-\-noreport\fP
Don\(aqt include the SpamAssassin report in the message copied to your
spam folder
.TP
\fB\-\-nostats\fP
Don\(aqt print stats
.TP
\fB\-\-partialrun\fP \fInum\fP
Stop operation after scanning \(aq\fInum\fP\(aq unseen emails [Default: \fI50\fP].
You can run \fBisbg\fP without \fB\-\-partialrun\fP with \fI\-\-partialrun=0\fP
.TP
\fB\-\-passwdfilename\fP \fIfile\fP
Use a file to supply the password
.TP
\fB\-\-savepw\fP
Store the password to be used in future runs. This will save the
password in a file in your home directory. The file is named
\fI\&.isbg\-XXXX\fP where XXXX is a 16 byte identifier based on the IMAP
host, username and port number (the same as for the multiple
accounts description above). You can override the filename with
\fB\-\-passwdfilename\fP\&. The password is obfuscated, so anyone just
looking at the contents won\(aqt be able to see what it is. However, if
they study the code to isbg then they will be able to figure out how
to de\-obfuscate it, and recover the original password. (isbg needs
the original password each time it is run as well). Consequently you
should regard this as providing minimal protection if someone can
read the file.
.TP
\fB\-\-spamc\fP
Use spamc instead of standalone SpamAssassin binary
.TP
\fB\-\-spaminbox\fP \fImbox\fP
Name of your spam folder [Default: \fIINBOX.Spam\fP]
.TP
\fB\-\-nossl\fP
Don\(aqt use SSL to connect to the IMAP server
.TP
\fB\-\-teachonly\fP
Don\(aqt search spam, just learn from folders
.TP
\fB\-\-trackfile\fP \fIfile\fP
Override the trackfile name
.TP
\fB\-\-verbose\fP
Show IMAP stuff happening
.TP
\fB\-\-verbose\-mails\fP
Show mail bodies (extra\-verbose)
.UNINDENT
.sp
(Your inbox will remain untouched unless you specify \fB\-\-flag\fP or
\fB\-\-delete\fP)
.SH EXAMPLES
.SS Do your first run
.INDENT 0.0
.INDENT 3.5
\fB$ isbg\ \-\-imaphost\  mail.foo.com\ \-\-imapuser rogerb@mail.foo.com \-\-imaplist
\-\-savepw\fP
.sp
\fBIMAP password for rogerb@mail.foo.org@mail.foo.org:\fP
.UNINDENT
.UNINDENT
.sp
Will request the password for your user account and store it obfuscated for
future use, after login, it will show the IMAP folder list:
.INDENT 0.0
.INDENT 3.5
\fI[u\(aq  INBOX"\(aq, u\(aq  INBOX.Esborranys"\(aq, u\(aq  INBOX.Spam"\(aq, u\(aq  INBOX.Sent"\(aq,
u\(aq  INBOX.NOSPAM"\(aq, u\(aq  INBOX.Archive"\(aq, u\(aq  INBOX.Drafts"\(aq,
u\(aq  INBOX.Trash"\(aq, u\(aq  INBOX.Paperera"\(aq]\fP
.UNINDENT
.UNINDENT
.SS Scan your account for spam
.sp
In future uses you can scan for spam with:
.INDENT 0.0
.INDENT 3.5
\fBisbg\ \-\-imaphost\  mail.foo.com\ \-\-imapuser rogerb@mail.foo.com\fP
.UNINDENT
.UNINDENT
.sp
After some time, it will return the stats:
.INDENT 0.0
.INDENT 3.5
0 spams found in 0 messages
.sp
0/0 was automatically deleted
.UNINDENT
.UNINDENT
.SH OVERVIEW
.sp
The amount of time it takes will be proportional to the size of your
inbox and the amount of mails specified with \fB\-\-partialrun\fP\&. You can specify
\fB\-\-verbose\fP if you want to see the gory details of what is going on.
.sp
You can now examine your spam folder and will see what spam was
detected. You can change the SpamAssassin threshold in your
\fIuser_prefs\fP file it created earlier.
.sp
isbg remembers which messages it has already seen, so that it doesn\(aqt
process them again every time it is run. If you are testing and do want
it to run again, then remove the trackfile (default
\fI$HOME/.cache/isbg/track*\fP).
.sp
If you specified \fB\-\-savepw\fP then isbg will remember your password the
next time you run against the same server with the same username. You
should not specify \fB\-\-savepw\fP in future runs unless you want to change
the saved password.
.sp
You\(aqll probably want something to actually be done with the original
spams in your inbox. By default nothing happens to them, but you have
two options available. If you specify \fB\-\-flag\fP then spams will be
flagged.
.sp
You can get the messages marked for deletion by specifying \fB\-\-delete\fP\&.
If you never want to see them in your inbox, also specify the
\fB\-\-expunge\fP option after \fB\-\-delete\fP and they will be removed when
isbg logs out of the IMAP server.
.SS SpamAssassin
.sp
If you have never used SpamAssassin before, you\(aqll probably be quite
nervous about it being too good and taking out legitimate email, or not
taking out enough spam. It has an easily adustable threshold to change
how aggressive it is. Run the following command to create your
preferences file (\fI$HOME/.spamassassin/user_prefs\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ spamassassin </dev/null >/dev/null
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Your Folder Names
.sp
Each IMAP implementation names their folders differently, and most IMAP clients
manage to hide most of this from you. If your IMAP server is \fICourier\fP, then
your folders are all below INBOX, and use dots to separate the components.
.sp
The \fIUWash\fP server typically has the folders below Mail and uses slash (\fI/\fP) to
separate components.
.sp
If you don\(aqt know how your IMAP folders are implemented, you can always use the
\fB\-\-imaplist\fP option to find out.
.SH SEE ALSO
.sp
\fIspamassassin(1)\fP,
\fIMail::SpamAssassin::Conf(3)\fP\&.
.sp
The full documentation for isbg is maintained in \fI\%https://isbg.gitlab.io/isbg\fP
.SH EXIT CODES
.INDENT 0.0
.TP
.B \fI0\fP
All went well.
.TP
.B \fI10\fP
There were errors in the command line arguments.
.TP
.B \fI11\fP
The IMAP server reported an error or error with the IMAP connection.
.TP
.B \fI12\fP
There was an error of communication between \fIspamc\fP or \fISpamAssassin\fP\&.
.TP
.B \fI20\fP
The program was not launched in an interactive terminal.
.TP
.B \fI30\fP
Error with the \fIlock\fP file, is another instance of \fBisbg\fP must be
running.
.TP
.B \fI\-1\fP
Other errors.
.UNINDENT
.sp
With \fB\-\-exitcodes\fP there are also:
.INDENT 0.0
.TP
.B \fI1\fP
There was at least one new message, and none of them were spam.
.TP
.B \fI2\fP
There was at least one new message, and all them were spam.
.TP
.B \fI3\fP
There were new messages, with at least one spam and one non\-spam.
.UNINDENT
.SH BUGS
.sp
You can report bugs on \fI\%https://gitlab.com/isbg/isbg/issues\fP
.SH AUTHOR
See the CONTRIBUTORS file in the git repository for more
information on who wrote and maintains this software
.SH COPYRIGHT
License GPLv3: GNU GPL version 3 https://gnu.org/licenses/gpl.html

This is free software: you are free to change and redistribute it. There is
NO WARRANTY, to the extent permitted by law.
.\" Generated by docutils manpage writer.
.