Contents


Preface

What iPlanet Web Proxy Server Provides
What's in This Book?
Conventions Used in This Book
Contacting iPlanet Technical Support

Administering the Proxy Server

Chapter 1 Starting the Administration and Proxy Servers

Starting and Stopping the Administration Server

Starting the Administration Server
Stopping the Administration Server

Using the Server Administration Page
Starting and Stopping iPlanet Web Proxy Server

Starting the Proxy Server

Using the Server Administration Page
Manually

Restarting the Proxy Server

Restarting with inittab
Restarting with the System RC Scripts
Soft Starting the Proxy
The Start-Up Process

Stopping the Proxy Server

Using the Server Administration Page
Manually

Chapter 2 Managing Your Server

Overview
Using the Server Manager

Chapter 3 Managing Templates and Resources

What is a Template?

Understanding Regular Expressions
Understanding Wildcard Patterns
Hierarchies of Templates

Creating Templates
Viewing and Removing Templates
Removing Resources
Online Forms for Controlling Resources

Chapter 4 Configuring Server Preferences

Starting and Stopping the Proxy Server
Viewing Server Settings
Restoring and Viewing Backup Configuration Files
Changing System Specifics

Bind Address
Server Port
Server User
Processes
Process Life
DNS
ICP
Proxy Array
Parent Array
Remote Access
Proxy Timeout

Creating MIME Types

Understanding DNS Caching

How DNS Caching Works
Configuring the DNS Cache

Setting Levels of DNS Subdomains

Enabling HTTP Keep-Alive

Chapter 5 Controlling Access to Your Server

How Does Access Control Work?

Access Control Files

ACL File Syntax

Controlling Access with Client Certificates

Restricting Access

Denying Access to a Resource
Allowing Access to a Resource

Chapter 6 Proxying and Routing URLs

Enabling Proxying for a Resource
Configuring Routing for a Resource
Chaining Proxy Servers
Routing Through a SOCKS Server
Sending the Client's IP Address to the Server
Allowing Clients to Check IP Addresses
Disconnecting the Proxy from the Network
Changing the Default FTP Transfer Mode
Using Remote Access

Configuring Remote Access
Enabling Remote Access

Mapping URLs to Other URLs

Creating a URL Mapping
Editing Existing Mappings
Redirecting URLs

Specifying the SOCKS Name Server IP Address
Client Autoconfiguration

Chapter 7 Reverse Proxy

How Reverse Proxying Works

Proxy as a Stand-in for a Server

Secure Reverse Proxying

Proxying for Load Balancing

Setting up a Reverse Proxy

Setting up a Secure Reverse Proxy

Chapter 8 Using SOCKS v5

Using a SOCKS Server

Configuring SOCKS v5
Creating SOCKS v5 Authentication Entries
Editing SOCKS v5 Authentication Entries
Deleting SOCKS v5 Authentication Entries
Moving SOCKS v5 Authentication Entries
Creating SOCKS v5 Connection Entries
Editing SOCKS v5 Connection Entries
Deleting SOCKS v5 Connection Entries
Moving SOCKS v5 Connection Entries
Creating Routing Entries

Creating SOCKS v5 Routing Entries
Creating Proxy Routing Entries

Editing Routing Entries
Deleting Routing Entries
Moving Routing Entries
Enabling SOCKS

Authenticating Through a SOCKS Server Chain

Chapter 9 Caching

How Caching Works
Understanding the Cache Structure
Distributing Files in the Cache
Setting Cache Specifics

Enabling the Cache
Creating a Cache Working Directory
Recording URLs
Setting the Cache Size
Editing the Cache Capacity
Caching HTTP Documents

Setting the HTTP Cache Refresh Interval
Setting the HTTP Cache Expiration Policy
Reporting HTTP Accesses to the Remote Server

Caching FTP and Gopher Documents

Setting FTP and Gopher Cache Refresh Intervals

Configuring the Cache

Setting the Cache Default
Caching Pages Retrieved Using HTTPS
Caching Pages that Require Authentication
Caching Queries
Setting the Minimum and Maximum Cache File Sizes
Setting the Cache Behavior for Client Interruptions
Setting the Cache Behavior for Failed Origin Server Connections

Adding and Modifying Cache Partitions
Adding and Modifying Cache Sections
Setting the Cache Capacity
Enabling the Cache Monitor and Manager

Accessing Cache Manager Information

Caching Local Hosts
Using Cache Batch Updates

Creating a Batch Update
Editing or Deleting a Batch Update Configuration

Using the Cache Command Line Utilities

Building the Cache Directory Structure
Upgrading the Cache Structure

Upgrading a 1.1 Cache Structure
Upgrading a 2.0 Cache Structure

Repairing the Cache URL List
Cleaning the URL List

Routing through Proxy Arrays

Creating a Proxy Array Member List

Deleting Proxy Array Members
Editing Proxy Array Member List Information

Configuring Proxy Array Members
Enabling Routing Through a Proxy Array
Enabling a Proxy Array
Redirecting Requests in a Proxy Array
Generating a PAC File from a PAT File

Manually Generating a PAC File from a PAT File
Automatically Generating a PAC File from a PAT File

Routing Through a Parent Array

Viewing Parent Array Information

Routing Through ICP Neighborhoods

Adding Parents to an ICP Neighborhood
Removing Parents from an ICP Neighborhood
Editing Configurations for Parents in an ICP neighborhood
Adding Siblings to an ICP Neighborhood
Removing Siblings from an ICP Neighborhood
Editing Configurations for Siblings in an ICP Neighborhood
Configuring Individual ICP Neighbors
Enabling ICP
Enabling Routing Through an ICP Neighborhood

Chapter 10 Filtering Content Through the Proxy

Filtering URLs

Creating a Filter File of URLs
Setting Default Access for a Filter File

Restricting Access to Specific Web Browsers
Request Blocking
Suppressing Outgoing Headers
Filtering by MIME Type
Filtering out HTML Tags

Chapter 11 Using the Client Autoconfiguration File

Understanding Autoconfiguration Files

What Does the Autoconfiguration File Do?
Accessing the Proxy as a Web Server

Using Pac Files with a Reverse Proxy

Using the Server Manager Forms to Create an Autoconfiguration File
Creating the Autoconfiguration File Manually

The FindProxyForURL Function
The Function Return Values
JavaScript Functions and Environment

Hostname-based Functions
Related Utility Functions
URL/host-name-based Condition
Time-based Conditions
Example 1: Proxy All Servers Except Local Hosts
Example 2: Proxy Local Servers Outside the Firewall
Example 3: Proxy Only Unresolved Hosts
Example 4: Connect Directly to a Subnet
Example 5: Balance Proxy Load with dnsDomainIs()
Example 6: Balance Proxy Load with shExpMatch()
Example 7: Proxying a Specific Protocol

Chapter 12 Monitoring the Server's Status

Monitoring the Server Using HTTP

Server Usage
Activity Breakdown
Totals

Working with Log Files

Viewing the Error Log File
Viewing an Access Log File
Understanding Access Logfile Syntax
Understanding Status Codes
Setting Access Log Preferences
Working with the Log Analyzer

Transfer Time Distribution Report
Status Code Report
Data Flow Report
Requests and Connections Report
Cache Performance Report
Transfer Time Report
Hourly Activity Report

Running the Log Analyzer from the Server Manager
Running the Log Analyzer from the Command Line
Archiving Log Files

Monitoring the Server Using SNMP

How Does SNMP Work?
The Proxy Server MIB

Installing Subagents on AIX
Enabling the Subagent
Starting, Stopping, and Restarting the Subagent

Chapter 13 Proxy Error Log Messages

Proxy Error Messages

Catastrophe
Failure
Warning
Security

SOCKS Error Messages

Chapter 14 Understanding Encryption and SSL

What is Encryption?

Using Encryption in the Proxy Server

What is SSL?

Tunneling SSL through the Proxy Server

What is HTTPS?

Enabling HTTPS Proxying

Enabling SSL on Your Server

Activating SSL

Setting Encryption Preferences

SSL Version
Client Certificates
Ciphers
Keeping Clients from Caching SSL Files
Configuring SSL Tunneling

Increasing Server Security
What is Client Authentication?

Client Authentication in a Reverse Proxy
Setting up Client Authentication in a Reverse Proxy

Proxy Authenticates Client
Content Server Authenticates Proxy
Proxy Authenticates Client and Content Server Authenticates Proxy

Effects of an SSL-Enabled Server

Secure URL Construction
Secure Server Document Root

The Secure Log

Unprotected Server Document Directory
Changes to the magnus.conf File

Security
SSL2
SSL3
Keyfile
Certfile
Ciphers
SSL3Ciphers
SSLClientAuth

Chapter 15 Tuning Server Performance

Using Timeouts Effectively

Read Timeout
Proxy Timeout
Timeout After Interrupt
Keep-Alive Timeout
Global Netlib Timeout
Stall Timeout Override

Controlling Up-to-Date Checks

Setting the Last-modified Factor

Using DNS Effectively
Determining the Number of Processes
Disabling Keep-Alives
Using SOCKS Effectively

Worker Threads
Accept Threads

Tuning FTP Listing Width
Using the Cache Effectively

Optimizing Cache Architecture
Tuning the Cache

Add'l Cch-status Values
Mmap on Initial Writes
Mmap on Cache Updates
Use Shared Memory I/O
Notify Num Changes
Notify Blk Limit
C-mon Tick Interval
Max Mmap Size
Min Sync Interval
Notify Blk Chunk/Proc
Fs Full Retry After
Update After Percent
Sync Dump Ticks
Byte-Ranges
Single Accept

Tuning the Garbage Collector

Gc URL DB Interval
Gc Nap Length
Hard Gc Nap Count
Soft Gc Nap Count
Hard Gc Max Entries
Gc Dir Chunk
Gc Hi Margin Percent
Gc Lo Margin Percent
Gc Extra Margin Percent
Gc Leave Fs Full Percent

Chapter 16 Configuring the Proxy Manually

The magnus.conf File
The obj.conf File

The Structure of obj.conf

Directive Syntax
A Sample Object

Required Objects for obj.conf

The Default Object

How the Proxy Server Handles Objects

The mime.types File
The admpw File
The socks5.conf File
The bu.conf File

Object Boundaries
Examples of bu.conf

The icp.conf File
The parray.pat File
The parent.pat File

Programming the Proxy Server

Chapter 17 Creating Server Plug-in Functions

What Is the Server Plug-in API?
Writing Plug-in Functions

The Server Plug-in API Header Files
Getting Data From the Server: The Parameter Block
Passing Parameters to Server Application Functions

Parameter-manipulating Functions
Data Structures and Data Access Functions
Application Function Status Codes

Reporting Errors to the Server

Setting an HTTP Response Status Code
Error Reporting

Compiling and Linking Your Code
Loading Your Shared Object
Using Your Plug-in Functions

Appendix A Server Plug-in API Function Definitions

cache_digest (declared in libproxy/cache.h
cache_filename (declared in libproxy/cutil.h
cache_fn_to_dig (declared in libproxy/cutil.h
ce_free (declared in libproxy/cache.h
ce_lookup (declared in libproxy/cache.h
cif_load (declared in libproxy/cif.h
cif_clear (declared in libproxy/cif.h
cif_load_all_data (declared in libproxy/cif.h
cif_load_cif (declared in libproxy/cif.h
cif_read_entry (declared in libproxy/cif.h
cif_stat_entries (declared in libproxy/cif.h
cif_write_entry (declared in libproxy/cif.h
cinfo_find (declared in base/cinfo.h
condvar_init (declared in base/crit.h
condvar_notify (declared in base/crit.h
condvar_terminate (declared in base/crit.h
condvar_wait (declared in base/crit.h
crit_enter (declared in base/crit.h
daemon_atrestart (declared in netsite.h
fast_dump_cif (declared in libproxy/cif.h
fast_get_cif_entry_for (declared in libproxy/cif.h
fast_load_cif (declared in libproxy/cif.h
fast_put_cif_entry (declared in libproxy/cif.h
filebuf_buf2sd (declared in base/buffer.h
filebuf_close (declared in base/buffer.h
filebuf_getc (declared in base/buffer.h
filebuf_open (declared in base/buffer.h
filebuf_open_nostat (declared in base/buffer.h
FREE (declared in netsite.h
fs_blks_available (declared in libproxy/fs.h
fs_blk_size (declared in libproxy/fs.h
func_exec (declared in frame/func.h
func_find (declared in frame/func.h
http_dump822 (declared in frame/http.h
http_hdrs2env (declared in frame/http.h
# http_scan_headers (declared in frame/http.h
http_set_finfo (declared in frame/http.h
http_start_response (declared in frame/http.h
http_status (declared in frame/http.h
http_uri2url (declared in frame/http.h
log_error (declared in frame/log.h
magnus_atrestart (declared in netsite.h
make_log_time (declared in libproxy/util.h
MALLOC (declared in netsite.h
netbuf_buf2sd (declared in base/buffer.h
netbuf_close (declared in base/buffer.h
netbuf_getc (declared in base/buffer.h
netbuf_grab (declared in base/buffer.h
netbuf_open (declared in base/buffer.h
net_ip2host (base/net.h
net_read (declared in base/net.h
net_socket (declared in base/net.h
net_write (declared in base/net.h
param_create (declared in base/pblock.h
param_free (declared in base/pblock.h
pblock_copy (declared in base/pblock.h
pblock_create (declared in base/pblock.h
pblock_dup (declared in base/pblock.h
pblock_find (declared in base/pblock.h
pblock_findlong (declared in libproxy/util.h
pblock_findval (declared in base/pblock.h
pblock_free (declared in base/pblock.h
pblock_nlinsert (declared in libproxy/util.h
pblock_nninsert (declared in base/pblock.h
pblock_nvinsert (declared in base/pblock.h
pblock_pb2env (declared in base/pblock.h
pblock_pblock2str (declared in base/pblock.h
pblock_pinsert (declared in base/pblock.h
pblock_remove (declared in base/pblock.h
pblock_replace_name (declared in libproxy/util.h
pblock_str2pblock (declared in base/pblock.h
PERM_FREE (declared in netsite.h
PERM_MALLOC (declared in netsite.h
PERM_STRDUP (declared in netsite.h
protocol_dump822 (declared in frame/protocol.h
protocol_finish_request (declared in frame/protocol.h
protocol_handle_session (declared in frame/protocol.h
protocol_hdrs2env (declared in frame/protocol.h
protocol_parse_request (declared in frame/protocol.h
protocol_scan_headers (declared in frame/protocol.h
protocol_set_finfo (declared in frame/protocol.h
protocol_start_response (declared in frame/protocol.h
protocol_status (declared in frame/protocol.h
protocol_uri2url (declared in frame/protocol.h
protocol_uri2url_dynamic (declared in frame/protocol.h
REALLOC (declared in netsite.h
request_create (declared in frame/req.h
request_free (declared in frame/req.h
request_header (declared in frame/req.h
request_stat_path (declared in frame/req.h
request_translate_uri (declared in frame/req.h
sem_grab (declared in base/sem.h
sem_init (declared in base/sem.h
sem_release (declared in base/sem.h
sem_terminate (declared in base/sem.h
sem_tgrab (declared in base/sem.h
session_create (declared in base/session.h
session_free (declared in base/session.h
session_maxdns (declared in base/session.h
shexp_casecmp (declared in base/shexp.h
shexp_cmp (declared in base/shexp.h
shexp_match (declared in base/shexp.h
shexp_valid (declared in base/shexp.h
shmem_alloc (declared in base/shmem.h
shmem_free (declared in base/shmem.h
STRDUP (declared in netsite.h
systhread_attach (declared in base/systhr.h
systhread_current (declared in base/systhr.h
systhread_getdata (declared in base/systhr.h
systhread_init (declared in base/systhr.h
systhread_newkey (declared in base/systhr.h
systhread_setdata (declared in base/systhr.h
systhread_sleep (declared in base/systhr.h
systhread_start (declared in base/systhr.h
systhread_terminate (declared in base/systhr.h
systhread_timerset (declared in base/systhr.h
system_errmsg (declared in base/file.h
system_fclose (declared in base/file.h
system_flock (declared in base/file.h
system_fopenRO (declared in base/file.h
system_fopenRW (declared in base/file.h
system_fopenWA (declared in base/file.h
system_fread (declared in base/file.h
system_fwrite (declared in base/file.h
system_fwrite_atomic (declared in base/file.h
system_gmtime (declared in base/file.h
system_localtime (declared in base/file.h
system_ulock (declared in base/file.h
system_unix2local (declared in base/file.h
util_can_exec (declared in base/util.h
util_chdir2path (declared in base/util.h
util_does_process_exist (declared in libproxy/util.h
util_env_create (declared in base/util.h
util_env_find (declared in base/util.h
util_env_free (declared in base/util.h
util_env_replace (declared in base/util.h
util_env_str (declared in base/util.h
util_get_current_gmt (declared in libproxy/util.h
util_get_int_from_aux_file (declared in libproxy/cutil.h
util_get_long_from_aux_file (declared in libproxy/cutil.h
util_get_string_from_aux_file (declared in libproxy/cutil.h
util_get_int_from_file (declared in libproxy/cutil.h
util_getline (declared in base/util.h
util_get_long_from_file (declared in libproxy/cutil.h
util_get_string_from_file (declared in libproxy/cutil.h
util_grab_lock (declared in libproxy/cutil.h
util_host name (declared in base/util.h
util_is_mozilla (declared in base/util.h
util_is_url (declared in base/util.h
util_itoa (declared in base/util.h
util_later_than (declared in base/util.h
util_make_filename (declared in libproxy/cutil.h
util_make_gmt (declared in libproxy/util.h
util_make_local (declared in libproxy/util.h
util_make_lockname (declared in libproxy/cutil.h
util_make_printable (declared in libproxy/cutil.h
util_move_dir (declared in libproxy/util.h
util_move_file (declared in libproxy/util.h
util_parse_http_time (declared in libproxy/util.h
util_put_int_to_file (declared in libproxy/cutil.h
util_put_long_to_file (declared in libproxy/cutil.h
util_put_string_to_aux_file (declared in libproxy/cutil.h
util_put_string_to_file (declared in libproxy/cutil.h
util_release_lock (declared in libproxy/cutil.h
util_sect_id (declared in libproxy/cutil.h
util_sh_escape (declared in base/util.h
util_snprintf (declared in base/util.h
util_sprintf (declared in base/util.h
util_strcasecmp (declared in base/systems.h
util_strncasecmp (declared in base/systems.h
util_uri_check (declared in libproxy/util.h
util_uri_escape (declared in base/util.h
util_uri_is_evil (declared in base/util.h
util_uri_parse (declared in base/util.h
util_uri_unescape (declared in base/util.h
util_url_cmp (declared in libproxy/util.h
util_url_fix_host name (declared in libproxy/util.h
util_url_has_FQDN (declared in libproxy/util.h
util_vsnprintf (declared in base/util.h
util_vsprintf (declared in base/util.h

Appendix B Server Data Structures

The Session Data Structure
The Parameter Block (pblock) Data Structure

The Pb_entry Data Structure
The Pb_param Data Structure

The Client Parameter Block

The Request Data Structure
The Stat Data Structure
The Shared Memory Structure, Shmem_s
The Netbuf Data Structure
The Filebuffer Data Structure
The Cinfo Data Structure
The SYS_NETFD Data Structure
The SYS_FILE Data Structure
The SEMAPHORE Data Structure
The Sockaddr_in Data Structure
The CONDVAR Data Structure
The CRITICAL Data Structure
The SYS_THREAD Data Structure
The CacheEntry Data Structure
The CacheState Data Structure
The ConnectMode Data Structure

Appendix C Proxy Configuration Files

The magnus.conf File

Certfile
Ciphers
DNS
ErrorLog
Keyfile
LDAPConnPool
LoadObjects
MaxProcs
PidLog
Port
ProcessLife
RootObject
Security
ServerName
SSLClientAuth
SSL2
SSL3
SSL3Ciphers
User

The obj.conf File

AddLog

flex-log (starting proxy logging)

AuthTrans

proxy-auth (translating proxy authorization)

Connect
DNS

dns-config (suggest treating certain host names as remote)
your-dns-function (a plug-in dns function you create)

Error
Filter
Init

Init function order in obj.conf
Calling Init functions
flex-init (starting the flex-log access logs)
icp-init (initializes ICP)
init-batch-update (starting batch updates)
init-cache (starting the caching system)
init-dns-cache (starting dns caching)
init-clf (starting the Common Log File subsystem)
init-partition (specifying cache partitions)
init-proxy (starting the network software for proxy)
init-proxy-auth (specifying the authentication strategy)
init-proxy-certs (loading the default certificate database)
init-sockd (starting the SOCKD feature)
init-urldb (setting up the URL database)
load-modules (loading shared object modules)
load-types (loading MIME-type mappings)
pa-init-parent-array (initializing a parent array member)
pa-init-proxy-array (initializing a proxy array member)
tune-proxy (tuning server performance)
tune-cache (tuning cache performance)
tune-gc (tuning garbage collector performance)

NameTrans

assign name (associating templates with path)
map (mapping URLs to mirror sites)
pac-map (mapping URLs to a local file)
pat-map (mapping URLs to a local file)
pfx2dir (replacing path prefixes with directory names)

ObjectType

cache-enable (enabling caching)
cache-setting (specifying caching parameters)
force-type (assigning MIME types to objects)
http-config (using keep-alive feature)
java-ip-check (checking IP addresses)
type-by-extension (determining file information)

PathCheck

check-acl (attaching an ACL to an object)
deny-service (denying client access)
require-proxy-auth (requiring proxy authentication)
url-check (checking URL syntax)

Route

icp-route (routing with ICP)
pa-enforce-internal-routing (enforcing internal distributed routing)
pa-set-parent-route (setting a hierarchical route)
set-proxy-server (using another proxy to retrieve a resource)
set-socks-server (using a SOCKS server to retrieve a resource)
unset-proxy-server (unsetting a proxy route)
unset-socks-server (unsetting a SOCKS route)

Service

proxy-retrieve (retrieving documents with the proxy)
send-file (sending text file contents to client)
deny-service (denying access to a resource)

The socks5.conf File

Authentication/Ban Host Entries
Routing Entries
Variables and Flags

Available Settings
Proxy Entries
Access Control Entries
Specifying Ports

The bu.conf File

Accept
Connections
Count
Days
Depth
Object boundaries
Reject
Source
Time
Type

The icp.conf File

add_parent (adding parent servers to an ICP neighborhood)
add_sibling (adding sibling servers to an ICP neighborhood)
server (configuring the local proxy in an ICP neighborhood)

Glossary