CheckAuthLog Reference documentation: Difference between revisions

From voipsupport
Jump to navigation Jump to search
No edit summary
 
(11 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 7: Line 18:
The following entry will run CheckAuthLog every 5 minutes
The following entry will run CheckAuthLog every 5 minutes


*/5 * * * *    root /path/to/check_auth_log
<pre>*/5 * * * *    root /path/to/check_auth_log</pre>


If you provide the configuration file in the standard location /etc/check_auth_log.conf there is no need to run with any parameters, for example
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==
==Command Line Parameter Reference==


This is a list of all parameters accepted:
===-a username===
-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
Manually adds the user to the blocked users
-d username: 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.
===-c config_file===
-t activates tracing to standard output. Useful for debugging.
 
-v prints the version and terminates
Uses the named configuration file instead of checking in /etc/check_auth_log.conf
-x extract the authenication 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.
===-d username===
-z runs the self check routines only
 
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