NameTrans
The NameTrans directive translates virtual URLs to physical directories on your server. The NameTrans directive must appear in the default object. For more information, see NameTrans.
The following NameTrans-class functions are described in detail in this section:
- 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:
assign-name
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:
NameTrans fn="assign-name" name="personnel" from="/personnel"
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.
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 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. |
Example
# 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"
document-root
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.
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.
Parameters
The following table describes parameters for the document-root function.
Table 7-6 document-root Parameters
| Parameter | Description |
|---|---|
| root | File system path to the server’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. |
Example
NameTrans fn="document-root" root="/usr/sun/webserver7/https-server/docs" NameTrans fn="document-root" root="$docroot"
See Also
home-page
The home-page function specifies the home page for your server.
Parameters
The following table describes parameters for the home-page function.
Table 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’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. |
Example
NameTrans fn="home-page" path="/path/to/file.html" NameTrans fn="home-page" path="/path/to/$id/file.html"
map
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.
Parameters
The following table describes parameters for the map function.
Table 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. |
Example
# Map everything under /docs to http://docs.sun.com/app/docs NameTrans fn="map" from="/docs" to="http://docs.sun.com/app/docs"
See Also
ntrans-dav
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.
Parameters
The following table describes parameters for the ntrans-dav function.
Table 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. |
Example
NameTrans fn="ntrans-dav" name="dav"
See Also
ntrans-j2ee
The ntrans-j2ee function determines whether a request maps to a Java web application context.
Parameters
The following table describes parameters for the ntrans-j2ee function.
Table 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. |
Example
NameTrans fn="ntrans-j2ee" name="j2ee"
See Also
pfx2dir
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.
Parameters
The following table describes parameters for the pfx2dir function.
Table 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. |
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.
NameTrans fn="pfx2dir" from="/cgi-bin" dir="/httpd/cgi-local" name="cgi"
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).
NameTrans fn="pfx2dir" from="/icons/happy" dir="/users/nikki/images"
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.
NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin" dir="/export/home/cgi-bin" name="cgi"
See Also
reverse-map
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.
Parameters
The following table describes parameters for the reverse-map function.
Table 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. |
Example
NameTrans fn="reverse-map" from="http://docs.sun.com/app/docs" to="/docs"
See Also
rewrite
The rewrite function allows flexible mappings between URIs and file system paths.
Parameters
The following table describes parameters for the rewrite function.
Table 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. |
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:
<If $path =~ "^/~([^/]+)(|/.*)$"> NameTrans fn="rewrite" root="/home/$1/public_html" path="$2" </If>
See Also
strip-params
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.
Parameters
The following table describes parameters for the strip-params function.
Table 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. |
Example
NameTrans fn="strip-params"
unix-home
(UNIX only) The unix-home function translates user names (typically of the form ~username) into the user’s home directory on the server’s UNIX machine. You specify a URL prefix that signals user directories. Any request that begins with the prefix is translated to the user’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 *):
username:*:*:groupid:*:homedir:*
If you want the server to scan the password file only once at startup, use the Init-class function init-uhome in magnus.conf.
Parameters
The following table describes parameters for the unix-home function.
Table 7-15 unix-home Parameters
| Parameter | Description |
|---|---|
| subdir | Subdirectory within the user’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. |
Example
NameTrans fn="unix-home" from="/~" subdir="public_html" NameTrans fn="unix-home" from "/~" pwfile="/mydir/passwd" subdir="public_html"
Sign up or Log in to add a comment or watch this page.
