search

darold / squidguardmgr

SquidGuard Manager is a Perl CGI script used to manage SquidGuard blocklists and ACLs. It also have a GUI for SquidClamav. It support all configurations directives of SquidGuard and SquidClamav, configuration files can still be edited by hand.
http://squidguardmgr.darold.net/
Other
12 stars 5 forks source link

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