Welcome to squclac v0.1.6

  this is squid redirector for traffic scanning with clam antivirus.
  It is written in pure c, so it is fast and ready for clusetrs!

  package requirments:

    clamav-80 *
    curl-7.12.2 *
    runing squid proxy server
    some web server to catch redirects

    * both of them are used as libraries



  CONFIGURATION
  =============

  by default squclac looks for config file /etc/squclac.conf, you can use other:

      squclac -c /dir/config.conf



  contents of configuration file is something like this:


      log "/usr/local/squid/var/logs/squclac.log";
      stat 1h;

      src trusted {
          ident "admin";
          ident "root";
      }

      dst whitelist {
          domain "kernel.org";
          domain "
      }

      dst blacklist {
          domain "virus.org";
      }

      clamscan {
        pass whitelist;
        block blacklist;
        pass trusted;

        minsize 100kb;
        maxsize 2mb;
        timeout 1m;

        timout action redirect;

        useragent firefox;
        redirect "http://server/information.php?url=%u&virus=%v";
      };


  any numerical parameter in configuration file can have postfix, valid
  postfixes are:

    kb  - kilobytes(1024 bytes)
    mb  - magabytes(1024 kilobytres)
    m   - minutes(60 seconds)
    h   - hours(60 minutes)



  global configuratin directives:
  -------------------------------

  log
    where redirector will log its messages, this file need to be writable by
    squid user(usualy it is nobody).

  stat
    time in secounds, how often redirector will log statistics about its work
    and checks for clam virus database update. First statistics is loged after
    one minute.

  stat string
    what information will be logged in stats time. formating variables can be
    used:

      %c - clean items
      %i - infected items
      %p - items processed per stat time
      %m - maximum block scnaned(kb)
      %a - average size scaned(kb)
      %t - total amount of data scaned(kb)

    for example: "STAT: infected:%i";



  randomsleep
    when squid starts multiple squclac instances at once, your host can get
    high load. Possibly some of isntances will not be started at all, it
    depends on host performance and redirect_children count. If your redirector
    processes can't handle the load, consider changing the pattern or seting
    randomsleep values if you want more redirector processes.

    this will add random delay on redirector startup and clam initialisation,
    so the load will be more scattered in time.

    example:
      randomsleep 950 50;

    maximum and minimum times in miliseconds.

    this is experimental but important feature and possibly random sleep will
    be called not only from one place, maybe two or four times, and if your
    randomsleep is about 1000, you can get 4s sleep.

    randomsleep values hardly depends on your server hardware and link load. so
    I run into problems, sendig pkill -HUP squclac because all redirectors get
    busy, and link load is high, squid reloads all of them.

    be carefull!!! if you set randomsleep to high, squid will kill all
    redirectors, because they do not respond. If you are not sure do not set
    randmomsleep at all.

    for me it works so: 300 10, but may not work for you!



  define
    debub_mode enables more verbose loging, normaly not used.



  src and dst section:
  --------------------

  after src or dst folows freely choosen name of defined item, later you can
  use this name. src or dst section body can contain folowing keywords:

  ip
    add ip adress to src or dst defination, can be aplied to src and dst. this
    is not implemented now.

  ident
    add ident to src defination, and it is valid only in src

  domain
    valid only in dst and adds domain to dst defination

  urlregex
    valid in dst, adds regular expresion for urls



  for example:

      src trusted {
        ident "root";
        ident "domain\user";
      }

      dst whitelisted {
        domain "kernel.org";
        domain "linux.org";
      }


    so theoreticaly you can define large lists, there are no software
    limitations to sizes. keep in mind: every single instance of redirector
    will keep full copy of definations in memory, therefore it is not good idea,
    to define large lists.




  clamav section:
  ---------------

  maxsize
    all biger that this size will not be scaned.

  minsize      
    minimum size for download, only after this size timeout timer starts to
    count(default 200000).


  timeout      
    maximum time in secounds for each request after size is downloaded. if file
    can not be fetched in this time download is stoped and file is passed or
    blocked, sou you can define it.


  timeout action
    specify default action what to do when timeout is meet. it can be to pass
    or to redirect timed out files.


  timeout exeption
    here folows src or dst defination. to listed defination will be aplied
    reverse timeout acction. if you define timeout action as redirect, then
    everything in timeout exeption will be passed.


  useragent
    it is a client agent for scaner downloads, so you can fake it or use any
    predefined agent string: firefox or msie:

      useragent firefox;

    or use your own:

      useragent "clamscan/0.80";


  redirect      
    redirection url if viruss is found or url can be passed to client. in url
    formating variables can be used.

      %u - represents url
      %v - virus name
      %i - client ident
      %h - client dns host name
      %a - client ip
      %r - reason: 1 - timeout, 2 - blocked, 3 - virus


  proxy      
    set difrent proxy server, default is 127.0.0.1:8080, so it is in loopback
    mode, normaly you do not need to change this value! only ip adress and port
    is valid parameter.

  pattern      
    set up regullar expression matching pattern, only matched urls will be
    scanned. if pattern is not defined, everything is scaned. fo example:

      pattern "^http:.+\.(exe|com|zip)$";


  pass or block
    folows src or dst defination, so you can define waht pages will no be scaned
    and passed without scan or blocked without scan.

    example:

      pass whitelist;