CheckAuthLog Reference documentation: Difference between revisions
(9 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
==CheckAuthLog Processing Logic== | |||
CheckAuthLog defines a configurable processing window, default 3600 seconds (1 hour). CheckAuthLog allows an administrator to define the maximum number of authentications by a user in that processing window and/or the maximum number of different ip addresses used in the authentications. If those limits are exceeded the predefined blocking action is taken. | |||
The processing window is configured via the "expire" configuration variable. The limit for authentications is configured via the "auth_limit" variable. The limit for different ip addresses is configured via the "ip_limit" variable. To disable the authentication check or the ip limit check, set the value to 0. | |||
The blocking action taken by CheckAuthLog can be: | |||
* update a Postfix access file | |||
* update a MySQL database | |||
* update an Exim acl file | |||
==Running from Crontab== | ==Running from Crontab== | ||
After installing Check Auth Log the best way to run it is to schedule it in crontab, for example: | After installing and configuring Check Auth Log the best way to run it is to schedule it in crontab, for example: | ||
<pre>vi /etc/crontab</pre> | <pre>vi /etc/crontab</pre> | ||
Line 13: | Line 24: | ||
==Command Line Parameter Reference== | ==Command Line Parameter Reference== | ||
===-a username=== | |||
-a username | |||
-c config_file | Manually adds the user to the blocked users | ||
-d username | |||
-e email | ===-c config_file=== | ||
-t | |||
-v | Uses the named configuration file instead of checking in /etc/check_auth_log.conf | ||
-x | |||
-y | ===-d username=== | ||
-z | |||
Manually deletes the block, thereby re-enabling mail sending for the user. | |||
===-e email=== | |||
Sends a test blocking notification email to the specified address. Useful for testing email setup and template without having to trigger a block. | |||
===-t=== | |||
Activates tracing to standard output. Useful for debugging. | |||
===-v=== | |||
Prints the version and terminates | |||
===-x=== | |||
Extracts the authentication entries from internal db. The database contains info on the authentication times and ip addresses. When new entries are added old ones are purged if no longer needed (older than expire time). | |||
===-y=== | |||
Extract the cache file entries from internal cache file db. The cache file contains info on the log lines already parsed and their offset in the mail log file. | |||
===-z=== | |||
Runs the self check routines only | |||
==Configuration File Reference== | ==Configuration File Reference== | ||
<pre> | |||
;mta: | |||
; the mta. Default is postfix, also supported: exim | |||
mta = postfix | |||
;logfile: | |||
; the mail log file to parse, this must already exist and be readable. | |||
logfile = /var/log/maillog | |||
;logfile_rotated: | |||
; the mail log file to parse, this must already exist and be readable. | |||
logfile_rotated = /var/log/maillog-YYYYMMDD | |||
;cachefile: | |||
; a suitable location for storing info about last log file line read. | |||
; This file is created if it does not exist. | |||
cachefile = /tmp/.check_auth_log_cache | |||
;dbfile: | |||
; a suitable location for storing info about sasl authentications | |||
; login name, ip and timestamp are stored. | |||
; This file is created if it does not exist. | |||
dbfile = /tmp/.check_auth_log_db | |||
;dbtype: | |||
; type of database (depends on those supported by your install) | |||
; db4 is recommended. | |||
; This is a database for internal use and should not be confused | |||
; with the databsae used to hold uers (e.g. mysql). Do not set | |||
; this value to mysql. | |||
dbtype = db4 | |||
;expire: | |||
; window time in seconds before sasl authentication records are | |||
; removed | |||
expire = 3600 | |||
;auth_limit: | |||
; how many authentications per sasl username are allowed within | |||
; the expire window | |||
auth_limit = 100 | |||
;ip_limit: | |||
; how many different ips per sasl username are allowed within the | |||
; expire window | |||
ip_limit = 5 | |||
;max_auth_records: | |||
; the maximum number of auth session records to store | |||
; per sasl username | |||
max_auth_records = 200 | |||
;posix: | |||
; whether to include posix functions for checking existing running | |||
; processes. Requires php posix extension. You can skip this | |||
; requirement (and relative checking) by setting to false. In | |||
; this case the stale_lock_time is used to determine how long | |||
; another process should be considered active before removing | |||
; its lock. | |||
;posix = true | |||
; | |||
;stale_lock_time: | |||
; the time to wait before considering another process not active | |||
;stale_lock_time = 300 | |||
;block_type: | |||
; type of blocking method when users exceed predetermined limits | |||
; mysql: run a query defined by query_block. | |||
; access: write username to postfix access file defined by accessfile. | |||
; exim: use a file of blocked accounts | |||
block_type = mysql | |||
;accesfile: | |||
; defines the output file for postfix access map | |||
; This file is created if it does not exist. | |||
accessfile = /etc/postfix/smtp_auth_access.in | |||
;reject_msg: | |||
; the value to use on rhs of postfix access map | |||
reject_msg = REJECT send quota exceeded. Contact support to re-enable | |||
;sql_connect: | |||
; connect string for database in format | |||
; mysql://username:password@hostname:port/database | |||
sql_connect = mysql://username:password@hostname:port/database | |||
;sql_block: | |||
; query to run for blocking user access. %u is substituted with | |||
; the username | |||
sql_block = "update mailbox set active=0 where username='%u'" | |||
;sql_unblock: | |||
; query to run for unblocking user access. %u is substituted | |||
; with the username | |||
; example | |||
sql_unblock = "update mailbox set active=1 where username='%u'" | |||
;exim_block_file | |||
; file used by exim containing blocked email accounts | |||
; | |||
;exim_blcok_file = /tmp/blocklist | |||
; exim_temp_file | |||
; file used when updating the exim blocklist. Modifications are | |||
; done to a temporary file and then it is renamed | |||
; in order to avoid exim using the file while it is still being | |||
; updated. | |||
; | |||
;exim_temp_file = /tmp/blocklist.out | |||
</pre> |
Latest revision as of 17:42, 13 June 2016
CheckAuthLog Processing Logic
CheckAuthLog defines a configurable processing window, default 3600 seconds (1 hour). CheckAuthLog allows an administrator to define the maximum number of authentications by a user in that processing window and/or the maximum number of different ip addresses used in the authentications. If those limits are exceeded the predefined blocking action is taken.
The processing window is configured via the "expire" configuration variable. The limit for authentications is configured via the "auth_limit" variable. The limit for different ip addresses is configured via the "ip_limit" variable. To disable the authentication check or the ip limit check, set the value to 0.
The blocking action taken by CheckAuthLog can be:
- update a Postfix access file
- update a MySQL database
- update an Exim acl file
Running from Crontab
After installing and configuring Check Auth Log the best way to run it is to schedule it in crontab, for example:
vi /etc/crontab
The following entry will run CheckAuthLog every 5 minutes
*/5 * * * * root /path/to/check_auth_log
If you provide the configuration file in the standard location /etc/check_auth_log.conf there is no need to run with any parameters.
Command Line Parameter Reference
-a username
Manually adds the user to the blocked users
-c config_file
Uses the named configuration file instead of checking in /etc/check_auth_log.conf
-d username
Manually deletes the block, thereby re-enabling mail sending for the user.
-e email
Sends a test blocking notification email to the specified address. Useful for testing email setup and template without having to trigger a block.
-t
Activates tracing to standard output. Useful for debugging.
-v
Prints the version and terminates
-x
Extracts the authentication entries from internal db. The database contains info on the authentication times and ip addresses. When new entries are added old ones are purged if no longer needed (older than expire time).
-y
Extract the cache file entries from internal cache file db. The cache file contains info on the log lines already parsed and their offset in the mail log file.
-z
Runs the self check routines only
Configuration File Reference
;mta: ; the mta. Default is postfix, also supported: exim mta = postfix ;logfile: ; the mail log file to parse, this must already exist and be readable. logfile = /var/log/maillog ;logfile_rotated: ; the mail log file to parse, this must already exist and be readable. logfile_rotated = /var/log/maillog-YYYYMMDD ;cachefile: ; a suitable location for storing info about last log file line read. ; This file is created if it does not exist. cachefile = /tmp/.check_auth_log_cache ;dbfile: ; a suitable location for storing info about sasl authentications ; login name, ip and timestamp are stored. ; This file is created if it does not exist. dbfile = /tmp/.check_auth_log_db ;dbtype: ; type of database (depends on those supported by your install) ; db4 is recommended. ; This is a database for internal use and should not be confused ; with the databsae used to hold uers (e.g. mysql). Do not set ; this value to mysql. dbtype = db4 ;expire: ; window time in seconds before sasl authentication records are ; removed expire = 3600 ;auth_limit: ; how many authentications per sasl username are allowed within ; the expire window auth_limit = 100 ;ip_limit: ; how many different ips per sasl username are allowed within the ; expire window ip_limit = 5 ;max_auth_records: ; the maximum number of auth session records to store ; per sasl username max_auth_records = 200 ;posix: ; whether to include posix functions for checking existing running ; processes. Requires php posix extension. You can skip this ; requirement (and relative checking) by setting to false. In ; this case the stale_lock_time is used to determine how long ; another process should be considered active before removing ; its lock. ;posix = true ; ;stale_lock_time: ; the time to wait before considering another process not active ;stale_lock_time = 300 ;block_type: ; type of blocking method when users exceed predetermined limits ; mysql: run a query defined by query_block. ; access: write username to postfix access file defined by accessfile. ; exim: use a file of blocked accounts block_type = mysql ;accesfile: ; defines the output file for postfix access map ; This file is created if it does not exist. accessfile = /etc/postfix/smtp_auth_access.in ;reject_msg: ; the value to use on rhs of postfix access map reject_msg = REJECT send quota exceeded. Contact support to re-enable ;sql_connect: ; connect string for database in format ; mysql://username:password@hostname:port/database sql_connect = mysql://username:password@hostname:port/database ;sql_block: ; query to run for blocking user access. %u is substituted with ; the username sql_block = "update mailbox set active=0 where username='%u'" ;sql_unblock: ; query to run for unblocking user access. %u is substituted ; with the username ; example sql_unblock = "update mailbox set active=1 where username='%u'" ;exim_block_file ; file used by exim containing blocked email accounts ; ;exim_blcok_file = /tmp/blocklist ; exim_temp_file ; file used when updating the exim blocklist. Modifications are ; done to a temporary file and then it is renamed ; in order to avoid exim using the file while it is still being ; updated. ; ;exim_temp_file = /tmp/blocklist.out