his chapter describes the configuration files that the Netscape Proxy Server uses. These are the files that you're changing when you use the Netscape Proxy Server Manager on-line forms. You can also configure the Netscape Proxy Server manually by editing the files directly.
You might need to configure the Netscape Proxy Server manually 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 change information manually in the proxy's configuration files. Perhaps more importantly, you will probably need to develop an understanding of what your configuration files do for you, so that you can write scripts to automate configuration functions that you might want in addition to those available in the on-line forms. This is especially useful if, for example, you are using many proxy servers or your URL lists require frequent or high-volume updates.
Before you can edit any of the configuration files, you must have permission to read and write to the files. You might need to log in as root or use the proxy's user account.
The files that you use to configure the proxy are in a directory called proxy-<PROXY-ID>/config, in your server root directory. Here's a brief description of each file:
Directive Value
Directive identifies an aspect of server operation. This string is case insensitive. Value is a number or label you give the directive. Its format depends on the directive. Unlike the Directive string, this string is usually case sensitive.
Sample magnus.conf file
magnus.conf:
# Sample magnus.conf file for Netscape Proxy 2.0
# 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 /usr/ns-home
#
# Accept connections to port 8080
Port 8080
#
# Object configuration file name (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 /usr/ns-home/logs/errors
#
# Parent process id file (default for admin scripts.
# Don't change this line.)
PidLog /usr/ns-home/logs/pid
#
# The Unix user id that the proxy runs as
User nobody
#
# Server name to be used with redirects
ServerName step.mcom.com
#
# Maximum number of child processes active simultaneously
MaxProcs 6
DNS on
chroot /www
The directives in magnus.conf are explained in detail in Appendix C, "Proxy configuration files."
The obj.conf file
The Netscape Proxy Server object configuration file, obj.conf, uses objects to control how the server performs access control, routes URLs and initializes server subsystems. This obj.conf file is quite different in content from other Netscape server files of the same name.
Configuration objects (also referred to as "resources") are settings that tell the proxy how to treat URLs. URLs matching a specified wildcard pattern belong to the same configuration 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 host name or a string within a URL).
Note
All path names must be relative if you use chroot. See page 353 for more information.
The structure of obj.conf
The obj.conf file must have specific objects in it (the objects are described on page 231). You can add other objects to this file. To specify an object, you would use the following format:
<Object ppath=reg-exp>
Directives
...
<Client dns=shell-exp>
Directives
...
</Client>
</Object>
Although <Client> lines are not required, you can have as many as needed.
If you want to control access at the URL level, you can use regular expression patterns to control which URLs are grouped in the object. You can then specify one or more directives to control what the proxy server does when it encounters any URL matching the regular expression pattern specified with ppath.
You can also set options for specific client hosts. This is a powerful feature. Unlike other proxy servers that simply control whether a host can or cannot access a URL, you can make the proxy act differently depending on which user or host is requesting the URL.
Directive syntax
Each directive line (regardless of where it appears in obj.conf) 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.Caution!
If you are using the Administration forms, you shouldn't use continuation lines
in the obj.conf file. Instead, put each directive entirely on a single line. If you
are absolutely sure you will never use the Administration forms to edit the
obj.conf file, you can use the character.
A sample object
The following sample object applies to all HTTP URLs (the pattern is http://.*). When the proxy receives a request for an HTTP document, it scans the URL for the characters play (as specified in PathCheck); if it finds that string in the URL, it doesn't retrieve the document from the remote server, and it denies service to the client.
<Object ppath="http://.*">
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. Figure 13.2shows an example of an obj.conf file:
PathCheck fn=deny-service
path=".*play.*"
ObjectType fn=cache-setting
max-uncheck=14400
lm-factor=0.1
Service fn=proxy-retrieve
</Object>
Sample obj.conf file
# Netscape Communications Corporation - obj.conf
# You can edit this file, but comments and formatting changes
# might be lost when the admin server makes changes.
Init fn="flex-init" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
"%Req->reqpb.proxy-request%" %Req->srvhdrs.status% %Req->vars.p2c-cl%"
access="/usr/ns-proxy/proxy-TEST/logs/access"
Init fn="load-types" mime-types="mime.types"
Init fn="init-proxy" timeout2="15" timeout="1200"
Init fn="init-cache" dir="/usr/ns-proxy/cache" status="on" ndirs="1"
Init fn="init-partition" min-avail="5" max-size="10" dir="/usr/ns-proxy/cache" status="on"
name="NoName"
Init fn="init-urldb" dir="/usr/ns-proxy/cache/urldb" status="on"
Init conf-file="bu.conf" fn="init-batch-update" dir="/tmp" status="off"
<Object name="default">
NameTrans from="file:" fn="map" to="ftp:"
NameTrans from="/ns-icons" fn="pfx2dir" dir="/usr/ns-proxy/ns-icons" name="file"
PathCheck fn="url-check"
PathCheck fn="check-acl" acl="proxy-TEST_formgen-READ-ACL_allow-1970"
PathCheck fn="check-acl" acl="proxy-TEST_formgen-WRITE-ACL_deny-1970"
Service fn="deny-service"
AddLog fn="flex-log" name="access"
AddLog fn="urldb-record"
</Object>
<Object name="file">
PathCheck fn="unix-uri-clean"
PathCheck index-names="index.html" fn="find-index"
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
Service fn="send-file"
</Object>
<Object ppath="ftp://.*">
ObjectType fn="cache-enable"
ObjectType fn="cache-setting" max-uncheck="21600"
Service fn="proxy-retrieve"
</Object>
<Object ppath="http://.*">
ObjectType fn="cache-enable"
ObjectType lm-factor="0.100" fn="cache-setting" max-uncheck="3600"
Service fn="proxy-retrieve"
</Object>
<Object ppath="https://.*">
Service fn="proxy-retrieve"
</Object>
<Object ppath="gopher://.*">
ObjectType fn="cache-enable"
ObjectType fn="cache-setting" max-uncheck="14400"
Service fn="proxy-retrieve"
</Object>
<Object ppath="connect://.*:443">
Service fn="connect" method="CONNECT"
</Object>
<Object ppath="connect://.*:563">
Service fn="connect" method="CONNECT"
</Object>
Required objects for obj.conf
Certain objects must be in the obj.conf file to make the Administration forms work for your proxy. If you are familiar with the Netscape Server software (a regular HTTP server), you might notice that these functions control local file access and CGI execution.
On a proxy server the local access interface is a simplified version, and it cannot be used for any purpose other than the on-line forms. Special care is taken inside the proxy software to guarantee that it cannot be used, accidentally or otherwise, as a normal HTTP server. If you don't use the on-line forms, these objects don't necessarily have to be in obj.conf.
The default object
The default object contains the required directives. 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. Here is an example of a default object:
Example
<Object name=default>
NameTrans fn=map from=file: to=ftp:
NameTrans fn=pfx2dir from=/ns-icons dir="/usr/ns-home/ns-icons"
name=file
Service fn=deny-service
AddLog fn=proxy-log
AddLog fn=urldb-record
</Object>
function, which doesn't belong to the actual proxy configuration (you'll get errors if you try to use it anywhere else).
The 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 (MIME) 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 can't tell the difference between an HTML page and a graphic file.
The mime.types file, shown in Figure 13.3, 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
Parameters
Other non-comment lines have the format:
type=type/subtype exts=[file extensions] icon=icon
where each parameter is as follows:
type/subtype
is the MIME type and subtype.
icon is the name of the icon the browser displays; the icons are shown in
Figure 13.4. Netscape Navigator keeps these images internally. If you use a
browser that doesn't have these icons, the Netscape Proxy Server delivers them.
Sample mime.types file
Internal icons for MIME types
The 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 user:password.
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 administration server, you don't need to enter a new password, but you should immediately go to Access Control in the Netscape Proxy Server Manager and set a new one.
Warning!
Because you can replace the Administration password, it is very important to
keep secure the proxy's Unix id account and to ensure that only that proxy
account and the root account have full (read/write) access to the server root
directory. This way, only someone running as root or with the proxy's user
account can enter the proxy-EXAMPLE/config directory and edit the file.
The sockd.conf file
The SOCKS daemon is a generic firewall daemon that controls point-to-point access through the firewall. By default, the SOCKS daemon features are disabled. The Netscape Proxy Server supports SOCKS version 4.
Although SOCKD doesn't know if a host is internal to its network, it does know 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.
Note
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 the following as the first line
in sockd.conf to protect your internal hosts from external access attempts:
deny 0.0.0.0 0.0.0.0 198.95.0.0 255.255.0.0
The 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 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/sockd.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 in this file can be up to 1023 characters long and has the following format:
Syntax
permit|deny [*=userlist] [@=serverlist] src_addr src_mask [dst_addr
dst_mask]
[op dst_port] [ : shell_cmd ]
Use spaces or tabs to separate the fields. Text in square brackets is optional.
Lines in the sockd.conf file that begin with # are comment lines, except lines
that start with #NO_IDENTD: or #BAD_ID:.
permit|deny The line begins with an action, either permit or deny--this
defines how the server behaves when it gets a matching request.
Warning!
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 198.95.251.30 255.255.255.255
permit 198.95.251.30 255.255.255.255
If the two lines switch position, then requests by user chris
The elements you can place in a line in the sockd.conf file are described in detail in Appendix C, "Proxy configuration files.". are granted
because the user belongs to the domain listed in the first line.
The bu.conf file
The optional bu.conf file contains batch update directives. You can use these 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. For more information on batch updating and starting the batch update function, see "init-batch-update (starting batch updates)" on page 375.
Object boundaries
All of the batch update directives must be within Object boundaries.
The pairs of Object boundaries indicate the individual configurations in the
bu.conf file. If you give a unique name to each occurrence, you can specify
these boundaries any number of times.
Syntax
<Object name=object_name>
...
</Object>
The directives in bu.conf are explained in detail in Appendix C, "Proxy configuration files."
Examples of bu.conf
The following example code updates the entire cache every evening:
The following example code tells the proxy to mirror a company internal site to a local proxy:
<Object name=cache update>
Source internal
Accept .*
Type ignore
Connections 4
Depth 1
Count 300
Days Sun Mon Tue Wed Thu Fri Sat
Time 20:00 - 3:00
</Object>
<Object name= HumanResourcesMirror>
Source http://hr.mycompany.com
Accept .*
Type inline
Connections 6
Depth 9
Count 1000
Days Mon Tue Wed Thu Fri
Time 4:00 - 6:00
</Object>