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 allow full management of SquidGuard blocklist and
    ACLs. You can also manage graphicaly your SquidClamav configuration.

    This program support all configurations 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 allow you to define SquidGuard globals variables.

    Schedules
        This interface allow you to define schedules time to be used in
        other SquidGuard object (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
        them. These can be issued from a list, a file, an ldap query, a
        mysql query or a command line utility.

    Url rewriting
        This interface allow you to define as many as URL rewriting rules
        that you want . They will be applied by SquidGuard following regex
        pattern matching.

    Filters
        This interface allow you to defined URL destination groups based on
        predefined lists of domain, url or regexp expressions.

    ACLs
        This is the central place where you defined your access rules to
        apply to the different source object following the defined filter
        destination

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

    Manage Lists
        This interface allow you to manage all lists by editing them fully
        or adding, removing and searching entries.

    Logs
        This interface allow you to consult all log files you have defined
        in the SquidGuard object configuration.

    SquidClamav
        Links you to a GUI interface to administer SquidClamav configuration
        file. This interface is enable only if you have SquidClamav
        installed on the system.

    Restart Squid
        This link allow you to 'reconfigure' Squid when changes to
        SquidGuard and/or SquidClamav redirectors configuration files are
        done.

  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 allow you to manage SquidClamav globals variables.

    Virus Scanning
        This interface allow you to desactivate virus scan based on regex
        pattern on URL or Content-Type.

    Whitelists
        Use this interface to define which domain name or site hostname to
        whitelist, i-e there will be 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 allow you to see the SquidClamav configuration file.

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

    In resume you can do all you're doing by hand in dedicated HTML
    interfaces, modification are written immediatly to 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 run be run as uid and gid holding SquidGuard (most of the
    time this is squid cache effective user/group). This is to allow
    SquidGuard Manager to read and write into the configuration files to
    manage blocklists and acls. If you use SquidClamav, it must also be run
    under the same user.

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

INSTALLATION
    To install SquidGuard Manager you must be root as you need to set
    specials grants on the filesystem.

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

    For that 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.

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

    To allow httpd to run squidguardmgr.cgi as a different user or group you
    must edit your httpd.conf file and change the User/Group directive to
    the user and group running Squid.

    To be able to reconfigure squid after configuration change from the web
    GUI SquidGuard Manager use a setuid wrapper as root user. So you system
    may support this feature or will need to do that by hand.

    IMPORTANT: SquidGuard Manager do not support symbolic link into the
    SquidGuard dbhome directory. You need to remove these symbolic links
    from your system and modify your squidguard.conf file to replace them by
    the directories real names.

  Automatic installation
    Execute the install script and answer to the questions as follow:

            perl Makefile.PL
            make && make install

    By default it will install all files into /var/www/squidguardmgr/ and
    give you a configuration sample to include in your httpd.conf. After
    that restart your httpd server and take a look at
    http://my.proxy.dom/squidguardmgr/

    You can fully customize this installation by using the following
    variables:

            CONFFILE => Where is the SquidGuard configuration file
            DBHOME => Where is the SquidGuard DB directory
            LOGDIR => Where is the SquidGuard log directory
            WWWDIR => SquidGuard Manager base directory installation
            CGIDIR => Where to install CGI: WWWDIR/CGIDIR. Default: WWWDIR
            HTMLDIR =>  Where to install css,js and images files: WWWDIR/HTMLDIR. Default: WWWDIR
            LANGDIR => Translation directory to use (en_US or fr_FR). Default: en_US
            BASEURL => Base url where css,js and images files will be found. Default: /squidguardmgr
            SQUIDUSR => User running Squid
            SQUIDGRP => Group running Squid
            SQUIDCLAMAV => Path to squidclamav binary (v5.x only)
            CICAP_SOCKET => c-icap server control socket (v6.x only)
            SQUIDCLAMAVCONF => Path to squidclamav.conf file

    For packaging there's two more configuration variables:

            DESTDIR => Directory prefix wher install will be done
            QUIET => Do not display the post install message

    Example:

            perl Makefile.PL CONFFILE=/usr/local/etc/squidguard.conf \
            DBHOME=/usr/local/squidguard/database \
            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

            make && 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
    images 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/database. All
    installed files will be owned by the squid user and squid group. The
    squid wrapper (use to reconfigure squid after change) will be setuid as
    root user.

  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 into you cgi directory and check that
    all path are conform 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
    repository:

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

    Before that you must edit squid_wrapper.c and change the path to squid
    binary.

CONFIGURATION
    SquidGuard Manager need some configuration informations. They are stored
    into the squidguardmgr.conf file. During the automatic installation this
    file is self generated.

    SQUIDGUARD /usr/local/squidGuard/bin/squidGuard
        This directive allow 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 translation are:
        en_US, fr_FR.

    SQUID_WRAPPER /var/www/squidguargmgr/squid_wrapper
        Command wrapper to reload Squid. You must use this wrapper as squid
        can only be reload as root. This wrapper will execute the following
        system command as root user: /usr/local/squid/sbin/squid -k
        reconfigure

    IMG_DIR /squidguargmgr/images
        SquidGuard Manager base URL where images are stored.

    CSS_FILE /squidguargmgr/squidguardmgr.css
        SquidGuard Manager Style Sheet CSS URL.

    JS_FILE /squidguargmgr/squidguardmgr.js
        SquidGuard Manager Javascript URL.

    LOG_LINES 1000
        Number of last lines displayed from log files.

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

    TAIL, FIND, DIFF, RM, GREP
        These optionals configuration directives are used to overide 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
        Allow keeping added/removed items from squidGuard blocklists as diff
        files to be able to recover changes after a fresh download of
        blocklists. Default value is 1, enabled. To disable this feature set
        it to 0.

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

COPYRIGHT
    Copyright (c) 2010-2011 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 volontee to help construct a better software by submitting bug
    report or feature request as well as code contribution are welcome.

