Chapter 3. Configuring the Proxy Server

This chapter describes how to configure the Netscape Proxy Server by using the configuration forms from the Proxy Server Manager. The configuration forms control the entire proxy server; the Resource Manager (discussed in the following chapter) controls specific access to the proxy server based on URL patterns. This chapter also discusses how to create and modify user databases.

Using the Proxy Server Manager Configuration Forms


Note: You must restart the server for your changes to take place. After you submit the configuration forms, you get a pointer to a script that restarts your server.

If you installed your proxy server and then realized you need to reconfigure some aspect of the entire server, you can use either the Full Configuration or Quick Configuration forms. The Full Configuration forms contain more documentation, but the options you can configure are identical.

The following sections reference forms and options in both the Full Configuration and the Quick Configuration.

Basic Server Configuration

This form lets you change the basic aspects of your server. Change as many options as you want, then click the Submit this form button. The changes you make here take effect only after you restart the server; a link is provided for restart after you submit the form.

The link to the script that restarts the proxy server makes the server internally restart (called a soft restart because it doesn't interrupt proxy service). The proxy rereads its configuration files and restarts its child processes. The script finds the proxy's parent process ID from the logs/pid file and sends the hang-up signal (-HUP) to that process ID. For more information about stopping the proxy server and then starting it (called a hard restart), see “Starting and Stopping the Server Manually”.

Server Name

The server name is the full hostname of your proxy server host. When clients access your proxy, they use this name. The format for the Server Name is [hostname].[yourdomain].[domain]. For example, if your full domain name is sgi.com, you could install a proxy server with the name proxy.sgi.com.

This name is used in redirections automatically generated by the proxy server. This way it knows what DNS name or alias to use, and clients always see one consistent name.

Server Port Number

Server Port Number specifies the TCP port the server listens to. The number you choose is used by proxy users when they configure their Web browsers (such as the Netscape Navigator) to use the proxy server (they must specify a server name and port number).

Port numbers for all network-accessible services are maintained in the /etc/services file on IRIX systems. The standard Telnet port number is 23, and the standard HTTP port number is 80. But because the proxy isn't a regular HTTP server, you shouldn't use port 80. Proxies haven't been assigned an official port number yet.

If you aren't sure the port number you plan to use is available, look at the contents of /etc/services on the server host.

Technically, the proxy port number can be any port from 1 to 65535. If you aren't running as root or superuser when you install or start the proxy, you'll have to use a number above 1024.

A recommended proxy port number is 8080. When configuring client programs to use this proxy server, you have to include both the hostname and the port number. For example, you would use the following in the proxy preferences dialog box in the Netscape Navigator:

proxy.sgi.com 8080

If you use proxy's SOCKS daemon feature, the proxy should listen to the standard SOCKS port (1080).

See “Choose a Unique Port Number” for more information.

Proxy Server User

Proxy Server User specifies an IRIX user account that the proxy uses (all the proxy processes are assigned to this user account).

You don't need to specify a Proxy Server User if you chose a port number greater than 1024 and aren't running as root (in this case, you don't need to be logged in as root to start the proxy). If you don't specify a user account, the proxy runs with the user account you start it with, so make sure that when you start the proxy server, you use the correct user account.

Even if you need to start the server as root, you don't want it to run as root all the time. You want it to have restricted access to your system resources and run as a nonprivileged user. The user name you enter as the Proxy Server User should already exist as a normal IRIX user account. When the server starts, it runs as this user.

If you want to avoid creating a new user account, you can choose the user “nobody” or an account used by another HTTP server running on the same host. However, on some systems the user “nobody” can own files but not run programs. See “Create an IRIX User Account” for more information.

Server Processes

Whenever people use the proxy server, the proxy uses background processes to service their requests. You can specify the number of processes dedicated to the proxy. These processes are spawned when the server starts and remain idle until needed. Base your choice on achieving a balance between system load and server requests:

  • On a high-demand system, the server needs many of these processes (for example, 80 processes) to handle many simultaneous requests.

  • On a low-demand system (less than a dozen users, only a few simultaneous connections active at any given time), 20-40 processes should be sufficient.


Note: The number of processes the proxy can use is limited by the process table for the computer the proxy runs on.

Each process uses around 200K of RAM when idle and 300-500K when active. If you specify more processes than can fit simultaneously in main memory, the system starts swapping (using virtual memory), which considerably slows down proxy service. All proxy processes must fit in the main memory simultaneously to make the proxy efficient.

To use the table in Figure 3-1 you must know how long requests take and how many requests the proxy receives per second.

  • To find the average service time per request, use the pstats utility with the access log file (in the extended format). See “Using the pstats Utility” for more information on using pstats.

  • To estimate the average number of new requests per second, view the access log during peak hours. Use tail with the -f option to continuously view the access log file as the proxy adds entries to it. As entries are added, base your estimate on the number of users and how active they are.

Figure 3-1 presents a table showing the suggested number of processes based on average request service time and number of requests. Use this figure to determine the number of processes for your proxy server.

Figure 3-1. Suggested Number of Server Processes


You can change the number of processes at any time using the Administration forms. If the server appears slow or is not responding (especially during peak hours), you should increase the number of processes available to the proxy. You might have to increase the RAM or the size of the operating system's process table before you increase the number of processes.

Proxy Timeout

Because the proxy connects to servers on remote hosts, there is always a risk that the remote host won't respond within a reasonable period of time, either because of network problems or trouble on the remote host. To prevent the proxy from waiting long periods for a response, you can set a timeout. After a specified number of seconds without receiving new data, the proxy terminates the connection.

This time limit is not the same as the maximum time allowed for data transfer. The Proxy Timeout is the maximum time between successive network data packets.

When the remote server uses server-push (actively “pushes” a new document out to the client) and the delay between pages is longer than the proxy timeout, you can have problems. Instead, use client-pull (request an updating document), which sends multiple requests to the proxy.

Server Root

The Netscape Proxy Server and its support files were installed in the central directory listed in this section of the form. This directory contains the proxy server program, log files, configuration files, and administrative forms. Certain accessory programs were configured at installation time to directly use this directory. In this version of the Netscape Proxy Server, changing the Server Root is not possible.

Connecting To and Disconnecting From the Network

You can connect the proxy server host to or disconnect from the network. This makes it convenient to install the proxy on a portable host that you can use for demonstrations. (See Chapter 5 for more information on caching.)

When the proxy server is disconnected from the network, documents are returned directly from the cache—the proxy can't do up-to-date checks, so the documents are retrieved very quickly.

Also, if no network is selected, connections never hang, because the proxy server is aware of the missing network and never tries to connect to a remote server. You can use this setting when the network is down but the server host is up.

Server Logging Configuration

Under normal operation, the Netscape Proxy Server maintains two log files in your server root directory.

  • The Access Log keeps track of who accesses the proxy. It can record host names or IP addresses. This file can help you optimize the number of processes the proxy needs.

  • The Error Log keeps track of proxy errors. Errors are reported to a file or to the system's syslog facility.

Access Log File

You can keep track of every user who accesses your proxy—including those who try to access it but are denied service.

The access log is saved in a file whose name and directory you specify. Use the Log Format and the Remote Hostname Logging options on the same form to control what host (user) information is saved in the file.

Log Format

You can configure your proxy server to use either the common log file format used by other servers or the extended format specific to the proxy server. The common log file reports

  • the date and time of the request (using the proxy's time zone)

  • the actual request (method, URL, protocol)

  • returned HTTP status code

  • size of the document returned

Example 3-1 shows sample extended log entries. Each entry is a single, no-breaking line in the file. The file should have no empty lines. (The lines in Example 3-1 are formatted for the printed page.)

The extended log file format facilitates accounting based on byte counts. In addition to the information in the previous list, the following byte counts are available in the extended log file format in this order:

  • Remote server's response status code (HTTP only)

  • Remote server's response content length

  • Client's request POST data size (content-length)

  • The POST data size actually forwarded to the remote server

  • Client's request header size

  • Proxy's response header length to the client

  • Proxy's request header size to the remote server (HTTP only)

  • Remote server's response header length to the proxy (HTTP only)

  • Transfer time in seconds

    Example 3-1. Sample Extended Log File Entries (Each entry is a single line in the file and there are no blank lines)


    helium.sgi.com--[23/Jan/1995:11:09:15 -0800] "GET http://home.sgi.com/ HTTP/1.0" 200 2573 200 2573 - - 224 188 289 188 11
    
    helium.sgi.com--[23/Jan/1995:11:09:24 -0800] "GET http://home.sgi.com/icons/welcome.gif HTTP/1.0" 200 567 200 567 - - 210 190 275 190 9
    
    helium.sgi.com--[23/Jan/1995:11:09:24 -0800] "GET http://home.sgi.com/icons/logo.gif HTTP/1.0" 200 5611 200 5611 - - 209 191 274 191 9
    
    helium.sgi.com--[23/Jan/1995:11:09:39 -0800] "GET http://www.sgi.com/cgi-bin/gadget HTTP/1.0" 200 1645 200 1645 - - 225 158 290 158 2
    
    helium.sgi.com--[23/Jan/1995:11:09:39 -0800] "GET http://www.sgi.com/icons/gadget-icon.gif HTTP/1.0" 200 881 200 881--241 190 306 190 1
    
    oxygen.sgi.com - - [24/Jan/1995:02:57:44 -0800] "GET http://home.sgi.com/people/ari/ HTTP/1.0" 200 7718 304 - - - 266 190 331 190 1
    
    

Remote Hostname Logging

If you set up the proxy server to be used only by local hosts, you can simply log the IP address of the requesting host. This saves precious CPU cycles when doing a DNS lookup and relieves the impact on the DNS server. These are the two remote hostname logging options:

  • Log client DNS hostname. This might have an impact on the performance of the proxy server, and the DNS server might become a bottleneck.

  • Log only the IP addresses.

If your access control is DNS-based, you can log the hostnames without affecting performance, because a reverse DNS lookup is required in any case. You can avoid an inpact on performance by having access control based on IP number.

The Error Log File

Error Log specifies the file where the server logs its errors. You can use the SYSLOG facility instead of logging the errors to a file.


Note: The directory and file must be writeable by the proxy's user account.

If you choose error logging to go to a file under the Server Root directory in /logs/errors, you can easily view the file using the Netscape Proxy Manager. Click the View error log link in the Miscellaneous section of the Proxy Manager page.

Appendix A contains a description of the errors stored in the error log file.

Default Caching Configuration

The Caching configuration form controls the major aspects of caching the proxy server. You can configure the finer aspects (resource by resource) of the cache through the Resource Manager, which lets you specify different configuration parameter values for URLs matching a given wildcard pattern.

See Chapter 5, “Caching,” for more information on what caching is, how it works with the proxy server, and how you should configure it for your proxy.

Enabling Caching

Caching reduces network impact and offers faster response times for clients using the proxy. If caching is turned on, the proxy copies documents from the remote server to its local filesystem. When another client accesses the same file, the proxy returns the file from the cache.

Special care is taken by the proxy server to guarantee that documents are up to date. The Netscape Garbage Collector daemon performs cache cleanup on a regular basis, ensuring that the cache doesn't get too full or get cluttered with old documents.

The directory you specify is the parent directory for the cache. All cached files appear in an organized directory structure under this caching directory. If you change the cache directory name or move it to another location, you have to tell the proxy the new location. For more information on moving or splitting the cache directory, see “Moving or Splitting the Cache Directory”.

Cache Size

The amount of disk space available for the proxy cache has considerable impact on cache performance. If the disk space is too small, the garbage collector must remove valuable cached documents just to make room on the disk.

Large cache sizes are best because the more documents cached, the less network traffic load and faster response times the proxy will provide. Also, cached documents are removed only if they are not needed anymore. Cache size can never be too large; the excess space simply remains unused.


Note: The Proxy Manager allows up to 4 GB for the cache. To increase this, manually edit magnus.conf. See “magnus.conf File”.

Netscape Proxy Caching is designed to work efficiently at any size between 10 MB and 4 GB. The exact cache size you choose depends on the number of people using your proxy server. For a single user cache, 20 to 50 MB is usually enough. For a proxy that caches a lot of documents, you should allocate an entire 1 or 2 GB disk partition for the cache. You can also have the cache split on multiple disk partitions, see “Moving or Splitting the Cache Directory” for more information.


Note: You might encounter problems with caching if the filesystem where the cache root resides has less disk space than the cache size you specify.


Cache Lock Timeout

While the Netscape Proxy is writing a cache file, the file is locked so that no other proxy process can access it until it is successfully written to the cache. Sometimes (although rarely) a locked file might be left in the cache. A locked file might be left if the system is suddenly shut down or if the proxy server process terminates for some other reason.

To recover from situations like this, you can specify a timeout period after which a lock can be broken by another proxy process. You should choose a timeout period that encompasses the largest file transfer time you expect for your proxy (for example, 15 minutes).

Locked files left in the directory aren't a serious problem—they make some transactions take a longer time. When a client accesses a document through the proxy and the proxy looks in the cache, it sees the lock file and assumes that another process is active. The proxy then goes to the remote server and passes the document directly to the client. However, if the proxy receives a request for the same document after the lock timeout period has elapsed and it sees the same lock file, the proxy determines that the transaction failed, so it deletes the lock file and restarts the transaction with the remote server.

Specifying a short timeout causes processes to discard large files that are only partially copied when the same file is requested again. Discarding large files doesn't cause any harm other than degradeing performance.

Very long timeouts prevent caching of a resource that wasn't successfully cached during the previous retrieve because of race conditions. A race condition terminates the proxy process prematurely; race conditions include a KILL signal received by the process, a fatal software error, or a system crash.

Race conditions are so rare that you should feel free to set the timeout to an hour without degrading the cache performance.

Transfers interrupted by the client or broken connections to the remote server are not race conditions. The Netscape Proxy easily recovers from these other conditions and releases the lock accordingly.

Cached Protocols

You can control which documents are cached in two ways. The Cached Protocols option lets you specify which documents to cache based on their protocol; the Resource Manager lets you specify more specific rules based on URL wildcard patterns.


Note: The Cached Protocols option supersedes any other caching settings.

Caching must be turned on for a given protocol before any URL of that type can be cached. For example, if you turn on caching in the Resource Manager for a specific URL pattern (such as ftp://ftpdir/*), that setting has no effect if the entire FTP protocol isn't cached.

By default, the proxy caches the HTTP protocol but doesn't cache FTP or Gopher. See “Cache Refresh Setting” for information on caching with FTP and Gopher.

Caching Strategy

Usually, everything that can be cached is cached. This includes all non-protected documents that don't expire immediately and weren't a result of script processing. Scripts often have (intentional) side effects that might affect the document content (in the case of forms data) and that certainly affect the remote server. However, the script results might be cached if the script explicitly allows this with appropriate Expires or Last-Modified headers.

  • Cache everything unless explicitly forbidden. If you have a large cache and plan to cache many types of documents, use this option. Every document is cached (except the ones that can't be cached—usually CGI script output), unless you forbid caching for a specific document (via the Resource Manager).

  • Cache only documents explicitly marked for caching. This disables caching by default and lets you explicitly enable caching for certain URLs by using the Resource Manager. This is the best way to handle caching if you have a small cache or if you want to cache only a small set of documents with specific types (for example, caching only specific HTTP documents).

Cache Refresh Setting

The proxy server can do an up-to-date check for every HTTP request it gets (FTP and Gopher don't have a way to check if a file is up to date—only a way to retrieve a new copy), or it can do the up-to-date check only after a refresh interval has elapsed.

If you set a time interval, choose one that you consider safe for the information you store. For example, if you store information that rarely changes, use a high number (several days). If your data changes constantly, you'll want the files to be checked each time they are accessed.

During the refresh time, you risk getting an outdated file. But if the interval is short enough (a few hours), you eliminate most of this risk while getting notably faster response times.

Because FTP and Gopher protocols don't include a method for checking that a document is up to date, having a default refresh time is the only way to make FTP and Gopher caching effective. If you don't want to use a Refresh Setting for HTTP documents, you can use the Resource Manager to specify a refresh only for FTP and Gopher documents.

Cache Expiration Setting

The Netscape Proxy Server can use the time a file was last modified to estimate how long a document is likely to remain unchanged. For example, a GIF file that was last changed three months ago would take longer to expire (and have an up-to-date check done) than an HTML file that was updated 2 days ago. This option works only with the HTTP protocol.

The expiration time is used with the Cache Refresh setting; the shorter of the two intervals is used.

If you use this feature, you need to select a factor to use in the estimation. The factor is multiplied by the time between the last modification and the time that the document last had an up-to-date check. Smaller values make the proxy behave more cautiously and check documents more often.

For example, if you set the factor to 0.1, a document that was last modified ten days ago is estimated to remain unchanged for one day (10 x 0.1). The proxy returns the document directly from the cache if less than one day has passed since the proxy last performed an up-to-date check. However, if the Cache Refresh setting is set to less than one day, the proxy does the up-to-date check if that time has elapsed. The proxy always uses the smaller value (Cache Refresh or Cache Expiration) that makes it update the files most frequently.

Remote Server Unavailable

If a document is in the cache and the proxy determines the file needs to be updated but the remote server is unavailable (for a variety of reasons), you can configure the proxy to return the document from the cache instead of returning an error saying the remote server is down (you'll get the error message if this option is not on).

To use this option, you must specify how old a document can be when sent from the cache. For example, you can specify that a document be no older than 7 days. If someone tries to access a document that is older than 7 days, the proxy won't return it from the cache—it returns an error indicating that an error occurred when contacting the remote server.

An error while contacting the remote server can occur for different reasons. There can be a long timeout period (30 to 60 seconds with DNS lookups) before the proxy detects the error, or sometimes the error can occur immediately.

Even though this feature can increase the usability of the World Wide Web, it also involves a risk of sending stale data from the cache during the time that the remote server is unavailable. It can also return documents that no longer exist on the remote server or from servers that no longer exist.

Configuring the Garbage Collector

The Netscape Garbage Collector Daemon traverses the cache directory and removes old files. It runs through the cache regularly one or more times per day. The garbage collector daemon is started automatically by the same script that starts the proxy server—whenever the proxy is running, so is the garbage collector.

If the garbage collector is accidentally killed, you can start the it manually with the ns-gc command. Use the -d option to specify the cache root directory. The garbage collector uses the same configuration file as the proxy server.


Note: If you haven't enabled caching on the proxy, settings made to the garbage collector have no effect and the garbage collector won't be started by the startup script.

See Chapter 5 for more information about the garbage collector and how it works with the cache.

Garbage Collection Times

You can choose up to three garbage collection times (once a day is sufficient if you have a large cache that doesn't fill easily). A hyphen means no garbage collection. If all three collection times are marked with a hyphen ( - ), the default garbage collection time is used (3:00 a.m.).

Garbage Collector Process Priority

The garbage collector is often run in lower priority; select a priority (nice) value. Zero means normal priority; 39, the lowest priority. If you have a busy CPU and you set a low priority (you use a high nice value), garbage collection might not run as scheduled.

See “What is the Garbage Collector?” for more information on the garbage collector and what happens if garbage collection doesn't occur and the cache gets full.

Mapping URLs to Mirror Servers

The Configuration Manager lets you map URLs to another (mirror) server. You specify a URL prefix to map and where to map it. When a client accesses the proxy with a mirrored URL, the proxy gets the requests from the mirrored server and not from the original server. You can also use mapping to send requests to mirror servers only when the requests come from specific clients.

For example, suppose you have a heavily loaded Web server called hi.load.com that you want mirrored to another server (mirror.load.com). You would add this mapping in the Configuration Manager:

Map URL Prefix: http://hi.load.com
Mirror site prefix: http://mirror.load.com

The source URL prefix must be unescaped, but in the destination (mirror) URL prefix illegal characters must be escaped.

Do not use trailing slashes in the prefixes! You can leave the remaining fields (host restrictions) blank.

Editing Existing Mappings

You can edit your existing mappings by clicking the link at the bottom of the mappings form.

All mappings are grouped in sections, so you can change any mapping and click the Change this mapping button to save your edits. You can edit the prefix, the mirror site, and the host and IP addresses that are affected by the mirror mapping.

Check Remove this mapping and then click the Change this mapping button to remove the mapping from the proxy configuration.

URL Control

The Configuration Manager haS an option that starts the Resource Manager. See Chapter 4 for information on using the Resource Manager.

SOCKS Daemon Configuration

Netscape Proxy Server includes a SOCKS daemon that understands the usual sockd.conf file format used by other SOCKS daemons. See “Structure of sockd.conf” for information on this file format. (The Netscape Proxy Server supports SOCKS version 4.)

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, but you can enable them through this form.

SOCKD Configuration File

The Netscape SOCKS daemon understands the same configuration file format as the other SOCKS daemons; the default location is /etc/sockd.conf. You can specify another filename and directory.

Remote Identity Check

The SOCKS daemon can verify the identity of remote users by connecting to the client host's identity daemon (identd), if it is running on their host.

There are three levels of identity checking:

  • Strict. The remote identity daemon is contacted, and the given user name is verified. If the remote host isn't running identd or if verification fails, access is denied to the client.

  • Loose. The remote identity daemon is contacted to verify the user name, but if the host isn't running identd or if verification fails, the user name check is bypassed and access allowed.

  • None. The remote identity daemon isn't contacted, and the user name is never verified.

SOCKD Logging

Netscape SOCKD provides four different ways to log SOCKS requests. Log entries can be sent to the common log (a separate log file) or to the SYSLOG facility. The log format is either Netscape Proxy's extended log file format or the usual format used by regular SOCKS daemons.

  • Common Log. Uses the common log file and the same format in it. This uses the special names SOCKS-CONNECT and SOCKS-BIND as method names to denote the two SOCKS commands, CONNECT and BIND.

  • Common Log Format, Separate File. Uses the common log file format, but stores the log entries in a separate file.

  • Syslog. Makes the usual SOCKD type log entries to the syslog facility.

  • Syslog-style, to a Separate File. Makes syslog-type log entries, but to a separate file.

Separate Log Name

If you use one of the two options that store log entries in separate files (common-separate and syslog-separate), you'll need to specify the directory and filename where you want the entries stored.

Filter Outgoing Headers

You can configure the headers the proxy filters out from the request (usually for security reasons). For example, you might want to prevent the From: header from going out because it reveals the user's email address (although Netscape Navigator does not send it unless it is specifically configured to do that).

This feature doesn't affect headers that are specially handled, generated by the proxy itself, or necessary to make the protocol work properly (such as If-modified-since and Forwarded).

The fact that the Forwarded header cannot be stopped from originating from a proxy isn't really a security hole because the remote server can detect the connecting proxy host from the connection.

However, in a proxy chain, a Forwarded header coming from an inner proxy can be suppressed by an outer proxy. This is recommended if it is not desirable to have the inner proxy hostname revealed to the remote server.

The value of this setting must be a wildcard pattern that matches the HTTP header field name up to, but not including, the colon. Two examples are:

from 
(from|user-agent) 

Access Control

Access Control lets you restrict access to a resource according to the client's hostname or IP address.

You can either protect your entire server, or select a resource to apply it to. If you get to the Access Control form directly from the Proxy Manager Configuration form, you are modifying the entire proxy server. If you get to this form from the Resource Manager, you are modifying access only to the resource you chose in the Resource Manager. This form specifies what you are modifying. If you want to specify a host that is not allowed, start the pattern with *~.


Caution: Access Control affects this configuration interface; if you specify a set of hosts that excludes the hosts with access to the administration forms, you cannot access these forms after you restart the proxy server. There are two ways to fix this. You can manually edit the configuration file obj.conf in admin/config under your Server Root directory (see “obj.conf File” for more information).

You can also access the Proxy Manager forms from the local host using the URL http://localhost:port/admin/. Localhost is literally “localhost,” so don't replace it with the local hostname, but you do need to use the correct port number. This assumes the /etc/hosts file includes the entry “127.0.0.1 localhost”. In that case, use the numeric loopback address:

http://127.0.0.1:[port]/admin/

User Databases

User data bases are lists of users who can access the proxy server. Each user has a user name and password. User databases control who has access to the Internet and other resources through the proxy server.

The Netscape Proxy Server stores its user files in a high-speed format called a DBM. This format can search an infinitely large database with one filesystem read (normal files search the database linearly).

The Netscape Proxy Server stores its databases in the directory admin/userdb in the server root. When specifying a database, use only the name, not the full path.

Creating a User Database

To create a user database for your proxy server, type a name for the database. Don't type a path because all databases are stored in admin/userdb. The database name can be up to 256 characters.

Type a password for this database. The password can be up to 8 characters. Retype the password to ensure correctness. When you click the Submit this form button, the proxy creates the database, then lets you jump to the page where you can add users to the new database.

Adding, Editing, and Removing Users in a Database

To add, edit, or remove a user to a database:

  1. Type the name of the database and the password for the database.

  2. Check Add User, Edit User, or Remove User, depending on what you want to do.

  3. Type a user name. This is the name the user types when authenticating with the proxy. It can be up to 254 characters.

  4. If adding or editing a user name, type a password for the user. It can be up to 8 characters. Type it twice to ensure correctness. The user uses this password when authenticating with the proxy.

    If you want to change the user name, first remove the user and then add the changed user name. If you're removing a user, you don't need to type the password.

  5. Click the Submit this form button. The user name and password are added to the database. You can return to adding names to the database, or you can return to the User Databases page.

Converting an NCSA or Text File to a User Database

The Netscape Proxy Server stores its databases in the server root, in the directory admin/userdb. The NCSA-style file can reside anywhere.

The format of the file to convert should look something like this:

user1:password1
user2:password2
user3:password3
user4:password4

Passwords are not normally stored in clear text. Usually, they are encrypted so that you cannot read them. If the file is an NCSA file, the passwords will already be encrypted. If the passwords aren't encrypted, you can have the converter encrypt the passwords for you.

You need to choose a name for the converted file. You don't need to type a full path name because the user databases are always kept in admin/userdb.

You also need to specify a password for the user database; type it twice to ensure accuracy. You need this password to add, remove, or edit users.

Changing a Database Password

You can change the administrative password for a database. Type the name of the database whose password you want to change. Type its current password, then type the new password twice (to ensure accuracy). Click the Submit this form button. The proxy stores the new password.

Removing an Existing Database

You can remove a database from the admin/userdb directory. This deletes the file from the directory.

Type the name of the database you want to delete. Type the password for the database. Click the Submit this form button. The proxy deletes the file from the filesystem.

Understanding Wildcard Patterns

In many parts of the proxy server configuration (especially the Resource Manager), you specify wildcard patterns to represent one or more items to configure. For example, to restrict access to the proxy, you specify a wildcard pattern that matches all of the clients who should get access.

Wildcard patterns use special characters. If you want to use one of these characters without the special meaning, precede it with a backslash (\) character.

* matches zero or more characters.

? matches exactly one character, and it can be any character.

(this|that) is an or expression. It matches either the substring this or the substring that. The substrings can contain other special characters such as * or $.

$ matches the end of the string. This is useful in or expressions.

[abc] matches one occurrence of the characters a, b, or c. Within these expressions, the only character that needs to be escaped in this is ], all others are not special.

[a-z] matches one occurrence of a character between a and z.

[^az] matches any character except a or z.

*~ followed by another expression removes any pattern matching the expression from the match list.

Wildcard Usage Examples

*.sgi.com matches any string ending with the characters .sgi.com.

(core|flop).sgi.com matches either core.sgi.com or flop.sgi.com.

198.93.9{23}.??? matches a numeric string starting with either 198.93.92 or 198.93.93 and ending with any three characters.

*.* matches any string with a period in it.

*~sgi-* matches any string starting with sgi-.

*.sgi.com~quark.sgi.com matches any host from domain sgi.com except for a single host quark.sgi.com.

*.sgi.com~(quark|neutrino|energy).sgi.com matches any host from domain sgi.com except for hosts quark.sgi.com, neutrino.sgi.com, and energy.sgi.com.

*.com~*.sgi.com matches any host from domain com except hosts from subdomain sgi.com.