RETSINA(1)

NAME
retsina - the perfect acompanyment to squid

SYNOPSIS
retsina [options]

DESCRIPTION
retsina is a powerful squid proxy redirector. It allows or denies access to URLs based upon rules created for IP address groups within specified timeslots.

During normal use, retsina will be started by squid with no parameters supplied. An appropriate entry in the squid.conf file could look as follows:
    redirect_program /path/to/retsina
Most of the parameters that retsina does support, however, are designed for administration purposes and most relate to the database itself.

OPTIONS

-c  Process the main configuration file and display the results on screen.

-d <constraint name>
    Delete all the domains listed against <constraint name> in the database. This can be done prior to using the -u option to prevent duplication.

-h  Syntax help.

-p <url>
    Demonstrate which domain name / IP address will be searched for in the database by the pattern matching if the valid <url> was used.

-s  Build the database schema by creating the necessary table. This should be the first thing done prior to using retsina as other options will not work otherwise. Any existing tables of the same names will be deleted first. This options does NOT create the database itself, instead it uses the database details provided in the main configuration file.

-t <squid input>
    Test the setup using a sample <squid input> line, returning the result as would be provided to squid.

-u <constraint name> -f <filename> [-r <redirect url>]
    Update the database list of entries for <constraint name> from <filename>. The file should contain one domain name per line. An optional <redirect url> may be supplied that will be used as the url to redirect the user to should the domain be blocked.

-v  Show version and supported databases.

CONFIGURATION
retsina supports a powerful configuration file. It is made up of various sections. A well commented sample will have been installed by the distribution under /usr/local/share/retsina/retsina.conf

Settings Section

The generic section entitled "settings" houses options that affect the way retsina interacts with the database as well as options that are independant of rules and constraints. It appears with the following syntax:

    settings {
        [settings options]
    }

"settings options" may be one or more of the following:

blockurl <url>
    The default url used to block an IP if one is not found in the database.

db_type <mysql|pgsql>
    Only databases supported during compilation may be selected (a list of supported databases can be listed using the -v option).

dbport <port number>
    The TCP/IP port to connect to the database server on.

dbname <database name>
    The name of the database schema to connect to.

dbuname <username>
    The username to use when connecting to the database.

dbpass <password>
    The password to use when connecting to the database.

Times Section

The times section defines all the timeslots that rules can be made applicable to. Its syntax is as follows:

    times {
        [timeslots]
    }

One or more "timeslots" are defined in the following way:

<timeslot name> <start time> - <end time>
    <timeslot name> is a single word to define the timeslot, for example "lunch". <start time> and <end time> define the start and end times for the timeslot respectively and are defined in 24hour format.

Groups Section

The groups section defines lists of IP addresses that form a commonality within the use environment, for example, there could be a group of IP addresses that are the "sales team" and another group of IP addresses that form the "finance team". Each group is defined in the following way:

    group <group name> {
        [IP addresses]
    }

<group name> is a single word to define the group, for example "sales". "IP addresses" are one or more IP addresses listed one per line.

Rules Section

The rules section defines which constraints a group can or cannot visit within a timeslot. Each rule is defined as follows:

    rules <group name> in <timeslot name> {
         [constraint names]
    }

<group name> is the name of the group (as defined in the "group section") to which this rule is applicable. <timeslot name> is the name of the timeslot (as defined in the "timeslot section") which defines when this rule is applicable.

"constraint names" are a list of the constraint names (as created in the database). For example, if a list of domains is uploaded into the database with a constraint name of "fun" then the word "fun" can be placed in the list to allow groups to visit that list of domains within the timeslot. To deny access to a list of domains within the timeslot, a '!' can be prepended to the constraint name, for example "!fun".

Default Section

The default section is always applicable. It is a list of constraint names that apply to all groups and all rules, and will be used for any IP addresses not found in a group. As it also forms part of the constraint inheritance (see below) it can be used as a blanket cover, ideal for blocking constraints such as adult based domains. It is defined as follows:

    Default {
        [constraint names]
    }

"constraint names" are defined in exactly the same was as for rules.

Other important notes

Constraint inheritance is a pivotal feature of retsina. It allows the configuration file to remain small, clean and easy to read while underlying logical principles are employed. If, for example, a timeslot for a full workday is defined as "workday" and starts at 09:00 and ends at 17:00 and another timeslot is defined as "lunchtime" and begins at 12:00 and ends at 13:00, and a group is created called "staff", then any constraint names within the "workday" rule for "staff" will also be applicable within the "lunchtime" rule for "staff" should one be created. These can be overridden within the "lunchtime" rule by redefining the constraint name as required. This inheritance only occurs to inner starting timeslots for the same group.

There is a magical constraint name that can be used in any rule or the default section. If used in a rule, it will negate the use of the default section for obvious reasons. It, too, is inherited. The constraint is " all " and if used as an "allow" will allow any site not resolved by constraints listed in the rule within which the magical constraint is used, or any rules that inherit it. If used as a "deny" it will block any site not resolved by constraints listed in the rule within which the magical constraint is used, or any rules that inherit it.

It is customary to use the magical constraint name only in the "default section" as a blanket cover for all users - by either making domains that are not resolved with constraint names in applicable rules, or the "default section", allowed or blocked.

FILES
/usr/local/etc/retsina/retsina.conf
    The main configuration file location.

/var/retsina/retsina.log
    The log file. It will only be used if the directory exists and retsina has sufficient permissions to write to it.

EXAMPLES
To upload a list of known domains under the constraint "ads" from the file "domain_ads", with a redirect to a blank gif on a LAN webserver for the entries:

    retsina -u ads -f domain_ads -r 'http://10.0.0.1/transp.gif'

AUTHOR
Phil Pereira <phil at bsdnexus dot com>

SEE ALSO
squid(1),

BUGS
To date there are no known bugs.

SECURITY
Retsina's command line options allow full control of the database. In order to ensure database security a readonly username and password should be set in the main configuration file when no further changes to the database are required.