1. Hooman Valibeigi
  2. churl

Wiki

Clone wiki

churl / Home

Summary

churl is a redirector helper for the squid caching proxy.

Requirements

  • JRE 7

Usage

> java -Xmx16m -jar churl.jar config.xml

Command line arguments

  • -b, --benchmark -- Prints statistics to stderr. Use it to measure how fast it can handle a large list of URLs.
  • -v, --verbose -- Prints debugging information to stderr. Use it to test your configuration.

Configuration

Churl uses XML style configuration. Here's an example:

<configuration>
    <concurrency threads="1" request-buffer-size="100" />
    <redirect status="301" url="http://mycompany.com/blocked.html">
        <any>
            <all>
                <protocol equals="http" />
                <none>
                    <port equals="80" />
                    <port equals="8080" />
                </none>
            </all>
            <host contains="game">
                <except>
                    <any>
                        <user equals="me" />
                        <client-fqdn equals="mypc.mycompany.com" />
                    </any>
                </except>
            </host>
            <path regex="/ads?/" />
            <path regex="/banners?/" />
        </any>
    </redirect>
</configuration>

Configuration Directives

<churl>

Attributes: none

Children:

  • <concurrency> (occurs 0..1)
  • <redirect> (occurs 1+)

<redirect>

Specifies a redirect rule. There can be 1 or more redirect rules per configuration.

Attributes:

  • status -- The status code for the http response
  • url -- The url to redirect to

Children:

  • MATCH_DIRECTIVE (occurs 1+)

<concurrency>

Attributes:

  • threads -- Number of worker threads. Default value is 1.
  • request-buffer-size -- Size of the request buffer. Default value is 1.
    • if 1: concurrency is off and the first element of every request line is expected to be a URL. url_rewrite_concurrency option in squid.conf must be set to 0.
    • if greater than 1: concurrency is on and the first element of every request line is expected to be a channel-id. url_rewrite_concurrency option in squid.conf must be set accordingly.

Children: none

MATCH_DIRECTIVE

Composite MATCH_DIRECTIVE

  • <all> -- Matches when all child match directives match
  • <any> -- Matches when any child match directives match
  • <none> -- Matches when none of the child match directives match

Attributes: none

Children:

  • MATCH_DIRECTIVE (occurs 1+)

Pattern MATCH_DIRECTIVE

  • <url> -- Matches if the entire URL matches the specified pattern
  • <protocol> -- Matches if the URL's protocol matches the specified pattern
  • <host> -- Matches if the URL's host matches the specified pattern
  • <port> -- Matches if the URL's port matches the specified pattern
  • <path> -- Matches if the URL's path matches the specified pattern
  • <query> -- Matches if the URL's query matches the specified pattern
  • <user> -- Matches if the username matches the specified pattern
  • <client-ip> -- Matches if the client's IP address matches the specified pattern
  • <client-fqdn> -- Matches if the client's FQDN matches the specified pattern
  • <method> -- Matches if the HTTP request method matches the specified pattern

Attributes:

  • MATCHER="pattern"

MATCHER =

  • equals -- String equals matcher
  • contains -- String contains matcher
  • regex -- Regular expression matcher
  • regexi -- Case-insensitive regular expression matcher

Children:

  • <except> (occurs 0..1)

<except>

Adds exceptions to a MATCH_DIRECTIVE. This will cancel a match if the exceptions's MATCH_DIRECTIVE matches.

Attributes: none

Children:

  • MATCH_DIRECTIVE (occurs 1+)

Squid Configuration

Add the following to your squid.conf

redirect_program /path/to/churl.sh
url_rewrite_children 1

To enable concurrency, set url_rewrite_concurrency according to the value of request-buffer-size in your configuration.

Other Pages

Change History

Updated