modules/spam/INSTALL.txt

The spam module is a powerful collection of tools designed to help website
administrators to automatically deal with spam.  Spam is any content that is
posted to a website that is unrelated to the subject at hand, usually in the
form of advertising and links back to the spammer's own website.  This module
can automatically detect spam, instantly unpublish it, and send notification
to the site administrator.  For more information, refer to README.txt.
------------
Requirements:
------------

- Drupal 4.5.x or 4.6.x


------------
Installation:
------------

1) The first thing to do is to update your database, adding the tables
   used by the spam module.  This can easily be done from the command line
   by copying the included 'spam.mysql' file to your webserver, then
   running a command something like:
      $ mysql -u<username> -p<password> <database> < spam.mysql

   For example, if your username is 'drupal', your password is 'secret', and
   your database is called 'drupal', you'd type the following command:
      $ mysql -udrupal -psecret drupal < spam.mysql

2) Move 'spam.module' into your modules/ directory, (or into a modules/spam
   subdirectory) and be sure your web server has read permissions to this file.
   (It should match the ownership and permissions of the other files in this 
   directory)

3) Now you need to log in to your site and enable the spam.module.
    (Goto :: administer -> modules :: then check 'spam')


-------------
Configuration:
-------------

4) Optionally reconfigure the spam module.  The default configuration will
   protect you from many common spammer techniques.
    (Goto :: administer -> settings -> spam)
  - In the "Filter" section, check the boxes next to the types of content that
    you want the spam filter to examine.  If only trusted users can post some
    type of content, there is no reason to filter that content.  If anonymous
    users are allowed to post certain types of content (such as comments), it
    would be wise to filter that content.
  - In the "Limits" section, select appropriate values in the drop down boxes.
    The first to boxes will catch a large percentage of spam, as spammers tend
    to include an abnormally high number of URLs in their content.  It can
    also be effective to catch duplicate content when it is posted.  Finally,
    blacklisting is helpful in that it will minimize the affect of repeat
    offenders.
  - In the "Actions" section, check the boxes next to the desired actions.
    Automatically unpublishing spam is wise, as it will prevent probable
    spam from showing up on your web pages.  You will be able to manually
    review content determined to be spam, giving you a chance to publish
    anything that was wrongly filtered.  The notify user action is a useful
    way to prevent user confusion, as should content be filtered the user will
    see a message explaining what has happened.  Email notification is a
    good way to let the site administrator know that there is spam in the
    queue to be reviewed.  The final option is a drop down menu, allowing you
    to automatically delete spam content after a specified amount of time.  
    This is a useful way to prevent your databases from getting clogged with
    spam content.
  - In the "Advanced" section you should not need to make any changes, unless
    you are trying to better understand how the spam filter works.
  - Now click "Save configuration".

5) Setup spam module permissions.
    (Goto :: administer -> access control -> permissions)
  - Assign the "report spam" permission to users that should be able to report
    content that they think is spam.  It is recommended that you do not give
    this ability to anonymous guests otherwise spambots could easily flood you
    with false reports.
  - Assign the "access spam" permission to users that should be able to see
    whether content is considered to be spam or not.
  - Assign the "administer spam" permission to users that should be able to
    manually mark content as spam or not spam.
  - Assign the "bypass filter" permission to trusted users who's content does
    not need to be run through the filter because you are certain it will
    never be spam.

6) Defining custom filters.
    (Goto :: administer -> spam -> custom filters)
   - In the 'custom filter' text area, enter a string.  You can enter a
     word, a phrase, a regular expression.  For example, if a large number
     of spam contents on your site contain the word 'Viagra', you can use
     it as your custom filter.
   - If the string you entered was formatted as a regular expression, you
     need to check the "Regular expression" box to let the spam module know
     it should treat your filter as a regular expression.  (If your regular
     expression is formatted incorrectly, you will get an error message when
     you try to save it)
   - You need to tell the filter what it should do if the filter
     matches.  Choices are 'always spam', 'usually spam', 'usually not spam',
     and 'never spam'.  The first option, 'always spam', allows you to
     blacklist matching words, phrases and regular expressions.  The last
     option, 'never spam', allows you to whitelist matching words, phrases
     and regular expressions.  The middle two options allow you to greylist
     matching words, phrases or regular expressions.  When only one greylist
     filter matches, the final choice of making new content spam or not spam
     is left up to the Bayesian filter.
   - If you normally receive email notification when content is marked as
     spam, but you tend to be flooded with spam matching this filter, it can
     be helpful to check "Disable email notification" to prevent the spam
     module from sending you a notification email.  It is better to use this
     option and then to "auto expire" spam than it is to check the next
     option.
   - If you are 100% confident that your custom filter only matches spam,
     and never accidently matches non-spam, you can check the "automatically
     delete spam" box.  If checked, any content that matches this filter and
     is ultimately determined to be spam will be automatically, irrevocably and
     silently deleted.  Be warned that it consumes a lot of resources to
     delete spam content, and that if you are under a flood of spam postings
     this can lead to a DoS.  Instead, it is suggested that you instead check
     the earlier "Disable email notification" box and configure your spam
     module to automatically delete spam after a certain amount of time.
   - After defining custom filters, it is a good idea to regularly visit this
     page and review how effective your custom filters are.  Simple statistics
     are provided to show you how often your filters matched new content, and
     when was the last time each of them matched.
   - Whitelisting words, phrases and regular expressions can be a bad idea.
     If a spammer discovers items from your whitelist, they will be able to
     consistently get spam through your filter.
   - Spam is constantly evolving, thus you will probably find that you are
     constantly having to update your spam filter.

7) Defining URL filters.
    (Goto :: administer -> spam -> URL filters)
   - If enabled, URL filters are automatically learned by the Bayesian
     filter.  Domains listed here are considered "spammer domains", and
     any new comment or other content will containing references (ie links)
     to these domains will be marked as spam.
   - Domain names that were erroneously learned by the Bayesian filter
     as spammer domain can be manually deleted here.
   - Known spammer domains can also be manually entered.

1	The spam module is a powerful collection of tools designed to help website
2	administrators to automatically deal with spam. Spam is any content that is
3	posted to a website that is unrelated to the subject at hand, usually in the
4	form of advertising and links back to the spammer's own website. This module
5	can automatically detect spam, instantly unpublish it, and send notification
6	to the site administrator. For more information, refer to README.txt.
7	------------
8	Requirements:
9	------------
10
11	- Drupal 4.5.x or 4.6.x
12
13
14	------------
15	Installation:
16	------------
17
18	1) The first thing to do is to update your database, adding the tables
19	used by the spam module. This can easily be done from the command line
20	by copying the included 'spam.mysql' file to your webserver, then
21	running a command something like:
22	$ mysql -u<username> -p<password> <database> < spam.mysql
23
24	For example, if your username is 'drupal', your password is 'secret', and
25	your database is called 'drupal', you'd type the following command:
26	$ mysql -udrupal -psecret drupal < spam.mysql
27
28	2) Move 'spam.module' into your modules/ directory, (or into a modules/spam
29	subdirectory) and be sure your web server has read permissions to this file.
30	(It should match the ownership and permissions of the other files in this
31	directory)
32
33	3) Now you need to log in to your site and enable the spam.module.
34	(Goto :: administer -> modules :: then check 'spam')
35
36
37	-------------
38	Configuration:
39	-------------
40
41	4) Optionally reconfigure the spam module. The default configuration will
42	protect you from many common spammer techniques.
43	(Goto :: administer -> settings -> spam)
44	- In the "Filter" section, check the boxes next to the types of content that
45	you want the spam filter to examine. If only trusted users can post some
46	type of content, there is no reason to filter that content. If anonymous
47	users are allowed to post certain types of content (such as comments), it
48	would be wise to filter that content.
49	- In the "Limits" section, select appropriate values in the drop down boxes.
50	The first to boxes will catch a large percentage of spam, as spammers tend
51	to include an abnormally high number of URLs in their content. It can
52	also be effective to catch duplicate content when it is posted. Finally,
53	blacklisting is helpful in that it will minimize the affect of repeat
54	offenders.
55	- In the "Actions" section, check the boxes next to the desired actions.
56	Automatically unpublishing spam is wise, as it will prevent probable
57	spam from showing up on your web pages. You will be able to manually
58	review content determined to be spam, giving you a chance to publish
59	anything that was wrongly filtered. The notify user action is a useful
60	way to prevent user confusion, as should content be filtered the user will
61	see a message explaining what has happened. Email notification is a
62	good way to let the site administrator know that there is spam in the
63	queue to be reviewed. The final option is a drop down menu, allowing you
64	to automatically delete spam content after a specified amount of time.
65	This is a useful way to prevent your databases from getting clogged with
66	spam content.
67	- In the "Advanced" section you should not need to make any changes, unless
68	you are trying to better understand how the spam filter works.
69	- Now click "Save configuration".
70
71	5) Setup spam module permissions.
72	(Goto :: administer -> access control -> permissions)
73	- Assign the "report spam" permission to users that should be able to report
74	content that they think is spam. It is recommended that you do not give
75	this ability to anonymous guests otherwise spambots could easily flood you
76	with false reports.
77	- Assign the "access spam" permission to users that should be able to see
78	whether content is considered to be spam or not.
79	- Assign the "administer spam" permission to users that should be able to
80	manually mark content as spam or not spam.
81	- Assign the "bypass filter" permission to trusted users who's content does
82	not need to be run through the filter because you are certain it will
83	never be spam.
84
85	6) Defining custom filters.
86	(Goto :: administer -> spam -> custom filters)
87	- In the 'custom filter' text area, enter a string. You can enter a
88	word, a phrase, a regular expression. For example, if a large number
89	of spam contents on your site contain the word 'Viagra', you can use
90	it as your custom filter.
91	- If the string you entered was formatted as a regular expression, you
92	need to check the "Regular expression" box to let the spam module know
93	it should treat your filter as a regular expression. (If your regular
94	expression is formatted incorrectly, you will get an error message when
95	you try to save it)
96	- You need to tell the filter what it should do if the filter
97	matches. Choices are 'always spam', 'usually spam', 'usually not spam',
98	and 'never spam'. The first option, 'always spam', allows you to
99	blacklist matching words, phrases and regular expressions. The last
100	option, 'never spam', allows you to whitelist matching words, phrases
101	and regular expressions. The middle two options allow you to greylist
102	matching words, phrases or regular expressions. When only one greylist
103	filter matches, the final choice of making new content spam or not spam
104	is left up to the Bayesian filter.
105	- If you normally receive email notification when content is marked as
106	spam, but you tend to be flooded with spam matching this filter, it can
107	be helpful to check "Disable email notification" to prevent the spam
108	module from sending you a notification email. It is better to use this
109	option and then to "auto expire" spam than it is to check the next
110	option.
111	- If you are 100% confident that your custom filter only matches spam,
112	and never accidently matches non-spam, you can check the "automatically
113	delete spam" box. If checked, any content that matches this filter and
114	is ultimately determined to be spam will be automatically, irrevocably and
115	silently deleted. Be warned that it consumes a lot of resources to
116	delete spam content, and that if you are under a flood of spam postings
117	this can lead to a DoS. Instead, it is suggested that you instead check
118	the earlier "Disable email notification" box and configure your spam
119	module to automatically delete spam after a certain amount of time.
120	- After defining custom filters, it is a good idea to regularly visit this
121	page and review how effective your custom filters are. Simple statistics
122	are provided to show you how often your filters matched new content, and
123	when was the last time each of them matched.
124	- Whitelisting words, phrases and regular expressions can be a bad idea.
125	If a spammer discovers items from your whitelist, they will be able to
126	consistently get spam through your filter.
127	- Spam is constantly evolving, thus you will probably find that you are
128	constantly having to update your spam filter.
129
130	7) Defining URL filters.
131	(Goto :: administer -> spam -> URL filters)
132	- If enabled, URL filters are automatically learned by the Bayesian
133	filter. Domains listed here are considered "spammer domains", and
134	any new comment or other content will containing references (ie links)
135	to these domains will be marked as spam.
136	- Domain names that were erroneously learned by the Bayesian filter
137	as spammer domain can be manually deleted here.
138	- Known spammer domains can also be manually entered.
139