at32 Reverse Proxy Online Documentation

    l Accessing the Admin Interface
    l Program Setup
    l Basic Rule Setup
      l Example One
      l Example Two
    l Rule Activation Conditions
      l Example Three
      l Example Four
    l Advanced Activation Conditions
    l Regular Expressions
      l Full Documentation (separate document)
      l Download RE Software (external file)
    l Altering Request and Response Header Fields
      l Syntax
        l add
        l delete
        l replace
        l replacesubs
    l Support
[ Top ]
Accessing the Admin Interface

Setup is almost handled entirely by the admin interface which is accessible via a browser. You can get to this by opening a browser window on the machine in which the program is installed and typing http://localhost:8082

By default the reverse proxy works on port 80 - if you already have a web service installed and using that port you will get an error. In this instance you will change the port number of either the web server or the proxy. Typically, the reverse proxy will sit on port 80 and pull requests from the web server transparently on another port.

[ Top ]
Program Setup

With the program window open you can access the Setup menu. From here you can configure the program as a service - remember to reboot the machine before the changes take effect. You can also change port numbers for the reverse proxy and browser-based admin interface.

[ Top ]
Basic Rule Setup

With the admin interface accessed in your browser, it is necessary to always setup one rule before the reverse proxy can actually work. Typically, this is to point the proxy to your primary web server - or the web server that will deal with requests that are not trapped by the proxy.
i) Click Reverse Proxy Rules from the menu followed by Create New Rule.

ii) Enter the IP address and port number where you wish to pull http requests from and click submit.

iii) Now, when you access the reverse proxy using it's address and port number you should in fact see the output from the web server which you have tied it to.
Important (1): Be aware that if you point the rule to a REMOTE web service you may have to add the keywords "delete host" into the customize request header box. This may also be true when using localhost during development or debugging of a website on certain web servers. You may also need to include "add host:[your_hostname]" too, depending upon how the web server deals with incoming requests itself (if you do, make sure "delete" comes BEFORE "add"!).

Important (2): In certain circumstances the Reverse Proxy may return an error when in fact the fault lies with your regular web service. e.g. ASP script errors close the connection early to send debugging information. For this reason, it is recommended that any development or debugging is done via the web server directly. When you receive a Reverse Proxy error always try your web service directly to see what the problem is. In normal conditions however, Reverse Proxy will do it's best to pass on any errors returned by your web service.

[ Top ]
Basic Rules: Example One - you are running a single web server on the same PC as the reverse proxy.
  • Set the port number of the web server to something other than the HTTP default (e.g. use 81).
  • Create a rule that simply points to http://localhost and port 81 (note: http://127.0.0.1 is the same as localhost).
  • [ Top ]
    Basic Rules: Example Two - you are running a single web server on a different PC connect by a LAN.
  • Create a rule that simply points to the IP of the other computer. You should be able to leave the web server on port 80 - though this is up to the exact needs of the administrator.
  • [ Top ]
    Rule Activation Conditions

    at32 Reverse Proxy really excels in allowing you to fuse together the output from multiple web servers. To do this, typically (though not always) you need to create separate rules with unique activation conditions that direct traffic to the appropriate server.

    In most cases, you will want to direct traffic based on the HTTP Host header field. e.g. mydomain1.com going to one server or server application, mydomain2.com going to another.

    [ Top ]
    Rule Activation Conditions: Example Three - you are running IIS (port 81) and Apache (port 82) on a single machine, each hosts a single website with a unique domain name each. (mydomain1.com / mydomain2.com)
  • Create two new rules and point both to the location of each web server. As you are running the web servers on a single machine - the address will be the same but you need to manually enter the correct port numbers.
  • Open the first rule and click Add New Activation Condition. Click Submit to the default "Host" setting.
  • In the Search String or Regular Expression field enter *mydomain1.com*. Note the asterisks - these allow the proxy to forward requests which may also come from both www.mydomain1.com and accounts.mydomain1.com. In addition, if you are running the PROXY on a port other than 80 the asterisk is necessary because the host field would then also include the port number. In short: always use the asterisk wild cards if in doubt!
  • Click Submit.
  • Do the same for the second rule, but this time enter *mydomain2.com*. Note that you need not actually alter this as long as the second rule comes AFTER the first. This is because the first rule will ALWAYS send traffic to mydomain1.com and the second rule would always send any other traffic to the other server.
  • [ Top ]
    Rule Activation Conditions: Example Four - you are running IIS which is hosting several websites (mydomain1.com - mydomain6.com) all on port 81. In addition - also have another web server application on port 82 running a single website (mydomain7.com). Both are on the same machine.
  • Create two rules. The first should point to the server on port 82, and have an activation condition appropriatly set to check the host field for *mydomain7.com*.
  • The second rule (which MUST come after the first - use the up/dn functions to control this) should point to the IIS server on port 81. There is no need to set any activation conditions because IIS will now work out what website to serve itself because at32 Reverse Proxy forwards the request as if it came directly from the user.
  • [ Top ]
    Advanced Activation Conditions

    It's possible to add more complex activation rules through manipulation of different headers. For example, you might want to run all your ASP scripts on one server - and serve everything else on a common resource server. For this, you could create an activation condidition that considers the URI host header field with the string "*.asp".

    You can also combine activation conditions. Using the OR boolean operator will activate the rule if either of the conditions are met. AND requires each condition to met, and NOT prevents the rule from activating if that condition is met.

    Even more complex conditions can be created by generating several rules. In all instances make sure you have the rules/conditions in the correct order in which they will be considered first.

    [ Top ]
    Regular Expressions

    Regular Expressions are a complex topic and best left to a separate document.

    You should also download (199kb) and experiment with the Regular Expression test program which will be a valuable resource if you are new to the format.

    Both the original authors of the document and the software are created by Andrey V. Sorokin, though some changes were made for relevancy and size.

    [ Top ]
    Altering Request and Response Header Fields

    A powerful feature of at32 Reverse Proxy is to be able to alter request and response header fields. This is done through simple text commands or more complex regular expressions.

    Request header fields are those sent from the client's browser, through at32 Reverse Proxy (where they are altered) before being passed onto the server.

    Response header fields are altered by the reverse proxy after they have been returned by the server and before they reach the client. It is perfectly possible to alter both request and response header fields in the same operation.

    If you need to perform different manipulations according to the activation condition - then create multiple rules.

    [ Top ]
    Syntax

    Specify a new command on a separate line. It is possible to specify unlimited commands in this way. Note that some commands require you to specify additional properties on an additional line.

    [ Top ]
    add (text)

    Simply adds a line of text to the the http header.
    e.g.
    add Server: Freds Server
    This would identify all output from your Reverse Proxy (for that rule) as using Fred's Server. This is of questionable value of course - perhaps useful for logging purposes - but what actual fields you add is up to you. Of course, most web servers return a server field of their own - so you should delete this field beforehand.

    Add also supports an additional function: publishing of the client's IP in the header, by entering [clientip] in the text. This does not apply to the other header field functions. Example usage is:
    add x-forwarded-for: [clientip]
    [ Top ]
    delete (field)

    Specify a field name to remove that field from the request or response header. You are also recommended to do this if you add a field: you must delete that field before you add the new one.
    e.g.
    delete server
    ...will remove the server field entirely, following on from the previous example.

    [ Top ]
    replace (field) (regular expression)
    [SPACE] (replacement string)


    Perform a Regular Expression "replace" operation on a HTTP header field. If the Regular Expression evaluates to true, the fields contents will be replaced by the replacement string.

    Important Note: the replacement string MUST be on a new line directly underneath the command, and have a leading space.

    e.g.
    "/custard/jam.asp" (http header uri field)
    "html" (replacement string)

    replace uri asp
     html


    result: "/custard/jam.html"
    [ Top ]
    replacesubs (field) (regular expression)
    [SPACE] (substitution string)


    This operates the same as replace but instead of directly replacing a string, it uses the substitution string as a template for the replacement operation. Consult the Regular Expression doumentation for further explanation.

    e.g.
    "/resources/25786/photo.jpg" (http header uri field)
    "resources.asp?id=$1" (substitution string)

    replace uri resources/(.*)/.*
     resources.asp?id=$1


    result: "/resources.asp?id=25786"
    Note that in both cases, a http header "uri" field doesn't really exist - but is in fact the opening http header line (including the query string). However, at32 Reverse Proxy will modify this accordingly when you enter the field as "uri". It's impossible to use the delete or add operators on this "field", though you could use a Regular Expression to mimic these effects.

    Processing for all other fields operate as normal.

    [ Top ]
    Support

    Please contact us regarding support via our website at at32.com. We regret we cannot provide individual support for network setup or regular expression generation - though we will try to help as best we can regardless.
    .