Appendix C
Proxy Configuration Files
This appendix describes the directives and functions in the configuration files that iPlanet Web Proxy Server uses. You can configure iPlanet Web Proxy Server manually by editing the files directly.
The files that you use to configure the proxy are in a directory called proxy-id/config in your server root directory. Here's a brief description of each file described in this appendix:
magnus.conf is the server's main technical configuration file. It controls aspects of the server operation not related to specific resources or documents, such as host name and port.
obj.conf is the server's object configuration file. It controls access to the proxy server, and determines how documents are proxied and cached.
socks5.conf is a file that contains the SOCKS server configuration. The SOCKS daemon is a generic firewall daemon that controls point-to-point access through the firewall.
bu.conf is an optional file that contains batch update directives. You can use these to update many documents at once. You can time batch updates; for example, you can have them occur during off-peak hours to minimize the effect on the efficiency of the server.
icp.conf is the Internet Cache Protocol (ICP) configuration file. It identifies the information about the parent and sibling servers in a proxy array that uses ICP.
Other files that affect the proxy are explained elsewhere in this book:
mime.types is the file the server uses to convert filename extensions such as .GIF into a MIME type like image/gif. This file is described in Chapter 16, "Configuring the Proxy Manually."
admpw is the administrative password file. Its format is user:password. The password is DES-encrypted just like /etc/passwd. This file is described in Chapter 16, "Configuring the Proxy Manually." The admpw file is located in the admserv directory.
autoconfig is a file in Netscape Navigator 2.0 JavaScript software that enables you to specify when to use the proxy. This file is described in Chapter 11, "Using the Client Autoconfiguration File."
parray.pat is the Proxy Array Table file. The PAT file is an ASCII file used in proxy to proxy routing. It contains information about a proxy array; including the members' machine names, IP addresses, ports, load factors, cache sizes, etc. For more information on the syntax of the parray.pat file, see "The parray.pat File," on page 274.
parent.pat is the Proxy Array Table file that contains information about an upstream proxy array. For more information on the syntax of the parent.pat file, see "The parent.pat File," on page 275.
The magnus.conf File
For each directive, this section provides the directive's characteristics, including the directive name, description, format for the value string, default value if the directive is omitted, and how many times the directive can be in the file. The directives are:
Certfile specifies the location of the certificate file.
Ciphers specifies which ciphers are enabled for your server.
DNS specifies if the server does DNS lookups on clients who access the server.
ErrorLog specifies the directory where the server logs its errors.
Keyfile specifies the location of the key file.
LDAPConnPool specifies the number of persistent connections to the LDAP directory.
LoadObjects specifies a startup object configuration file.
MaxProcs sets the maximum number of active processes.
PidLog specifies a file to record the proxy's main process ID (pid).
Port defines the TCP port to which the server listens.
ProcessLife specifies the number of requests each child process serves during its lifetime.
RootObject defines the default server object.
Security specifies whether SSL is enabled or disabled.
ServerName defines the proxy host name.
SSLClientAuth requires that client authentication be done for every request.
SSL2 specifies whether SSL 2.0 is enabled or disabled.
SSL3 specifies whether SSL 3.0 is enabled or disabled.
SSL3Ciphers specifies which encryption schemes are enabled.
User specifies the proxy's Unix user account.
Certfile
The Certfile directive specifies where the certificate file is located.
Syntax
certfile [filename]
certfile is the server's certificate file, specified as a relative path from the server root or as an absolute path.
Ciphers
The Ciphers directive specifies the ciphers enabled for your server. For a discussion of the pros and cons of these ciphers, see Chapter 14, "Understanding Encryption and SSL."
Syntax
Ciphers +rc4 +rc4export -rc2 -rc2export +idea +des +desede3
A + means the cipher is active, and a - means the cipher is inactive.
Valid ciphers are rc4, rc4export, rc2, rc2export, idea, des, desede3. Any cipher with export as port of its name is not stronger than 40 bits.
DNS
The DNS directive specifies whether the server performs DNS lookups on clients accessing the server. When a client connects to your server, the server knows the client's IP address but not its host name (for example, it knows the client as 198.95.251.30, rather than its host name www.a.com). The server will resolve the client's IP address into a host name for operations like access control, CGI, error reporting, and access logging.
If your server responds to many requests per day, you might want (or need) to stop host name resolution; doing so can reduce the load on the DNS or NIS server.
Syntax
DNS [on|off]
Default
DNS host name resolution is on as a default.
ErrorLog
The ErrorLog directive specifies the directory where the server logs its errors. You can also use the syslog facility. If errors are reported to a file (instead of syslog), then the file and directory in which the log is kept must be writable by whatever user account the server runs as.
Syntax
ErrorLog logfile
logfile can be a full path and filename or the keyword SYSLOG (which must be in all capital letters).
Keyfile
The Keyfile directive tells the server where the key file is located.
Syntax
keyfile [filename]
keyfile is the server's key file, specified as a relative path from the server root or as an absolute path.
LDAPConnPool
The LDAPConnPool Directive specifies the number of persistent connections to maintain to the LDAP directory server. Creating these connections and binding to the directory on each one is an expensive operation. This setting establishes a reasonably sized pool of connections that will be shared among the proxy's request handler threads. Increase this value to allow more connections and to improve proxy performance if your directory server is not overloaded. Decrease the value if your directory server is very busy.
The default value for LDAPConnPool is 5.
LoadObjects
The LoadObjects directive specifies one or more object configuration files to use on startup; these files tell the server the kinds of URLs to proxy and cache. If any User directive is in the magnus.conf file, it must appear before the LoadObjects directive.
Although you can have more than one object configuration file, the proxy's administration forms work with only one file and assume that it is in the server root in proxy-id/config/obj.conf. If you use the online forms (or plan to), don't put the obj.conf file in any other directory and don't rename it.
Syntax
LoadObjects filename
filename is either the full pathname or a relative pathname. Relative pathnames are resolved from the directory specified with the -d command line flag. If no -d flag is given, the server looks in the current directory.
MaxProcs
The MaxProcs directive sets the maximum number of processes the server can have active. The MaxProcs number is the number of processes that the proxy is to constantly keep active.
When you change MaxProcs, you must do a hard restart for the change to take effect.
Choose a number that is appropriate for the volume of access you expect for the proxy server. If this number is too small, clients will experience delays. If the number is too large, you might waste resources that other programs could use.
Syntax
MaxProcs number
number is a whole number between 1 and the size of your system's process table.
Default
MaxProcs 50
PidLog
The PidLog directive specifies a file in which to record the process ID (pid) of the base proxy server process. Some of the server support programs (including the forms-based iPlanet Web Proxy Server Manager) assume that the pid log is in the server root, in logs/pid.
To shut down your server, kill the base server process listed in the pid log file by using a -TERM signal. To tell your server to reread its configuration files and reopen its log files, use kill with the -HUP signal.
If the pid log file isn't writable by the user account that the server uses, the server does not log its process ID anywhere.
Syntax
PidLog file
file is the full pathname and filename where the process ID is stored.
Port
The Port directive controls to which TCP port the server listens. If you choose a port number less than 1024, the server must be started as root or superuser. The port you choose also affects how the proxy users configure their browsers (they must specify the port number when accessing the proxy server). There should be only one Port directive in magnus.conf.
There are no official port numbers for proxy servers, but two commonly used numbers are 8080 and 8000. If you use iPlanet Web Proxy Server's SOCKS daemon feature, the proxy should use the standard SOCKS port (1080).
Syntax
Port number
number is a whole number between 0 and 65535.
Default
Port 8080
ProcessLife
The ProcessLife directive specifies the number of requests that each of the proxy's child processes serves before the processes exit and get respawned. When the processes are stopped and restarted, the memory they use is freed and then reused.
Syntax
ProcessLife number
number is how many requests each child process serves before the processes exit and get respawned.
Default
ProcessLife 1024
By stopping and restarting a process, the proxy ensures that memory isn't wasted by "lost" processes. For example, on rare occasions, when a connection is terminated by the client or the remote server while the proxy is processing the request, the request fails and some part of allocated memory isn't freed. ProcessLife ensures that the memory is eventually freed.
RootObject
The RootObject directive tells the server which object loaded from an object file is the server default. The default object is expected to have all of the name translation directives for the server; any server behavior that is configured in the default object affects the entire server.
If you specify an object that doesn't exist, the server doesn't report an error until a client tries to retrieve a document.
Syntax
RootObject name
name is the name of an object defined in one of the object files loaded with a LoadObjects directive.
Default
There is no default if you do not specify a root object name; even if it is the "default" named object, you must specify "default." The administration forms assume you will use the default named object. Don't deviate from this convention if you plan to use the online forms.
Security
The Security directive tells the server whether encryption (Secure Sockets Layer version 2 or version 3 or both) is enabled or disabled.
If Security is set to on, and both SSL2 and SSL3 are enabled, then the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.
Syntax
Security on|off
Default
By default, security is off.
ServerName
The ServerName directive tells the server what to put in the host name section of any URLs it sends back to the client. This affects redirections that you have set up using the online forms. Combined with the port number, this name is what all clients use to access the server.
You can have only one ServerName directive in magnus.conf.
Syntax
ServerName host
host is a fully qualified domain name such as myhost.netscape.com.
Default
If ServerName isn't in magnus.conf, the proxy server attempts to derive a host name through system calls. If they don't return a qualified domain name (for example, they get myhost instead of myhost.netscape.com), the proxy server won't start, and you'll get a message telling you to set this value manually, meaning put a ServerName directive in your magnus.conf file.
SSLClientAuth
The SSLClientAuth directive causes SSL3 client authentication on all requests.
Syntax
SSL3ClientAuth on|off
on directs that SSL3 client authentication be performed on every request, independent of ACL-based access control.
SSL2
The SSL2 directive tells the server whether Secure Sockets Layer, version 2 encryption is enabled or disabled. The Security directive dominates the SSL2 directive; if SSL2 encryption is enabled but the Security directive is set to off, then it is as though SSL2 were disabled.
Syntax
SSL2 on|off
Default
By default, security is off.
SSL3
The SSL3 directive tells the server whether Secure Sockets Layer, version 3 security is enabled or disabled. The Security directive dominates the SSL3 directive; if SSL3 security is enabled but the Security directive is set to off, then it is as though SSL3 were disabled.
Syntax
SSL3 on|off
Default
By default, security is off.
SSL3Ciphers
The SSL3Ciphers directive specifies the SSL3 ciphers enabled for your server.
Syntax
SSL3Ciphers +rc4 +rc4export -rc2 -rc2export +idea +des +desede3
A + means the cipher is active, and a - means the cipher is inactive.
Valid ciphers are rsa_rc4_128_md5, rsa3des_sha, rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, and rsa_null_md5. Any cipher with 40 as part of its name is 40 bits.
User
The User directive specifies the Unix user account for the proxy server. If the proxy is started by the superuser or root user, the server binds to the port you specify and then switches its user ID to the user account specified with the User directive. This directive is ignored if the server isn't started as the superuser. The User directive must occur before any LoadObjects directive.
The user account you specify should have write permission to the proxy server's root and cache directories. The user account doesn't need any special privileges. Although you can use the nobody user for Unix proxy servers, it isn't recommended, and it will not work on some systems, such as HP-UX.
Syntax
User login
login is the eight-character (or fewer) login name for the user account.
Default
If there is no User directive, the server runs with the user account with which it was started. If the server was started as root or superuser, you'll see a warning message after startup.
The obj.conf File
This section defines the obj.conf directives and describes their characteristics, including the directive name and description, format for the function string, default value if the directive is omitted, and how many instances of the directive can be in the file. The directives are:
AddLog adds log entries to any log files.
AuthTrans protects server resources from specific users.
Connect provides a hook for you to call a custom connection function.
DNS calls a custom DNS function you specify.
Error sends customized error messages to clients.
Filter provides content-filtering hooks for functions such as virus detection.
Init (a special directive) initializes server subsystems.
NameTrans maps URLs to mirror sites and the local file system.
ObjectType tags additional information to requests.
PathCheck checks URLs after NameTrans.
Service sends data and completes the requests.
AddLog
After the request is finished and the proxy server has stopped sending to and receiving from the client, the proxy server logs the transaction. The proxy server records information about every time a client tries to gain access to the content server through the proxy, and it records information about the client making the request.
If an object has more than one AddLog directive, all are used.
The AddLog directive works with the log file function init-clf in the Init directive. For example, you could create three separate log files using the init-clf function:
Init fn=init-clf
log1=/usr/ns-home/logs/log-one
log2=/usr/ns-home/logs/log-two
log3=/usr/ns-home/logs/log-three
Later, you can refer to symbolic names log1, log2, and log3 from the AddLog fn=proxy-log function:
AddLog fn=proxy-log name=log1
In some other <Object> you could have this command to record those accesses in another log file:
AddLog fn=proxy-log name=log2
To log only the IP address of the client, and not the DNS name, the AddLog
fn-flex-log function takes one more optional parameter: iponly=1. This optional parameter saves CPU cycles because the DNS name of the client host doesn't have to be resolved by contacting the DNS server:
AddLog fn=flex-log name=log3 iponly=1
If the name parameter is left out, it defaults to global. The following are equivalent:
AddLog fn=flex-log
AddLog fn=flex-log name=global
This function initializes the URL database; it specifies whether to cache URLs and, if so, the directory where they will be contained.
To log URLs, the AddLog fn=urldb-record function has to be called for each object ("<Object>") for which URL recording is desired. Also, the init-urldb function of the Init directive status has to be on. If the init-urldb status is off, URLs will not be recorded even if the AddLog fn=urldb-record function is called. URLs for documents that don't get cached will not be recorded in the URL database.
flex-log (starting proxy logging)
The flex-log function is an AddLog function that records request-specific data in the flexible, common, extended (used by most HTTP servers), or extended-2 log format. There are a number of free statistics generators for the common format, but the extended format gives more detailed information about the bytes transferred and the time elapsed. The extended-2 format provides as much information as the extended format, with additional kinds of information: the route through which the document was received as well as the finish status for the remote connection, the client connection, and the cache.
The log format is specified by the init-proxy function call, described in "init-proxy (starting the network software for proxy)".
Syntax
AddLog fn=proxyflex-log
name=name iponly
Parameters
name (optional) gives the name of a log file, which must have been given as a parameter to the init-clf function of the Init directive. If no name is given, global is the default.
iponly (optional) instructs the server not to look up the host name of the remote client but to record the IP address instead. The value of iponly can be anything, as long as it exists; the online forms set iponly="1".
Example
# Log all accesses to the central log file
AddLog fn=flex-log
# Log non-local accesses to another log file
<Client ip=*~198.93.9[2345].*>
AddLog fn=flex-log name=nonlocal
</Client>
AuthTrans
AuthTrans is the Authorization Translation directive. Server resources can be protected so that accessing them requires the client to provide certain information about the person using the client program. This authorization information is "encoded" to prevent clients from authorizing themselves as different users.
The server analyzes the authorization of client users in two steps. First, it translates authorization information sent by the client, and then it requires that such authorization information be present. This is done in the hope that multiple translation schemes can be easily incorporated, as well as providing the flexibility to have resources that record authorization information but do not require it.
If there is more than one AuthTrans directive in an object, all functions will be applied. The AuthTrans directive has a function called proxy-auth.
proxy-auth (translating proxy authorization)
The proxy-auth function of the AuthTrans directive translates authorization information provided through the basic proxy authorization scheme. This scheme is similar to the HTTP authorization scheme but doesn't interfere with it, so using proxy authorization doesn't block the ability to authenticate to the remote server.
This function is usually used with the PathCheck fn=require-proxy-auth function.
Syntax
AuthTrans fn=proxy-auth auth-type=basic
dbm=full path name
AuthTrans fn=proxy-auth auth-type=basic
userfile=full path name
grpfile=full path name
Parameters
auth-type specifies the type of authorization to be used. The type should be "basic" unless you are running a Unix proxy and are going to use your own function to perform authentication.
dbm specifies the full path and base filename of the user database in the server's native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to billions of users. If you use this parameter, don't use the userfile parameter.
userfile specifies the full pathname of the user database in the NCSA-style httpd user file format. This format consists of name:password lines where password is encrypted. If you use this parameter, don't use dbm.
grpfile (optional) specifies the NCSA-style httpd group file to be used. Each line of a group file consists of group:user1 user2...userN, where each user is separated by spaces.
Example
A Unix example:
AuthTrans fn=proxy-auth auth-type=basic
dbm=/usr/ns-home/proxy-EXAMPLE/userdb/rs
A Windows NT example:
AuthTrans fn=proxy-auth auth-type=basic
userfile=\netscape\server\proxy-EXAMPLE\.htpasswd
grpfile=\netscape\server\proxy-EXAMPLE\.grpfile
It is possible to have authentication be performed by a user-provided function by passing the user-fn parameter to the proxy-auth function.
Syntax
AuthTrans fn=proxy-auth auth-type=basic
user-fn=your function
userdb=full path name
Parameters
user-fn specifies the name of the user-provided function that will be used to perform authentication in place of the built-in authentication. If authentication succeeds, the function should return REQ-PROCEED and if authentication fails, it should return REQ-NOACTION.
userdb specifies the full path and base filename of the user database in the server's native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to billions of users.
Connect
The Connect directive calls the connect function you specify.
Syntax
Connect fn=your-connect-function
Only the first applicable Connect function is called, starting from the most restrictive object. Occasionally it is desirable to call multiple functions (until a connection is established). The function returns REQ_NOACTION if the next function should be called. If it fails to connect, the return value is REQ_ABORT. If it connects successfully, the connected socket descriptor will be returned.
The Connect function must have this prototype:
int your_connect_function(pblock *pb, Session *sn, Request *rq);
Connect gets its destination host name and port number from:
rq->host (char *)
rq->port (int)
The host can be in a numeric IP address format.
To use the NSAPI custom DNS class functions to resolve the host name, make a call to this function:
struct hostent *servact_gethostbyname(char *host name, Session *sn,
Request *rq);
Example
This example uses the native connect mechanism to establish the connection:
#include "base/session.h"
#include "frame/req.h"
#include <ctype.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
int my_connect_func(pblock *pb, Session *sn, Request *rq)
{
struct sockaddr_in sa;
int sd;
memset(&sa, 0, sizeof(sa));
sa.sin_family = AF_INET;
sa.sin_port = htons(rq->port);
/* host name resolution */
if (isdigit(*rq->host))
sa.sin_addr.s_addr = inet_addr(rq->host);
else
{
struct hostent *hp = servact_gethostbyname(rq->host, sn, rq);
if (!hp)
return REQ_ABORTED; /* can't resolv */
memcpy(&sa.sin_addr, hp->h_addr, hp->h_lenght);
}
/* create the socket and connect */
sd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
if (sd == -1)
return REQ_ABORTED; /* can't create socket */
if (connect(sd, (struct sockaddr *)&sa, sizeof(sa)) == -1) {
close(sd);
return REQ_ABORTED; /* can't connect */
}
return sd; /* ok */
}
DNS
The DNS directive calls either the dns-config built-in function or a DNS function that you specify.
dns-config (suggest treating certain host names as remote)
Syntax
DNS fn=dns-config local-domain-levels=<n>
local-domain-levels specifies the number of levels of subdomains that the local network has. The default is 1.
iPlanet Web Proxy Server optimizes DNS lookups by reducing the times of trying to resolve hosts that are apparently fully qualified domain names but which DNS would otherwise by default still try to resolve relative to the local domain.
For example, suppose you're in the netscape.com domain, and you try to access the host www.xyzzy.com. At first, DNS will try to resolve:
www.xyzzy.com.netscape.com
and only after that the real fully-qualified domain name:
www.xyzzy.com
If the local domain has subdomains, such as corp.netscape.com, it would do the two additional lookups:
www.xyzzy.com.corp.netscape.com
www.xyzzy.com.netscape.com
To avoid these extra DNS lookups, you can suggest to the proxy that it treat host names that are apparently not local as remote, and it should tell DNS immediately not to try to resolve the name relative to the current domain.
If the local network has no subdomains, you set the value to 0. This means that only if the host name has no domain part at all (no dots in the host name) will it be resolved relative to the local domain. Otherwise, DNS should always resolve it as an absolute, fully qualified domain name.
If the local network has one level of subdomains, you set the value to 1. This means that host names that include two or more dots will be treated as fully qualified domain names, and so on.
An example of one level of subdomains would be the netscape.com domain, with subdomains:
corp.netscape.com
engr.netscape.com
mktg.netscape.com
This means that hosts without a dot, such as step would be resolved with respect to the current domain, such as engr.netscape.com, and so the dns-config function would try this:
step.engr.netscape.com
If you are on corp.netscape.com but the destination host step is on the engr subdomain, you could say just:
step.engr
instead of having to specify the fully qualified domain name:
step.engr.netscape.com
your-dns-function (a plug-in dns function you create)
This is a DNS-class function that you define.
Syntax
DNS fn=your-dns-function
Only the first applicable DNS function is called, starting from the most restrictive object. In the rare case that it is desirable to call multiple DNS functions, the function can return REQ_NOACTION.
The DNS function must have this prototype:
int your_dns_function(pblock *pb, Session *sn, Request *rq);
The DNS function looks for its parameter host name from:
rq->host (char *)
and it should place the resolved result into:
rq->hp (struct hostent *)
The struct hostent * will not be freed by the caller but will be treated as a pointer to a static area, as with the gethostbyname call. It is a good idea to keep a pointer in a static variable in the custom DNS function and on the next call either use the same struct hostent or free it before allocating a new one.
The DNS function returns REQ_PROCEED if it is successful, and REQ_NOACTION if the next DNS function (or gethostbyname, if no other applicable DNS class functions exist) should be called instead. Any other return value is treated as failure to resolve the host name.
Example
This example uses the normal gethostbyname call to resolve the host name:
#include "base/session.h"
#include "frame/req.h"
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
int my_dns_func(pblock *pb, Session *sn, Request *rq)
{
rq->hp = gethostbyname(rq->host);
if (rq->hp)
return REQ_PROCEED;
else
return REQ_ABORTED;
}
Error
At any time during a request, conditions can occur that cause the server to stop fulfilling a request and to return an error to the client. When this happens, the server can send a short HTML page to the client, very generically describing the error.
To help you make error handling more user friendly, the proxy server lets you intercept certain errors and send a file with your customized error message in place of the server's default error message. You can create an HTML file containing the error message you want to send and associate that message with an error.
Syntax
Error fn=send-error code=code path=path
code is the error code for the default error message, as listed below.
path is the full path to the HTML file containing the message you want to send.
The following are errors returned by the server. Each error has a three-digit HTTP code that designates it, followed by a short description of the error. The description might help you write your custom error message.
401 Unauthorized (for administration forms only). The server requires HTTP user authorization to allow access to the administration forms, and either the client provided none or its HTTP authorization was insufficient.
403 Forbidden. The server tried to access a file or directory and found that the user it was running as didn't have sufficient permission to access the file.
404 Not Found. The client asked for a file system path that doesn't exist or the server was configured to tell the client that it doesn't exist. If you use access control, changing the response to this error lets you tell people nicely that they don't have that access to your proxy.
407 Proxy Authorization Required. The proxy requires proxy authorization, and either the client didn't provide any or it was insufficient. Also, the client software might not support proxy authorization. Netscape Navigator version 1.1 or newer supports this authorization.
500 Server Error. Server errors mean that an error has occurred in the server that prevents it from finishing the request. Server errors mainly happen because of misconfiguration or machine resources such as swap space being exhausted.
Example
Error fn=send-error Code=401
path=/usr/ns-home/proxy-EXAMPLE/errors/401.html
Filter
The Filter directive runs an external command and then pipes the data through the external command before processing that data in the proxy. This is accomplished using the pre-filter function. The format of the Filter directive is as follows:
Syntax
Filter fn="pre-filter" path="/your/filter/prog"
The Filter directive performs these tasks:
It runs the program /your/filter/prog as a separate process.
It establishes pipes between the proxy and the external program.
It writes the response data from the remote server to the stdin of the external program.
It reads the stdout of the program as if it were the response generated by the server.
This is equivalent to this command:
Filter fn="pre-filter"
path="/your/filter/prog"
headers="stdin"
Init
Init is a special directive that initializes certain proxy subsystems such as the networking library, caching module, and access logging. The functions referenced with the Init directive load data for specific subsystems once on server startup and keep that data internally until the server is shut down.
Init lines can contain spaces at the beginning of the line and between the directive and value, but you shouldn't have spaces after the value because they might confuse the server. Long lines (although probably not necessary) can be continued with a backslash (\) continuation character before the line feed.
|
Caution
|
If you are using iPlanet Web Proxy Server Manager online forms, you shouldn't use continuation lines in the obj.conf file. Instead, put each Init configuration entirely on a single line. If you are absolutely sure you will never use the online forms to edit the obj.conf file, you can use the \ character.
|
Syntax
Init fn=function-name [parm1=value1]...[parmN=valueN]
function-name identifies the server initialization function to call. These functions shouldn't be called more than once.
parm=value pairs are values for function-specific parameters. The number of parameters depends on the function you use. The order of the parameters doesn't matter. The functions of the Init directive listed here are described in detail in the following sections.
flex-init initializes the flex-log flexible access logging feature
icp-init initializes the ICP feature.
init-batch-update initializes the batch update feature.
init-cache enables and initializes caching.
init-clf initializes the Common Log File subsystem.
init-dns-cache enables and initializes dns caching.
init-partition initializes the partitions.
init-proxy initializes the networking code used by the proxy.
init-proxy-auth tells proxy how to authenticate itself.
init-proxy-certs loads a default certificate database on startup.
init-sockd enables and initializes the SOCKD feature.
init-urldb initializes the URL database that you specify.
load-modules tells the server to load functions from a shared object file.
load-types maps file extensions to MIME types.
Init function order in obj.conf
The Init functions are a series of steps that the server has to follow in order for the proxy to run. Each function depends on the results of the one before it:
Start the proxy.
Start the proxy's cache.
Initialize the partitions inside the cache.
Initialize the batch update process (which might be updating what's inside the partitions).
|
Note
|
In obj.conf, the order of certain init- functions is crucial. These functions must occur in the order shown here:
Init fn=init-proxy ...
Init fn=init-cache ...
Init fn=init-partition ...
Init fn=init-batch-update ...
|
Calling Init functions
Some functions of the Init directive are crucial to proxy functioning and must be called once and only once. Others are optional but must be called no more than once, and some are optional and can be called many times. They are shown in Table C-1.
Table C-1 Calling functions of the Init directive.
|
Function
|
Crucial, call just once
|
Optional, call just once
|
Optional, call many times
|
|
flex-init
|
|
X
|
X
|
|
icp-init
|
|
X
|
|
|
init-batch-update
|
|
X
|
|
|
init-cache
|
|
X
|
|
|
init-clf
|
X
|
|
|
|
init-dns-cache
|
|
X
|
|
|
init-partition
|
|
|
X
|
|
init-proxy
|
X
|
|
|
|
init-proxy-auth
|
|
X
|
|
|
init-proxy-certs
|
|
X
|
|
|
init-sockd
|
|
X
|
|
|
load-modules
|
|
|
X
|
|
load-types
|
X
|
|
|
|
pa-init-parent-array
|
|
X
|
|
|
pa-init-proxy-array
|
|
X
|
|
flex-init (starting the flex-log access logs)
The flex-init function initializes the flexible logging system. It opens the log file whose name is passed as a parameter and establishes a record format that is passed as another parameter. The log file stays open until the server is shut down, or for Unix proxies, until the base server process is sent the -HUP signal (at which time all logs are closed and reopened).
You use flex-init to specify a log filename (such as
loghttp=/var/ns-server/loghttp); then you use that name with the flex-log function in the obj.conf file to add a log entry to the file (such as AddLog fn=flex-log name=loghttp).
|
Note
|
You can use AddLog to store transactions in more than one log file.
|
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or back up a log file on a Unix proxy, you need to rename the file and then send the -HUP signal to restart the server. The server uses the inode number, but when you do a soft restart, the server first looks for the filename, and if it doesn't find the log file, it creates a new one (the renamed original log file is left for you to use).
Parameters
The flex-init function recognizes two possible parameters: one that names the log file and one that specifies the components of a record in that file.
The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in your program. (The one exception to this rule is the %SYSDATE% component, which delivers the current system date.)
Any additional text is treated as literal text, so you can add to the line to make it more readable. Typical components of the formatting parameter are listed in Table C-1. Certain components might contain spaces, so they should be bounded by escaped quotes (/").
Table C-2 Options for flex-logging
|
Flex-log option
|
Component
|
Escaped
|
|
Client host name
|
%Ses->client.ip%
|
|
|
Authenticate user name
|
%Req->vars.auth-user%
|
|
|
System date
|
%SYSDATE%
|
|
|
Full request
|
/"%Req->reqpb.proxy-request%/"
|
Yes
|
|
Status
|
%Req->srvhdrs.clf-status%
|
|
|
Content length
|
%Req->vars.p2c-cl%
|
|
|
Referer
|
/"%Req->headers.referer%/"
|
Yes
|
|
User-agent
|
/"%Req->headers.user-agent%/"
|
Yes
|
|
Method
|
%Req->reqpb.method%
|
|
|
URI
|
%Req->reqpb.uri%
|
|
|
Query string of the URI
|
%Req->reqpb.query%
|
|
|
Protocol
|
/"%Req->reqpb.protocol%/"
|
Yes
|
|
Accept header
|
%Req->headers.accept%
|
|
|
Date header
|
/"%Req->headers.date%/"
|
Yes
|
|
"If Modified Since" header
|
%Req->headers.if-modified-since%
|
|
|
Authorization
|
%Req->headers.authorization%
|
|
|
Cache finish status
|
%Req->vars.cch-status%
|
|
|
Remote server finish status
|
%Req->vars.svr-status%
|
|
|
Client connection finish status
|
%Req->vars.cli-status%
|
|
|
Status code from server
|
%Req->vars.remote-status%
|
|
|
Route to proxy
|
%Req->vars.actual-route%
|
|
|
Transfer time in seconds
|
%Req->vars.xfer-time%
|
|
|
Transfer time in milliseconds
|
%Req->vars.xfer-time-total%
|
|
|
DNS time
|
%Req->vars.xfer-time-dns%
|
|
|
Connect wait time
|
%Req->vars.xfer-time-cwait%
|
|
|
Initial wait time
|
%Req->vars.xfer-time-iwait%
|
|
|
Full wait time
|
%Req->vars.xfer-time-fwait%
|
|
|
Header-length from server response
|
%Req->vars.r2p-hl%
|
|
|
Request header size from proxy to server
|
%Req->vars.p2r-hl%
|
|
|
Response header size sent to client
|
%Req->vars.p2c-hl%
|
|
|
Request header size received from client
|
%Req->vars.c2p-hl%
|
|
|
Content-length from proxy to server request
|
%Req->vars.p2r-cl%
|
|
|
Content-length received from client
|
%Req->headers.content-length%
|
|
|
Content-length from server response
|
%Req->vars.r2p-cl%
|
|
|
Unverified user from client
|
%Req->vars.unverified-user%
|
|
Example
This example for a Unix proxy server initializes flexible logging in to the file /usr/ns-home/proxy-NOTES/logs/access:
Init fn=flex-init access="/usr/ns-home/https-NOTES/logs/access" format.access=
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
/"%Req->reqpb.proxy-request%/"
%Req->srvhdrs.clf-status% %Req->vars.p2c-c1%"
This example for a Windows NT proxy server initializes flexible logging in to the file netscape\server\proxy-NOTES\logs\access:
Init fn=flex-init access="\" format.access=
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
/"%Req->reqpb.proxy-request%/"
%Req->srvhdrs.clf-status% %Req->vars-p2c-c1%"
This will log the following items:
IP or host name, followed by the three characters " - "
the user name, followed by the two characters " ["
the system date, followed by the two characters "] "
the full request, followed by a single space
the full status, followed by a single space
the content length
This is the default format, which corresponds to the Common Log Format (CLF).
The first six elements of any log should always be in exactly this format, because a number of log analyzers expect that as output.
icp-init (initializes ICP)
The icp-init function enables and initializes ICP. ICP (Internet Cache Protocol) is an object location protocol that enables caches to communicate with one another. Caches can use ICP to send queries and replies about the existence of cached URLs and about the best locations from which to retrieve those URLs.
Syntax
Init fn="icp.init"
config_file="file name"
status="on|off"
Parameters
config_file is the name of the ICP configuration file.
status specifies whether ICP is enabled or disabled. Possible values are:
Example
Init fn="icp.init"
config_file="icp.conf"
status="on"
init-batch-update (starting batch updates)
The init-batch-update function starts and specifies a configuration file for batch updating. Batch updating (or similarly, autoloading) is the process of loading frequently requested objects into the proxy cache in anticipation of those requests.
Batch updating is useful for a number of tasks. A proxy administrator might want to perform up-to-date checks during low-usage hours on all the cached objects to avoid doing these checks when usage is heavier. If a site has heavy daytime usage but little in the evening, the batch update could run in the evening. The process can converse with remote servers and update any objects that have been modified.
At larger sites with a network of servers and proxies, you, as the administrator, might want to use autoloading to "inhale" (pre-load into the cache) a given area of the web. You provide an initial URL, and the batch process does a recursive ("worm") descent across links in the document. Because this function can be a burden on remote servers, be careful when using it. Measures are taken to keep the process from performing recursion indefinitely, and the parameters in bu.conf give you some control of this process. You could also use this functionality to update proxies to compensate for any unexpected changes in a company-wide directory index.
Syntax
Init fn=init-batch-update
status=on|off
conf-file="absolute filename"
Parameters
status enables or disables batch updating.
conf-file is the pathname to the batch update (autoload) configuration file.
Example
A Unix example:
Init fn=init-batch-update
status=on
conf-file="/usr/ns-home/java-proxy/config/bu.conf"
A Windows NT example:
Init fn=init-batch-update
status=on
conf-file=""
init-cache (starting the caching system)
The init-cache function enables and initializes the cache and starts the caching system. Calling this function is crucial if you want to use caching; otherwise it is optional and must be called only once.
Syntax
For Unix version:
Init fn=init-cache
status=on|off
dir=directory
ndirs=n
cmon=on|off
Parameters
status enables or disables caching.
on enables caching
off turns caching off
dir specifies a working directory for the proxy's caching module. This is not necessarily the cache directory. To specify directories where cached data is actually stored, use the init-partition function.
cmon enables or disables monitoring of the cache size.
on enables monitoring and is the default
off disables monitoring
Setting cmon to off disables the internal Cache Monitor and Cache Manager processes that the ns-proxy process automatically initiates when caching is enabled. The Cache Monitor process monitors the cache size and when necessary sends a message to the Cache Manager process to trigger garbage collection (cleaning up the cache to allow more space for new cache files). Disabling these internal cache management processes lets you use an external custom program to perform cache management tasks.
Further, setting cmon to off makes it possible for two separate proxy pools to share the same cache. In this situation, only one of the proxies can have cache management enabled, and the other must have it disabled.
ndirs specifies cache capacity as the number of cache sections you want set up for the proxy. The number you specify must be a power of 2, from 1 to 256. This number is related to cache capacity as shown in Table C-3. To determine the number to use, see the capacity entry in Table C-3 for the optimum designed capacity of your machine.
Table C-3 shows the optimum designed capacity, the minimum suggested capacity, and the maximum suggested capacity for each valid number of sections. The optimum capacity for a specific ndir matches the minimum capacity for the next larger ndir and also matches the maximum capacity for the next smaller ndir.
For a small cache size you can set a small cache capacity, although an oversized cache structure is not a problem. If the cache is actually larger than the maximum capacity for the number of sections you specify, its performance could be diminished because of an undersized cache structure, that is, there may not be enough sections.
Table C-3 Cache capacity and the number of sections
|
Optimum
|
Minimum
|
Maximum
|
Number of sections
|
|
125MB
|
0MB
|
250MB
|
1
|
|
250MB
|
125MB
|
500MB
|
2
|
|
500MB
|
250MB
|
1GB
|
4
|
|
1GB
|
500MB
|
2GB
|
8
|
|
2GB
|
1GB
|
4GB
|
16
|
|
4GB
|
2GB
|
8GB
|
32
|
|
8GB
|
4GB
|
16GB
|
64
|
|
16GB
|
8GB
|
32GB
|
128
|
|
32GB
|
16GB
|
64GB
|
256
|
Example
Init fn=init-cache
status=on
dir=/usr/ns-home/cache
ndirs=8
init-dns-cache (starting dns caching)
The init-dns-cache function specifies (when DNS lookups are enabled through a Server Manager setting) that you want to cache the DNS entries. If you cache DNS entries, then when the server gets a client's host name information, it can store the data it receives. Then, if the server needs information about the client in the future, the information is available to the server without querying for the information again.
You can specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries; the default value is 1024 entries. Values for the time it takes for a cache entry to expire can range from 1 second to 1 year (specified in seconds); the default value is 1200 seconds (20 minutes).
Syntax
Init fn=init-dns-cache
cache-size=entries
expire=seconds
visible=yes|no
Parameters
The init-dns-cache function takes two arguments, cache-size and expire.
cache-size specifies how many entries are contained in the cache. Acceptable values for cache-size are 32 to 32768; the default value is 1024.
expire specifies how long it takes for a cache entry to expire. Acceptable values (specified in seconds) for expire are 1 second to 1 year; the default is 1200 seconds (20 minutes).
visible specifies whether the DNS cache file is visible. Possible values include:
Example
Init fn="init-dns-cache"
cache-size="2140"
expire="600"
visible=yes
init-clf (starting the Common Log File subsystem)
The init-clf function initializes the Common Log File subsystem. Use this function to specify which log files the proxy uses to record transactions. Then, use the AddLog directive to specify the log file where the proxy stores the transaction record. For more information on the AddLog directive, see page 421.
|
Note
|
You can use the AddLog directive to store transactions in more than one log file.
|
The init-clf function opens the log files that you specify. The log files stay open until the server is shut down or, for a Unix proxy server, until the base server process is sent the -HUP signal (at which time the logs are closed and re-opened). Initializing this function is required if you are using the log features.
|
Caution
|
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or back up a log file on a Unix proxy, you need to rename the file and then send the -HUP signal to restart the server. The proxy uses the inode number, but when you do a soft restart, the proxy first looks for the filename, and if it doesn't find the log file, it creates a new one (the renamed original log file remains for you to use).
|
Syntax
Init fn=init-clf
global=main log filename
Parameters
global tells the proxy to use this log file by default. This function doesn't have any predefined parameters, just name and pathname pairs in the format <name>=<pathname> where:
Example
Init fn=init-clf
global=\netscape\server\proxy-TEST\logs\access
To open three separate log files, you could use name and pathname pairs like this:
Init fn=init-clf
log1=/usr/ns-home/logs/log-one
log2=/usr/ns-home/logs/log-two
log3=/usr/ns-home/logs/log-three
Later, you can refer to symbolic names log1, log2, and log3 from the AddLog fn=proxy-log function. For details, see AddLog.
init-partition (specifying cache partitions)
The init-partition function specifies the status, location, and size of cache partitions.
Syntax
Init fn=init-partition
status=on|off
dir=directory
max-size=megabytes
min-avail=megabytes
Parameters
status enables or disables the cache partition.
on means that the cache partition is active (in normal use, data is written to and read from that partition).
off means that the cache partition is not in use (cache data mapping to that partition will not be written to or looked up from that partition).
dir is the directory to use as the cache. The cache structure (that is, sections) must exist under that directory (which can be created and maintained through the online forms).
max-size is the optional number for the maximum size, in megabytes, to allow for the cache partition to grow. You can choose not to set size limits by leaving this parameter out.
min-avail is the minimum amount of available space, in megabytes, on the physical partition. This is the actual disk on which the cache partition (defined by the dir parameter) resides. If less space is ever available, the proxy stops caching to that cache partition, even if it hasn't reached the maximum size (max-size). It continues to write to other partitions that are not full. It also notifies the Cache Monitor that the partition is filling up, and the Cache Manager consequently starts to clean up the cache. You can choose not to set the minimum by leaving this parameter out.
Example
Init fn=init-partition
status=on
dir=/usr/ns-home/cache
max-size=2000
min-avail=5
init-proxy (starting the network software for proxy)
The init-proxy function initializes the networking software used by the proxy. Calling this function in obj.conf is crucial (even though it is called automatically, you should call it manually as a safety measure).
Syntax
For Unix version:
Init fn=init-proxy
timeout=<seconds>
timeout-2=seconds
read-timeout=seconds
keep-alive-timeout=seconds
stall-timeout-override=seconds
netlib-timeout=seconds
sig="Some readable name"
anon-pw="e-mail address"
socks-ns="IP address"
Parameters
timeout is the number of seconds of delay allowed between consecutive network packets received from the remote server. If the delay exceeds the timeout, the connection is dropped. The default is 120 seconds (2 minutes). This is not the maximum time allowed for an entire transaction, but the delay between the packets. For example, the entire transaction can last 15 minutes, as long as at least one packet of data is received before each timeout period.
timeout-2 tells the proxy how much time it has to continue writing a cache file after a client has aborted the transaction. In other words, if the proxy server has almost finished caching a document and the client aborts the connection, the proxy can continue caching the document until it reaches the timeout after interrupt value.
To determine the best timeout-2 (timeout after interrupt) value for your proxy server, use sitemon. If sitemon reports that the proxy server is using too much of its process pool, you should reduce your timeout after interrupt accordingly. The highest recommended timeout after interrupt value is 5 minutes.
read-timeout is the number of seconds the proxy server will wait for an incoming request. The default value for this timeout is 60 seconds. Setting the timeout a few seconds shorter will allow proxy resources to be released faster if the connection stays idle (e.g., if you telnet to the proxy port and let it just sit there).
keep-alive-timeout is the number of seconds the proxy server will wait for the next request from a keep-alive connection. The default value for this timeout is 5 seconds. Shorter timeouts let the proxy release resources that are tied up by idle keep-alive connections. Longer timeouts will make keep-alive more effective, but can tie up valuable proxy resources, and thus, bog down the server. You should not use the keep-alive feature because it can easily cause problems when the entire process pool is tied up by idle keep-alive connections. This problem can occur quickly - especially with clients that open multiple simultaneous connections, such as Navigator, which by default, opens 4 connections.
stall-timeout-override should not be changed.
netlib-timeout is the absolute maximum number of seconds that the proxy will wait for any HTTP, FTP, Gopher or HTTPS retrieval. The default value for this timeout is 10800 seconds (3 hours).
sig is the signature (trailer) that the proxy appends to its error messages. By default, it contains the proxy host name and the port number. If your site does not want to send that information out or perhaps gives more descriptive names to proxies, you can use sig to do that.
anon-pw is the email address to send to anonymous FTP servers as the password. This information can be used by FTP sites to later send notifications to people who downloaded files from their FTP site. Using this option overrides the default that the proxy will derive from its current execution environment (which could be, for example, "nobody@your.site").
socks-ns is equivalent to using the SOCKS_NS environment variable in the proxy's execution environment. This tells the proxy the DNS server IP address instead of having the proxy try to derive the default from its environment. This option is useful when the internal DNS server is not capable of resolving external DNS names. It is often necessary when routing the proxy through a SOCKS server.
Example
Init fn=init-proxy
log-format=extended-2
timeout=120
sig="Main proxy gateway"
anon-pw="webmaster@your.site"
socks-ns="123.1.2.3"
init-proxy-auth (specifying the authentication strategy)
The init-proxy-auth function tells the proxy server whether it should require authentication from clients as a proxy, or reverse proxy (web server). If the obj.conf file does not call this function, the server will automatically act as a proxy requiring authentication.
Syntax
Init fn=init-proxy-auth
pac-auth=on|off
Parameters
pac-auth specifies whether local files ( PAC files, local icons, etc.) are password-protected.
Example
Init fn=init-proxy-auth
pac-auth=yes
init-proxy-certs (loading the default certificate
database)
The init-proxy-certs function points the proxy to the default certificate database and loads that file at startup.
Syntax
When you make changes to the certificate database and Initialize Certificates Only is disabled, this line is automatically inserted into the obj.conf file upon restart:
Init fn=init-proxy-certs
certfile=absolute filename
If the proxy is set up to authenticate itself to remote servers by using its certificate, and Initialize Certificates Only is enabled, this line is automatically inserted into the obj.conf file upon restart:
Init fn=init-proxy-certs
security=on|off
keyfile=absolute filename
Parameters
certfile is the absolute filename of the default certificate database.
security enables or disables encryption for the proxy.
keyfile is the absolute filename of the private keyfile for the proxy.
Example
Init fn=init-proxy-certs
certfile="/usr/ns-home/proxy-java-proxy/config/ServerCert"
Init fn=init-proxy-certs
security=on
keyfile="/usr/ns-home/proxy-java-proxy/config/ ServerKey.db"
init-sockd (starting the SOCKD feature)
The init-sockd function enables and initializes iPlanet Web Proxy Server's SOCKD feature. It makes the proxy behave like a SOCKS daemon in addition to its normal tasks.
The SOCKD configuration is done through the normal SOCKD configuration file, /etc/socks5.conf. The same care must be taken as when configuring any other SOCKS daemon.
Syntax
Init fn=init-sockd
status=on|off
sockd-conf=absolute filename
ident-check=none|loose|strict
log-type=common-separate|syslog|syslogseparate
log-name=absolute filename
Parameters
status enables or disables the sockd function.
on means the SOCKD feature is enabled; that is, the proxy will act as a SOCKS server.
off means the SOCKD feature is disabled; same as if the function is left out. SOCKS requests will not be answered by the proxy (an error will be returned to the client).
sockd-conf (optional) specifies the absolute pathname for the SOCKD configuration file to use. The default is /etc/sockd.conf. The format follows the standard SOCKD configuration file format.
ident-check (optional) specifies the type of remote identity checking. The possible values are:
strict means an identity check is required, and if the remote host is not running identd, ("Identity Daemon") the request is denied. The strict identity check is like the "loose" identity check, except that if the remote identity query fails, access will be denied.
loose means an identity check is required, but if the remote host is not running identd, access is granted anyway. Remote identity will be queried from the remote identd, and the given user name will be verified against the one returned by the remote identd. If there's a mismatch, access will be denied. If the remote identity query fails (the remote server's not running identd), access will be granted.
none means no remote identity check is performed. The remote user name will not be queried from the remote identd. The user name given in the SOCKS request will not be verified.
log-type (optional) specifies where the proxy SOCKD module stores the access information. The directive can be one of the following:
common-separate uses the common log format, but puts the entries in a separate log file (the log filename is given in the log-name parameter).
syslog uses the traditional SOCKD format and reports to the syslog facility.
syslog-separate uses the SOCKD syslog format, but instead of syslog, it uses a separate log file as specified by the log-name parameter.
log-name specifies the absolute pathname for a separate log file used for logging SOCKS accesses. This name is required when the log-type is either common-separate or syslog-separate.
Example
Init fn=init-sockd
status=on
sockd-conf=/etc/sockd.conf
ident-check=strict
log-type=syslog
log-name=/d/proxy/logs/sockd.log
init-urldb (setting up the URL database)
The init-urldb function initializes the URL database and it specifies whether to cache URLs. It also identifies the directory where URLs will be contained if they are cached.
Syntax
Init fn=init-urldb
status=on|off
dir=absolute filename
Parameters
status is whether the URL database is enabled or disabled.
on means that URL recording to the URL database is enabled. This database is the one that can be browsed from the administration interface to find out what's actually cached.
-
To log the URLs, the AddLog fn=urldb-record function has to be called for each object ("<Object>") for which URL recording is desired. URLs for documents that don't get cached will never be recorded in this database.
off means that URL recording is disabled. URLs will not be recorded even if the AddLog fn=urldb-record function is called.
dir is the name of the directory containing the URL database. Don't use /tmp because it is cleared at boot time.
Example
Init fn=init-urldb
status=on
dir=/usr/ns-home/cache/urldb
load-modules (loading shared object modules)
You can use the load-modules function to tell the server to load the functions you need from the shared object. Calling the load-modules function is crucial to proxy function.
Unix allows shared libraries, which are archives of multiple functions packed into a single file (with a .so suffix). If you want to link in functions from shared libraries you have created, use this function to pass required information to the server. To do this, you have to tell the main executable where the shared library file resides and the names of the functions to be loaded (which are indexed by name in the .so file).
Binaries referring to functions in the shared libraries you specify dynamically load the individual functions at runtime (without loading the entire library).
To register SAF classes with the server you could use this:
Init fn=load-modules shlib=/your/lib.so funcs=alpha,beta,alpha-beta
where alpha, beta, and alpha-beta represent the functions alpha(), beta(), and alpha_beta() from the shared library /your/lib.so. Note the correlation between hyphens and underscores (where the configuration files use hyphens, C code uses underscores).
You can call those functions as you normally would; for example, to call the C function alpha_beta() you would use:
Connect fn=alpha-beta
Syntax
Init fn=load-modules
shlib=[path]filename.so
funcs="function1, function2, ..., functionN"
Parameters
shlib is the full path and filename of the shared object library containing the functions of interest.
funcs is a list of functions in the shared library to be dynamically loaded.
Example
A Unix example:
Init fn=load-modules
shlib=/u/myfolder/func.so
funcs="func1, func2"
A Windows NT example:
Init fn=load-modules
shlib= funcs="func1, func2"
load-types (loading MIME-type mappings)
The load-types function scans a file that tells it how to map filename extensions to MIME types. MIME types are essential for network navigation software like Netscape Navigator to tell the difference between file types. For example, they are used to tell an HTML file from a GIF file. See "The mime.types File," on page 269 for more information.
Calling this function is crucial if you use iPlanet Web Proxy Server Manager online forms or the FTP proxying capability.
Syntax
Init fn=load-types
mime-types="mime.types"
This function loads the MIME type file mime.types from the configuration directory (the same directory as magnus.conf and obj.conf). This function call is mandatory and in practice is always as shown in the syntax.
Parameters
mime-types specifies either the full path to the global MIME types file or a filename relative to the server configuration directory. The proxy server comes with a default file called mime.types.
local-types is an optional parameter to a file with the same format as the global MIME types file, but it is used to maintain types that are applicable only to your server.
Example
Init fn=load-types mime-types=mime.types
Init fn=load-types mime-types=/tp/mime.types \
local-types=local.types
pa-init-parent-array (initializing a parent array member)
The pa-init-parent-array function initializes a parent array member and specifies information about the PAT file for the parent array of which it is a member.
|
Note
|
The load modules directive should come before the pa-init-proxy-array function in the obj.conf file.
|
Syntax
Init fn=pa-init-parent-array
set-status-fn=pa-set-member-status
poll="yes|no"
file="absolute filename"
pollhost="host name"
pollport="port number"
pollhdrs="absolute filename"
pollurl="url"
status="on|off"
Parameters
set-status-fn specifies the function that sets the status for the member.
poll tells the array member whether or not it needs to poll for a PAT file.
yes means that the member should poll for the PAT file. A member should only poll for a PAT file if it is not the master proxy. The master proxy has a local copy of the PAT file, and therefore, does not need to poll for it.
no means that the member should not poll for the PAT file. A member should not poll for the PAT file if it is the master proxy.
file is the full pathname of the PAT file.
pollhost is the host name of the proxy to be polled for the PAT file. This parameter only needs to be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
pollport is the port number on the pollhost that should be contacted when polling for the PAT file. This parameter only needs to be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
pollhdrs is the full pathname of the file that contains any special headers that must be sent with the HTTP request for the PAT file. This parameter is optional and should only be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
pollurl is the URL of the PAT file to be polled for. This parameter only needs to be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
status specifies whether the parent array member is on or off.
Example
The following example tells the member not to poll for the PAT file. This example would apply to a master proxy.
Init fn=pa-init-parent-array
poll="no"
file="c:/netscape/server/bin/proxy/pa1.pat"
The following example specifies that the member should poll for a PAT file. This member is not the master proxy.
Init fn=pa-init-parent-array
poll="yes"
file="c:/netscape/server/bin/proxy/pa2.pat"
pollhost="proxy1"
pollport="8080"
pollhdrs="c:/netscape/server/proxy-name/parray/pa2.hdr"
status="on"
set-status-fn=set-member-status
pollurl="/pat"
pa-init-proxy-array (initializing a proxy array member)
The pa-init-proxy-array function initializes a proxy array member and specifies information about the PAT file for the array of which it is a member.
|
Note
|
The load modules directive should come before the pa-init-proxy-array function in the obj.conf file.
|
Syntax
Init fn=pa-init-proxy-array
set-status-fn=pa-set-member-status
poll="yes|no"
file="absolute filename"
pollhost="host name"
pollport="port number"
pollhdrs="absolute filename"
pollurl="url"
status="on|off"
Parameters
set-status-fn specifies the function that sets the status for the member.
poll tells the array member whether or not it needs to poll for a PAT file.
yes means that the member should poll for the PAT file. A member should only poll for a PAT file if it is not the master proxy. The master proxy has a local copy of the PAT file, and therefore, does not need to poll for it.
no means that the member should not poll for the PAT file. A member should not poll for the PAT file if it is the master proxy.
file is the full pathname of the PAT file.
pollhost is the host name of the proxy to be polled for the PAT file. This parameter only needs to be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
pollport is the port number on the pollhost that should be contacted when polling for the PAT file. This parameter only needs to be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
pollhdrs is the full pathname of the file that contains any special headers that must be sent with the HTTP request for the PAT file. This parameter is optional and should only be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
pollurl is the URL of the PAT file to be polled for. This parameter only needs to be specified if the poll parameter is set to yes, meaning that the member is not the master proxy.
status specifies whether the parent array member is on or off.
Example
The following example tells the member not to poll for the PAT file. This example would apply to a master proxy.
Init fn=pa-init-proxy-array
poll="no"
file="c:/netscape/server/bin/proxy/pa1.pat"
The following example specifies that the member should poll for a PAT file. This member is not the master proxy.
Init fn=pa-init-proxy-array
poll="yes"
file="c:/netscape/server/bin/proxy/pa2.pat"
pollhost="proxy1"
pollport="8080"
pollhdrs="c:/netscape/server/proxy-name/parray/pa2.hdr"
status="on"
set-status-fn=set-member-status
pollurl="/pat"
tune-proxy (tuning server performance)
The tune-proxy function allows you to tune the performance of your proxy server.You should not change the default settings unless directed to do so by iPlanet Technical Support.
Syntax
Init fn=tune-proxy
byte-ranges=on|off
single-accept= (do not change)
ftp-listing-width=number
Parameters
byte-ranges determines whether or not the proxy is allowed to generate byte-range responses from the cache. By default, this feature is disabled. This version of the proxy server supports single byte-ranges only.
|
Note
|
Applications which require multiple byte ranges, such as Adobe Acrobat, may see problems when this feature is enabled. If you are not using such applications, enabling this feature will allow faster truncated document/image retrievals by Navigator clients. Possible values are:
|
single-accept should not be changed.
ftp-listing-width is the maximum number of characters allowed for filenames in the FTP listing. The default is 80.
Example
Init fn=tune-proxy
byte-ranges=off
single-accept=(do not change)
ftp-listing-width=80
tune-cache (tuning cache performance)
The tune-cache function allows you to tune the performance of your proxy server's cache. You should not change the default settings unless directed to do so by iPlanet Technical Support.
Syntax
Init fn=tune-cache
cch-status=DO-NOT-CACHE|NON-CACHEABLE|NOT-IN-CACHE
mmap-wr=on|off
mmap-rdwr=on|off
shmem-io=on|off
notify-num-changes=number
notify-blk-limit=number
cmon-tick-interval=(do not change)
mmap-max=kilobytes
min-sync-interval=seconds
notify-block-chunk-per-proc=blocks
cache-fs-full-retry-after=number
update-after-percent=percentage
sync-dump-ticks=(do not change)
cch-status determines whether to use additional cache status values in the access log. Possible values are:
DO-NOT-CACHE - pre-determined non-cacheable (by configuration)
NON-CACHEABLE - post-determined non-cacheable (by response fields)
NOT-IN-CACHE - with disconnected operation, cache miss
mmap-wr determines whether to use mmap or lseek+write to create the initial CIF header. By default, this value is off. You should not change this value. Possible values are:
mmap-rdwr determines whether to use memory mapped I/O when sending data from the cache and updating cache files. By default, this value is on.
on means that memory mapped I/O will be used to send data from the cache or to update cache files.
off means that memory mapped I/O will not be used to send data from the cache or to update cache files.
shmem-io determines whether shared memory is enabled. The child processes communicate with the cache monitor and cache manager via either an interprocess pipe/socket, or shared memory. The shared memory based I/O is faster. By default, shared memory I/O is enabled.
notify-num-changes is used only when shared memory I/O is enabled. This parameter determines the number of changes after which the cache monitor is notified about changes made by that child process. More frequent notifications keep the cache monitor up-to-date on the status and size of the cache, but create more work for the cache monitor. The valid range for notify num changes is 1 to 500, and the default value is 10.
notify-blk-limit is used only when shared memory I/O is enabled. This parameter determines the number of blocks cache size usage has changed by a single child process until the cache monitor is notified. Smaller notification limits keep the cache monitor up-to-date on the status and size of the cache, but create more work for the cache monitor. The valid range for notify num changes is 1 to 10000 (0.5K to 5MB), and the default value is 100 (50K).
cmon-tick-interval should not be changed.
mmap-max is the maximum number of kilobytes memory-mapped at once by a single process. Files larger than the max mmap size will be memory-mapped in portions of this size. By default, the max mmap size is 256K.
The max mmap size must be at least 16, and it must be a multiple of page size, which is often four.
min-sync-interval specifies the amount of time the cache manager waits before traversing the entire cache to find out the actual cache size. The cache monitor attempts to maintain current information about the size of each cache section. However, the information may get skewed by unexpected software shutdowns, system crashes, power failures, etc. Another reason for skew is that a server shutdown will lose unnotified changes to the cache in child processes. Because of these skews, the cache manager periodically traverses the entire cache to determine the actual cache size.
The valid range for min-sync-interval is 1800 seconds(1/2 hour) to 604800 seconds (1 week), and the default is 86400 seconds (24 hours).
notify-block-chunk-per-proc controls the threshold which triggers each child process to report their cache usage to the cache monitor. Each server child process notifies the cache monitor about how much new cache space it has taken up (or released) by creating new cache files or updating old ones. To avoid message overflow, these notifications are not sent for every cache operation, but rather each process waits until it has reached a certain threshold before notifying the cache monitor about its activities. The notify-blk-chunk-per-proc parameter controls this threshold. The units are in "blocks". A block is always 512 bytes (0.5 KB), regardless of the operating system filesystem block size.
The notify-block-chunk-per-proc value is multiplied by the value of the MaxProcs directive. Therefore, the effect of having a higher MaxProcs setting is that child processes will buffer more cache change messages before they notify the cache monitor about them. This effect avoids message overflow on systems with a high load (large MaxProcs), and allows small caches to maintain more accurate size information (small MaxProcs).
cache-fs-full-retry-after controls how many cache write requests should be skipped before the proxy attempts a write operation. When a server child process fails to write to disk and the error code is ENOSPC (No space left on device), the process stops writing data to that cache partition, allowing time for the garbage collector to correct the situation. The fs full retry after variable controls the number of cache write requests that are skipped before the proxy attempts a write operation again.
The valid range for fs full retry after is 1 (retry immediately) to 1024 (practically don't retry), and the default value is 50.
update-after-percent controls the percentage of used cache space that triggers a partition table update. The cache monitor continuously receives messages from server child processes about how much new cache space they have used (see the parameter, notify-block-chunk-per-proc). To conserve CPU time, the cache monitor does not update its partition table or evaluate garbage collection needs after every such message. Instead, it waits until there is big enough percentage change in size. The update after percent value controls that percentage.
The valid range for update after percent is 0 (every time) to 100 (after size doubles), and the default value is 1.
sync-dump-ticks should not be changed.
Example
Init fn=tune-cache
cch-status=DO-NOT-CACHE
mmap-wr=off
mmap-rdwr=on
shmem-io=off
notify-num-changes=10
notify-blk-limit=100
cmon-tick-interval=(do not change)
mmap-max=256
min-sync-interval=86400
notify-block-chunk-per-proc=67
cache-fs-full-retry-after=50
update-after-percent=1
sync-dump-ticks=(do not change)
tune-gc (tuning garbage collector performance)
The tune-gc function allows you to tune the performance of your proxy server's garbage collector.You should not change the default settings unless directed to do so by iPlanet Technical Support.
Syntax
Init fn=tune-gc
gc-urldb-interval=seconds
gc-nap-length=seconds
hard-gc-nap-count=number
soft-gc-nap-count=number
hard-gc-chunk-entries=number
gc-dir-chunk=number
gc-hi-margin-percent=percent
gc-lo-margin-percent=percent
gc-extra-margin-percent=percent
gc-leave-fs-full-percent=percent
Parameters
gc-urldb-interval controls how often the URL database is cleaned of old URLs and how often it is checked for consistency.
The valid range for the gc URL db interval is 1800 sec (30 minutes) to 604800 (1 week), and the default value is 79200 seconds (22 hours).
gc-nap-length is the amount of time that the garbage collector sleeps during one "nap." The garbage collector takes "naps" every so often so that it does not hog all the CPU from other processes. The frequency of these naps is controlled by two variables: hard gc nap count and soft gc nap count.
The valid range for gc nap length is 0 (no naps) to 120 (2 minutes), and the default is 1 second
hard-gc-nap-count specifies how many naps hard garbage collector takes during the garbage collection cycle of a single cache section. There are two types of garbage collection: hard and soft. The hard garbage collector traverses the entire cache section and finds all the files individually, picking the ones to delete, and then generates lists of files in the cache ordered by their relative value. These lists are then used by the soft garbage collector to delete files without traversing the entire cache structure.
Hard garbage collection is more resource intensive than soft garbage collection, but it is required every time soft garbage collection runs out of the lists generated by hard garbage collection.
There are 64 subdirectories on each cache section, and naps can be taken between directories only. This means that there can be at most 64 naps. The number of naps should be a power of two.
The valid values for hard gc nap count are: 0 (no sleeps), 1, 2, 4, 8, 16, 32, and 64 (max). The default value is 16 (sleep after every 4 directories).
soft-gc-nap-count specifies how many naps the soft garbage collector takes during the garbage collection cycle. The soft garbage collector simply reads a list of cache files from a set of files produced by the hard garbage collector. It still looks up the file using the stat() system call, to find out if there have been subsequent accesses to the cache file during the last garbage collection, which suggests that the cache file is being (or may be) actively used, and should not be removed.
The valid range for soft gc nap count is 0 (no naps) to 1000 naps, and the default value is 20 naps.
hard-gc-chunk-entries identifies the number of cache entry slots allocated during one pass for garbage collection. One "pass" in garbage collection is defined by the variable gc dir chunk, which is the number of subdirectories within a cache section that will be processed in one pass.
This number should be of the same order as the number of files in a typical chunk of directories. As an example, a typical subdirectory in a cache section has 100-200 files. If the gc dir chunk variable is set to 8, then the "hard gc max entries" value should be set to around 800-1600.
A single cache entry is about 32 bytes, so every 1000 entries in this variable means 32KB pool allocation. A valid range for hard gc max entries is 100(3K) to 5000 (160K), and the default value is 500 (16K).
gc-dir-chunk controls the sample size for the LRU algorithm. Basically, this means it controls how many subdirectories under each cache section are processed by the garbage collector in one pass. Because a larger gc dir chunk value causes the proxy to process more files simultaneously, more memory is required. Larger gc dir chunk values also cause the garbage collector to be slower and more CPU intensive. The smaller the gc dir chunk value is, the lighter-weight garbage collection becomes. However, the sample size for the LRU algorithm becomes smaller.
The gc dir chunk value must be a power of two.
Valid values for gc dir chunk are: 1 (single directory), 2, 4, 8, 16, 32, and 64 (all directories at once). The default value is 8 directories.
gc-hi-margin-percent controls the percentage of the maximum cache size that, when reached, triggers garbage collection. This value must be higher than the value for gc lo margin percent.
The valid range for gc hi margin percent is 10 to 100 percent (trigger garbage collection when full). The default value is 80 percent (trigger gc when 80% full).
gc-lo-margin-percent controls the percentage of the maximum cache size that the garbage collector targets. This value must be lower than the value for gc-hi-margin-percent.
The valid range for gc lo margin percent is 5 to 100 percent. The default value is 70 percent (target at 70% full cache after gc).
gc-extra-margin-percent specifies the fraction of the cache the garbage collector will remove. If the garbage collection is triggered by a reason other than the partition's size getting close to the maximum allowed size (see gc-hi-margin-percent), the garbage collector will use the percentage set by the gc extra margin percent variable to determine the fraction of the cache to remove.
The valid range for gc extra margin percent is 0 to 100 percent, and the default value is 30 percent (remove 30% of existing cache files).
gc-leave-fs-full-percent determines the percentage of the cache partition size below which garbage collection will not go. This value prevents the garbage collector from removing all files from the cache if some other application is hogging the disk space.
The valid range for gc leave fs full percent is 0 (allow total removal) to 100 percent (remove nothing). The default value is 60 percent (allow the cache size to shrink to 60% of current).
Example
Init fn=tune-gc
gc-urldb-interval=79200
gc-nap-length=1
hard-gc-nap-count=16
soft-gc-nap-count=20
hard-gc-chunk-entries=500
gc-dir-chunk=8
gc-hi-margin-percent=80
gc-lo-margin-percent=70
gc-extra-margin-percent=30
gc-leave-fs-full-percent=60
NameTrans
NameTrans is the name translation directive, which maps URLs to mirror sites and to the local file system (for the online forms). NameTrans directives should appear in the root object (the "default" object), although you can put them elsewhere. If an object has more than one NameTrans directive, the server applies each name translation function until one succeeds and then modifies the URL to either a mirror site URL or to a full file system path.
assign name (associating templates with path)
The assign-name function associates the name of a configuration object with a path specified by a regular expression. It always returns REQ_NOACTION.
Syntax
NameTrans fn=assign-name
from=regular expression
name=named object
Parameters
from specifies a pattern, presented as a regular expression,. that specifies a path to be affected.
name is the name of the configuration object to associate with the path.
Example
NameTrans fn=assign-name
name=personnel from=/httpd/docs/pers*
map (mapping URLs to mirror sites)
The map function of the NameTrans directive 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.
Syntax
NameTrans fn=map
from="site prefix"
to="site prefix"
name="named object"
Parameters
from is the prefix to be mapped to the mirror site.
to is the mirror site prefix.
name (optional) gives a named object from which to derive the configuration for this mirror site.
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"
pac-map (mapping URLs to a local file)
The pac-map function maps proxy-relative URLs to local files that are delivered to clients who request configuration.
Syntax
NameTrans fn=pac-map
from=URL
to=prefix
name=named object
Parameters
from is the proxy URL to be mapped.
to is 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://home.netscape.com
to=index.html
name=file
pat-map (mapping URLs to a local file)
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
from is the proxy URL to be mapped.
to is 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://home.netscape.com
to=index.html
name=file
pfx2dir (replacing path prefixes with directory names)
The pfx2dir function looks for a directory prefix in the path and replaces the prefix with a real directory name. Don't use trailing slashes in either the prefix or the directory.
Syntax
NameTrans fn=pfx2dir
from=prefix
dir=directory
name=named object
Parameters
from is the prefix to be mapped.
dir is the directory that the prefix is mapped to.
name (optional) gives a named object (template) from which to derive configuration for this mirror site.
Example
NameTrans fn=pfx2dir
from=/icons
dir=c:/netscape/suitespot/ns-icons
ObjectType
The ObjectType directives tag additional information to the requests, such as caching information and whether another proxy should be used.
If there is more than one ObjectType directive in an object, the directives are applied in the order they appear. If a directive sets an attribute and a later directive tries to set that attribute to something else, the first setting is used and the subsequent one is ignored.
cache-enable (enabling caching)
The cache_enable function tells the proxy that an object is cacheable, based on specific criteria. As an example, if it appears in the object
<Object ppath="http://.*">, then all the HTTP documents are considered cacheable, as long as other conditions for an object to be cacheable are met.
Syntax
ObjectType fn=cache-enable
cache-auth=0|1
query-maxlen=number
min-size=number
max-size=number
log-report=feature
cache-local=0|1
Parameters
cache-enable tells the proxy that an object is cacheable. As an example, if it appears in the object <Object ppath="http://.*">, then all HTTP documents are considered cacheable (as long as other conditions for an object to be cacheable are met).
cache-auth specifies whether to cache items that require authentication. If set to 1, pages that require authentication can be cached also. If not specified, defaults to 0.
query-maxlen specifies the number of characters in the query string (the "?string" part at the end of the URL) that are still cacheable. The same queries are rarely repeated exactly in the same form by more than one user, and so caching them is often not desirable. That's why the default is 0.
min-size is the minimum size, in kilobytes, of any document to be cached. The benefits of caching are greatest with the largest documents. For this reason, some people prefer to cache only larger documents.
max-size represents the maximum size in kilobytes of any document to be cached. This allows users to limit the maximum size of cached documents, so no single document can take up too much space.
log-report is used to control the feature that reports local cache accesses back to the origin server so that content providers get their true access logs.
cache-local is used to enable local host caching, that is, URLs without fully qualified domain names, in the proxy. If set to 1, local hosts are cached. If not specified, it defaults to 0, and local hosts are not cached.
Example
The following example of cache-enable allows you to enable caching of objects matching the current resource. This applies to normal, non-query, non-authenticated documents of any size. The proxy requires that the document carries either last-modified or expires headers or both, and that the content-type reported by the origin server (if present) is accurate.
ObjectType fn=cache-enable
The example below is like the first example, but it also caches documents that require user authentication, and it caches queries up to five characters long. The cache-auth=1 indicates that an up-to-date check is always required for documents that need user authentication (this forces authentication again).
ObjectType fn=cache-enable
cache-auth=1
query-maxlen=5
The example below is also like the first example, except that it limits the size of cache files to a range of 2 KB to 1 MB.
ObjectType fn=cache-enable
min-size=2
max-size=1000
cache-setting (specifying caching parameters)
cache-setting is an ObjectType function that sets parameters used for cache control. Defaults for these settings are provided through the init-cache function, described on page 438.
This function is used to explicitly cache (or not cache) a resource, create an object for that resource, and set the caching parameters for the object.
Syntax
ObjectType fn=cache-setting
max-uncheck=seconds
lm-factor=factor
connect-mode=always|fast-demo|never
cover-errors=number
Parameters
max-uncheck (optional) is the maximum time in seconds, allowed between consecutive up-to-date checks. If set to 0 (default), a check is made every time the document is accessed, and the lm-factor has no effect.
lm-factor (optional) is a floating point number representing the factor used in estimating expiration time (how long a document might be up to date based on the time it was last modified). The time elapsed since the last modification is multiplied by this factor, and the result gives the estimated time the document is likely to remain unchanged. Specifying a value of 0 turns off this function, and then the caching system uses only explicit expiration information (rarely available). Only explicit Expires HTTP headers are used. This value has no effect if max-uncheck is set to 0.
connect-mode specifies network connectivity and can be set to these values:
always (default) connects to remote servers when necessary.
fast-demo connects only if the item isn't found in the cache.
never no connection to a remote server is ever made; returns an error if the document is not found in the cache.
cover-errors, if present and greater than 0, returns a document from the cache if the remote server is down and an up-to-date check cannot be made. The value specified is the maximum number of seconds since the last up-to-date check; if more time has elapsed, an error is returned. Using this feature involves the risk of getting stale data from the cache while the remote server is down. Setting this value to 0, or not specifying it (default) causes an error to be returned if the remote server is unavailable.
term-percent means to keep retrieving if more than the specified percentage of the document has already been retrieved.
Example
<Object ppath="http://.*">
ObjectType fn=cache-enable
ObjectType fn=cache-setting max-uncheck="7200"
ObjectType fn=cache-setting lm-factor="0.020"
ObjectType fn=cache-setting connect-mode="fast-demo"
ObjectType fn=cache-setting cover-errors="3600"
Service fn=proxy-retrieve
</Object>
# Force check every time
ObjectType fn=cache-setting max-uncheck=0
# Check every 30 minutes, or sooner if changed less than
# 6 hours ago (factor 0.1; last change 1 hour ago would
# give 6-minute maximum check interval).
ObjectType fn=cache-setting max-uncheck=1800 lm-factor=0.1
# Disable caching of the current resource
ObjectType fn=cache-setting cache-mode=nothing
force-type (assigning MIME types to objects)
The force-type function assigns a type to objects that do not already have a MIME type. This is used to specify a default object type.
Syntax
ObjectType fn=force-type
type=text/plain
enc=encoding
lang=language
Parameters
type is the type to assign to matching files.
enc (optional) is the encoding given to matching files.
lang (optional) is the language assigned to matching paths.
Example
ObjectType fn=force-type
type=text/plain
ObjectType fn=force-type
lang=en_US
http-config (using keep-alive feature)
http-config is an ObjectType function that lets the proxy use the HTTP keep-alive feature between the client and the proxy server, and between the proxy server and the remote server.
Syntax
ObjectType fn=http-config a
keep-alive=on|off
Parameters
on enables this keep-alive feature.
off disables the keep-alive feature, and is the default.
The keep-alive feature lets several requests be sent through the same connection.
Using this feature could actually degrade performance if the proxy is heavily loaded and it receives a lot of new requests every second and the network can establish connections fairly quickly. The reason for this degradation is that every connection is kept by the server for several seconds after the request processing has finished, even if the client doesn't happen to send a new request.
If connections to the proxy server take a long time to establish, or if the connection simply hangs, this feature should be disabled to reduce the total number of active connections.
Example
ObjectType fn=http-config keep-alive=on
java-ip-check (checking IP addresses)
The java-ip-check function allows clients to query the proxy server for the IP address used to rerouted a resource. Because DNS spoofing often occurs with Java Applets, this feature enables clients to see the true IP address of the origin server. When this features is enabled, the proxy server attaches a header containing the IP address that was used for connecting to the destination origin server.
Syntax
ObjectType fn=java-ip-check
status=on|off
Parameters
status specifies whether Java IP address checking is enabled or not. Possible values are:
type-by-extension (determining file information)
The type-by-extension function uses file extensions to determine information about files. (Extensions are strings after the last period in a file name.) This matches an incoming request to extensions in the mime.types file. The MIME type is added to the "content-type" header sent back to the client. The type can be set to internal server types that have special results when combined with function you write using the server plug-in API.
Syntax
ObjectType fn=type-by-extension
Parameters
None.
Example
ObjectType fn=type-by-extension
PathCheck
The PathCheck directives check the URL that is returned after all of the NameTrans directives finish running. Local file paths (with the administration forms) are checked for elements such as ../ and //, and then any access restriction is applied.
If an object has more than one PathCheck directive, all of the directives will be applied in the order they appear.
check-acl (attaching an ACL to an object)
The check-acl function attaches an Access Control List to the object in which the directive appears. Regardless of the order of PathCheck directives in the object, check-acl functions are executed first, and will cause user authentication to be performed if required by the specified ACL, and will also update the access control state.
Syntax
PathCheck fn=check-acl
acl="ACL name"
bong-file=path name
Parameters
acl is the name of an Access Control List.
bong-file (optional) is the path name for a file that will be sent if this ACL is responsible for denying access.
Example
PathCheck fn=check-acl
acl="HRonly"
deny-service (denying client access)
The deny-service function is a PathCheck function that sends a "Proxy Denies Access" error when a client tries to access a specific path. If this directive appears in a client region, it performs access control on the specified clients.
The proxy specifically denies clients instead of specifically allowing them access to documents (for example, you don't configure the proxy to allow a list of clients). The "default" object is used when a client doesn't match any client region in objects, and because the "default" object uses the deny-service function, no one is allowed access by default.
Syntax
PathCheck fn=deny-service path=.*someexpression.*
Parameters
path is a regular expression representing the path to check. Not specifying this parameter is equivalent to specifying *. URLs matching the expression are denied access to the proxy server.
Example
<Object ppath="http://netscape/.*">
# Deny servicing proxy requests for fun GIFs
PathCheck fn=deny-service path=.*fun.*.gif
# Make sure nobody except Netscape employees can use the object
# inside which this is placed.
<Client dns=*~.*.netscape.com>
PathCheck fn=deny-service
</Client>
</Object>
require-proxy-auth (requiring proxy authentication)
The require-proxy-auth function is a PathCheck function that makes sure that users are authenticated and triggers a password pop-up window.
Syntax
PathCheck fn=require-proxy-auth
auth-type=basic
realm=name
auth-group=group
auth-users=name
Parameters
auth-type specifies the type of authorization to be used. The type should be "basic" unless you are running a Unix proxy and are going to use your own function to perform authentication.
realm is a string (enclosed in double-quotation marks) sent to the client application so users can see what object they need authorization for.
auth-user (optional) specifies a list of users who get access. The list should be enclosed in parentheses with each user name separated by the pipe | symbol.
auth-group (optional) specifies a list of groups that get access. Groups are listed in the password-type file.
Example
PathCheck fn=require-auth
auth-type=basic
realm="Marketing Plans"
auth-group=mktg
auth-users=(jdoe|johnd|janed)
url-check (checking URL syntax)
The url-check function checks the validity of URL syntax.
Route
The Route directive specifies information about where the proxy server should route requests.
icp-route (routing with ICP)
The icp-route function tells the proxy server to use ICP to determine the best source for a requested object whenever the local proxy does not have the object.
Syntax
Route fn=icp-route
redirect=yes|no
Parameters
redirect specifies whether the proxy server will send a redirect message back to the client telling it where to get the object.
yes means the proxy will send a redirect message back to the client to tell it where to retrieve the requested object.
no means the proxy will not send a redirect message to the client. Instead it will use the information from ICP to get the object.
pa-enforce-internal-routing (enforcing internal distributed routing)
The pa-enforce-internal-routing function enables internal routing through a proxy array. Internal routing occurs when a non PAC-enabled client routes requests through a proxy array.
Syntax
Route fn="pa_enforce_internal_routing"
redirect="yes|no"
Parameters
redirect specifies whether or not client's requests will be redirected. Redirecting means that if a member of a proxy array receives a request that it should not service, it tells the client which proxy to contact for that request.
|
Caution
|
Redirect is not currently supported by any clients, so you should not use the feature at this time.
|
pa-set-parent-route (setting a hierarchical route)
The pa-set-parent-route function sets a route to a parent array.
Syntax
Route fn="pa_set_parent_route"
set-proxy-server (using another proxy to retrieve a resource)
The set-proxy-server function directs the proxy server to connect to another proxy for retrieving the current resource. It also sets the address and port number of the proxy server to be used.
Syntax
Route fn=set-proxy-server
host name=otherhost name
port=number
Parameters
host name is the name of the host on which the other proxy is running.
port is the port number of the remote proxy.
Example
Route fn=set-proxy-server
host name=proxy.netscape.com
port=8080
set-socks-server (using a SOCKS server to retrieve a resource)
The set-socks-server directs the proxy server to connect to a SOCKS server for retrieving the current resource. It also sets the address and port number of the SOCKS server to be used.
Syntax
Route fn=set-socks-server
host name=sockshost name
port=number
Parameters
host name is the name of the host on which the SOCKS server runs.
port is the port on which the SOCKS server listens.
Example
ObjectType fn=set-socks-server
host name=socks.netscape.com
port=1080
unset-proxy-server (unsetting a proxy route)
The unset-proxy-server function tells the proxy server not to connect to another proxy server to retrieve the current resource. This function nullifies the settings of any less specific set-proxy-server functions.
Syntax
Route fn=unset-proxy-server
unset-socks-server (unsetting a SOCKS route)
The unset-socks-server function tells the proxy server not to connect to a SOCKS server to retrieve the current resource. This function nullifies the settings of any less specific set-socks-server functions.
Syntax
Route fn=unset-socks-server
Service
Once the other directives have done all the necessary checks and translations, the functions of the Service directive send the data (first receiving it from a remote server when necessary) and complete the request. Most of the time, the Service directive connects to a remote server, making the request for the client and then passing the results back to the client.
Parameters
Service directives support these optional parameters to help determine if the directive is used:
method specifies a regular expression that indicates which HTTP methods the client must be using to have the directive applied. Valid HTTP methods include GET, HEAD, POST, and INDEX (CONNECT through SSL tunneling is also available). Multiple values are enclosed in parentheses and separated by the pipe (|) symbol.
type (not with proxy-retrieve) specifies a regular expression that indicates the MIME types to which to apply the directive. The proxy server defines several MIME types internally that are used only to select a Service function that translates the internal type into a form presentable to the client.
If an object has more than one Service directive, the first applicable directive is used and the rest are ignored.
proxy-retrieve (retrieving documents with the proxy)
The proxy-retrieve function retrieves a document from a remote server and returns it to the client. It also manages caching if it is enabled.
Syntax
Service fn=proxy-retrieve
method=GET|HEAD|POST|INDEX|CONNECT...
Parameters
method lets you specify a retrieval method. By default, all methods are allowed unless the method parameter is given.
Example
# Normal proxy retrieve
Service fn=proxy-retrieve
# Proxy retrieve with POST method disabled
Service fn=proxy-retrieve
method=(POST)
send-file (sending text file contents to client)
The send-file function sends the contents of a plain text file to the client. If this function finds any extra path information, it doesn't send the text file to the client.
Syntax
Service fn=send-file
method=GET|HEAD|POST|INDEX|CONNECT...
type=MIME type
Parameters
method lets you specify a retrieval method. By default, all methods are allowed unless the method parameter is given.
type specifies a regular expression that indicates the MIME types to which to apply the directive.
Example
Service fn=send-file
method=(GET|HEAD)
type=*~magnus-internal/*
deny-service (denying access to a resource)
The deny-service function is the only function that belongs to two classes: PathCheck and Service. It prevents access to the requested resource.
The socks5.conf File
The proxy uses the file /etc/socks5.conf to control access to the SOCKS proxy server SOCKD and its services. Each line defines what the proxy does when it gets a request that matches the line.
When SOCKD receives a request, it checks the request against the lines in
/etc/socks5.conf. When it finds a line that matches the request, the request is permitted or denied based on the first word in the line (permit or deny). Once it finds a matching line, the daemon ignores the remaining lines in the file. If there are no matching lines, the request is denied. You can also specify actions to take if the client's identd or user ID is incorrect by using #NO_IDENTD: or #BAD_ID as the first word of the line. Each line can be up to 1023 characters long.
There are five sections in the socks5.conf file. These sections do not have to appear in the following order. However, because the daemon uses only the first line that matches a request, the order of the lines within each section is extremely important. The five sections of the socks5.conf file are:
ban host/authentication - identifies the hosts from which the SOCKS deamon should not accept connections and which types of authentication the SOCKS daemon should use to authenticate these hosts
routing - identifies which interface the SOCKS deamon should use for particular IP addresses
variables and flags - identifies which logging and informational messages the SOCKS daemon should use
proxies - identifies the IP addresses that are accessible through another SOCKS server and whether that SOCKS server connects directly to the host
access control - specifies whether the SOCKS daemon should permit or deny a request
When the SOCKS daemon receives a request, it sequentially reads the lines in each of these five sections to check for a match to the request. When it finds a line that matches the request, it reads the line to determine whether to permit or deny the request. If there are no matching lines, the request is denied.
Each line in this file can be up to 1023 characters long and in order for a line to match a request, each entry in the line must match.
Authentication/Ban Host Entries
There are two lines in authentication/ban host entries. The first is the authentication line.
Syntax
auth source-hostmask source-portrange auth-methods
Parameters
source-hostmask identifies which hosts the SOCKS server will authenticate.
source-portrange identifies which ports the SOCKS server will authenticate.
auth-methods are the methods to be used for authentication. You can list multiple authentication methods in order of your preference. In other words, if the client does not support the first authentication method listed, the second method will be used instead. If the client does not support any of the authentication methods listed, the SOCKS server will disconnect without accepting a request. If you have more than one authentication method listed, they should be separated by commas with no spaces in between. Possible authentication methods are:
n (no authentication required)
u (user name and password required)
- (any type of authentication)
The second line in the authentication/ban host entry is the ban host line.
Syntax
ban source-hostmask source-portrange
Parameters
source-hostmask identifies which hosts are banned from the SOCKS server.
source-portrange identifies from which ports the SOCKS server will not accept requests.
Example
auth 127.27.27.127 1024 u,-
ban 127.27.27.127 1024
Routing Entries
Syntax
route dest-hostmask dest-portrange interface/address
Parameters
dest-hostmask indicates the hosts for which incoming and outgoing connections must go through the specified interface.
dest-portrange indicates the ports for which incoming and outgoing connections must go through the specified interface.
interface/address indicates the IP address or name of the interface through which incoming and outgoing connections must pass. IP addresses are preferred.
Example
route 127.27.27.127 1024 le0
Variables and Flags
Syntax
set variable value
Parameters
variable indicates the name of the variable to be initialized.
value is the value to set the variable to.
Example
set SOCKS5_BINDPORT 1080
Available Settings
The following settings are those that can be inserted into the variables and flags section of the SOCKS5.conf file. These settings will be taken from the administration forms, but they can be added, changed, or removed manually as well.
SOCKS5_BINDPORT
The SOCKS5_BINDPORT setting sets the port at which the SOCKS server will listen. This setting cannot be changed during rehash.
Syntax
set SOCKS5_BINDPORT port number
Parameters
port number is the port at which the SOCKS server will listen.
Example
set SOCKS5_BINDPORT 1080
SOCKS5_PWDFILE
The SOCKS5_PWDFILE setting is used to look up user name/password pairs for user name/password authentication. This setting only applies to situations in which ns-sockd is running separately from the administration server.
Syntax
set SOCKS5_PWDFILE full pathname
Parameters
full pathname is the location and name of the user name/password file.
Example
set SOCKS5_PWDFILE /etc/socks5.passwd
SOCKS5_CONFFILE
The SOCKS5_CONFFILE setting is used to determine the location of the SOCKS5 configuration file.
Syntax
set SOCKS5_CONFFILE full pathname
Parameters
full pathname is the location and name of the SOCKS configuration file.
Example
set SOCKS5_CONFFILE /etc/socks5.conf
SOCKS5_LOGFILE
The SOCKS5_LOGFILE setting is used to determine where to write log entries.
Syntax
set SOCKS5_LOGFILE full pathname
Parameters
full pathname is the location and name of the SOCKS logfile.
Example
set SOCKS-5_LOGFILE /var/log/socks5.log
SOCKS5_NOIDENT
THe SOCKS5_NOIDENT setting disables Ident so that SOCKS does not try to determine the user name of clients. Most servers should use this setting unless they will be acting mostly as a SOCKS4 server. (SOCKS4 used ident as authentication.)
Syntax
set SOCKS5_NOIDENT
Parameters
None.
SOCSK5_DEMAND_IDENT
The SOCKS5_DEMAND_IDENT setting sets the Ident level to "require an ident response for every request". Using Ident in this way will dramatically slow down your SOCKS server. If neither SOCKS5_NOIDENT or SOCKS5_DEMAND_IDENT is set, then the SOCKS server will make an Ident check for each request, but it will fulfill requests regardless of whether an Ident response is received.
Syntax
set SOCSK5_DEMAND_IDENT
Parameters
None.
SOCKS5_DEBUG
The SOCKS5_DEBUG setting causes the SOCKS server to log debug messages. You can specify the type of logging your SOCKS server will use.
If it's not a debug build of the SOCKS server, only number 1 will work.
Syntax
set SOCSK5_DEBUG number
Parameters
number determines the number of the type of logging your server will use. Possible values are:
1 - log normal debugging messages. This is the default.
2 - log extensive debugging (especially related to configuration file settings).
3 - log all network traffic.
Example
set SOCKS5_DEBUG 2
SOCKS5_USER
The SOCKS5_USER setting sets the user name to use when authenticating to another SOCKS server.
Syntax
set SOCKS5_USER user name
Parameters
user name is the user name the SOCKS server will use when authenticating to another SOCKS server.
Example
set SOCKS5_USER mozilla
SOCKS5_PASSWD
The SOCKS5_PASSWD setting sets the password to use when authenticating to another SOCKS server. It is possible for a SOCKS server to go through another SOCKS server on its way to the Internet. In this case, if you define SOCKS5_USER, ns-sockd will advertise to other SOCKS servers that it can authenticate itself with a user name and password.
Syntax
set SOCKS5_PASSWD password
Parameters
password is the password the SOCKS server will use when authenticating to another SOCKS server.
Example
set SOCKS5_PASSWD m!2@
SOCKS5_NOREVERSEMAP
The SOCKS5_NOREVERSEMAP setting tells ns-sockd not to use reverse DNS. Reverse DNS translates IP addresses into host names. Using this setting can increase the speed of the SOCKS server.
If you use domain masks in the configuration file, the SOCKS server will have to use reverse DNS, so this setting will have no effect.
Syntax
set SOCKS5_NOREVERSEMAP
Parameters
None.
SOCKS5_HONORBINDPORT
The SOCKS5_HONORBINDPORT setting allows the client to specify the port in a BIND request. If this setting is not specified, the SOCKS server ignores the client's requested port and assigns a random port.
Syntax
set SOCKS5_HONORBINDPORT
Parameters
None.
SOCKS5_ALLOWBLANKETBIND
The SOCKS5_ALLOWBLANKETBIND setting allows the client to specify an IP address of all zeros (0.0.0.0) in a BIND request. If this setting is not specified, the client must specify the IP address that will be connecting to the bind port, and an IP of all zeros is interpreted to mean that any IP address can connect.
Syntax
set SOCKS5_ALLOWBLANKETBIND
Parameters
None.
SOCKS5_STATSFILE
The SOCKS5_STATSFILE setting identifies a different file for storing running statistics about the SOCKS server.
Syntax
set SOCKS5_STATSFILE full pathname
Parameters
full pathname is the location and name of the statistics file.
Example
set SOCKS5_STATSFILE /tmp/socksstat.any.1080
SOCSK5_QUENCH_UPDATES
The SOCKS5_QUENCH_UPDATES setting tells the SOCKS server not to write a line to the logfile every hour. This line, if written, provides a brief summary of statistics. The following is a sample line:
[04/aug/1997:21:00:00] 000 info: 78 requests,
78 successful: connect 77, bind 1, udp 0
Syntax
set SOCKS5_QUENCH_UPDATES
Parameters
None.
SOCKS5_WORKERS
The SOCKS5_WORKERS setting tunes the performance of the SOCKS server by adjusting the number of worker threads. Worker threads perform authentication and access control for new SOCKS connections. If the SOCKS server is too slow, you should increase the number of worker threads. If it is unstable, decrease the number of worker threads.
The default number of worker threads is 40, and the typical number of worker threads falls between 10 and 150.
Syntax
set SOCKS5_WORKERS number
Parameters
number is the number of worker threads the SOCKS server will use.
Example
set SOCKS5_WORKERS 40
SOCKS5_ACCEPTS
The SOCKS5_ACCEPTS setting tunes the performance of the SOCKS server by adjusting the number of accept threads. Accept threads sit on the SOCKS port listening for new SOCKS requests. If the SOCKS server is dropping connections, you should increase the number of accept threads. If it is unstable, decrease the number of accept threads.
The default number of accept threads is 1, and the typical number of accept threads falls between 1 and 10.
Syntax
set SOCKS5_ACCEPTS number
Parameters
number is the number of accepts threads the SOCKS server will use.
Example
set SOCKS5_ACCEPTS 1
LDAP_URL
The LDAP-URL setting sets the URL for the LDAP server.
Syntax
set LDAP-URL URL
Parameters
URL is the URL for the LDAP server used by SOCKS.
Example
set LDAP-URL ldap://name:8180/0=Netscape,c=US
LDAP_USER
The LDAP-USER setting sets the user name that the SOCKS server will use when accessing the LDAP server.
Syntax
set LDAP-USER user name
Parameters
user name is the user name SOCKS will use when accessing the LDAP server.
Example
set LDAP-USER admin
LDAP_PASSWD
The LDAP-PASSWD setting sets the password that the SOCKS server will use when accessing the LDAP server.
Syntax
set LDAP-PASSWD password
Parameters
password is the password SOCKS will use when accessing the LDAP server.
Example
set LDAP-PASSWD T$09
Proxy Entries
Syntax
proxy-type dest-hostmask dest-portrange proxy-list
Parameters
proxy-type indicates the type of proxy server. This value can be:
dest-hostmask indicates the hosts for which the proxy entry applies.
dest-portrange indicates the ports for which the proxy entry applies.
proxy-list contains the names of the proxy servers to use.
Example
socks5 127.27.27.127 1080 proxy1
Access Control Entries
Syntax
permit|deny auth-type connection-type source-hostmask dest-hostmask
source-portrange dest-portrange [LDAP-group]
Parameters
auth-type indicates the authentication method for which this access control line applies.
connection-type indicates the type of command the line matches. Possible command types are:
source-hostmask - indicates the hosts for which the access control entry applies.
dest-hostmask indicates the hosts for which the access control entry applies.
source-portrange indicates the ports for which the access control entry applies.
dest-portrange is the port number of the destination.
LDAP-group is the group to deny or permit access to. This value is optional. If no LDAP group is identified, the access control entry applies to everyone.
Example
permit u c - - - [0-1023] group1
Specifying Ports
You will need to specify ports for many entries in your socks5.conf file. Ports can be identified by a name, number, or range. Ranges that are inclusive should be surrounded by brackets (i.e. [ ]). Ranges that are not inclusive should be in parentheses.
The bu.conf File
The optional bu.conf file contains batch update directives. You can use these directives to update many documents at once. You can time these updates to occur during off-peak hours to minimize the effect on the efficiency of the server. The format of this file is described in this section.
Accept
A valid URL Accept filter consists of any POSIX regular expression. It is used as a filter to test URLs for retrieval in the case of internal updates, and determines whether branching occurs for external updates.
This directive may occur any number of times, as separate Accept lines or as comma or white space delimited entries on a single Accept line and is applied sequentially. Default behavior is .*, letting all URLs pass.
Syntax
Accept regular expression
Connections
For the Connections directive, n is the number of simultaneous connections to be used while retrieving. This is a general method for limiting the load on your machine and, more importantly, the remote servers being contacted.
This directive can occur multiple times in a valid configuration, but only the smallest value is used.
Syntax
Connections n
Count
The argument n of the Count directive specifies the total maximum number of URLs to be updated via this process. This is a simple safeguard for limiting the process and defaults to a value of 300. This directive can occur multiple times in a valid configuration, but only the smallest value is used.
Syntax
Count n
Days
The Days directive specifies on which days you want to allow the starting of batch updates. You can specify this by naming the days of the week (Sunday,..., Saturday), and you can use three-letter abbreviations (Sun, Mon, Tue, Wed, Thu, Fri, Sat).
This directive can occur multiple times in a valid configuration, but only the first value is used. The default is seven-day operation.
Syntax
Days day1 day2...
Depth
The Depth directive lets you ensure that, while enumerating, all collected objects are no more than a specified number of links away from the initial URL. The default is 1.
Syntax
Depth depth
Object boundaries
The Object wrapper signifies the boundaries between individual configurations in the bupdate.conf file. It can occur any number of times, though each occurrence requires a unique name.
All other directives are only valid when inside Object boundaries.
Syntax
<Object name=name>
...
</Object>
Reject
A valid URL Reject filter consists of any POSIX regular expression. It is used as a filter to test URLs for retrieval in the case of internal updates, and determines whether branching occurs for external updates.
This directive may occur any number of times, as separate Reject lines or as comma or white space delimited entries on a single Reject line, and is applied sequentially. Default behavior is no reject for internal updates and .* (no branching, get single URL) for recursive updates.
Syntax
Reject regular expression
Source
In the Source directive, if the argument is the keyword internal, it specifies batch updates are to be done only on objects currently in the cache (and a directive of Depth 1 is assumed); otherwise, you specify the name of a URL for recursive enumeration.
This directive can occur only once in a valid configuration.
Syntax
Source internal
Source URL
Time
The Time directive specifies the time to start and stop updates. Valid values range from 00:00 to 24:00 (24-hour "military" time).
This directive can occur multiple times in a valid configuration, but only the first value will be used.
Syntax
Time start - end
Type
This function lets you control the updating of mime types that the proxy caches. This directive can occur any number of times, in any order.
Syntax
Type ignore
Type inline
Type mime_type
Parameters
ignore means that updates will act on all MIME types that the proxy currently caches. This is the default behavior and supersedes all other Type directives if specified.
inline means that in-lined data is updated as a special type, regardless of any later MIME type exclusions, and are meaningful only when doing recursive updates.
mime-type is assumed to be a valid entry from the system mime-types file, and is included in the list of MIME types to be updated. If the proxy doesn't currently cache the given MIME type, the object may be retrieved but is not cached.
The icp.conf File
This file is used to configure the Internet Cache Protocol (ICP) feature of your server. There are three functions in the icp.conf file, and each can be called as many times as necessary. Each function should be on a separate line. The three functions are add_parent, add_sibling, and server.
add_parent (adding parent servers to an ICP neighborhood)
The add_parent function identifies and configures a parent server in an ICP neighborhood.
Syntax
add_parent name=name icp_port=port number
proxy_port=port number mcast_address=IP address ttl=number round=1|2
|
Note
|
The above text should all be on one line in the icp.conf file.
|
Parameters
name specifies the name of the parent server. It can be a dns name or an IP address.
icp_port specifies the port on which the parent listens for ICP messages.
proxy_port specifies the port for the proxy on the parent.
mcast_address specifies the multicast address the parent listens to. A multicast address is an IP address to which multiple servers can listen. Using a multicast address allows a proxy to send one query to the network that all neighbors listening to that multicast address can receive, therefore eliminating the need to send a query to each neighbor separately.
ttl specifies the time to live for a message sent to the multicast address. ttl controls the number of subnets a multicast message will be forwarded to. If the ttl is set to 1, the multicast message will only be forwarded to the local subnet. If the ttl is 2, the message will go to all subnets that are one hop away.
round specifies in which polling round the parent will be queried. A polling round is an ICP query cycle. Possible values are:
1 means that the parent will be queried in the first query cycle with all other round one neighbors.
2 means that the parent will only be queried if none of the neighbors in polling round one return a "HIT."
Example
add_parent name=proxy1 icp_port=5151 proxy_port=3333
mcast_address=189.98.3.33 ttl=3 round=2
add_sibling (adding sibling servers to an ICP neighborhood)
The add_sibling function identifies and configures a sibling server in an ICP neighborhood.
Syntax
add_sibling name=name icp_port=port number proxy_port=port number
mcast_address=IP address ttl=number round=1|2
|
Note
|
The above text will all be on one line in the icp.conf file.
|
Parameters
name specifies the name of the sibling server. It can be a dns name or an IP address.
icp_port specifies the port on which the sibling listens for ICP messages.
proxy_port specifies the port for the proxy on the sibling.
mcast_address specifies the multicast address the sibling listens to. A multicast address is an IP address to which multiple servers can listen. Using a multicast address allows a proxy to send one query to the network that all neighbors listening to that multicast address can receive, therefore eliminating the need to send a query to each neighbor separately.
ttl specifies the time to live for a message sent to the multicast address. ttl controls the number of subnets a multicast message will be forwarded to. If the ttl is set to 1, the multicast message will only be forwarded to the local subnet. If the ttl is 2, the message will go to all subnets that are one hop away.
round specifies in which polling round the sibling will be queried. A polling round is an ICP query cycle. Possible values are:
1 means that the sibling will be queried in the first query cycle with all other round one neighbors. This is the default polling round value.
2 means that the sibling will only be queried if none of the neighbors in polling round one return a "HIT."
Example
add_sibling name=proxy2 icp_port=5151 proxy_port=3333
mcast_address=190.99.2.11 ttl=2 round=1
|
Note
|
The above text will all be on one line in the icp.conf file.
|
server (configuring the local proxy in an ICP neighborhood)
The server function identifies and configures the local proxy in an ICP neighborhood.
Syntax
server bind_address=IP address mcast=IP address num_servers=number
icp_port=port number default_route=name default_route_port=port number
no_hit_behavior=fastest_parent|default timeout=seconds
|
Note
|
The above text will all be on one line in the icp.conf file.
|
Parameters
bind_address specifies the IP address to which the server will bind. For machines with more than one IP address, this parameter can be used to determine which address the ICP server will bind to.
mcast the multicast address to which the neighbor listens. A multicast address is an IP address to which multiple servers can listen. Using a multicast address allows a proxy to send one query to the network that all neighbors who are listening to that multicast address can see, therefore eliminating the need to send a query to each neighbor separately.
If both a multicast address and bind address are specified for the neighbor, the neighbor uses the bind address to communicate with other neighbors. If neither a bind address nor a multicast address is specified, the communication subsystem will decide which address to use to send the data.
num_servers specifies the number of processes that will service ICP requests.
icp_port specifies the port number to which the server will listen.
default_route tells the proxy server where to route a request when none of the neighboring caches respond. If default_route and default_route_port are set to "origin," the proxy server will route defaulted requests to the origin server. The meaning of default_route is different depending on the value of no_hit_behavior. If no_hit_behavior is set to default, the default_route is used when none of the proxy array members return a hit. If no_hit behavior is set to fastest_parent, the default_route value is used only if no parent responds.
default_route_port specifies the port number of the machine specified as the default_route. If default_route and default_route_port are set to "origin," the proxy server will route defaulted requests to the origin server.
no_hit_behavior specifies the proxy's behavior whenever none of the neighbors returns a "HIT" for the requested document. Possible values are:
timeout specifies the maximum number of milliseconds the proxy will wait for an ICP response.
Example
server bind_address=198.4.66.78 mcast=no num_servers=5 icp_port=5151
default_route=proxy1 default_route_port=8080
no_hit_behavior=fastest_parent timeout=2000
|
Note
|
The above text will all be on one line in the icp.conf file.
|