Toolserver:ZWS

This page was moved from the Toolserver wiki.
Toolserver has been replaced by Toolforge. As such, the instructions here may no longer work, but may still be of historical interest.
Please help by updating examples, links, template links, etc. If a page is still relevant, move it to a normal title and leave a redirect.

ZWS or Zeus Web Server is the web server the Toolserver has been using since 2008-12-02. ZWS replaced Apache and switchboard and supports most of the functionality of Apache, including .htaccess.

.htaccess

# If you migrated your whole ~/public_html
Redirect /~user/ //tools.wmflabs.org/$YOUR_TOOL/

# If you just want to pick individual subdirectories
Redirect /~user/tool/ //tools.wmflabs.org/$YOUR_TOOL/

# Permanently redirect from the old address
Redirect 301 /~user/links.html /~user/view/Links

# Temporarily redirect 
Redirect 302 /~user/tool_lastest.fcgi /~user/tool_132.fcgi

# Gone, tell searching engines and spider to remove
Redirect 410 /~user/tool_broken.fcgi

Directory Listing Directives

DirectoryIndex index.cgi index.py index.txt index.html

If you don't want users to accidentally stumble across ./temp/ or script.fcgi

IndexIgnore temp script.fcgi

Content-Type

Server files with a file extension of txt with a UTF-8 character encoding

AddType text/plain;charset=UTF-8  txt

Change the default type from text/plain to include a character encoding:

DefaultType text/plain;charset=UTF-8

.htpasswd

/opt/zeus/web/bin/htpasswd .htpasswd username

Note: While passwords are stored using crypt (3) (very weak) they are still transmitted unencrypted. This file should be chmod 600 (non-world readable).

rewrite.script

However, it doesn't support rewriterules (i.e. the RewriteRule directive). Fortunately, equivalent functionality is supported in a different form. To use rewrites with ZWS, you need to create a rewrite script. Some documentation on this is available here:

Your rewrite script should be placed in $HOME/rewrite.script. Unlike Apache rewrite rules, there is only one script for your entire public_html, not one per directory.

Converting rewriterules

If your rewrite rules are fairly simple, you can convert them using the convert_rewrite utility on wolfsbane:

$ /opt/zeus/webadmin/bin/convert_rewrite $HOME/public_html/.htaccess >$HOME/rewrite.script

You will want to inspect the script after running this to make sure it does what you want. In particular, you might find that if you used this kind of rewrite rule:

RewriteBase /~user
RewriteRule ^mytool$ /some/other/path

Then the URLs in the generated rewrite.script will look like this:

match URL into $ with ^mytool$

However, this URL is wrong; the converter did not convert the RewriteBase. You will need to edit the script to look like this:

match URL into $ with ^/~user/mytool$

Apart from this, the rewrite scripts that convert_rewrite generates are somewhat convoluted, so you might want to clean them up by hand.

Note: Redirect directive are still kept in the .htaccess files

Examples

Redirection

For many use cases, you will want to tell a client that has requested some resource to instead request some other resource with a 301 (permanent) or 302 (temporary) redirect.

# Redirect /~user/ to /~user/docs/
match URL into $ with ^/~user(/docs/?)?$
if matched then
    set URL             = /~user/docs/home
    set RESPONSE        = 301
    set OUT:Location    = %{URL}
    set BODY            = Please try <a href="%{URL}">here</a> instead.\n
endif

This solves the problem of relative URLs pointing to the wrong location when using the rewrite mechanism below.

Caution If /~user/ 301 redirected to /~user/docs/first_tool and it was changed to /~user/docs/home, all services that had previously accessed the old URL continue to pointed to /~user/docs/first_tool as the correct address

Hiding internals

This method rewrites the client request internal to the web server.

match URL into $ with ^/~user/docs/([^?]+)(\?(.*))?$
if matched then
    set URL = /~user/cgi-bin/docs.pl?$1&$3
    goto END
endif

Using this method of internal rewriting may not be what you want - check if #Redirection applies to your situation.

# Hide internals of viewer.py
# General form: /~user/action/page [ ?additional=CGI parameters ]
# Example: /~user/edit/About?format=html
match URL into $ with ^/~user/(edit|view)/([^?]+)\??(.*)
if matched
    set URL = /~user/cgi-bin/viewer.py/$2?action=$1&$3
endif

Notes

We've changed the program a little, it will use PATH_INFO part (viewer.py/PAGE) since it keeps the characters & + but for it we give up ? without encoding it as %3F. And we allow additional parameter to be pass with the original URL after ?.

Loops

To prevent infinite loops, there is an upper limit on the number of commands that can be executed in a rewrite script. If this is exceeded, an internal server error will be generated.

The following code will decode ?, &, and = characters which allows tools to be linked with [[tools:]] (e.g. tools:~user/cgi-bin/tool.php?user=example).

# Makes [[tools:]] linking possible for cgi scripts
match URL into $ with ^/~user/cgi-bin/([^"%+;=?]+)%3[Ff](.+)$
if not matched then goto RULE_1_END
    set URL = /~user/cgi-bin/$1?$2

    AMPERSANDLOOP:
    match URL into % with ^(.*)%26(.*)$
    if not matched then goto LOOPEND_A
        set URL = %1&%2
        goto AMPERSANDLOOP
    LOOPEND_A:

    EQUALLOOP:
    match URL into % with ^(.*)%3[Dd](.*)$
    if not matched then goto LOOPEND_E
        set URL = %1=%2
        goto EQUALLOOP
    LOOPEND_E:

    set RESPONSE = 301 # Use a 301 (permanent) redirect
    set OUT:Location = %{URL}
    set BODY = Please try <a href="%{URL}">here</a> instead\n
goto END
RULE_1_END:

Imitating Apache's `[QSA,L]` flag

The [QSA,L] feature in Apache allows combining the original query string with a query string built by a RewriteRule. This can be done manually as shown in #Hiding internals since ZWS treats the whole URL as one unit (Apache handles the query string separately). However, a more general way of imitating the familiar apache flag [QSA,L] in ZWS can be found by harnessing ZWS' powerful flow control in your rewrite.script.

Use the following at the top of your rewrite.script:

# get the document root
map path into SCRATCH:DOCROOT from /
# initialize our variables
set SCRATCH:ORIG_URL = %{URL}
set SCRATCH:REQUEST_URI = %{URL}

# If there's a query part split it off from `URL`
# We can access it later from `SCRATCH:ORIG_URL`
match URL into $ with ^([^?]*)\?(.*)$
if matched then
  set SCRATCH:REQUEST_URI = $1
  set SCRATCH:QUERY_STRING = $2
endif

Then add a rule with your rewrites:

match URL into $ with ^/~user/dir/(.+)
if matched then
    set URL = /~user/cgi-bin/script.pl?$1
    goto QSA_RULE_START
endif

# More rewrite sections...

# Skip QSA correction rule
goto END

The QSA rule goes at the bottom:

QSA_RULE_START:
# append the query string if there was one originally
# the same as [QSA,L] for Apache
match SCRATCH:ORIG_URL into % with \?(.*)$
if matched then
    set URL = %{URL}&%{SCRATCH:QUERY_STRING}
endif
goto END
QSA_RULE_END:

Obviously, this is cumbersome unless you need the power provided. Consider using the method shown in [[Toolserver:

Hiding internals|#Hiding internals]] instead.

Category:Documentation