| NOTES: |
1.) if you are installing over a previous installation of JSpamFilter on Microsoft Windows, please run the UninstallService.bat file first. This will be located in your
existing JSpamFilter directory.
Uninstall directions are available by clicking here. Platform-specific configuration notes
are available here.
|
| 2.) Click here for installation notes for *nix-like operating systems (e.g., Linux, OS X, BSD). It should also be
noted that the configuration choices covered below correspond to the entries of the JSpamFilter.conf file and apply to all platforms*.
*The installation of the JavaService does not apply to *nix installations.
|
| We are developing additional installation and configuration notes, to be released soon. |
| Pre-installation Review and Notes: |
 |
| The description that follows covers the specific steps installing JSpamFilter with the graphical installation assistant.
The choices for a the non-graphical installation are the same, though you don't have to follow any particular order.
|
|
| Keep handy the path to your JRE executable (i.e., the "server" jvm.dll) that you noted in the Pre-Installation step (e.g., C:\j2sdk1.4.2_04\jre\bin\server\jvm.dll). Note this because during the installation process you will need to confirm the location of the JRE and the installer may not "guess" the right location.
|
|
|
If you use the non-graphical installation, note that JSpamFilter is distributed as a Java Archive (.jar)
file, and accepts one command-line parameter, which should be the full path to
its configuration file. If no file is specified on the command line, the "current"
directory will be checked for a file called "JSpamFilter.conf".
|
|
NOTE: DURING THE INSTALLATION PROCESS, YOUR MAIL SERVER MUST NOT BE
RUNNING ON THE SAME IP ADDRESS AND PORT THAT JSPAMFILTER IS TO LISTEN ON!
IF YOU HAVE QUESTIONS, SEE THE NOTES AT THE BOTTOM OF THE PREVIOUS SECTION.
|
|
| JSpamFilter is going to be "inserted" into the mail flow and if your mail server is running, JSpamFilter will not be able to bind to port 25 during the installation process. |
|
- JSpamFilter now has a graphical Installation Assistant for any windowing system that supports Java. The Installation Assistant speeds the installation process by ensuring that all configuration parameters are valid (e.g., verifies that a mail server is running at the talk IP and port specified, etc.).
You will need to be able to supply the following pieces of information during the installation:
IP address JSpamFilter is to listen on
IP address the Mail Server is listening on
Port Number JSpamFilter listens on (default is 25)
Port Number the Mail Server listens on (default is 26)
Please note that the talk and listen IP addresses, port numbers, or both must be different.
|
|
To complete tne installation, you will need either a permanent, non-expiring JSpamFilter license or a current, non-expired
Trial License to run JSpamFilter. Trial Licenses are fully-featured, time-limited licenses, you can request a free, no-obligation
Trial License by filling out the request form here.
|
 |
|
Step Zero: [Click here to go back to the top of the page.]
Start the graphical installer by double-clicking on the JSpamFilter_Windows.exe to begin the installation process.
The pre-installation archive decompressor will ask you to confirm the installation location.
The default location is:
c:\jspamfilter
Either accept this location by clicking yes or select a different location (note that you will need to remember where you installed JSpamFilter).
If you are installing JSpamFilter "manually", create a configuration file named "JSpamFilter.conf". See the "Configuration
Options" and "Sample Configuration" sections of this manual for
more information.
|
|
|
Step One: [Click here to go back to the top of the page.]
After the greeting page, the Installation Assistant will begin the installation process by prompting you for the IP address
on which you want JSpamFilter to listen (this will be the IP addresses from which mail could be received).
1. What is the IP address you want JSpamFilter to listen on?
The current value is: all
 |
The JSpamFilter Configurator will give you the option of either verifying the current choice or accepting the default.
If you are not sure, use the verify function to check that the default selection (or whatever you have chosen) works.
|
The default value for the "listening" IP address is:
all
And you should leave this choice as it is.
This means that you will be listening for messages sent from any address on the Internet. If you choose to block certain
addresses or blocks of addresses, you should do so explicitly later using the block parameter, discussed in detail in Seciont
Block=(IP address or block)
 |
Additionally, while JSpamFilter can be installed on any machine in the mail flow, it
needs to be the "first link in the chain" in that it needs to be able to "see" the incoming mail as it arrives in
order to use the various DNSBL and SURBL lookup functions. That is, for JSpamFilter to determine whether a sending
server is on a DNSBL or SURBL list, JSpamFilter has to be able to "see" the IP address from which incomiing mail is
being sent.
|
|
|
|
Step Two: [Click here to go back to the top of the page.]
2. What is the TCP Port number you want JSpamFilter to listen on?
The current value is: 25 (Simply press your key to accept the current value.)
The default value is:
25
and you should leave this value as port 25 is the standard port on which SMTP mail is sent. The mail servers
sending you mail will be sending the mail on port 25, so you should leave this value so that JSpamFilter is
listening for incoming connections.
|
If your mail server is still listening on this port, you will receive the following error message: |
* I am unable to bind to that IP address and port number.
* This is usually because the mail server is still listening
* on that port, and only one process is allowed to.
* Please verify that the mail server is NOT listening on that port.
* (Response from socket bind was:
* java.net.BindException: Address already in use: JVM_Bind)
|
 |
THIS WILL HAPPEN IF YOUR MAIL SERVER IS RUNNING ON
THE PORT TO WHICH JSPAMFILTER IS TRYING TO BIND. |
|
|
|
Step Three: [Click here to go back to the top of the page.]
3. what is the IP address you want JSpamFilter to "talk" to?
The current value is: all (Simply press your <enter> key to accept the current value.)
The default value is:
all
This represents the IP address which the mail server is listening to. You can leave this value at all, but you may want to
change it to the specific IP address of your mail server (e.g., an internal address). See the notes in the next step.
|
|
|
Step Four: [Click here to go back to the top of the page.]
4. What is the TCP Port number you want JSpamFilter to Talk on?
The current value is: 26
The default value is:
26
Possible error:
I am unable to connect to a mail server at the IP and port entered.
This is usually because there isn't a server there!
You can also try to connect to the mail server using the telnet command:
telnet localhost 26
Please verify that the mail server is listening on that port.
(Response from socket connect was:
java.net.ConnectException: Connection refused: connect)
Change the mail server to listen on port 26, if you'll be running JSpamFilter
on the same machine as the mail server. Notes on changing the "listen"
port on various mail servers can be found here.
|
You may have to go back and change the "Talk" IP address of your mail server from "all" to the specific IP address of your mail server.
(Note: the IP address of the mail server is the IP address that JSpamFilter "talks" to).
|
Where XXX.XXX.XXX.XXX is the IP address of your mail server.
|
|
|
Step Five: [Click here to go back to the top of the page.]
5.) Please paste your one- or two-line license key into the blank below.
If you license key includes an expiration, you must paste both lines.
Paste your JSpamFilter License Key into the space provided (note: window may resize after you have pasted the information;
this is harmless, just resize back and continue).
|
|
|
Step Six: [Click here to go back to the top of the page.]
6.) What is the full host name of your mail server?
Substitute your mail server's fully qualified host name (e.g., machinename.domain.com) for the provided value.
|
|
|
Step Seven: [Click here to go back to the top of the page.]
7.) What domains are local to your mail server?
Enter at least one domain served by, that is local to, your mail server (e.g., the primary domain name).
Step Seven, Cont'd: [Click here to go back to the top of the page.]
What is the full path to your filter file?
Make sure that the stated default path is correct or change it to the path to your filter file (e.g., this was
the directory in which JSpamFilter was installed).
Step Seven, Cont'd:
Confirmation of correct path to filter file
Step Seven, Cont'd:
Congratualations!
You have successfully completed the basic configuration!
Now, we install the network service and we're done!
Step seven, Cont'd:
The JSpamFilter Configurator asks if you would like to JSpamFilter as a service.
You should answer "yes".
|
|
|
Step Eight: [Click here to go back to the top of the page.]
What is the path to your jvm.dll?
Click "Verify" to determine if this is the correct fully-qualified path to the server jvm.dll.
Step Eight, Cont'd:
If you see this error, it means that the JRE is not where the Configurator thinks it should be.
|
If you recieve this error message, compare the given value of the full path to the server JRE (i.e., the "server" version of
jvm.dll) to the path you noted in the pre-installation checklist in the previous section Part 3 (Pre-Installation Checklist).
|
|
JSpamFilter uses environment variables to "guess" where your JRE is located.
Sometimes the JVM doesn't report this location correctly.
|
We've noticed that the environment variable will report that the path is:
C:\Program Files\Java\jre1.5.0_02\jre\bin\server\
When it is actually:
C:\Program Files\Java\jdk1.5.0_02\jre\bin\server\
Step Eight, Cont'd:
Substitute the correct path to the JRE
|
NOTE: When you download the installer from Sun Microsystems, make sure you download the Java "Software Development Kit"
SDK (formerly called "JDK" or "Java Development Kit") and not just the JRE as the JRE does not include the server version of jvm.dll.
|
|
|
|
Step Nine: [Click here to go back to the top of the page.]
The Configurator confirms that it found JSpamFilter.jar
|
|
|
Step Ten:
The Configurator confirms that it found JSpamFilter.conf
|
|
|
Step Eleven:
The Configurator confirms that it found JavaService.exe
|
|
|
Step Twelve:
JavaService is being installed
|
|
|
Step Thirteen:
Woo-hoo! We're Done!
|
|
|
Step Fourteen:
Thank you for using JSpamFilter! We do appreciate it!
|
|
|
Addendum:
Step Fifteen:
Configure your system to start JSpamFilter when the server starts.
Instructions for this are platform-specific:
See Section 13: Platform Specific Installation Instructions.
|
|
|
The JSpamFilter configuration file overrides the default settings that the server starts with.
|
The jspamfilter.conf file is now dynamically reloaded. However, changes to the talk or listen port or IP address still require a restart.
|
Comments can be added to the file by beginning comment lines
with "//" or ";".
// (comment)
;(comment)
(Comments are not allowed at the end of
configurations lines.) See the next section of this manual for examples of configuration
files. JSpamFilter supports the following options in the file JSpamFilter.conf:
License=(org name):(key)
Note that Trial License Keys include an expiration date (that must be present for the Trial License Key to work). When replacing a Trial License Key, be sure to remove the "expiration=" line.
 |
 |
 |
NOTE: Please keep track of your JSpamFiter evaluation period! JSpamFilter can be evaluated on a production machine, but be aware that when the
evaluation period is over, all tagged messages will be tagged with the "new" tag:
(JSpamFilter eval expired.)
and JSpamFilter will refuse to restart. Additionally, for this reason, when using an evaluation copy of JSpamFilter, we recommed that if you implement mail
client rules or filters to route tagged to a particular folder or inbox that you use the full "[JSpamFilter]" tag (i.e., with square brackets) and not just the name "JSpamFilter" as the test string.
|
|
|
 |
|
LogDir=(dir)
The directory you want JSpamFilter to create log files in. The files will be
named "jspamfilteryyyymmdd.log", based on the current date.
This will override LogFile, if specified. New files will be created as midnight
is passed.
|
|
NOTE: you must specify a valid directory name for the logging directory or an error will occur! |
LogFile=(path)
The name of the file you want JSpamFilter to log to. The file will be appended
to (not overwritten) when JSpamFilter restarts, and may quickly grow very large.
Instead, the LogDir option is recommended. If neither LogDir nor LogFile are
specified, JSpamFilter will log to the console.
LogLevel=("actions"|"verbose"|"debug")
The amount of data you want to log; the default is "Verbose". "Actions"
will only log actions taken by JSpamFilter; "Verbose" will log all
messages, and "Debug" logs all SMTP commands.
If you want the log file to show the filter entries hit, add the following line to your jspamfilter.conf file:
logFilterHits=on
|
Depending on the log-level used and the amount of email traffic, JSpamFilter logs can grow rapidly. For many businesses, daily log files
will likely be under a megabyte per day but, however, we recommend that you watch the log files after first implementing JSpamFilter to get an idea of how quickly they will grow in your system. Establish
a regular maintenance schedule to keep track of logs, in particular if disk space is a consideration.
|
JSpamFilter now gives you the option of a "dead letter mailbox" that lets you direct messages blocked after filtering to a specific mailbox. To use this feature, add the following line to your jspamfilter.conf file:
deadLetterBox=[full@email.addr]
To prevent abuse of Inter-Exchange connections based on the proprietary Microsoft XEXCH50 protocol from bypassing JSpamFilter, you can add the following line to your jspamfilter.conf:
disableProtocol=XEXCH50
BufferSize=(number)
Optional, default 10000. This controls how many bytes of each message are
scanned for filter keywords. Increasing this value will increase the CPU utilization
of JSpamFilter, but will also defeat spammer tricks such as putting 7k of whitespace
at the top of HTML e-mails.
The first 10k of the message is scanned for these keyphrases, and the sum of scores (for each different keyphrase found) is totaled.
FilterFile=c:\JSpamFilter\filter.txt
The full path to the filter.txt file, which determines the SPAM scoring.
A sample filter.txt is included in the distribution zip file.
|
|
|
| Part 6 ("Talk and Listen" Parameters) |
If you'll be running JSpamFilter on the same machine as the mail server, change the mail server to listen on port 26. Notes on changing the "listen"
port on various mail servers can be found here.
 |
These parameters are arguably the most fundamental parameters controlling JSpamFilter's communications
with the mail server. |
ListenPort=25
The port you want to listen on. The default is 25.
ListenIP=all
The IP address you want to listen on. Options are "all" (listen on
all available IP addresses), or a single IP or hostname to listen on. The default
is "all".
TalkPort=26
The port you want to send validated connections to. The default is 26.
TalkIP=all
The IP address you want to send validated connections to. If "all",
JSpamFilter will connect to the same IP that the inbound connection had connected
to. The default is "all".
|
NOTE: If "all" is specified, or if the ListenIP and TalkIP are identical,
then the ListenPort and TalkPort must be different.
Otherwise JSpamFilter will wind up "talking to itself" in a feedback loop.
|
|
|
|
| Part 7 (Basic Server and Domain Configuration) |
ServerName=mail.example.com
The name of your server (used for "Received:" header.) If not specified,
no "by" clause will be added to the "Received" header added
by JSpamFilter, which may confuse any software that reads Received headers (for
example, the SpamCop reporting engine.)
LocalDomainList=example.com mail.example.com anotherexample.com
If this option is specified, Open Relay protection is enabled. Incoming mail
sent to any domain that is not on the list will be dropped, unless the
IP address is "whitelisted" (see below), or the user successfully authenticates
to the mail server using the SMTP AUTH command. If there are many entries on
this list, more than one LocalDomainList entry can be used in the configuration
file (for the administrator's convenience). Separate multiple entries with spaces.
LocalDomainFile=(filename)
[Version 2.1+] The name of the file you want to read local domains from. Two formats
are accepted: one domain per line, or "BIND" named.boot DNS configuration
file format. (Only "primary" and "secondary" zone records
are read, and "in-addr" domains are ignored.) This option cannot be
used in conjunction with LocalDomainList.
|
|
|
 |
Warning:
If you do not use LocalDomainList or LocalDomainFile, you will probably
turn your mail server into an open relay, which will soon get abused by spammers,
and place you into the same blackhole lists you're checking. Remember,
unless JSpamFilter is running on a separate machine, mail servers think the
connections are coming from one of its own IP addresses, and will usually
relay mail without question from those IPs.
You'll want to use these settings anyway to make sure that only the domains for which you want
to provide mail service can use your server.
|
|
|
|
|
|
| Part 8 (Advanced Server and Domain Configuration) |
LocalDomainFileRefresh=(seconds)
[Version 2.1+] Setting this value will cause JSpamFilter to check the LocalDomainFile
at the interval specified. If the timestamp of the file has changed, JSpamFilter
will reload the domain list from the file.
- RCPT TO limiting (limits the number of recipients for any given message.)
- The FilterTest shows which keyphrases were hit in the tested messages.
- IP-based "greylisting", which allows relaying, but only when the "from" address is in the local domain list.
- Connections that successfully SMTP AUTH can also be treated as greylisted connections (the default is to whitelist anyone who successfully authenticates to the mail server.)
AllowRelay=10.x 192.168.x 172.16.1.1
The IP address "whitelist." IP addresses in this list will explicitly
be allowed to relay mail (overriding the LocalDomainList and the spam filter.)
Additionally, a Received header will not be added to mail accepted from a whitelisted
IP address (to protect internal network address schemes.) Blocks of addresses
can be added using ".x" instead of a number. Separate multiple entries
with spaces.
Block=192.168.99.x
The IP address "blacklist." No mail will be accepted from the IP
addresses (or blocks) listed. This overrides the "AllowRelay" parameter,
and completely shuts out mail from the addresses (or blocks of addresses) listed.
If not specified, the server behaves as if the list were empty. Separate multiple
entries with spaces.
MaxRcptTo=(number)
[Version 3.1+] Optional. Setting this value will cause JSpamFilter to drop connections
if the specified number of recipients is exceeded.
AllowLocalDomainRelay=(IP Address List)
[Version 3.1+] Optional. This IP Address "greylist" will only allow
relay for messages using local domain names (the domain names in the LocalDomainList)
in the From header. If the "From" header does not match a domain name
in the list, the connection will be dropped.
SmtpAuthAllowsRelayFor=(Local|All)
[Version 3.1+] Optional, default is All. Normally, mail clients that use SMTP
Auth are treated as if they were on the "AllowRelay" whitelist; if
you set this value to Local, then clients using SMTP Auth are treated as if they
were on the "AllowLocalDomainRelay" greylist.
DebugIP=(ip.nu.mb.er)
[Version 2.1+] Setting this value will cause JSpamFilter to behave as if all inbound
connections came from the specified address. This can be used (in a non-production
environment!) to test for proper DNSBL operation.
|
|
|
| Part 9 (DNSBL and SURBL Look-Up Configuration) |
Space-delimited list of DNSBLs to use for checking remote IP addresses.
DNSBL=dnsbl.sorbs.net* relays.ordb.org! bl.spamcop.net? sbl.spamhaus.org
If a question mark ("?") is added to the end of the name, the Action
will be set to Tag for mail received from servers on that list. If an exclamation
point ("!") is added to the server name, the Action for that server
is set to Block, and connections from servers on that list will be dropped. If you want to outright refuse connections, use an asterisk ("*" aka "splat") after the DNSBL name.
Separate multiple entries with spaces.
Here's a summary of the modifiers for the DNSBLs:
| Symbol |
Name |
Action |
Description |
Additional Notes |
*
(Splat/asterisk) |
REFUSE |
Refuse connection outright |
Pre-emptive refusal of connection |
Cannot be over-ridden by filter file scores. Can be used with the "tarpit" setting (see below). |
!
(Bang/Exclamation Point) |
BLOCK |
Block Connection |
Dropping of connection: the server drops connections and returns a "550 service not available" error |
Can be over-ridden by filter file scores. |
?
(Question Mark) |
TAG |
Tag |
Successful look-ups result in messages being tagged |
"[JSpamFilter]" tag will be prepended to the subject line of the message. |
| |
Nothing |
Default Action |
See also Section 10 on Actions. |
|
| NOTES: |
- Note: Modest Software is not associated with any particular DNSBL maintainer, and many of them ask for a donation in return for use of their services. Some DNSBL maintainers do require payment before you are able to use their services.
|
- JSpamFilter checks each DNSBL in the list, and stops when it finds the first match.
|
- If you are doing both Blocking and Tagging, you should list any Blocking DNSBLs before any Tagging DNSBLs.
|
- DNSBL look-ups are performed before filtering. Therefore, set a DNSBL to BLOCK or REFUSE only when you are certain.
|
- Allows the list of domains to be read from either a simple flat file (one domain per line), or from a BIND-formatted DNS boot file. A refresh interval can also be set; JSpamFilter will check to see if the file is updated on that interval, and if so, reload it.
|
- The "REFUSE" ("*") setting is stronger than the BLOCK ("!") setting in that values in the filter.txt file cannot over-ride the REFUSE setting. The REFUSE option for DNSBL handling; this setting causes the connections to be pre-empitvely dropped so that messages are not accepted at all.
|
JSpamFilter can cache positive and negative DNSBL responses for 30 minutes to speed look-ups.
The following parameters set the behaviour, add these lines to your jspamfilter.conf file:
DnsCacheTTL sets number of seconds for time to live
DnsCacheTTL=(number in seconds)
DnsCacheSkimmerInterval determines how often (in seconds) the cache is checked for old entries
DnsCacheSkimmerInterval=(number in seconds)
The following switch makes dnsbl-based drops very slow to slow down spammers; note that this only works
with DNSBL entries that use the "splat" (*) value.
tarpit=on
surbl=multi.surbl.org:75
Use a separate line for each SURBL source to be used followed by a colon (":") and the filter score to be associted to the SURBL.
That is, if my.surblone.org and my.surbltwo.org are the SURBLs you'd like to use with filter scores of 50 and 75 respectively, you would add
them to your JSpamFilter.conf file as:
surbl=my.surblone.org:50
surbl=my.surbltwo.org:75
 |
*There are several parameters that determine overall performance and the numbers above represent a typical configuration.
The buffer size and number of SURBL lookups probably have the greatest impact on message capacity, performance and processor load. SURBL lookups
aren't so much a performance load per se, but potentially generate a lot of look-up traffic.
The amount of look-up traffic increases with each SURBL used.
|
|
|
|
| Part 10 (Action Configuration) |
JSpamFilter computes a "score" based on its analysis of an incoming email message. The score is determined
by the lookup settings (see Part 9 (DNSBL and SURBL Look-Up Configuration))
and the entries in the filter file. The score can be thought of as a relative "open-ended" probability: the bigger
score, the more likely the message is spam email.
The Block and Tag thresholds determine the values at which different "actions" occur:
- When setting the Block and Tag thresholds, set the Block threshold higher than the tag threshold.
- If the score exceeds the "block" threshold, the connection is Blocked.
- If the score exceeds the "tag" threshold, the message is Tagged.
DefaultAction
DefaultAction=Tag
If not overridden in the DNSBL entry (see JSpamFilter Manual Part 9
(DNSBL and SURBL Configuration)), this specifies the default
action to use for "hits" on a DNSBL. If set to "block", the
server will drop connections with a "550 service not available" error;
if "tag", a "[JSpamFilter]" tag will be prepended to the
Subject line of any message from a suspicious source. The default is Tag.
FilterTagThreshold
FilterTagThreshold=50
Mandatory when using tagging, even if not using a filter file.
This is the score at which JSpamFilter will tag the e-mail. Note:
If a message is on a "Tag" DNSBL list, the score starts
at this value; this makes it so that messages that are already suspect are
more likely to be blocked.
FilterBlockThreshold
FilterBlockThreshold=100
Optional. The score at which JSpamFilter will block
the e-mail. In JSpamFilter Enterprise, messages on "Block" DNSBLs
start at this score.
|
|
|
| Part 11b (Basic Filter File Parameters) |
The content filtering functions of JSpamFilter are handled through the Filter File and the settings therein which determines the SPAM scoring.. The Filter File is structured for ease
of use and simplicity, efficiency and speed. A relational database look-up feature is in development.
This section and the next will include several examples to illustrate the use of conditional searching using the Filter File.
- The filter is applied in all cases except the DNSBL "REFUSE" ("*") setting, so you can "unblock" messages that are on "Block" DNSBLs through the use of negative scores. Filter settings cannot un-refuse REFUSE ("*") DNSBLs.
- You can search for certain keyphrases if one or more "root" keyphrases are found. This improves accuracy and efficiency, by skipping searches for words that only bode evil when found in context. A bad analogy is to think of it as "progressive slots" on keywords.
- The "d00d-speak" feature of the Anti-Obfuscation filter performs a repeated letter check; the filter collapses repeated letters and rescans the filter.txt file. This picks up filterable terms where the spammer tried to obfuscate the meaning by repeating letters. The next section includes a full description of the anti-obfuscation filters.
- JSpamFilter performs recursive content searches to defeat attempts to obscure MIME content by nesting MIME boundaries.
- JSpamFilter will even decode messages that are "Base64 encoded", which defeats other content filters that rely on the message being sent in plain ASCII text.
- Full support for binary message transfers (BDAT).
- Full Unicode support is provided for messages and filter terms. (Use "FilterFileEncoding=charset" in JSpamFilter.conf to select the character encoding for the filter file).
The basic format for a Filter File entry is:
// [comment]
[score] [word or phrase]
|
JSpamFilter will look for all occurences of a particular string, even inside other strings. If you want to search for a term in isolation and make sure
that you do not pick up any "outer" strings, add leading and trailing spaces. For example, if you wanted to search for the string "reed" and associate to it a score of 50.
If made the following entry to the filter file:
50 reed
You would also score the word "freedom" in that "freedom" contains the string "reed".
To avoid this, add a leading and trailing space to the entry (i.e., a regular space before and after the word reed) as follows:
50 reed
|
Note: you will need to provide the full path to the filter file in your jspamfilter.conf file:
FilterFile=c:\JSpamFilter\filter.txt
The full path to the filter.txt file.
A snippet of the file might look like this:
30 EMAIL ADDRESSES
50 ONE TIME MAILING
30 CALL IMMEDIATELY
20 TO ORDER
10 TOLL FREE
A sample filter.txt is included in the distribution zip file. (PLEASE SEE NOTE ABOVE ON FILTER FILE ORGANIZATION)
|
To test your filter's effectiveness and speed, save the full source of the
e-mails you want to score into files named "*.mail" (as in, "spam01.mail,
spam02.mail, notspam01.mail", etc.), then score all of the messages in
batch by using the command:
java -jar FilterTest.jar *.mail
(Your filter file must be named "filter.txt", and must be in the
current directory.)
If you look at the message headers of inbound mail, you'll notice that JSpamFilter
adds its own X-JSpamFilter-Version header; in 3.0, the score and elapsed time
(in 1/1000 of a second) are also part of that header, like this:
X-JSpamFilter-Version: 3.8 Enterprise (Modest Software) (Score: 50,
32ms)
|
|
If you discuss SPAM filtering with a colleague via e-mail, it's easy to get
caught by your own filters. It is possible to use negative numbers
in your filter.txt to allow those messages to pass the filter, like this:
-300 friend@some-other-mail-server.com
|
Every word or phrase found will increase the score for that message by the [score]
provided. For example:
20 second income
50 guaranteed money maker
30 earn up to
JSpamFilter will search for "second income" at 20 points, "guaranteed money maker" at
50 points [so for me, that phrase reads "guaranteed JSpamFilter tag"], and "earn up to"
at 30 points. So, if you received a message as follows:
Subject: A Second Income From Home!
Make $$$Millions$$$ Selling Anything From Home!
THIS IS A GUARANTEED MONEY MAKER!!!
EARN UP TO $14,243.87 A WEEK!!!
CLICK HERE NOW!!!!!!! |
This message would score 100 points and if, for instance, the Block threshold was set for 100 points,
this message would be blocked from entering the server
|
|
|
| Part 12 (Advanced Filter File Settings) |
|
JSpamFilter will even decode messages that are "Base64 encoded", which defeats
other content filters that rely on the message being sent in plain ASCII text.
Conditional Searches:
JSpamFilter supports conditional keyword searching. There are three different kinds of
keywords in JSpamFilter; "root" keywords, "optional root" keywords indicated by a "|", and "optional"
keywords indicated by a "+". Optional keywords are only checked if the preceding "root" keyword, and/or
one of the "optional root" keywords are found.
The following table summarizes the use of the switches, examples of their use follow:
| Symbol |
Name |
Syntax |
Action |
Notes |
| |
Nothing |
[score] [word or phrase] |
The value "[score]" is added to the message score when "[word or phrase]" is found. |
The basic Filter File entry |
| | |
Pipe |
|[score] [word or phrase] |
Is combined with the immediately preceding term. |
JSpamFilter searches for the term and/or the preceding term. |
| + |
Plus Sign |
+[score] [word or phrase] |
|
|
| - |
Minus Sign |
-[score] [word or phrase] |
The value "[score]" is subtracted from the message score when "[word or phrase]" is found. |
Can be used as a "manual" form of white-listing. Drop-box white-listing is being developed. |
| |
space |
[word or phrase] |
By adding white space around a term (notice the space before and after "[word or phrase]"), only the exact term is scored. |
That is, the term will not be scored if it is found inside other terms. |
Consider this filter file snippet:
20 mortgage companies
|20 mortgage broker
+30 compete for
+30 for your business
In this case, JSpamFilter will always search for "mortgage companies" and "mortgage broker".
If either of those terms are found, then JSpamFilter will also search for the phrases
"compete for", and "for your business". Every search phrase found will score the number
of points indicated. Essentially, this filter file snippet is saying, "If you find 'mortgage companies'
and/or 'mortgage broker', then also search for 'compete for' and 'for your business'."
This technique can also be used to prevent unnecessary searches. If you have several search phrases that
contain the word "email", then you can improve efficiency by only searching for phrases that contain
"email" if the word "email" itself is found. The example filter.txt includes this:
5 email
+20 This email was sent to you because
+30 EMAIL ADDRESSES
+30 MILLION EMAIL
+30 FRESH EMAIL
+30 bulk email
+30 email marketing
+30 mass email
+30 cdrom
+30 cd-rom
+30 sent in compliance
So, 8 searches that include variants of "email" will be skipped if the message does not
contain "email". (i.e., it's not possible for "fresh email" to exist in the
message if "email" doesn't exist in the message.) There are also a few terms that are
often found in spam in conjunction with the word "email".
Filter for Un-necessarily Brief Messages
The following is added to the filter.txt file:
1 <a
+30# href="http:
1 <img
+30# src="http:
5# <!--
This is quite effective on those typical, and typically small, messages that include an excessive number of hyperlink references and lets the JSpamFilter algorithm filter out messages that contain almost no filterable content.
Anti-Obfuscation Filters: d00d-speak and HTML Filters
These filters look for efforts by spammers to "obfuscate" the content of their messages by inserting
irrelevant HTML tags, replacing letters with numbers, and other content-malformation exploits.
The Anti-Obfuscation filter and scoring process has been added that detects and thwarts attempts to intentionally obscure or conceal content. The filter detects keywords that have been intentionally obfuscated, that is, concealed and obscured by the spammer, and applies a multiplier to their score. This uses the following switches:
- Note: all of the "$$" filters should be last in filter.txt; also, the entry for $$html should be first of them.
-
This switch converts a message from HTML and sets a multiplier for keywords found after HTML removal to detect keywords purposefully obscured by irrelevant HTML (the value of "20" is used as an example: it means that a multiplier of 2.0 is used against the base score for keywords that were obfuscated using HTML).
20 $$html
-
Here the value "35" is used for the score applied to HTML messages that contain no text (images only).
35 $$BlankMessage
-
Switch for messages where the subject line has been intentionally obfuscated (an example score of "35" is used).
35 $$SubjectObfuscation
-
A switch that looks for randomized text. This is recommended for English-only mail servers. Here too the value is a multiplier; 20 means: 2.0x base score.
20 $$RandomText
-
A new function that removes punctuation and then searches again for words that were overlooked. Again, the value is a multiplier; 20 means: 2.0x score of words de-obfuscated.
20 $$PunctuationFilter
-
A filter that counters "d00dspeak": this looks for and converts numbers into letters: e.g., "de-obfuscation" = "d3-0bfusc4t10n". Value is a multiplier; 20 means: 2.0x score of words de-obfuscated.
20 $$d00dSpeak
- *Note for clients using the Updater: please copy the following text and paste it into to your filter.txt file (this corresponds to the switches described above). Make sure the commented lines are unbroken:
// All "$$" filters should be last; the entry for $$html should be first of them
// Convert message to HTML and set multiplier
// (20 means: 2.0x base score for keywords that were obfuscated using HTML)
20 $$html
// Score for HTML messages that contain no text (images only)
35 $$BlankMessage
// Score for messages where the subject line has been intentionally obfuscated
35 $$SubjectObfuscation
// Looks for randomized text. Recommend for English-only mail servers.
// Value is a multiplier; 20 means: 2.0x base score
20 $$RandomText
// Removes punctuation then searches again for words that were overlooked.
// Value is a multiplier; 20 means: 2.0x score of words de-obfuscated
20 $$PunctuationFilter
// Converts numbers into letters for "d00dspeak" d3-0bfusc4t10n
// Value is a multiplier; 20 means: 2.0x score of words de-obfuscated
20 $$d00dSpeak
|
|
|
| Part 13 (Advanced Configuration Options I) |
|
Windows NT/2000/2003
There are several pieces of software available that can be used to install
JSpamFilter as a service. We've successfully tested "JavaService" from
http://javaservice.objectweb.org.
Once javaservice.exe was copied to, for instance, C:\JSpamFilter directory, the one-line command
used was (from within the JSpamFilter directory):
(Your browser will probably word-wrap this to several lines; change
the path to the jvm.dll to match your Java installation:)
javaservice -install JSpamFilter "c:\jdk\jre\bin\hotspot\jvm.dll"
-Djava.class.path=c:\JSpamFilter\JSpamFilter.jar -start JSpamFilter
-params c:\JSpamFilter\jspamfilter.conf -out c:\JSpamFilter\stdout.txt
-err c:\JSpamFilter\stderr.txt
The response you receive should be:
The service was successfully installed.
At this point, you should be able to start the service by typing:
net start JSpamFilter
If you have problems, check stdout.txt and stderr.txt for error messages. The class name in the "-start"
parameter is case sensitive; if you get "Java.lang.NoClassDefFoundError:jspamfilter", it means you typed
"-start jspamfilter" instead of "-start JSpamFilter". Run the command "javaservice -uninstall JSpamFilter" and try again.
UNIX-like Systems:
Installation of JSpamFilter amounts to downloading the Full Archive, decompressing the archive to the directory of your choice
and then simply add this command:
java -jar /usr/JSpamFilter/JSpamFilter.jar /usr/JSpamFilter/JSpamFilter.conf
to your RC scripts. (Change the paths as appropriate to reflect the directory into you which you decompressed the archive). You then
establish the settings for JSpamFilter by editing the JSpamFilter.conf file that comes with the archive. While there is no graphical installer yet for non-Windows installation,
the installation instructions for the graphical installer available here do cover the parameters and choices appropriate for installations on all platforms.
Novell Netware / Groupwise:
JSpamFilter requires a JVM version of 1.3 or higher. If required, newer versions of the Novell JVM can be downloaded from
http://download.novell.com/filedist/pages/PublicSearch.jsp.
Load java.nlm, then execute JSpamFilter with a command something like this:
java -jar sys:\jspamfilter\jspamfilter.jar sys:\jspamfilter\jspamfilter.conf
You can set the listening port for the GWIA to 26 by following the instructions here:
http://support.novell.com/cgi-bin/search/searchtid.cgi?/10072891.htm
Uninstalling JSpamFilter
To uninstall JSpamFilter for Microsoft Windows, run the following command from a console:
UninstallService.bat
Note that you have to be "in" the JSpamFilter directory (where the UninstallService.bat file is located). This will unistall the JavaService; then just delete the JSpamFilter directory.
|
|
|
| Part 14 (Advanced Configuration Options II) |
| JSpamFilter Troubleshooting Checklist |
 |
0.) Make sure your license data is correctly entered into your JSpamFilter.conf file, JSpamFilter will refuse to start if the
license key data is incorrectly written:
- If you're using a trial license key, make sure that both the license data and the expiration date lines are present.
- If you've purchased a permanent license key (thank you!), make sure the expiration date from any previous trial version has been removed.
- Make sure you copy the license data in its entiriety.
- Make sure there aren't any leading or trailing spaces on the license key line. Place a cursor on the license key line in your JSpamFilter.conf file,
hit "End" and "Home" to see if there are any spaces and remove any that might be there.
|
|
1.) Are you running a Java virtual machine with a version of at least 1.4?
|
|
2.) Does JSpamFilter show up as "Running" in the Services Control Panel (Windows)
or process list ("ps -aux" should show a Java process under Linux)?
|
| If you start JSpamFilter from the Services Control Panel and receive the following error: |
 |
| Then you should check your JSpamFilter license and see if the expiration date has passed. |
|
3.) If not, Are any error messages logged to the console on startup? (Windows
users should check the "stdout.txt" and "stderr.txt" files)
|
|
4.) Does "netstat -an" show a process listening on both port 25 and 26? If
not, make sure your mail server is listening on 26 and JSpamFilter is on 25.
Verify that jspamfilter.conf reflects this.
|
|
5.) If you telnet to port 25 on the mail server ("telnet [servername] 25"),
do you get a mail server greeting message? If not, check the log, and make
sure the mail server is running on the IP and port that you told JSpamFilter
to find it at.
|
|
6.) Does the logfile indicate that connections are being received? If you are
getting a message about "No response from the mail server" then the mail server
is not running at the IP and port JSpamFilter is expecting.
|
 |
Very little. Most DNS servers will give up in a few seconds. If the DNS lookup fails,
then JSpamFilter assumes the remote server is not listed, so the net effect
is that JSpamFilter pauses for a few seconds, then continues as if the lookup was not
even requested.
|
|
JSpamFilter only reads the first 10000 bytes (i.e., the value of the BufferSize setting) of the message; it's possible that
the keywords appeared after that boundary. It's also possible that certain encoding is
causing JSpamFilter to not "see" a word or phrase. If you find a message mis-scored in this
way, please forward it (as an attachment) to sales@modestsoftware.com.
|
|
FilterTest, providing an accurate simulation of JSpamFilter, only reads the first 5000 bytes
(or so) of the message. It's likely that the missing keyword is after that boundary.
|
|
These errors are caused by one end of the TCP connection unexpectedly terminating
the network connection. This is due to a network problem, such as a modem losing
its connection while in the middle of sending a message, and can be ignored (unless it's
happening all the time, which usually means that JSpamFilter is unable to connect to the
mail server it's proxying for.)
|
|
|
|
|
|
If none of this helps or if your question isn't covered, send a message to JSpamFilter Support by clicking here; please include the following information: |
|
- A description of the problem (please be specific.)
- Your JSpamFilter.conf file
- Any console output (stdout.txt and stderr.txt)
- A logfile that includes a product restart (much useful information is logged
during a restart)
- If applicable, a logfile of the failed message while "loglevel=debug" is set in jspamfiler.conf
|
|
|
|
| Part 15 (Advanced Configuration Options III) |
| Sample Configurations:
The configurations below are meant as general examples and guidelines. If you are not certain as to the approach you want
to take, be sure to either to primarily rely on tagging or use a DeadLetter mailbox for blocked mail to avoid false positives. |
|
|
 |
|
Scenario One: Corporate LAN
In this scenario, all of the corporate users are on an internal (firewalled)
network, with IP addresses in the 10.x.x.x block reserved for use behind firewalls.
The domains that recieve mail are "example.com", "support.example.com",
and "engineering.example.com". Due to problems with abusive mail from
a competitor's mail server at 192.168.5.11, that server's IP address is explicitly
blocked. This company relies on e-mail to conduct business, and only wants to
Tag mail that is probably spam, so that there is no possiblity of mail getting
dropped. JSpamFilter is running on the same Windows 2000 machine as the mail
server, which has been reconfigured to listen on port 26.
logDir=c:\JSpamFilter
license=Example Corp:1234567890a
defaultAction=tag
ListenPort=25
ListenIP=all
TalkPort=26
TalkIP=all
dnsbl=relays.ordb.org bl.spamcop.net
servername=example.com
LocalDomainFile=/etc/named.boot
LocalDomainFileRefresh=60
allowrelay=10.x
blockrelay=192.168.5.11
|
|
|
|
|
Scenario Two: Separate JSpamFilter machine
In this scenario, JSpamFilter is loaded on a Linux-based machine that doubles
as the DNS server, and the Firewall blocks all inbound TCP connection attempts
to the Mail Server. The DNS name "mail.example.com" points to the JSpamFilter
machine's IP address, and the DNS name for the Mail Server is "relay.example.com".
This company wants to Block connections from servers listed in the Open Relay
database "relays.ordb.org", and wants to Tag mail from servers in SpamCop's
DNSBL. Since users are not connecting to the JSpamFilter machine to send mail,
no IP address whitelist is necessary. Since they host the DNS for all of the
domains that they handle mail for, they read the Local Domain list from /etc/named.boot,
and check for updates every minute.
Sample configuration file:
logDir=/var/adm/jspamfilter/
license=Example Corp:1234567890a
defaultAction=tag
ListenPort=25
ListenIP=all
TalkPort=25
TalkIP=relay.example.com
dnsbl=relays.ordb.org! bl.spamcop.net
servername=example.com
localdomainlist=example.com mail.example.com
|
|
|
|
|
Scenario Three: Aggressive Filtering
In this scenario, JSpamFilter is loaded on the same NT machine as the mail
server. The server's admin is fed up with SPAM and has configured her server
to block any mail from servers on any of three different DNSBLs. Additionally,
several blocks of IP addresses owned by ISPs she considers to be SPAM-friendly
are explicitly blocked.
license=Example Corp:1234567890a
defaultAction=block
logDir=/var/adm/jspamfilter/
ListenPort=25
ListenIP=all
TalkPort=26
TalkIP=all
dnsbl=relays.ordb.org bl.spamcop.net sbl.spamhaus.org
servername=example.com
localdomainlist=example.com mail.example.com
blockrelay=172.16.45.x 172.29.110.x 172.29.111.x 172.29.112.x 172.29.113.x
|
|
|
|
|
Scenario Four: Refuse Connections from DNSBL-Listed Servers and Send All Other Suspicious Mail to a Dead Letter Mailbox:
In this scenario, we use a standard netowrk configuration as in the above examples. Here we create a Dead Letter mail box used to collect all mail that is not blocked outright (i.e., the connection refused). We've left out all of the parameters except the ones important for this example.
defaultAction=block
dnsbl=relays.ordb.org* bl.spamcop.net* sbl.spamhaus.org*
FilterTagThreshold=100
FilterBlockThreshold=100
deadLetterBox=example@example.com
We use "100" and "example@example.com" as examples, you would use the threshold value that works for you and the full email address of your Dead Letter mail box.
In this situation, any attempted mail connection coming from the DNSBLs listed will be refused and all mail that scores a value of 100 or higher will be routed to the Dead Letter mail box.
|
|
|
|
|
|
|
