NameTrans stands for Name Translation. NameTrans directives translate virtual URLs to physical directories on your server. For example, the URL
http://www.test.com/some/file.html
NameTrans directives should appear in the default object. If there is more than one NameTrans directive in an object, the server executes each one in order until one succeeds.
The following NameTrans-class functions are described in detail in this section:
assign-name tells the server to process directives in a named object.
document-root translates a URL into a file system path by replacing the http://server-name/ part of the requested resource with the document root directory.
home-page translates a request for the server’s root home page (/) to a specific file.
map looks for a certain URL prefix in the URL that the client is requesting.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
ntrans-j2ee determines whether a request maps to a JavaTM technology-based web application context. This is applicable only to the Administration Server.
pac-map maps proxy-relative URLs to local files that are delivered to clients who request configuration.
pat-map maps proxy-relative URLs to local files that are delivered to proxies that request configuration.
pfx2dir translates any URL beginning with a given prefix to a file system directory and optionally enables directives in an additional named object.
redirect redirects the client to a different URL.
reverse-map rewrites HTTP response headers when the proxy server is functioning as a reverse proxy.
set-variable enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.
strip-params removes embedded semicolon-delimited parameters from the path.
unix-home translates a URL to a specified directory within a user’s home directory.
Applicable in NameTrans-class directives.
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, consider the following directive in the default object:
NameTrans fn=assign-name name=personnel from=/personnel
Let’s suppose 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.
The following table describes parameters for the assign-name function.
Table 5–35 assign-name parameters
# 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" |
Applicable in NameTrans-class directives.
The document-root function specifies the root document directory for the server. If the physical path has not been 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/webserver61/server1/docs, then 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/webserver61/server1/docs/a/b/file.html.
This function always returns REQ_PROCEED. NameTrans directives listed after this will never be called, so be sure 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 to set up additional path name translations.
The following table describes parameters for the document-root function.
Table 5–36 document-root parameters
Parameter |
Description |
---|---|
File system path to the server’s root document directory. |
|
bucket |
(Optional) Common to all obj.conf functions. |
NameTrans fn=document-root root=/usr/sun/webserver61/server1/docsNameTrans fn=document-root root=$docroot |
Applicable in NameTrans-class directives.
The home-page function specifies the home page for your server. Whenever a client requests the server’s home page (/), they’ll get the document specified.
The following table describes parameters for the home-page function.
Table 5–37 home-page parameters
Parameter |
Description |
---|---|
Path and name of the home page file. If path starts with a slash (/), it is assumed to be a full path to a file. 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 continuing on to the other NameTrans directives. |
|
bucket |
(Optional) Common to all obj.conf functions. |
NameTrans fn="home-page" path="/path/to/file.html" NameTrans fn="home-page" path="/path/to/$id/file.html" |
Applicable in NameTrans-class directives.
The map function looks for a certain URL prefix in the URL that the client is requesting. If map finds the prefix, it replaces the prefix with the mirror site prefix. When you specify the URL, don’t use trailing slashes—they cause “Not Found” errors.
NameTrans fn=map from="source site prefix" to="destination site prefix" name="named object"
The following table describes parameters for the map function.
Table 5–38 map parameters
Parameter |
Description |
---|---|
from |
The prefix to be mapped to the mirror site. |
to |
The mirror site prefix. |
name |
(optional) gives a named object from which to derive the configuration for this mirror site. |
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 may wish to specify rewrite-host="false". The default is "true", meaning that the Host HTTP request header is rewritten. |
Example
# Map site http://home.netscape.com/ to mirror site http://mirror.com NameTrans fn=map from="http://home.netscape.com" to="http://mirror.com" |
See match-browser.
This is applicable only to the Administration Server.
Applicable in NameTrans-class directives.
The ntrans-j2ee function determines whether a request maps to a Java web application context.
The following table describes parameters for the ntrans-j2ee function.
Table 5–39 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. |
NameTrans fn="ntrans-j2ee" name="j2ee" |
Applicable in NameTrans-class directives.
The pac-map function maps proxy-relative URLs to local files that are delivered to clients who request configuration.
NameTrans fn=pac-map from=URL to=prefix name=named object
The following table describes parameters for the pac-map function.
Table 5–40 pac-map parameters
Parameter |
Description |
---|---|
The proxy URL to be mapped. |
|
to |
The local file to be mapped to. |
name |
(optional) gives a named object (template) from which to derive configuration. |
Example
NameTrans fn=pac-map from=http://proxy.mysite.com/pac to=<Install_Root><Instance_Directory>pac/proxy.pac name=file |
Applicable in NameTrans-class directives.
The pat-map function maps proxy-relative URLs to local files that are delivered to proxies who request configuration.
Syntax
NameTrans fn=pat-map from=URL to=prefix name=named object
Parameters
The following table describes parameters for the pat-map function.
Table 5–41 pat-map parameters
Parameter |
Description |
---|---|
from |
The proxy URL to be mapped. |
to |
The local file to be mapped to. |
name |
(optional) gives a named object (template) from which to derive configuration. |
Example
NameTrans fn=pat-map from=http://proxy.mysite.com/pac to=<Install_Root><Instance_Directory>pac/proxy.pac name=file |
Applicable in NameTrans-class directives.
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 the discussion of assign-name for details of using named objects.)
The following table describes parameters for the pfx2dir function.
Table 5–42 pfx2dir parameters
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" |
Applicable in NameTrans-class directives.
The redirect function lets you change URLs and send the updated URL to the client. When a client accesses your server with an old path, the server treats the request as a request for the new URL.
The following table describes parameters for the redirect function.
Table 5–43 redirect parameters
Parameter |
Description |
---|---|
from |
Specifies the prefix of the requested URI to match. |
(Maybe optional) Specifies a complete URL to return to the client. If you use this parameter, don’t use url-prefix (and vice versa). |
|
(Maybe optional) The new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix. If you use this parameter, don’t use url (and vice versa). |
|
(Optional) Flag that tells the server to util_uri_escape the URL before sending it. It should be yes or no. The default is yes. For more information about util_uri_escape, see the Sun Java System Web Proxy Server 4.0.2 NSAPI Developer’s Guide. |
|
bucket |
(Optional) Common to all obj.conf functions. |
In the first example, any request for http://server-name/whatever is translated to a request for http://tmpserver/whatever.
NameTrans fn=redirect from=/ url-prefix=http://tmpserver |
In the second example, any request for http://server-name/toopopular/whatever is translated to a request for http://bigger/better/stronger/morepopular/whatever.
NameTrans fn=redirect from=/toopopular url=http://bigger/better/stronger/morepopular |
Applicable in NameTrans-class directives.
The reverse-map function is used to rewrite HTTP response headers when the proxy 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.
The following table describes parameters for the reverse-map function.
Table 5–44 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) Boolean that indicates whether the Location HTTP response header should be rewritten. The default is "true", meaning the Location header is rewritten. |
rewrite-content-location |
(Optional) Boolean that indicates whether the Content-location HTTP response header should be rewritten. The default is "true", meaning the Content-location header is rewritten. |
rewrite-headername |
(Optional) Boolean that 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", meaning the headername header is not rewritten. |
See set-variable.
Applicable in NameTrans-class directives.
The strip-params function removes 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.
The following table describes parameters for the strip-params function.
Table 5–45 strip-params parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions. |
NameTrans fn=strip-params
Applicable in NameTrans-class directives.
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 needed 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.
The following table describes parameters for the unix-home function.
Table 5–46 unix-home parameters
Parameter |
Description |
---|---|
Subdirectory within the user’s home directory that contains their web documents. |
|
(Optional) Full path and file name of the password file if it is different from /etc/passwd. |
|
(Optional) Specifies an additional named object whose directives will be applied to this request. |
|
bucket |
(Optional) Common to all obj.conf functions. |
NameTrans fn=unix-home from=/~ subdir=public_html NameTrans fn=unix-home from /~ pwfile=/mydir/passwd subdir=public_html |