search cancel

ProxySG user-defined exception page guidelines.

book

Article ID: 173830

calendar_today

Updated On:

Products

ProxySG Software - SGOS

Issue/Introduction

The purpose of this article is to provide some basic guidelines regarding custom exception pages management.

Custom or User-Defined Exceptions can either be applied as general (in which case the format will apply to all exceptions) or as a single page (in which case a rule must be created with action "Return Exception" in the Visual Policy Manager, where you'll be able to select the custom exception previously created).

Resolution

There are two main ways to set up the User-Defined exception page:

Exception pages are written in a hierarchical manner.

"Exception.all" is the parent, containing all exceptions under it. Whatever we apply here, will be applied to all other exceptions by default, for instance, if we want all exceptions to display certain a background color, we can modify this section, and unless told otherwise (on a particular exception page code itself), the background color will always be applied. Note that every thing we define on other exceptions will override the default behavior set by Exception.all.
 

Custom exceptions are defined under (exception.user-defined.all ...).

Part 1: default values

(exception.user-defined.all
    (contact "")
    (details "")
    (format "")
    (help "")
    (summary "")
    (http
      (code "404")
      (contact "Contact your network administrator")
      (details "")
      (format "")
      (help "")
      (summary "")
    )

As previously explained with exception.all, these lines will only set default values for all pages under exception.user-defined.all (for all custom pages), overriding any defaults set at exception.all, and any values set here will be overridden if something else is defined on the custom exception page's code itself.

For instance, here we have defined a 404 and below on our custom exception a 403. If we haven't defined that 403, the default code would be 404, and it will be the code of any pages with the tag (code "") empty.

Note that (exception.user-defined.all isn't closed yet. If we write/paste a custom page, it has to be after the (http...) section of exception.user-defined.all, and then (after our custom code is introduced) we'll close the exception.user-defined.all with an extra ) at the end of our code.

Part 2: custom code

(exception.user-defined.customdenied
(http
(code "403")
(format <<--customdenied--


Our HTML code for the exception page goes here.


--customdenied--
)
)
)
  )

Line by line description:

(exception.user-defined.customdenied - We are stating that the following is the code for a page called "customdenied", which is under exception.user-defined.

Note that when calling this page from the VPM, we'll have it displayed with the name "user-defined.customdenied".

(http - This opens the HTTP response to be injected by the proxy to the client

(code "XXX") - Has to be a valid HTTP response code.

If the end user runs developer tools in the client browser, we should be able to see that code.

Note that codes such as 101 ("switching protocols") won't have the exception page displayed (because of how the browser itself handles that response code - similar things can be achieved with other 1XX or 3XX codes).

(format <<--customdenied--   - Here we are opening the actual HTML contents of the .customdenied page

...

--customdenied--  - We are closing the HTML and returning to the regular coding format for the exception pages.

Note that <<--page name-- opens the posibility for writing/pasting custom HTML code, and --page name-- is the tag to close that. If we were to have the HTML directlty under format, such as (format ), the Proxy would return an error, since we haven't told it what page is that HTML for.

) - We close the Format

) - We close the HTTP

) - We close the exception.user-defined.customdenied

  ) - We close the exception.user-defined.all
 

Here the custom code and exception.user-defined.all has ended.

All the rest of non-user-defined pages will be written next.

)  Then this one will close the exception.all code.
 

Finally, as an example, you can look for the (exception.user-defined.all on a proxy and replace it with the following example code for a custom exception:

(exception.user-defined.all
    (contact "")
    (details "")
    (format "")
    (help "")
    (summary "")
    (http
      (code "404")
      (contact "")
      (details "")
      (format "")
      (help "")
      (summary "")
    )

(exception.user-defined.customblockexample2
(http
(code "403")
(format <<--customblockexample2--

Please review corporate policies

Your IP is $(client.address)

Category $(category)


ALERT - UNAUTHORIZED ACCESS

 

Example exception page

 

Example unauthorized access page

 

--customblockexample2--

)
)
)
 )

A final note: as seen here, we can use variables such as

 $(client.address) 

on our HTML code.

For instance:

Your IP is $(client.address)

"$(" will escape the HTML and tell the Proxy to inject the content indicated - client.address in this case - then the escape is closed by ")" and we return to HTML.

The same applies for the line:

Category error $(category)

where

 $(category) 

will be injected in the middle of the HTML.

A list of variables and other details can be found on this resource:

ProxySG Log Fields and Substitutions

For more information on creating custom exception pages, you can review the "Create Custom Exception Pages" document under the ProxySG First Steps Solutions guide.