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
could be translated to the full file system path
/usr/Sun/WebServer61/server1/docs/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.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Server based upon the results by setting values for specified variables.
ntrans-dav determines whether a request should be handled by the WebDAV subsystem and if so, creates a dav objectset.
ntrans-j2ee determines whether a request maps to a Java™ technology-based web application context.
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.
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 4–9 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 4–10 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/docs NameTrans 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 4–11 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 all stage directives. The match-browser SAF matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Server based upon the results by setting values for specified variables. See match-browser.
Applicable in NameTrans-class directives.
The ntrans-dav function determines whether a request should be handled by the WebDAV subsystem and if so, adds a dav object to the pipeline.
The following table describes parameters for the ntrans-dav function.
Table 4–12 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. |
NameTrans fn="ntrans-dav" name="dav" |
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 4–13 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 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 4–14 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 4–15 redirect Parameters
Parameter |
Description |
---|---|
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 Server 6.1 SP7 NSAPI Programmer’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 all stage directives. The set-variable SAF enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands. 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 4–16 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 4–17 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 |