SOCKS5-STAT.CONF(5)

NAME
socks5-stat.conf - configuration file for socks5-stat

SYNOPSIS
/etc/socks5-stat.conf

DESCRIPTION
The socks5-stat.conf configuration file contains information used by socks5-stat to generate detailed connection summary information. This file can be used to select specific user names, host names, or services for which to give detailed usage summaries. It can be used to provide information for the users, hosts, or services utilizing the highest amount of firewall resources based on number of connections, amount of data transferred, and total connection time. Message reporting for failed connections, failed authentications, and deamon restarts can be tailored in the configuration file as well. An email address or list of email addresses to which to send the summary can be specified in this file.

Each line of the configuration file should be in the format

    keyword argument_list

where keyword is one of the valid keywords and argument_list is a comma and/or whitespace list of valid arguments. Blank lines and comment lines that begin with the `#' character are ignored. Furthermore, comments can be included on any line by preceeding the comment with the `#' character.

KEYWORDS
There are eleven valid keywords that can appear in the configuration file. Each keyword can appear multiple times within the configuration file although the failed, authfail, reversemap, showprogress, and restart keywords would not be useful to appear more than once. Conversely, any of the keywords may be left out of the configuration file. Each keyword must have an argument list following on the line. The argument list can have multiple arguments separated by whitespace and/or commas. The detail, failed, authfail, reversemap, showprogress, and restart keywords may only have a single argument following them.

user arg1[,arg2[,arg3[,...]]]
    Use the user keyword to specify a list of specific users you want to generate usage summaries for. You can also specify to summarize the users with the highest amount of usage based on number of connections, number of bytes transfered, and amount of connection time. The argument list can be any combination of the following:

    username
        A user name by itself will create a summary based on the statistics of all successful connections by username at any network address. Be careful with this general user name style argument since both bill@my.company.com and bill@some.school.edu would match an argument bill, therefore adding the statistics together as one general user bill.

    username@abc.abc.abc.abc
        This type of argument will summarize successful connection information for log entries that exactly match the username at abc.abc.abc.abc. This style of argument is preferred over a simple username alone since it prevents the ambiguous wildcarding.

    t= num
        This will give a summary of the top num users based on number of connections, amount of data transferred, and amount of connection time. num must be a positive integer.

    -   A dash indicates to generate summaries of all unique users found in the log files.

detail arg
    This keyword enables/disables the generation of a detailed user report. The traffic patterns of each user to each destination host is reported. arg must be one of the following:

    all This will enable the report.

    none
        This will disable the report.

source arg1[,arg2[,arg3[,...]]]
    Use the source keyword to specify a list of specific source hosts or domains to generate usage summaries for. You can also select to summarize the source hosts with the highest amount of usage based on number of connections, amount of data transferred, and amount of connection time. The argument list can be any of the following:

    host.domain.name
        All successful connections from a source address that exactly matches host.domain.name will be summarized.

    123.123.123.123
        Like host.domain.name except that it matches unresolved source IP addresses.

    .domain.name
        This style of source argument would summarize successful connections from a source address that matches *.domain.name. This style of argument MUST begin with a period.

    123.123.[123.]
        Like .domain.name except that it matches unresolved source network or subnet numbers. This style of argument MUST end with a period.

    t= num
        This will give a summary of the top num source addresses based on number of connections, amount of data transferred, and amount of connection time. num must be a positive integer.

    -   A dash indicates to generate summaries of all unique source addresses found in the log files.

dest arg1[,arg2[,arg3[,...]]]
    Use the dest keyword to specify a list of specific destination hosts or domains to generate usage summaries for. You can also select to summarize the destination hosts with the highest amount of usage based on number of connections, amount of data transferred, and amount of connection time. The argument list can be any combination of the following:

    host.domain.name
        All successful connections to a destination address that exactly matches host.domain.name will be summarized.

    123.123.123.123
        Like host.domain.name except that it matches unresolved destination IP addresses.

    .domain.name
        This style of destination argument would summarize successful connections to a destination address that matches *.domain.name. This style of argument MUST begin with a period.

    123.123.[123.]
        Like .domain.name except that it matches unresolved destination network or subnet numbers. This style of argument MUST end with a period.

    t= num
        This will give a summary of the top num destination addresses based on number of connections, amount of data transferred, and amount of connection time. num must be a positive integer.

    -   A dash indicates to generate summaries of all unique destination addresses found in the log files.

port arg1[,arg2[,arg3[,...]]]
    Use the port keyword to specify a list of destination ports or services to generate usage summaries for. You can also select to summarize the destination ports or services with the highest amount of usage based on number of connections, amount of data transferred, and amount of connection time. The argument list can be any combination of the following:

    portnumber
        This will summarize all connections to a destination portnumber. Note that socks5-stat does not attempt to resolve a port number to a service name and this type of port argument will only match log entries that appear with that port number (i.e. 25 will not match smtp).

    service
        This will summarize all connection to a destination service. Note that socks5-stat does not attempt to resolve a service name to a port number and this type of port argument will only match log entries that appear with that service name (i.e. smtp will not match 25).

    t= num
        This will give a summary of the top num destination ports and services based on number of connections, amount of data transferred, and amount of connection time. num must be a positive integer.

    -   A dash indicates to generate summaries of all unique destination ports and services.

failed arg
    This keyword tells how much information to report on failed connections. arg must be one of the following:

    all This will report the log message generated when a connection failed along with information about the user name, source and destination addresses, and port or service for each failed connection. This is the default action if the failed keyword does not appear in the configuration file.

    minimum
        This will report only the log message generated when each connection failed.

    none
        No reporting about failed connections will be done.

authfail arg
    This keyword tells how much information to report on failed authentications. Authentication failures are caused by connections to the SOCKS server by non-SOCKS clients, client protocol errors, and when the client cannot provide the proper authentication. arg must be one of the following:

    all Report each client that failed to authenticate and the number of times it failed. The total number of authentcation failures is also reported. This is the default action.

    minimum
        Report only the total number of authentcation failures.

    none
        No report of failed authentications.

reversemap arg
    This keyword tells whether IP addresses and port numbers in the log file should be mapped to hostnames and service names. Reverse mapping can be a very time consuming step. If a mapping does not exist, the script waits for the underlying system call to timeout. arg must be one of the following:

    all This will attempt to map IP addresses to hostnames and ports to service names.

    ip  This will map IP addresses to hostnames.

    service
        This will map port numbers to service names.

    none
        No mapping. This is the default action.

showprogress arg
    This keyword tells whether to report the progress of the script as it executes. Reverse mapping IP addresses & processing the log files can be very time consuming. The status is sent to stderr, so it can redirected seperately from the output. arg must be one of the following:

    all Report all status messages. This is the default action.

    none
        No status reporting.

restart arg
    This keyword tells whether or not messages about the socks5 daemon starting or restarting should be reported. arg must be one of the following:

    none
        No reporting about restarting will be done. This is the default action if the restart keyword does not appear in the configuration file.

    all Show all messages about restarting.

mailout addr1[,addr2[,addr3[,...]]]
    Use the keyword mailout to specify an email address or list of email addresses to send the output of the summary to. If this keyword is not present, the summary is sent to standard output.

EXAMPLES
The following line would generate summaries for the users george@*, and the user carl@my.company.com as well as generating summaries on the top 10 users:

    user   george, carl@my.company.com, t=10

and would be equivalent to the following two lines:

    user   george
    user   carl@my.company.com, t=10

The following line would generate summaries for the source address my.company.com and all source addresses in the domain x.company.com:

    source   my.company.com, .x.company.com

The following line would generate summaries for all destination addresses in the domain bigschool.edu as well as generate summaries for every unique destination address:

    dest   .bigschool.edu, -

The following three lines would print out the top 10 destination ports, produce minimum error reporting, and show all daemon restart messages:

    port     t=10
    failed   minimum
    restart  all

Following is a complete and functional configuration file:

    #
    # Sample /etc/socks5-stat.conf
    #
    user      carl@my.company.com, t=5
    source    .company.com, t=5
    dest      t=10
    port      -
    failed    all                   # default but specify as example
    restart   all
    mailout   bob@company.com       # send the summary via email
    #
    # end of /etc/socks5-stat.conf

SEE ALSO
socks5-stat (1)

NOTES

UDP log information is limited so a UDP is only counted in the summary and does not contribute to the data transfer size or to connection time.

No checking is done to see if arguments are duplicated in the configuration file. So if a specific user name is listed twice, it will show up in the summary twice.

All user names and host names specified in the configuration file are case independent. However, all are converted to lower case for comparison and in the summary.

The reversemap of port numbers assume TCP services.