INSTALL

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.

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
    See README file.

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

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

COPYRIGHT
    Copyright (c) 2010-2015 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.