NameTrans

                                                                                                                                                                                                                                                                                                                                      *Back to [[Book|Administrator's Configuration File Reference#cfr]]     [[Topic|Administrator's Configuration File Reference#chap7]]*

* [#{{assign-name}}]
* [#{{document-root}}]
* [#{{home-page}}]
* [#{{map}}]
* [#{{ntrans-dav}}]
* [#{{ntrans-j2ee}}]
* [#{{pfx2dir}}]
* [#{{reverse-map}}]
* [#{{rewrite}}]
* [#{{strip-params}}]
* [#{{unix-home}}]

In addition, the following common SAFs are also valid for the {{NameTrans}} directive:
* [{{match-browser}}|Common SAFs across Multiple Directives#saf2]
* [{{redirect}}|Common SAFs across Multiple Directives#saf4]
* [{{restart}}|Common SAFs across Multiple Directives#saf6]
* [{{set-variable}}|Common SAFs across Multiple Directives#saf8]

h3. {{assign-name}} {anchor:name1}

The {{assign-name}} function specifies the name of an object in {{obj.conf}} that matches the current request. The server then processes the directives in the named object in preference to the ones in the default object.

For example, if you have the following directive in the {{default}} object:
{code}
NameTrans fn="assign-name" name="personnel" from="/personnel"
{code}

Assume that the server receives a request for {{http://}}_server-name_{{/personnel}}. After processing this {{NameTrans}} directive, the server looks for an object named {{personnel}} in {{obj.conf}} and continues by processing the directives in the {{personnel}} object.

The {{assign-name}} function always returns {{REQ_NOACTION}}.

h4. Parameters

The following table describes parameters for the {{assign-name}} function.

Table 7-5 {{assign-name}} Parameters
||Parameter ||Description ||
|{{from}} |(Optional) Wildcard pattern that specifies the path to be affected. If you do not specify the {{from}} parameter, all paths are affected. |
|{{name}} |Specifies an additional named object in {{obj.conf}} whose directives will be applied to this request. |
|{{find-pathinfo-forward}} |(Optional) Instructs the server to look for the {{PATHINFO}} forward in the path right after the {anchor:indexterm-323} {{ntrans-base,}} instead of backward from the end of path as the server function {{assign-name}} does by default.The {{find-pathinfo-forward}} parameter is ignored if the {{ntrans-base}} parameter is not set in {{rq->vars}}. By default, {{ntrans-base}} is set.This feature can improve performance for certain URLs by reducing the number of statistics performed. |
|{{nostat}} |(Optional) Prevents the server from performing a stat on a specified URL.The effect of {{nostat="}}_virtual-path_{{"}} in the {{NameTrans}} function {{assign-name}} is that the server assumes that a stat on the specified _virtual-path_ will fail. Therefore, use {{nostat}} only when the path of the _virtual-path_ does not exist on the system. For example, use {{nostat}} for NSAPI plug-in URLs to improve performance by avoiding unnecessary stats on those URLs.When the default {{PathCheck}} server functions are used, the server does not stat for the paths {{/}}_ntrans-base/virtual-path_ and {{/}}_ntrans-base/virtual-path_{{/}}* if _ntrans-base_ is set (the default condition). It does not stat for the URLs {{/}}_virtual-path_ and {{/}}_virtual-path_{{/}}* if _ntrans-base_ is not set. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
# This NameTrans directive is in the default object.
NameTrans fn="assign-name" name="personnel" from="/a/b/c/pers"
...
<Object name=personnel>
...additional directives..
</Object>

NameTrans fn="assign-name" from="/perf" find-pathinfo-forward="" name="perf"

NameTrans fn="assign-name" from="/nsfc" nostat="/nsfc" name="nsfc"
{code}

h3. {{document-root}} {anchor:name2}

The {{document-root}} function specifies the root document directory for the server. If the physical path is not set by a previous {{NameTrans}} function, the {{http://}}_server-name_{{/}} part of the path is replaced by the physical path name for the document root.

When the server receives a request for {{http://}}_server-name_{{/somepath/somefile}}, the {{document-root}} function replaces {{http://}}_server-name_{{/}} with the value of its {{root}} parameter. For example, if the document root directory is {{/usr/sun/webserver7/https-server/docs}}, when the server receives a request for {{http://}}_server-name_{{/a/b/file.html}}, the {{document-root}} function translates the path name for the requested resource to {{/usr/sun/webserver7/https-server/docs/a/b/file.html}}.

You can also specify a document root in the {{virtual-server}} element of {{server.xml}}. For more information, see [virtual-server|V & W#v2].

This function always returns {{REQ_PROCEED}}.

{{NameTrans}} directives listed after this directive will never be called. Ensure that the directive that invokes {{document-root}} is the last {{NameTrans}} directive.

There can be only one root document directory. To specify additional document directories, use the {{pfx2dir}} function.

h4. Parameters

The following table describes parameters for the {{document-root}} function.

Table&nbsp;7-6 {{document-root}} Parameters
||Parameter ||Description ||
|{{root}} |File system path to the server&rsquo;s root document directory. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="document-root" root="/usr/sun/webserver7/https-server/docs"

NameTrans fn="document-root" root="$docroot"
{code}

h4. See Also

[#{{pfx2dir}}]

h3. {{home-page}} {anchor:name3}

The {{home-page}} function specifies the home page for your server.

h4. Parameters

The following table describes parameters for the {{home-page}} function.

Table&nbsp;7-7 {{home-page}} Parameters
||Parameter ||Description ||
|{{path}} |Path and name of the home page file. If {{path}} starts with a slash ({{/}}), it is assumed to be the full path to a file.If {{path}} is a relative path, this function sets the server&rsquo;s {{path}} variable and returns {{REQ_PROCEED}}. If {{path}} is a relative path, it is appended to the URI, and the function returns {{REQ_NOACTION}}. It then continues on to the other {{NameTrans}} directives. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="home-page" path="/path/to/file.html"

NameTrans fn="home-page" path="/path/to/$id/file.html"
{code}

h3. {{map}} {anchor:name4}

The {{map}} function maps a request URI to a URL on another server, allowing you to specify that a request should be serviced by another server. To load balance a given URI across multiple servers, use the {{map}} function in conjunction with the {{set-origin-server}} function. The {{map}} function looks for a certain prefix in the URI that the client is requesting. If {{map}} finds the prefix, it replaces the prefix with the mirror site prefix.

h4. Parameters

The following table describes parameters for the {{map}} function.

Table&nbsp;7-8 {{map}} Parameters
||Parameter ||Description ||
|{{from}} |The URI prefix to map. The prefix should not contain trailing slashes. |
|{{to}} |The URL prefix to which the request should be mapped. The prefix should not contain trailing slashes. |
|{{name}} |(Optional) Specifies an additional named object in {{obj.conf}}. The directives of the named object will be applied to this request. |
|{{rewrite-host}} |(Optional) Indicates whether the {{Host}} HTTP request header is rewritten to match the host specified by the {{to}} parameter. In a reverse proxy configuration where the proxy server and origin server service the same set of virtual servers, you can specify {{rewrite-host="false"}}. The default is {{true}}, indicating that the {{Host}} HTTP request header is rewritten. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
# Map everything under /docs to http://docs.sun.com/app/docs
NameTrans fn="map" from="/docs" to="http://docs.sun.com/app/docs"
{code}

h4. See Also

[{{set-origin-server}}|Route#rout1]

h3. {{ntrans-dav}} {anchor:name5}

The {{ntrans-dav}} function determines whether a request should be handled by the WebDAV subsystem. If the request should be handled by the WebDAV subsystem, the function adds a {{dav}} object to the pipeline.

h4. Parameters

The following table describes parameters for the {{ntrans-dav}} function.

Table&nbsp;7-9 {{ntrans-dav}} Parameters
||Parameter ||Description ||
|{{name}} |Specifies an additional named object in {{obj.conf}} whose directives will be applied to this request. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="ntrans-dav" name="dav"
{code}

h3. {{ntrans-j2ee}} {anchor:name6}

The {{ntrans-j2ee}} function determines whether a request maps to a Java web application context.

h4. Parameters

The following table describes parameters for the {{ntrans-j2ee}} function.

Table&nbsp;7-10 {{ntrans-j2ee}} Parameters
||Parameter ||Description ||
|{{name}} |Named object in {{obj.conf}} whose directives are applied to requests made to Java web applications. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="ntrans-j2ee" name="j2ee"
{code}

h3. {{pfx2dir}} {anchor:name7}

The {{pfx2dir}} function replaces a directory prefix in the requested URL with a real directory name. It also optionally allows you to specify the name of an object that matches the current request. See [#{{assign-name}}] for details on using named objects.

h4. Parameters

The following table describes parameters for the {{pfx2dir}} function.

Table&nbsp;7-11 {{pfx2dir}} Parameters
||Parameter ||Description ||
|{{from}} |URI prefix to convert. It should not have a trailing slash ({{/}}). |
|{{dir}} |Local file system directory path to which the prefix is converted. It should not have a trailing slash ({{/}}). |
|{{name}} |(Optional) Specifies an additional named object in {{obj.conf}} whose directives will be applied to this request. |
|{{find-pathinfo-forward}} |(Optional) Instructs the to server look for the {{PATHINFO}} forward in the path after {{ntrans-base}}, instead of backward from the end of path as the server function {{find-pathinfo}} does by default.The {{find-pathinfo-forward}} parameter is ignored if the {{ntrans-base}} parameter is not set in {{rq->vars}} when the server function {{find-pathinfo}} is called. By default, {{ntrans-base}} is set.This feature can improve performance for certain URLs by reducing the number of stats performed in the server function {{find-pathinfo}}.On Windows, you can use this feature to exclude the {{PATHINFO}} from the server URL normalization process (by changing `\' to `/') when the {{PathCheck}} server function {{find-pathinfo}} is used. Some double-byte characters have hexadecimal values that might be parsed as URL separator characters such as `\' or {{~}}. Using the {{find-pathinfo-forward}} parameter can sometimes prevent incorrect parsing of URLs containing double-byte characters. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example

In the first example, the URL {{http://}}_server-name_{{/cgi-bin/}}_resource_ (such as {{http://x.y.z/cgi-bin/test.cgi}}) is translated to the physical path name {{/httpd/cgi-local/}}_resource_ (such as {{/httpd/cgi-local/test.cgi}}), and the server also starts processing the directives in the object named {{cgi}}.
{code}
NameTrans fn="pfx2dir" from="/cgi-bin" dir="/httpd/cgi-local" name="cgi"
{code}

In the second example, the URL {{http://}}_server-name_{{/icons/}}_resource_ (such as {{http://x.y.z/icons/happy/smiley.gif}}) is translated to the physical path name {{/users/nikki/images/}}_resource_ (such as {{/users/nikki/images/smiley.gif)}}{{.}}
{code}
NameTrans fn="pfx2dir" from="/icons/happy" dir="/users/nikki/images"
{code}

The third example shows the use of the {{find-pathinfo-forward}} parameter. The URL {{http://}}_server-name_{{/cgi-bin/}}_resource_ is translated to the physical path name {{/export/home/cgi-bin/}}_resource_.
{code}
NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin"
dir="/export/home/cgi-bin" name="cgi"
{code}

h4. See Also
* [#{{assign-name}}]
* [#{{rewrite}}]

h3. {{reverse-map}} {anchor:name8}

The {{reverse-map}} function rewrites the HTTP response headers when the server is functioning as a reverse proxy. {{reverse-map}} looks for the URL prefix specified by the {{from}} parameter in certain response headers. If the {{from}} prefix matches the beginning of the response header value, {{reverse-map}} replaces the matching portion with the {{to}} prefix.

h4. Parameters

The following table describes parameters for the {{reverse-map}} function.

Table&nbsp;7-12 {{reverse-map}} Parameters
||Parameter ||Description ||
|{{from}} |URL prefix to be rewritten. |
|{{to}} |URL prefix that will be substituted in place of the {{from}} prefix. |
|{{rewrite-location}} |(Optional) Indicates whether the {{location}} HTTP response header should be rewritten. The default is {{true}}, indicating that the location header is rewritten. |
|{{rewrite-content-location}} |(Optional) Indicates whether the {{Content-Location}} HTTP response header should be rewritten. The default is {{true}}, indicating that the {{Content-Location}} header is rewritten. |
|{{rewrite-}}_headername_ |(Optional) Indicates whether the _headername_ HTTP response header should be rewritten, where _headername_ is a user-defined header name. With the exception of the {{Location}} and {{Content-Location}} headers, the default is {{false}}, indicating that the _headername_ header is not rewritten. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="reverse-map" from="http://docs.sun.com/app/docs" to="/docs"
{code}

h4. See Also

[#{{map}}]

h3. {{rewrite}} {anchor:name9}

The {{rewrite}} function allows flexible mappings between URIs and file system paths.

h4. Parameters

The following table describes parameters for the {{rewrite}} function.

Table&nbsp;7-13 {{rewrite}} Parameters
||Parameter ||Description ||
|{{from}} |(Optional) Wildcard pattern that specifies the path of requests that should be rewritten. The default is to match all paths. |
|{{root}} |(Optional) File system path to the effective root document directory. |
|{{name}} |(Optional) Name of an object in {{obj.conf}} whose directives will be applied to this request. |
|{{path}} |(Optional) Rewritten partial path. If non-empty, the path must begin with a slash ({{/}}). |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example

The following {{obj.conf}} code maps requests for the URI {{/~user/index.html}} to the file system path {{/home/user/public_html/index.html}}:
{code}
<If $path =~ "^/~([^/]+)(|/.*)$">
NameTrans fn="rewrite"
root="/home/$1/public_html"
path="$2"
</If>
{code}

h4. See Also

[{{restart}}|Common SAFs across Multiple Directives#saf6]

h3. {{strip-params}} {anchor:name10}

The {{strip-params}} function removes the embedded semicolon-delimited parameters from the path. For example, a URI of {{/dir1;param1/dir2}} would become a path of {{/dir1/dir2}}. When used, the {{strip-params}} function should be the first {{NameTrans}} directive listed.

h4. Parameters

The following table describes parameters for the {{strip-params}} function.

Table&nbsp;7-14 {{strip-params}} Parameters
||Parameter ||Description ||
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="strip-params"
{code}

h3. {{unix-home}} {anchor:name11}

(UNIX only) The {{unix-home}} function translates user names (typically of the form {{~username}}) into the user&rsquo;s home directory on the server&rsquo;s UNIX machine. You specify a URL prefix that signals user directories. Any request that begins with the prefix is translated to the user&rsquo;s home directory.

You specify the list of users with either the {{/etc/passwd}} file or a file with a similar structure. Each line in the file should have this structure (elements in the {{passwd}} file that are not required are indicated with *):
{code}
username:*:*:groupid:*:homedir:*
{code}

If you want the server to scan the password file only once at startup, use the {{Init}}-class function {{init-uhome}} in {{magnus.conf}}.

h4. Parameters

The following table describes parameters for the {{unix-home}} function.

Table&nbsp;7-15 {{unix-home}} Parameters
||Parameter ||Description ||
|{{subdir}} |Subdirectory within the user&rsquo;s home directory that contains the web documents of users. |
|{{pwfile}} |(Optional) Full path and file name of the password file if it is different from {{/etc/passwd}}. |
|{{name}} |(Optional) Specifies an additional named object whose directives will be applied to this request. |
|{{bucket}} |(Optional) Common to all {{obj.conf}} functions. Adds a bucket to monitor performance. For more information, see [The {{bucket}} Parameter|The bucket Parameter#b1]. |

h4. Example
{code}
NameTrans fn="unix-home" from="/~" subdir="public_html"

NameTrans fn="unix-home" from "/~" pwfile="/mydir/passwd" subdir="public_html"
{code}