Chapter 7. Proxy Configuration Files

This chapter describes the configuration files the proxy uses. You can use these files to manually configure the proxy server.

You might need to manually configure the proxy server for various reasons. If you accidentally lock your hosts out of the administrative forms or if you forget your administrative password, you'll have to manually change information in the proxy's configuration files.

Note: Before you can edit any of the configuration files, you must have permission to read and write the files. This probably means you need to log in as root or with the proxy's user account.

The proxy configuration files are kept in the directory admin/config in your server root directory. These files are described in more detail in the rest of this chapter.

If you use SOCKS, the proxy needs the SOCKS server configuration file stored in /etc/sockd.conf. This file is described in “sockd.conf File”.

magnus.conf File

The technical configuration file, called magnus.conf, controls all server operations not related to handling of URLs (documents)—the obj.conf file handles the URLs. All of the items in the magnus.conf configuration file are global and apply to the entire proxy server, as opposed to affecting only one URL or set of URLs.

Every command line in the file has the format:

Directive Value

  • Directive identifies an aspect of server operation. This string is case-insensitive.

  • Value is a specific value you are giving the directive. Its format depends on the directive. This string is usually case-sensitive.

Comment lines begin with a # character with no leading white space.

Directive lines can contain white space at the beginning of the line and between the directive and value, but trailing white space after the value might confuse the server. Long lines (which should only occur with the Init directive) can be continued with a backslash (\) character before the linefeed.

Caution: If you are using the Administration forms, you shouldn't use continuation lines in the magnus.conf file. Instead, put each Init configuration entirely on a single line. If you are absolutely sure you will never use the Administration forms to edit the magnus.conf file, you can use the backslash character.

Example 7-1. Example magnus.conf File

# Sample magnus.conf file for Netscape Proxy 1.1
# Note that ServerRoot isn't a directive to the proxy itself
# because all the paths are already specified absolute by the
# administration interface. This is only for the admin scripts.
#ServerRoot /var/ns_proxy
# Accept connections to port 8080
Port 8080
# Object configuration filename (this is the default for admin
# scripts -- don't change this line)
LoadObjects obj.conf
# Default object name (this is the default for admin scripts.
# Don't change this line.)
RootObject default
# Error log name (default place for admin scripts.
# Don't change this line.)
ErrorLog /var/ns_proxy
# Parent process id file (default for admin scripts. 
# Don't change this line.)
PidLog /u/luotonen/test/auth/logs/pid
# The IRIX user id that the proxy runs as 
User http
# Server name to be used with redirects
# Maximum number of child processes active simultaneously
MaxProcs 60
# Load MIME type information
Init fn=load-types mime-types=mime.types
# Initialize the common log filesystem, and
# Opens the global access log file
Init fn=init-clf global=/var/ns_proxy
# Activate the proxy network library, use extended log file 
# format, and set the proxy timeout to 2 minutes (120 seconds).
Init fn=init-proxy log-format="extended" timeout="120"
# Activate caching, set cache root to /vol1/ns-cache with 
# 2GB cache size; cache all HTTP, FTP and Gopher documents; 
# check that file is up to date if it's older than 1 hour;
# and do garbage collection at 3AM with reduced priority.
# Note: Don't use continuation lines (backslashes at the end of 
# lines) if you are using the administration interface—the
# scripts can't understand them. Instead, write all parameters on
# a single, long line. Using the \ character is OK if you never
# use the Administration forms.
Init fn=init-cache cache-root="/vol1/ns-cache" cache-size=2000 \
        cache-protocols="http,ftp,gopher" max-uncheck=3600 \
        lm-factor=0.06 gc-times="3:00" gc-nice=4

Directives in magnus.conf

This section defines the directives and describes their characteristics, including the directive name and description, format for the value string, default value if the directive is omitted, and how many instances of the directive should be in the file. The directives are

  • ServerName defines the proxy hostname.

  • Port defines the TCP port the server listens to.

  • User specifies the proxy's IRIX user account.

  • MaxProcs sets the maximum number of active processes.

  • MinProcs sets the minimum number of active processes. This directive isn't available through the proxy Administration forms.

  • ProcessLife specifies the number of requests each child process serves during its lifetime.

  • ErrorLog specifies the directory where the server logs its errors.

  • PidLog specifies a file to record the proxy's main process ID (pid).

  • LoadObjects specifies a startup object configuration file.

  • RootObject defines the default server object.

  • Chroot lets the server be placed into a jail—for security reasons.

  • Init (a special directive) initializes server subsystems.


ServerName tells the server what to put in the hostname section of any URLs it sends back to the client. This affects redirections done by the administration interface. This name is what all clients use to access the server; they need to combine this name with the port number.

You can't have more than one ServerName directive in magnus.conf.


ServerName host

host is a fully-qualified domain name such as


If ServerName isn't in magnus.conf, the proxy server attempts to derive a hostname through system calls. If they don't return a qualified domain name (for example, it gets myhost instead of, the proxy server won't start, and you'll get a message telling you to manually set this value.




Port controls which TCP port the server listens to. 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 navigators (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 common numbers are 8080 and 8000. If you use the Netscape Proxy's SOCKS daemon feature, the proxy should use the standard SOCKS port (1080).


Port number

number is a whole number between 0 and 65535.


If no port is specified, the server assumes 8080.


Port 8000
Port 8080
Port 1080


User specifies the IRIX 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 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, it isn't recommended.


User login

login is the eight-character (or less) login name for the IRIX user account.


If there is no User directive, the server runs with the user account it was started with. If the server was started as root or superuser, you'll see a warning message after startup.


User proxy
User sgi
User nobody
User Ari


MaxProcs sets the maximum number of processes the server can have active. The proxy server keeps the number of active processes between the number specified in MaxProcs and the number in MinProcs. If there is no MinProcs directive, then the MaxProcs number specifies the constant number of processes the proxy keeps active.

Choose a number that is appropriate for the type 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.


MaxProcs number

number is a whole number between 1 and the size of your system's process table.


MaxProcs 50


MaxProcs 20
MaxProcs 40
MaxProcs 80


MinProcs sets the minimum number of processes the server can have active. The proxy server regulates the number of processes between MinProcs and MaxProcs. If MinProcs isn't specified, a constant number of processes (specified with MaxProcs) will run.


MinProcs number

number is a whole number between 1 and the number specified in MaxProcs.


There is no default; if this directive is missing, the server uses the MaxProcs number to specify a constant number of processes.


MinProcs 10
MinProcs 20


ProcessLife specifies the number of requests each of the proxy's child processes serves before the processes exit and get respawned (this is set to 64 by default). When the processes are stopped and restarted, the memory they use is freed and then reused.

By stopping and restarting a process, the proxy ensures that memory isn't wasted by “lost” processes. For example, on rare occasions, a connection might be terminated while the proxy is reading the HTTP header, but when the request fails, the memory isn't freed.


ErrorLog 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.


ErrorLog logfile

logfile can be either a full path and filename or the keyword SYSLOG (it must be in all capital letters).


There is no default error log.


ErrorLog /var/ns_proxy/logs/errors


PidLog 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 Administration 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 PidLog file isn't writable by the user account that the server uses, the server does not log its process ID anywhere.


PidLog file

file is the full pathname and filename where the process ID is stored.


There is no default.


PidLog /var/ns_proxy/logs/pid
PidLog /tmp/


LoadObjects specifies one or more object configuration files to use on startup; these files tell the server the kinds of URLs to proxy and cache.

Although you can have more than one object configuration file, the proxy's Administration forms work only with one file and assume that it is in the server root in admin/config/obj.conf. If you use the Administration forms (or plan to), don't put the obj.conf file in any other directory and don't rename it.


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 was given, the server looks in the current directory.


There is no default.


LoadObjects obj.conf
LoadObjects /var/ns_proxy/admin/config/local-objs.conf


RootObject 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. The Administration forms assume the default to be the default named object. Don't deviate from this convention if you use (or plan to use) the Administration forms.


RootObject name

name is the name of an object defined in one of the object files loaded with a LoadObjects directive.


There is no default.


RootObject default
RootObject server1


Chroot lets the IRIX system administrator place the proxy server into a jail where it has access only to files in a given directory. This is useful if the server's security is ever compromised. For example, if an intruder somehow obtains shell access on the server host, the intruder could affect only a very limited set of files on the server host.

The server must be started as the superuser to use the Chroot directive. A server using Chroot can't be restarted with the -HUP signal, and it can't be configured with the Netscape Proxy Manager forms.

Logs and server configuration files should be kept outside the Chroot directory, but the cache root must be under the Chroot directory.

Note: All paths in magnus.conf must be absolute; paths in obj.conf must be relative to the Chroot directory.


Chroot directory

directory is the full pathname to the directory used as the server's root directory.


There is no default.


Chroot /d/ns_proxy
Chroot /www


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. You can specify zero or more Init directives.


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 parameters doesn't matter.

Init functions are described in detail in the following sections. Briefly, they are

  • init-proxy initializes the networking code used by the proxy.

  • init-cache enables and initializes caching.

  • init-sockd enables and initializes the SOCKD feature.

  • load-types maps file extensions to MIME types.

  • init-clf initializes the Common Log subsystem.


The function init-proxy initializes the networking code used by the proxy. Calling this function in magnus.conf is crucial (even though it is called automatically, you shouldn't rely on this feature).


timeout (optional) is the number of seconds after which the proxy should time out if it doesn't receive any new data from the remote server. This is not the maximum time allowed for the entire document transfer—it is the time between successive data packets. The timeout is set to 60 seconds by default.

log-format (optional) is either common or extended. It sets the log format used for proxy accesses. The default value is common.

suppress (optional) is a wildcard pattern for request header lines that should be filtered out from the request and not be forwarded to the remote server.


Init fn=init-proxy log-format=extended timeout=45
Init fn=init-proxy log-format=common timeout=30
Init fn=init-proxy log-format=common timeout=30 suppress="(from|user-agent)"


The function init-cache enables and initializes the caching system. It should be called only once if caching is enabled—calling this function is crucial if you want to use caching.

If you are using the Administration forms, you shouldn't use continuation lines in the magnus.conf file. Instead, put each Init configuration entirely on a single line. If you are absolutely sure you will never use the Administration forms to edit the magnus.conf file, you can use the backslash character to continue to the next line.


cache-root specifies the directory under which the cache resides. This directory must contain the Cache hierarchy, built either at installation time or through the Administration interface.

cache-size is the maximum allowed size of the cache in megabytes. When this size is reached, emergency garbage collection occurs.

cache-protocols is a comma-delimited list of protocols that can be cached (HTTP, FTP, and Gopher). Caching for a given protocol must be enabled this way before any document with that protocol can be cached.

gc-times is a comma-delimited list of 24-hour-clock times (for example, 20:30) that specifies when to run garbage collection.

lock-timeout (optional) is the time in seconds after which a hung cache lock can be broken. The default value is 1800 (30 minutes). See “Cache Lock Timeout” for more information on how this can happen.

top-dirs (optional) is the number of top-level cache directories (a, b, c, …) under the cache-root directory. It must be a power of two (1, 2, 4, 8, or 16) and the value must reflect the number of actual directories in the cache root (using a conflicting value causes badly degraded cache performance). The default value is 16.

Note: To explicitly not cache a document, you create an object for that document, and then set caching parameters for that object. See “ObjectType” for more information.

cache-mode (optional) has either the value all or nothing. “All” caches all documents unless you explicitly specify not to. Nothing caches no documents unless you explicitly specify that the given document should be cached. The default value is all.

max-uncheck is the number of seconds allowed between successive up-to-date checks. If the value is zero (default), an up-to-date check is always performed.

lm-factor is a floating point number used to estimate document expiration based on the last-modified date of the document. If the value is zero (default), the last-modified estimation is turned off and only explicit Expires HTTP headers are used. This value has no effect if max–uncheck is set to zero.

gc-nice is an integer from 0 to 39 that specifies the nice value of the garbage collector process. Zero (default) means normal priority; 39 means the lowest priority.

connect-mode specifies network connectivity and can be set to

  • normal (default) connects to remote servers when necessary.

  • fast-demo connects only if the item isn't found in the cache.

  • never returns an error if the document is not found in the cache, but no connection to a remote server is ever made.

cover-errors, if present and greater than zero, 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 a risk of getting stale data from the cache while the remote server is down. Setting this value to zero, or not specifying it (default) causes an error to be returned if the remote server is unavailable.


Init fn=init-cache cache-root=/var/mc-cache cache-size=500 \ 
     cache-protocols="http,ftp,gopher" gc-times="3:00,15:00" 
Init fn=init-cache cache-root=/var/mc-cache cache-size=500 \
	     lock-timeout=1200 top-dirs=16 \
	     cache-mode=all max-uncheck=86400 lm-factor=0.02 \
      gc-times="3:00" gc-nice=4 \
connect-mode=normal cover-errors=3600


The init-sockd function enables and initializes the Netscape Proxy 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/sockd.conf. The same care must be taken as when configuring any other SOCKS daemon.


sockd-conf (optional) specifies 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. These are the possible values:

  • strict means an identity check is required, and if the remote host is not running identd, the request is denied.

  • loose means an identity check is required, but if the remote host is not running identd, access is granted anyway.

  • none means an identity check is not performed.

log-type (optional) specifies where the proxy SOCKD module stores the access information. The directive can be

  • common uses the common log format and the same log file as other accesses. This is the default.

  • common-separate uses the common log format, but puts the entries in a separate log file (the log file name 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.


Init fn=init-sockd sockd-conf=/etc/sockd.conf log-type=syslog
Init fn=init-sockd log-type=common-separate 


The function load-types 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 “mime.types File” for more detailed information.

Calling this function is crucial if you use the Administration forms or the FTP proxying capability.


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.


Init fn=load-types mime-types=mime.types
Init fn=load-types mime-types=/tp/mime.types \


The function init-clf initializes the Common Log subsystem. It opens the log files whose names are given as parameters. The log files stay open until the server is shut down or until the base server process is sent the –HUP signal (at which time the logs are closed and reopened).

You use this function to specify which log files the proxy uses to record transactions. Then, you use the AddLog directive in the obj.conf file to specify the log file where the proxy stores the transaction record.

Note: Initializing this function is required if you are using the common log or extended log features.

For example, you use init-clf to specify a name that refers to a log file (such as http-log=/var/ns_proxy/loghttp); then you use the name with the AddLog function in obj.conf to add a log entry to the file (such as AddLog fn=proxy-log name=http-log). If you ever change the path or filename of the log file, you do it only once—in magnus.conf—instead of multiple times in obj.conf.

You also can use AddLog to store transactions in more than one log file. See “AddLog” for more information about the AddLog function.

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, rename the file and then send the -HUP signal to restart the proxy. 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 is left for you to use).


At least one log file should be given. The parm part of the parm=value pair should be a unique name for the log file. You will use this name later on, as a parameter to the proxy-log function.


Init fn=init-clf global=/var/ns_proxy/logs/access 
Init fn=init-clf global=/tmp/proxy-access

obj.conf File

The object configuration file, called obj.conf, uses objects to control how the server performs access control, configures the cache, and routes URLs.

Objects (also referred to as resources) are settings that tell the proxy how to treat all URLs. URLs matching a specified wildcard pattern belong to the same object (or resource). This object grouping can then be used to control (in fine detail) the behavior of the proxy server.

Using this object grouping scheme, you can specify single resources with their complete URL, whole "directories" with the path followed by /*, and various other groups such as *.html. You can then configure the settings you want to use for that object (for example, caching or denying access based on the server's hostname or a string within a URL).

Note: All pathnames must be relative if you use Chroot. See “Chroot” for more information.

Structure of obj.conf

The obj.conf file must have four specific objects in it (see “Required Objects for obj.conf” for a description of the objects). You can add other objects to this file. To specify an object, use the following format:

<Object ppath=wildcardpattern>
  <Client dns=wildcardpattern>

You use wildcard patterns to control which URLs are grouped in the object. You then specify one or more directives to control what the proxy server does when it encounters any URL matching the wildcard pattern specified with ppath.

You can also set options for specific client hosts. This is a powerful feature because, unlike other proxy servers where a host either can or cannot access a URL, you make the proxy act differently for a client depending on the URL the client sends to the proxy. Although you don't need any <Client> sections in an object section, you can specify more than one—so the proxy acts differently based both on who requests something and what the request is.

Directive Syntax

Each directive line (regardless of where it appears) has the format:

Directive fn=function [parameter1=value1]…[parameterN=valueN]

Directive identifies an aspect of server operation. This string is case-insensitive and must appear at the beginning of a line. Function is a function and parameters given to the directive. Its format depends on the directive.

Directive lines cannot contain white space at the beginning of the line and between the directive and value, but trailing white space after the value might confuse the server. Long lines (which should occur only with the Init directive) can be continued with a \ character before the linefeed. Comment lines begin with a # character with no leading white space.

Sample Object

The following sample object applies to all HTTP URLs (the wildcard is http://*).

When the proxy receives a request for an HTTP document, it scans the URL for the characters play (PathCheck); if it finds that string in the URL, it doesn't retrieve the document from the remote server (it denies service to the client).

<Object ppath="http://*">
		PathCheck		fn=deny-service
		ObjectType		fn=cache-setting
		Service		fn=proxy-retrieve

This object also caches all HTTP documents and refreshes the documents if they are older than four hours or if they need refreshing as determined by the date they were last modified. The Service directive tells the proxy to retrieve the HTTP documents by default.

Example 7-2. Example obj.conf File

# Sample obj.conf file for Netscape Proxy 1.1.
# The default object
# The default object is a special named object that applies to all URLs
<Object name="default">
# Authenticate the proxy user
AuthTrans fn="proxy-auth" auth-type="basic"
# Make FTP URLs that are of file:// form to work.
NameTrans fn="map" from="file:" to="ftp:"
# Mappings for the admin interface and icons -- these aren't actually 
# proxy configuration directives but features of a stripped down
# HTTP server that the Netscape Proxy contains for this purpose
NameTrans fn=pfx2dir from=/admin/bin dir=/var/ns_proxy/admin/bin  name=cgi
NameTrans fn=pfx2dir from=/admin     dir=/var/ns_proxy/admin/html name=file
NameTrans fn=pfx2dir from=/ns-icons  dir=/var/ns_proxy/ns-icons   name=file
# Allow proxy accesses only from inside the domain.
# That is, anything outside of that domain is denied service to the proxy.
<Client dns="*~*" ip="*~(198.93.*.*|198.95.*.*)>
PathCheck fn=deny-service
# Require all proxy users to authenticate to the proxy;
# grant access to any successfully authenticated user.
PathCheck fn=require-proxy-auth realm="Firewall proxy server" auth-type=basic auth-user=*
# Default action is to deny access (the remaining objects explicitly allow it).
Service fn=deny-service
# Log the access
AddLog fn=proxy-log
# End of default object
# ppath objects
# Allow FTP to be proxied through this proxy;
# retrieve a new copy if older than 10 hours.
<Object ppath="ftp://*">
ObjectType fn=cache-setting max-uncheck=36000
Service fn=proxy-retrieve
# Allow HTTP to be proxied; use the max-uncheck setting in the
# cache-init function (1 hour).
<Object ppath="http://*">
Service fn=proxy-retrieve
# Allow HTTPS URLs to be proxied (secure documents don't get cached)
<Object ppath="https://*">
Service fn="proxy-retrieve"
# Allow Gopher to be proxied; use the max-uncheck setting in the
# cache-init function (1 hour).
<Object ppath="gopher://*">
Service fn=proxy-retrieve
# Allow SSL proxying, i.e. CONNECT requests to remote 443 ports
<Object ppath="connect://*:443">
Service fn=connect method=CONNECT
# The following three objects are the standard settings to make the
# admin interface and the icons work, and admin interface protected
# by the admin password. Do not change!
<Object name=cgi>
PathCheck fn=unix-uri-clean
PathCheck fn=find-pathinfo
ObjectType fn=force-type type=magnus-internal/cgi
Service fn=send-cgi

<Object name=file>
PathCheck fn=unix-uri-clean
PathCheck fn=find-index index-names=index.html
ObjectType fn=type-by-extension
ObjectType fn=force-type type=text/plain
Service fn=send-file

<Object ppath="/var/ns_proxy/admin/*">
AuthTrans fn=basic-ncsa auth-type=basic userfile=/var/ns_proxy/admin/config/admpw
<Client dns="*~(helium|carbon|uranium)">
PathCheck fn=deny-service
PathCheck fn=require-auth auth-type=basic realm="Netscape Proxy Administration"

Required Objects for obj.conf

There are certain objects that must be in the obj.conf file to make the Administration forms work for your proxy. If you are familiar with the normal Netscape Server software (a regular HTTP server), you might notice that these functions control local file access and CGI execution.

Note: If you don't use the Administration forms, these objects don't necessarily need to be in obj.conf.

However, on a proxy server the local access interface is a simplified version, and it cannot be used for any purpose other than the Administration forms. Special care is taken inside the proxy software to guarantee that it cannot be used, accidentally or otherwise, as a normal HTTP server.

The following sections describe the objects that must be in obj.conf.

The Default Object

<Object name="default">
NameTrans fn="map" from="file:" to="ftp:"
NameTrans fn="pfx2dir" from="/admin/bin"
		dir="ServerRoot/admin/bin"  name="cgi"
NameTrans fn="pfx2dir" from="/admin" 
		dir="ServerRoot/admin/html" name="file"
NameTrans fn="pfx2dir" from="/mc-icons"  
		dir="ServerRoot/mc-icons"   name="file"
Service fn="deny-service"
AddLog fn="proxy-log"

Note: ServerRoot stands for the proxy installation directory, for example /var/ns_proxy.

The first NameTrans directive takes care of URLS that use file: by changing them to ftp: URLs. If you have any mappings to mirror sites, put them after this mapping.

The next three NameTrans directives map admin and icon URLs into their respective directories. These are the only legal uses for the pfx2dir function, which doesn't belong to the actual proxy configuration (you'll get errors if you try to use it anywhere else).

The deny-service function ensures that by default, access isn't granted. (Access isn't granted by default even if you forgot this function, but the error message would be less descriptive, and it would be classified as a misconfiguration.)

The proxy-log function takes care of proxy access logging, whether it is in common or extended log format. This function can have the additional iponly=1 parameter, which inhibits reverse DNS lookups and logs only the IP address of the requesting client.

CGI Object

This object controls the admin form handler scripts and should read exactly as follows:

  <Object name="cgi">
  PathCheck fn="unix-uri-clean"
  PathCheck fn="find-pathinfo"
  ObjectType fn="force-type" type="magnus-internal/cgi"
  Service fn="send-cgi"

Local Access Object

This object controls HTML Administration forms and internal images. It should read exactly as follows:

  <Object name="file">
  PathCheck fn="unix-uri-clean"
  PathCheck fn="find-index" index-names="index.html"
  ObjectType fn="type-by-extension"
  ObjectType fn="force-type" type="text/plain"
  Service fn="send-file"

Admin Interface Protection

The Administration forms are protected by default; the following object configures the protection. (ServerRoot stands for the proxy installation directory. )

<Object ppath="/var/ns_proxy/admin/*">
AuthTrans fn="basic-ncsa" 
PathCheck fn="find-index" index-names="index.html"
<Client ip="*~" dns="*~*.your.domain">
PathCheck fn="deny-service"
PathCheck fn="require-auth" realm="Netscape Proxy Administration"

What Are Named Objects?

Named objects are objects identified by <Object name=…> in the object configuration file.

To control the behavior of the entire server, you would modify the setting for the default object. This object must contain all of the name-translation directives for the server, and it should contain any global configuration changes.

How the Proxy Server Handles Objects

The Netscape design (both the HTTP Server and the Proxy) breaks down the process of responding to an information request. Each step in the process is done once for all objects, then another step is done for all objects, and so on. The process steps are as follows:

  1. Authorization translation. Translate any authorization information given by the client into a user and group. If necessary, decode the message to get the actual request. Also, proxy authorization is available.

  2. Name translation. Before anything else is done, a URL can be translated into a filesystem-dependent name (an administration URL), a redirection URL, mirror site URL, or it might be kept intact and retrieved as-is (the normal proxy case).

  3. Path checks. Perform various tests on the resulting path. Largely used to make sure that it's safe for the given client to retrieve the document (only for local access).

  4. Object types. Determine the MIME type information for the given document. MIME types can be registered document types such as text/html and image/gif, or they can be internal document identification types. Internal types always begin with magnus-internal/, and are used to select a server function to use to decode the document. (Only used for local access; the proxy system calls these routines automatically when necessary.)

  5. Service. Select an internal server function that should be used to send the result back to the client. This function can be the normal proxy-service routine or a CGI execution for admin forms.

  6. Log. Select a function to record information about the transaction that just finished.

These steps map directly to six of the configuration directives allowed for each object. There is a seventh configuration directive (send-error) that controls how the server responds to the client when it encounters an error.

Directives in obj.conf

This section defines the 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

  • AuthTrans protects server resources from specific users.

  • NameTrans maps URLs to mirror sites and the local filesystem.

  • PathCheck checks URLs after NameTrans.

  • ObjectType tags additional information to requests.

  • Service sends data and completes the requests.

  • AddLog adds log entries to any log files.

  • Error sends customized error messages to clients.


AuthTrans stands for Authorization Translation. 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 a different user.

The server analyzes the authorization of client users into two steps. First, it translates authorization information sent by the client, and then it requires that such authorization information is present. This is done in the hope that multiple translation schemes can be easily incorporated, as well as to provide 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.

Proxy authorization


proxy-auth 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 prevent the ability to authenticate to the remote server.

This function is usually used with the PathCheck function require-proxy-auth.


“auth-type” specifies the type of authorization to be used. This should always be “basic”.

“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.

“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 userfile as well.

“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.


AuthTrans fn=proxy-auth auth-type=basic 
AuthTrans fn=proxy-auth auth-type=basic 
  userfile=/var/ns_proxy/.htpasswd grpfile=/var/ns_proxy/.grpfile


NameTrans stands for Name Translation. This directive maps URLs to mirror sites and to the local filesystem (for the Administration forms).

NameTrans directives should appear in the root object (the "default" object), although you can put them elsewhere. If there is more than one NameTrans directive in an object, the server applies functions until one succeeds, and then modifies the URL to either a mirror site URL or to a full filesystem path.

Map URLs to Mirror Sites


map looks for a certain URL prefix in the URL the client is requesting. If it finds the prefix, it replaces the prefix with the mirror site prefix.

Don't use trailing slashes with the prefixes you specify—they cause Not Found errors.


“from” is the prefix to map.

“to” is the mirror site prefix that the from prefix is mapped to.

“name” (optional) gives a named object from which to derive the configuration for this mirror site.


# Map site to mirror site http://mirror.dom
NameTrans fn=map from="" 


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 things such as CGI path info and for dangerous elements such as ../ and //, and then any access restriction is applied.

If there is more than one PathCheck directive in an object, all of the directives will be applied in the order they appear.

Deny Proxy Access


deny-service 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, then 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.


“path” is a wildcard expression of the path to check. Not specifying this parameter is equivalent to specifying *. URLs matching the expression are denied access to the proxy server.


<Object ppath="http://sgi/*">
# 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 of which this is placed.
<Client dns=*~*>
PathCheck fn=deny-service


ObjectType directives tag additional information to the requests, such as caching information and if another proxy should be used.

If there is more than one ObjectType directive in an object, all of 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 ones ignored.

Use Another Proxy for Retrieving This Resource


set-proxy-server is an ObjectType function that directs the Netscape Proxy to connect to another proxy for retrieving the current resource.


“hostname” is the name of the host that the other proxy is running on.

“port” is the port number of the remote proxy.


ObjectType fn=set-proxy-server port=8080

Use a SOCKS Server When Retrieving This Resource


set-socks-server is an ObjectType function that tells the Netscape Proxy to make the connection to the remote server using a SOCKS daemon when retrieving the current resource.


“hostname” is the name of the host that the SOCKS daemon runs on.

“port” is the port number of the SOCKS daemon.


ObjectType fn=set-socks-server port=1080

Specify 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.


max-uncheck (optional) is the maximum time (in seconds) allowed between consecutive up-to-date checks. If set to zero, a check is made every time the document is accessed.

lm-factor (optional) is a floating point number specifying the factor used in expiration-time estimation (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 for the document to remain unchanged. Specifying a value of zero turns this off, and the caching system uses only explicit expiration information (rarely available). This value has no effect if max–uncheck is set to zero.

cache-mode can be either all or nothing. This overrides the default cache-mode set in the init-cache function. So, if the default cache-mode is on (all documents are cached unless explicitly inhibited), using the value “nothing” inhibits caching for the specified object. Similarly, to cache a resource (object) on a proxy that isn't caching by default, use the value all.


# 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

Maximum Length of Cached Queries


cache-queries is an ObjectType function that specifies the maximum length of a query in order for it to be cached (if it has either a Last-modified or an Expires header). The proxy caches the query results, not the query.


“maxlen” specifies the maximum length (in characters). The default value is 16. If zero, queries aren't cached.


# Cache queries not longer than 8 characters
ObjectType fn=cache-queries maxlen=8
# Don't cache queries at all
ObjectType fn=cache-queries maxlen=0


Once the other directives have done all the necessary checks and translations, the Service class of functions sends the data (first receiving it from a remote server when necessary) and completes the request. Most of the time, the Service function connects to a remote server making the request for the client and then passing the results back to the client.

Service directives support the following optional parameters to help determine whether the directive is used or not:

  • method specifies a wildcard expression of HTTP methods that the client must be using to have the directive applied. Valid HTTP methods are GET, HEAD, and POST. Multiple values are enclosed in parentheses and separated by the pipe (|) symbol.

  • type (not with proxy-retrieve) specifies a wildcard expression of MIME types to apply the directive to. 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 there is more than one Service directive in an object, the first applicable directive is used and the rest are ignored.

Proxy Retrieval


proxy-retrieve retrieves a document from a remote server and returns it to the client. It also manages caching if it is enabled.

By default (in the absence of the method parameter) all methods (GET, HEAD, and POST) are allowed.




# Normal proxy retrieve 
Service fn=proxy-retrieve
# Proxy retrieve with POST method disabled
Service fn=proxy-retrieve method=(GET|HEAD)

Denying Service


deny-service is the only function that belongs to two classes: PathCheck and Service. It prevents access to the requested resource.


“path” (optional) specifies a wildcard expression of the path to check. Not specifying this parameter is equivalent to specifying *. URLs that match the expression deny access to the client.


# Deny all requests for the current resource
Service fn=deny-service
# Deny POST requests
Service method=POST fn=deny-service
# Deny POST requests for the given site
Service method=POST path=* fn=deny-service


After the request is finished and the proxy server has stopped talking to the client, the proxy server logs the transaction. The server records information about every access clients make, and it records information about the client making the request.

If there is more than one AddLog directive in an object, all are used.

Log in the Common or Extended Format


proxy-log is an AddLog function that records request-specific data in either the extended or common log format (used by most HTTP servers). 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 (use pstats to interpret the log file; see “Interpreting the pstats Output”).

The log format is specified by the init-proxy function call.


“name” (optional) gives the name of a log file, which must have been given as a parameter to the init-clf Init function. If no name is given, global is assumed.

iponly (optional) instructs the server to skip looking up the host name of the remote client and records the IP address instead. The value of iponly has no significance, as long as it exists; the Administration forms set iponly="1".


# Log all accesses to the central log file
AddLog fn=proxy-log
# Log non-local accesses to another log file
<Client ip=*~198.93.9[2345].*>
AddLog fn=proxy-log name=nonlocal


At any time during a request, conditions can occur that stop the server from fulfilling a request and then return an error to the client. When these happen, the server can send a short HTML page to the client describing the error in very general terms.

In order to make error handling more friendly, the proxy server lets you intercept certain errors and send a file of your choosing instead of the server's default error message.

The following is a list of errors that are returned by the server. Each line has the 3-digit HTTP code that designates the error, followed by a short description of the error.

  • 401 Unauthorized (for Administration forms only). The server requires HTTP user authorization to allow access to the Administration forms, and the client either 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 filesystem 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 the client either didn't provide any, or it was insufficient. Also, the client software might not support proxy authorization. The Netscape Navigator version 1.1 supports this authorization.

  • 500 Server Error. Server errors mean that an error has occurred within the server that prevents it from finishing the request. Server errors mainly happen because of misconfiguration or host resources such as swap space being exhausted.


Error fn=send-error code=401 path=/var/ns_proxy/errors/401.html

mime.types File

The mime.types file tells the server how to convert files with certain extensions (such as .GIF) into a Multipurpose Internet Mail Extensions type (such as image/gif). MIME files are compact files and transfer quickly. Also, MIME is needed by browsers (like the Netscape Navigator); without MIME they couldn't tell the difference between an HTML page and a graphic file.

The mime.types file contains the global file extensions for all proxy servers. The first line in the file identifies the file format and must read:

#--Netscape Communications Corporation MIME Information

Other non-comment lines have the format

type=type/subtype exts=[file extensions] icon=icon

  • type/subtype

  • exts are the file extensions associated with this type. When the proxy transfers a file with one of these extensions, it uses the MIME type you specified in type.

  • icon is the name of the icon the browser displays. Netscape Navigator keeps these images internally. If you use a browser that doesn't have these icons, the proxy delivers them.

    Figure 7-1. Internal Icons for MIME Types

    Example 7-3. Example mime.types File

    #--Netscape Communications Corporation MIME Information
    # Don't delete the above line. It identifies this file's type.
    # This is a simple MIME types file for the Netscape Proxy. Most
    # of the MIME types are already compiled in the proxy. Types that 
    # are part of the Administration forms (HTML and GIF) must appear
    # here, or they won't be known to the part of the server that 
    # manages the Administration interface calls.
    # Icons (internal-gopher-…) are references to Netscape's 
    # internal icons. If a client doesn't support these icons, the
    # proxy will provide them.
    type=application/oda					exts=oda
    type=application/pdf					exts=pdf
    type=application/x-mif					exts=mif
    type=application/x-dvi					exts=dvi
    type=application/x-hdf					exts=hdf
    type=application/x-netcdf					exts=nc,cdf
    type=application/x-texinfo					exts=texinfo,texi
    type=application/zip					exts=zip
    type=application/x-tar					exts=tar
    type=application/x-macbinary					exts=bin
    type=application/x-stuffit					exts=sit
    type=image/gif       exts=gif          icon=internal-gopher-image
    type=image/jpeg   exts=jpeg,jpg,jpe    icon=internal-gopher-image
    type=image/x-xwindowdump   exts=xwd    icon=internal-gopher-image
    type=text/html   exts=htm,html,shtml    icon=internal-gopher-text
    type=text/plain  exts=txt               icon=internal-gopher-text
    type=text/richtext   exts=rtx           icon=internal-gopher-text
    type=text/tab-separated-values exts=tsv icon=internal-gopher-text
    type=text/x-setext      exts=etx        icon=internal-gopher-text
    type=application/x-tar enc=x-gzip exts=tgz
    enc=x-gzip                     exts=gz
    enc=x-compress                 exts=z

admpw File

The admpw file contains the Administration password. If you forget your password, there is no way to find out what it was. You must encrypt a new one and replace the old version with it. The file has the format:


If you forget your Administration password, you can edit the admpw file and delete the password section (everything after the semicolon). When you go to the Proxy Manager, you don't need to enter a new password—but you should immediately go to the Administration Manager and set a new one.

Caution: Because you can delete the password, it is very important to keep secure the proxy's IRIX id account and to ensure that only that proxy account and the root account have full (write) access to the server root directory. This way, only someone running as root or with the proxy's user account can enter the admin/config directory and edit the file.

sockd.conf File

Although SOCKD doesn't know if a host is internal to its network, it does knows which host is the requestor and which is the destination (it uses this for access control). This means SOCKD provides access from external hosts into your internal networks in addition to the normal internal-to-external proxy functionality. Use caution with the external-to-internal functionality. If you don't need external to internal access, you should specifically deny such connections. For example, if 198.95 is your internal network, use deny as the first line in sockd.conf to protect your inside hosts from external access attempts.

Note: The SOCKS daemon is a generic firewall daemon that controls access through the firewall on a point-to-point basis. By default, the SOCKS daemon features are disabled. The Netscape Proxy Server supports SOCKS version 4.

Structure of sockd.conf

The proxy uses the file /etc/sockd.conf to control access to the SOCKS proxy server SOCKD and its services. Each line in this file can be up to 1023 characters long and has the following format:

action [*=userlist] src_addr src_mask [dst_addr dst_mask]
[op dst_port] [ : shell_cmd ]

Note: Use spaces or tabs to separate the fields. Text in square brackets is optional. Comment lines begin with #, except for lines that start with #NO_IDENTD: or #BAD_ID:.

Each line defines what the proxy does when it gets a request that matches the line. The line begins with either permit or deny—this defines how the server behaves when it gets a matching request.

When SOCKD receives a request, it checks the request against the lines in /etc/sockd.conf. When it finds a line that matches the request, the request is either permitted or denied based on the first word in the line. The daemon ignores the remaining lines in the file. If there are no matching lines, the request is denied.

Caution: Because the daemon uses only the first line that matches a request, the order of the lines is important. For example, the following two lines in this order deny access to a user named chris at the specified domain:

deny *=chris

If the two lines switch position, then requests by user chris are granted because the user belongs to the domain listed in the first line.

The rest of this section describes the other elements you can place in a line in the sockd.conf file.


The optional userlist specifies one or more user IDs separated by commas—spaces and tabs aren't allowed. If you don't specify a user list, the other contents of the line applies to all users accessing the proxy.

Unlike other SOCKD applications, this version of the proxy doesn't support filenames in the userlist.

src_addr and dst_addr

You can specify lines that apply to requests based on the source or destination IP address. src_addr and dst_addr specify dotted IP addresses for hosts, networks, or subnets.

The src_mask and dst_mask fields are masks for the corresponding IP addresses. Bits in these masks that are set to 0 indicate the bit positions to be ignored during comparisons of IP addresses. So, specifying in the mask demands an exact match with the specified IP address field, whereas in the mask causes a match no matter what IP address is specified. (This is the same way netmasks are usually interpreted, and is the opposite of the interpretation in previous versions of SOCKD.) If the dst_addr dst_mask pair is omitted, the line applies to all destination hosts.

op dst_port

You can specify lines that apply to requests based on destination ports. If you don't specify a destination port, the line applies to all port numbers. The op section specifies an operator for the destination port number. The operator must be one of the following:

  • eq for equals

  • neq for not equals

  • lt for less than

  • gt for greater than

  • le for less than or equal to

  • ge for greater than or equal to

The destination port (dst_port) can be a port number or a service name specified in /etc/services (for example, you could use telnet instead of port number 23).


The shell_cmd specifies a string that runs when the host matches a line in sockd.conf. The proxy replaces the following items before the string is sent to the shell:

Table 7-1. String Substitutions in shell_cmd


Replaced by


The client's domain name if known, or its IP address


The client's IP address


connect or bind, the command SOCKD runs


The process ID of sockd


The service name if known, otherwise the destination port number


The destination port number


The user ID reported by identd


The user ID reported by the client program


The destination host's domain name if known, otherwise its IP address


The destination host's IP address


A single %

You can use several shell commands together. For example,

/usr/ucb/finger @%A | /usr/ucb/mail -s 'SOCKS: rejected %u@%A to %Z (%S)' root root@%A

fingers the client host and pipes the result into an e-mail message for superusers at the server host and the client host with an appropriate Subject line. Most often this feature is used with a deny line, but it can be used with permit also.

Although there is an implied deny all at the end of the configuration file, you can supply one explicitly to take some specific action when requests are so rejected. For example, the following would appear in one continuous line:

deny : /usr/ucb/finger @%A | /usr/ucb/mail -s 'SOCKS: rejected %u@%A to %Z (%S)' root root@%A


You can also specify commands to run when SOCKD can't connect to a client's identd or when the user IDs reported by the client programs and the client's identd don't match. These special entries must start with #NO_IDENTD: and #BAD_ID:, followed by the shell commands to run. For example:

#NO_IDENTD: /usr/ucb/mail -s 'Please run identd on host %A' root@%A
#BAD_ID: finger @%A | /usr/ucb/mail -s '%U pretends to be %u on %A' root root@%A