35 -----------------

    36 

    37 You must enable url rewriting from within the squid.conf file.

    38 

    39 	url_rewrite_program /usr/local/bin/volta

    40 

    41 ... and that's it.  You may need some additional customization, like where

    42 the volta database is stored on disk:

    43 

    44 	url_rewrite_program /usr/local/bin/volta -f /var/db/squid/volta.db

    45 

    46 Busy servers:

    47 

    48 Make sure rewrite_concurrency is disabled, volta is single threaded.

    49 Instead, just add more volta children.  They are lightweight, so load em

    50 up.  A proxy at my $DAYJOB is in use by around 450 people, and we get by

    51 nicely with 10 volta children.

    52 

    53 	url_rewrite_concurrency 0

    54 	url_rewrite_children 10

    55 

    58 -----------

    62 Volta reads its rewrite rules from a local database.  You can create the

    63 rules in a text editor, then convert it to the database like so:

    64 

    65 	% volta -c rules.txt

    66 

    67 You'll be left with a "volta.db" file in the current directory.  Put it

    68 wherever you please, and use the -f flag to point to it.

    69 

    70 

    71 Rule file syntax

    72 ----------------

    73 

    74 Volta's rule syntax is designed to be easy to parse by humans and

    75 machines.  Blank lines are skipped, as is any line that starts with the

    76 '#' character, so you can keep the ascii version of your rules well

    77 documented and in version control.

    78 

    79 When compiling the ruleset into the database format, volta detects

    80 malformed rules and stops if there are any problems, leaving your

    81 original database intact.  You can change the ruleset at any time while

    82 volta is running, and the new rules will take affect within about 10

    83 seconds.  No need to restart squid!

    84 

    85 There are two types of rules -- positive matches, and negative matches.

    86 Positive matches cause the rewrite, negative matches allow the original

    87 request to pass.  Rule order is consistent, top-down, first match wins.

    88 Fields are separated by any amount of whitespace (spaces or tabs.)

    89 

    90 

    91 ### Positive matches:

    92 

    93     First field: the hostname to match.

    94 

    95       You can use an exact hostname (www.example.com), or the top level

    96       domain (tld) if you want to match everything under a specific host

    97       (example.com.)  You can also use a single '*' to match every request,

    98       though this essentially bypasses a lot of what makes volta quick, it

    99       is included for completeness.  You may have an unlimited amount of

   100       rules per hostname.  Hostnames are compared without case sensitivity.

   101 

   102 

   103     Second field: the path to match.

   104 

   105 	  This can be an exact match ('/path/to/something.html'), a regular

   106 	  expression ('\.(jpg|gif|png)$'), or a single '*' to match for any

   107 	  path. Regular expressions are matches without case sensitivity.  There

   108 	  is currently no support for capturing, though this may be added in

   109 	  a future release.

   110 

   111 

   112     Third field: The redirect code and url to rewrite to.

   113 

   114       Any pieces of a url that are omitted are automatically replaced

   115       with the original request's element -- the exception is a hostname,

   116       which is required.  If you omit a redirect code, the URL rewrite is

   117       transparent to the client.  You can attach a 301: or 302: prefix to

   118       cause a permanent or temporary code to be respectively sent, instead.

   119 

   120 

   121 ### Negative matches:

   122 

   123     First field: the hostname to match.

   124 

   125 	  See above -- all the same rules apply.

   126 

   127 

   128     Second field: the path to match.

   129 

   130 	  See above -- all the same rules apply.

   131 

   132 

   133 	Third field: the 'negative' marker.

   134 

   135 	  This is simply the '-' character, that signals to volta that this is

   136 	  a negative matching rule.

   137 

   138 

   139 You can easily test your rules by running volta on the command line, and

   140 pasting URLs into it.   Boost the debug level (-d4) if you're having any issues.

   141 

   142 

   143 Examples

   144 --------

   145 

   146 Rewrite all requests to Google to the SSL version:

   147 

   148     google.com * 302:https://www.google.com

   149 

   150 	This will redirect the request "http://www.google.com/search?q=test" to

   151 	"https://www.google.com/search?q=test".

   152 

   153 

   154 Transparently alter all uploaded images on imgur to be my face:  :)

   155 

   156 	i.imgur.com \.(gif|png|jpg)$ http://www.martini.nu/images/mahlon.jpg

   157 

   158 

   159 Expand a local, non qualified hostname to a FQDN (useful alongside the

   160 'dns_defnames' squid setting to enforce browser proxy behaviors):

   161 

   162 	local-example * local-example.company.com

   163 

   164 

   165 Cause all blog content except for 2011 posts to permanently redirect to

   166 an archival page:

   167 

   168 	martini.nu /blog/2011 -

   169 	martini.nu /blog 301:martini.nu/content-archived.html

   170 

   171 

   172 Turn off rewriting for specific network segment or IP address:

   173 

   174 	Squid has this ability built in -- see the 'url_rewrite_access' setting.

   175