HOWTO: The URL toolkit

The URL toolkit is a set of tools to perform actions based on the URL or on the URL itself. Regular expressions are used to find a matching URL. Possible actions for matching URLs are rewriting the URL, denying access or redirecting to another URL.

The most important feature of the URL toolkit is URL rewriting. Via URL rewriting, the URL can be changed into another URL before Hiawatha handles it. The following example leaves URLs that matches an existing file or files in the images directory unchanged, denies access to files in the data directory and rewrites all other URLs to /index.php.

UrlToolkit {
    ToolkitID = rewrite
    RequestURI exists Return
    Match ^/images Return
    Match ^/data DenyAccess
    Match /(.*) Rewrite /index.php?page=$1
}

VirtualHost {
    Hostname = www.domain.com
    ...
    UseToolkit = rewrite
}

Syntax

The complete syntax of the URL toolkit in Hiawatha is:

UrlToolkit {
    ToolkitID = <toolkit_id>

    Call <rewrite_id>
    Header <key> [!]<value> Call|DenyAccess|Exit|Goto|Return|Skip|Use
    Match [!]<url> Ban|Call|DenyAccess|Exit|Expire|Goto|Return|Rewrite|Redirect|Skip|UseFastCGI
    Method [!]<request method> Call|DenyAccess|Exit|Goto|Redirect|Return|Skip|Use
    RequestURI exists|isfile|isdir Return|Exit
    Skip <lines>
    UseSSL Call|Exit|Goto|Return|Skip
}

The format of the actions is as follows:

    Ban <seconds>
    Call <toolkit_id>
    DenyAccess
    Exit
    Expire <number> (seconds|minutes|hours|days|weeks|months) [Public|Private] [Return|Exit]
    Goto <toolkit_id>
    Redirect <url>
    Return
    Rewrite <replace> [<max_loop>] [Continue|Return]
    Skip <lines>
    Use <url>
    UseFastCGI <fastcgi_server_id>

Explanation of the commands:

• Ban: Ban the client for <seconds> seconds.
• Call: Execute another rule and proceed with the current rule afterwards.
• DenyAccess: Denies access to the requested file (results in a 403 error) and terminate toolkit processing.
• Exit: Stop URL rewriting.
• Expire: Adds an Expires HTTP header with current timestamp + <time>. The default behaviour is to continue after an Expire action.
• Goto: Execute another rule and terminate toolkit processing.
• Match: Perform the following action if <url> matches the requested URL.
• Method: Perform an action for a certain request method.
• Redirect: Redirect the browser to <url> via a 301 and terminate toolkit processing.
• RequestURI: Check if the requested URL is a file or a directory.
• Rewrite: Rewrite the current URL for maximum <max_loop> times (default=1) and terminate toolkit processing.
• Return: Return from the current rewrite rule.
• Skip: Skip the following <number> of lines (ToolkitID excluded).
• ToolkitID: Assign a label to the current rule set.
• Use: Replace the current URL with a new one.
• UseFastCGI: Use FastCGI server with id <fastcgi_server_id> and terminate toolkit processing.
• UseSSL: Perform action when client is connected via HTTPS.

Wigwam

Hiawatha comes with a tool called 'wigwam'. With this tool, you can test your URL toolkit rules before activating them.

wigwam -t <toolkit_id>