README

NAME
    SquidGuard Manager - Web GUI for SquidGuard and SquidClamav
    administration

DESCRIPTION
    SquidGuard Manager is a Perl CGI Web GUI for squidGuard and SquidClamav
    administration. It allows full management of SquidGuard blocklist and
    ACLs. You can also manage graphicaly your SquidClamav configuration.

    This program supports all configuration directives of SquidGuard and
    SquidClamav without intrusive modification, i-e you can still edit the
    configuration files by hand before and after using SquidGuard Manager.

FEATURES
  SquidGuard Manager GUI interfaces
    Globals
        This interface allows you to define SquidGuard global variables.

    Schedules
        This interface allows you to define schedules time in order to use
        in other SquidGuard objects (Sources, URL Rewrites, Filters and
        ACLs).

    Sources
        Use this interface to define sources like users, groups, Ip
        addresses, range of Ip addresses or networks to apply policies on.
        These can be issued from a list, a file, an ldap query, a mysql
        query or a command line utility.

    Url rewriting
        This interface allows you to define URL rewriting groups, each
        consists of one or more Sed style substitution rules. They can be
        applied to source groups in ACLs menu.

    Filters
        Destination Groups filter selector in other words. In this interface
        you can shape each group by selecting a list for domain, url or
        regexp filter from those you defined in Manage Lists interface.

    ACLs
        This is the central place where you define what source objects
        follow what filters and when. Here everything fits together.

    View Configuration
        This interface allows you to see the SquidGuard configuration file.

    Manage Lists
        This interface allows you to build blocklists for each destination
        group. You can edit a whole list or add/remove individual entries.

    View logs
        This menu allows you to consult all log files in the log directory
        you'd defined in the SquidGuard global configuration.

    SquidClamav
        This link leads you to the GUI interface to administer SquidClamav
        configuration file. This interface is enabled only if you have
        SquidClamav installed on your system.

    Restart Squid
        This link allows you to 'reconfigure' or quick-restart Squid to make
        it recognize the changes you made to SquidGuard and/or SquidClamav
        configuration.

  SquidClamav Manager GUI interfaces
    Since release 1.4 SquidClamav Manager is able to manage both SquidClamav
    v5.x and v6.x branch.

    Globals
        This interface allows you to manage SquidClamav global variables.

    Virus Scanning
        This interface allows you to exclude URL or Content-Type from virus
        scan by defining regexp patterns.

    Whitelists
        Use this interface to define which domain name or site hostname to
        be whitelisted, i-e there happens no virus scan nor call to
        SquidGuard on these sites.

    Trusted Users
        Use this interface to define which users (RFC-931 usernames) will be
        excluded from virus scan and SquidGuard blocklists.

    Trusted Clients
        Use this interface to define which client hostnames or ip addresses
        will be excluded from virus scan and SquidGuard blocklists.

    View Configuration
        This interface allows you to see the SquidClamav configuration file.

    View log
        This interface allows you to consult the SquidClamav log file.

    In resume SquidGuard Manager is capable of every configuration task on
    SquidGuard and SquidClamav which otherwise you have to perform by
    opening terminal, editing files, becoming root and running commands
    manually. Modifications are written immediately to the configuration
    files.

REQUIREMENT
    SquidGuard Manager may run on any Unix like OS with any modern Perl
    installation using the perl CGI module. It must be run on a proxy server
    hosting squidGuard.

    You need to run this CGI script using Apache HTTP server. And the httpd
    daemon must be run as uid and gid holding SquidGuard (most of the time
    this is Squid cache effective user/group). This allows SquidGuard
    Manager to read and write the configuration files to manage blocklists
    and acls. If you use SquidClamav, it must be run under the same user
    too.

    SquidGuard Manager uses some system commands to manage blocklists and
    log files. Your system must have the following binaries installed: diff,
    grep, find, rm and tail.

INSTALLATION
    To install SquidGuard Manager you must be able to gain root privilege so
    that installer script can put files with appropriate permission.

  Prepare your system
    SquidGuard Manager needs to have read/write access onto SquidGuard
    configuration file and the dbhome directory. It must also have read
    rights onto the log file. If you use the SquidClamav Manager GUI it also
    requires read/write access to the squidclamav.conf file as well as the
    log file.

    For that reason SquidGuard Manager must be run as the user under which
    SquidGuard and SquidClamav are run. Most of the time this is the Squid
    cache effective user.

            chown -R squid:squid /usr/local/squidGuard
    or
            chown -R squid:squid /etc/squidguard.conf /var/lib/squidguard

    To allow httpd to run squidguardmgr.cgi as appropriate user/group you
    must edit your httpd.conf file and set the User and Group directives to
    the user and group running Squid.

    After configuration changes squid ought to be 'reconfigure'd, in other
    words quick-restarted. SquidGuard Manager Web GUI does it by using a
    'setuid root'ed wrapper. If your system doesn't support the feature
    unfortunately, you may need to do that by hand.

    IMPORTANT: SquidGuard Manager doesn't support symbolic links in the
    SquidGuard dbhome directory. If it is your case, you need to remove
    those symbolic links and modify your squidguard.conf file so that refers
    to the real files and directories.

  Automatic installation
    Execute the install script and answer to some questions it asks:

            $ perl Makefile.PL
            $ make
            $ su
            # make install

    By default it will install all files into /var/www/squidguardmgr/ and
    show you a configuration sample that should be included in your
    httpd.conf. Also, you can find some Apache configuration samples in
    contrib/ directory of the SquidGuard Manager source repository. Once you
    have done, restart httpd server and take a look at
    http://my.proxy.dom/squidguardmgr/ or
    http://my.proxy.dom:port/squidguardmgr/

    You can fully customize this installation by passing the following
    variables to Makefile.PL:

            SQUIDGUARD => Absolute path to the SquidGuard executable. Set to
                         'off' to disable its support
            CONFFILE => Absolute path to the SquidGuard configuration file
            DBHOME => Absolute path to the SquidGuard DB directory
            LOGDIR => Absolute path to the SquidGuard log directory
            WWWDIR => Absolute path to the SquidGuard Manager base installation
                      directory
            CGIDIR => Relative path from WWWDIR to install CGI script.
                      Default equals WWWDIR
            HTMLDIR => Relative path from WWWDIR to install css, js and
                       image files. Default equals WWWDIR
            LANGDIR => Translation language to use (en_US or fr_FR).
                       Default: en_US
            BASEURL => Path part of the base url to access SquidGuard
                       Manager Web GUI. Default: /squidguardmgr
            SQUIDUSR => User running Squid
            SQUIDGRP => Group running Squid
            SQUIDCLAMAV => Absolute path to the squidclamav binary (v5.x only).
                           Set to 'off' if you won't manage neither v5 nor V6.x
            CICAP_SOCKET => c-icap server control socket (v6.x only)
            SQUIDCLAMAVCONF => Absolute path to squidclamav.conf file

    For packaging there's two more configuration variables:

            DESTDIR => Directory prefix where install will be done
            QUIET => Specify with value '1' to suppress post install messages

    Example:

            perl Makefile.PL \
            CONFFILE=/usr/local/etc/squidguard.conf \
            DBHOME=/usr/local/squidguard/db \
            LOGDIR=/usr/local/logs/squidguard \
            WWWDIR=/usr/local/apache \
            CGIDIR=cgi-bin/admin HTMLDIR=htdocs/admin \
            LANGDIR=fr_FR BASEURL=/admin \
            SQUIDUSR=squid SQUIDGRP=squid \
            SQUIDCLAMAV=/usr/local/bin/squidclamav \
            SQUIDCLAMAVCONF=/etc/squidclamav.conf \
            QUIET=1

            make
            su
            make install

    This will install SquidGuard Manager CGI squidguardmgr.cgi,
    squidguardmgr.conf, squid_wrapper and all language files under
    /usr/local/apache/cgi-bin/admin/. All SquidGuard Manager css, js and
    image files will be copied under the directory
    /usr/local/apache/htdocs/admin/. Squidguard Manager will expect to find
    the SquidGuard configuration file at /usr/local/etc/squidguard.conf and
    the log and SquidGuard databases respectively at
    /usr/local/logs/squidguard and /usr/local/squidguard/db. All the
    installed files will be owned by user squid and group squid. The squid
    wrapper (used to reconfigure squid after change) will be setuid root
    unconditionally.

  Manual installation
    Copy all files from the cgi-bin repository into the CGI script directory
    of your choice. Check that squidguardmgr.cgi can be executable by your
    Apache server and chown the entire directory to the user and group
    running httpd.

    Copy all files from the htdocs repository into your DocumentRoot
    directory or any other subdirectory and check that they can be read by
    your httpd server.

    Edit the squidguardmgr.conf file in your cgi directory and check that
    all paths conforms to your installation.

    If you want to be able to reload Squid redirector from the GUI interface
    after your SquidGuard and/or SquidClamav modification, you must compile
    and install the squid_wrapper with suid root into the squidguardmgr cgi
    directory.

    Before compilation you may need to edit squid_wrapper.c and change the
    SQUID_BINARY definition to point correctly to your squid binary.

    Then as root:

            cd squid_wrapper/
            cc -o /path/squidguardmgr/cgi/squid_wrapper squid_wrapper.c
            chown root.root /path/squidguardmgr/cgi/squid_wrapper
            chmod 755 /path/squidguardmgr/cgi/squid_wrapper
            chmod u+s /path/squidguardmgr/cgi/squid_wrapper

CONFIGURATION
    SquidGuard Manager needs some configuration. They are stored in the
    squidguardmgr.conf file. During the automatic installation this file
    will be generated automatically.

    SQUIDGUARD /usr/local/squidGuard/bin/squidGuard
        This directive allows you to configure the path to the SquidGuard
        program. If you set it to off or no, the SquidGuard Manager
        interface will be disabled and it will only show the SquidClamav
        Manager interface.

    CONF_FILE /usr/local/squidGuard/squidguard.conf
        Configure the path to the SquidGuard configuration file.

    SQUIDCLAMAV /usr/bin/squidclamav | c-icap
        Path to the SquidClamav program when using SquidClamav v5.x branch
        and must be set to 'c-icap' when you're using v6.x branch.

    C_ICAP_SOCKET /var/run/c-icap/c-icap.ctl
        Path to the c-icap control socket. Used by SquidClamav Manager to
        reconfigure the c-icap server to apply SquidClamav configuration
        changes. Used only with SquidClamav 6.x branch.

    SC_CONF_FILE /etc/squidclamav.conf
        Path to the SquidClamav configuration file.

    LANG en_US
        Used to set the language, default is en_US. Current available LANGs
        are: en_US, fr_FR.

    SQUID_WRAPPER /var/www/squidguargmgr/squid_wrapper
        Command wrapper to reload Squid. Why you need this wrapper is
        because only root can do it. This wrapper will execute the following
        system command as root user:

                /path/to/squid/bin/squid -k reconfigure

    IMG_DIR /squidguargmgr/images
        Path part of SquidGuard Manager URL where images are found.

    CSS_FILE /squidguargmgr/squidguardmgr.css
        SquidGuard Manager URL to point to the Style Sheet(CSS) file.

    JS_FILE /squidguargmgr/squidguardmgr.js
        SquidGuard Manager URL which points to Javascript(js) file.

    LOG_LINES 1000
        Number of last lines out of log files to display.

    DNSBL your.preferred.blacklist.com,other.preferred.blacklist.com
        Comma separated list of DNS Blacklists. If you have SquidGuard 1.5
        or above put here the DNSBLs you want to use.

    TAIL, FIND, DIFF, RM, GREP
        These optional configuration directives are used to override the
        default path to the system commands /usr/bin/tail, /usr/bin/find,
        /usr/bin/diff, /usr/bin/rm and /usr/bin/grep.

    KEEP_DIFF
        This enables record of added/removed items from squidGuard
        blacklists in diff files which can be used to recover changes after
        a fresh download of blacklists. Default value is 1, enabled. Set it
        to 0 to disable this feature.

AUTHORS
    Gilles Darold <gilles @nospam@ darold.net>

    Tatsuya Nonogaki <winfield @nospam@ support.email.ne.jp>

COPYRIGHT
    Copyright (c) 2010-2013 Gilles Darold - All rights reserved.

            This program is free software: you can redistribute it and/or modify
            it under the terms of the GNU General Public License as published by
            the Free Software Foundation, either version 3 of the License, or
            any later version.

            This program is distributed in the hope that it will be useful,
            but WITHOUT ANY WARRANTY; without even the implied warranty of
            MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
            GNU General Public License for more details.

            You should have received a copy of the GNU General Public License
            along with this program.  If not, see < http://www.gnu.org/licenses/ >.

BUGS
    Your volunteer to help construct a better software by submitting bug
    report or feature request as well as code contribution are welcome.