Administrator’s Guide iPlanet Web Proxy Server

Version 3.6forUNIX

806-7575-01 September 2001 Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corporation. All rights reserved. Sun, Sun Microsystems, the Sun logo, Solaris, iPlanet, and the iPlanet logo, are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the U.S. and other countries. Other Netscape logos, product names, and service names are also trademarks of Netscape Communications Corporation, which may be registered in other countries. The product includes encryption software from RSA Data Security, Inc. Copyright © 1994, 1995 RSA DAta Security, Inc. All rights reserved. Portions of the software copyright © 1995 PEER Networks, Inc. All rights reserved. Portions of the software copyright © 1995, 1996 Webster Network Strategies, Inc. All rights reserved. Federal Acquisitions: Commercial Software—Government Users Subject to Standard License Terms and Conditions The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of the product or this document may be reproduced in any form by any means without prior written authorization of the Sun-Netscape Alliance and its licensors, if any. THIS DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. ______Copyright © 2001 Sun Microsystems, Inc. Pour certaines parties préexistantes, Copyright © 2001 Netscape Communication Corp. Tous droits réservés. Sun, Sun Microsystems, le logo Sun, Solaris, iPlanet, et le logo iPlanet sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et d’autre pays. Netscape et le logo Netscape N sont des marques déposées de Netscape Communications Corporation aux Etats-Unis et d’autre pays. Les autres logos, les noms de produit, et les noms de service de Netscape sont des marques déposées de Netscape Communications Corporation dans certains autres pays. Ce produit contient un module de cryptographie fourni par RSA Data Security, Inc. Copyright © 1994, 1995 RSA Data Security, Inc. Tous droits réservés. Certaines parties de ce logiciel sont protéges par un copyright © 1995 PEER Networks, Inc. Tous droits réservés. Certaines parties de ce logiciel sont protéges par un copyright © 1995, 1996 Webster Network Strategies, Inc. Tous droits réservés. Le produit décrit dans ce document est distribué selon des conditions de licence qui en restreignent l'utilisation, la copie, la distribution et la décompilation. Aucune partie de ce produit ni de ce document ne peut être reproduite sous quelque forme ou par quelque moyen que ce soit sans l’autorisation écrite préalable de l’Alliance Sun-Netscape et, le cas échéant, de ses bailleurs de licence. CETTE DOCUMENTATION EST FOURNIE “EN L'ÉTAT”, ET TOUTES CONDITIONS EXPRESSES OU IMPLICITES, TOUTES REPRÉSENTATIONS ET TOUTES GARANTIES, Y COMPRIS TOUTE GARANTIE IMPLICITE D'APTITUDE À LA VENTE, OU À UN BUT PARTICULIER OU DE NON CONTREFAÇON SONT EXCLUES, EXCEPTÉ DANS LA MESURE OÙ DE TELLES EXCLUSIONS SERAIENT CONTRAIRES À LA LOI. Contents

Preface...... 25 WhatiPlanetWebProxyServerProvides...... 25 What’sinThisBook?...... 27 ConventionsUsedinThisBook ...... 27 ContactingiPlanetTechnicalSupport ...... 27 Administering the Proxy Server ...... 29

Chapter 1 Starting the Administration andProxyServers...... 31 StartingandStoppingtheAdministrationServer ...... 31 StartingtheAdministrationServer...... 31 StoppingtheAdministrationServer...... 32 UsingtheServerAdministrationPage...... 32 StartingandStoppingiPlanetWebProxyServer...... 34 StartingtheProxyServer ...... 34 UsingtheServerAdministrationPage ...... 34 Manually ...... 34 RestartingtheProxyServer ...... 35 Restartingwithinittab ...... 35 RestartingwiththeSystemRCScripts ...... 36 SoftStartingtheProxy...... 36 TheStart-UpProcess ...... 36 StoppingtheProxyServer ...... 37 UsingtheServerAdministrationPage ...... 37 Manually ...... 37

Chapter 2 Managing Your Server ...... 39 Overview...... 39 UsingtheServerManager ...... 39

3 Chapter 3 Managing Templates and Resources ...... 43 WhatisaTemplate?...... 43 UnderstandingRegularExpressions ...... 44 UnderstandingWildcardPatterns ...... 46 HierarchiesofTemplates ...... 46 CreatingTemplates...... 47 ViewingandRemovingTemplates ...... 47 RemovingResources ...... 48 Online Forms for Controlling Resources ...... 48

Chapter 4 Configuring Server Preferences ...... 51 StartingandStoppingtheProxyServer ...... 51 ViewingServerSettings...... 51 RestoringandViewingBackupConfigurationFiles...... 52 ChangingSystemSpecifics ...... 53 BindAddress ...... 54 ServerPort ...... 54 ServerUser...... 54 Processes...... 55 ProcessLife...... 59 DNS...... 59 ICP...... 59 ProxyArray ...... 59 ParentArray...... 59 RemoteAccess...... 60 ProxyTimeout ...... 60 CreatingMIMETypes ...... 60 UnderstandingDNSCaching ...... 61 HowDNSCachingWorks ...... 61 ConfiguringtheDNSCache...... 62 SettingLevelsofDNSSubdomains ...... 63 EnablingHTTPKeep-Alive...... 63

Chapter 5 Controlling Access to Your Server ...... 65 HowDoesAccessControlWork? ...... 66 AccessControlFiles ...... 66 ACLFileSyntax ...... 66 Controlling Access with Client Certificates ...... 71 RestrictingAccess...... 71 DenyingAccesstoaResource...... 73 AllowingAccesstoaResource ...... 73

4 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Chapter 6 ProxyingandRoutingURLs...... 77 EnablingProxyingforaResource...... 77 ConfiguringRoutingforaResource...... 78 ChainingProxyServers ...... 79 RoutingThroughaSOCKSServer ...... 80 SendingtheClient’sIPAddresstotheServer ...... 81 AllowingClientstoCheckIPAddresses...... 82 DisconnectingtheProxyfromtheNetwork ...... 83 ChangingtheDefaultFTPTransferMode...... 84 UsingRemoteAccess ...... 85 ConfiguringRemoteAccess...... 86 EnablingRemoteAccess...... 86 MappingURLstoOtherURLs ...... 86 CreatingaURLMapping ...... 87 EditingExistingMappings...... 88 RedirectingURLs...... 89 SpecifyingtheSOCKSNameServerIPAddress ...... 89 ClientAutoconfiguration...... 90

Chapter 7 ReverseProxy ...... 91 HowReverseProxyingWorks ...... 91 ProxyasaStand-inforaServer...... 91 SecureReverseProxying ...... 93 ProxyingforLoadBalancing ...... 95 SettingupaReverseProxy...... 96 SettingupaSecureReverseProxy...... 98

Chapter 8 UsingSOCKSv5...... 101 UsingaSOCKSServer ...... 101 ConfiguringSOCKSv5...... 102 CreatingSOCKSv5AuthenticationEntries...... 103 EditingSOCKSv5AuthenticationEntries...... 105 DeletingSOCKSv5AuthenticationEntries...... 105 MovingSOCKSv5AuthenticationEntries ...... 106 CreatingSOCKSv5ConnectionEntries...... 106 EditingSOCKSv5ConnectionEntries...... 108 DeletingSOCKSv5ConnectionEntries...... 109 MovingSOCKSv5ConnectionEntries...... 109 CreatingRoutingEntries...... 109 CreatingSOCKSv5RoutingEntries ...... 110 CreatingProxyRoutingEntries ...... 110 EditingRoutingEntries...... 112 DeletingRoutingEntries...... 112

5 MovingRoutingEntries...... 112 EnablingSOCKS ...... 113 AuthenticatingThroughaSOCKSServerChain...... 113

Chapter 9 Caching ...... 115 HowCachingWorks ...... 115 UnderstandingtheCacheStructure...... 116 DistributingFilesintheCache ...... 117 SettingCacheSpecifics...... 118 EnablingtheCache ...... 119 CreatingaCacheWorkingDirectory...... 119 RecordingURLs...... 119 SettingtheCacheSize...... 120 EditingtheCacheCapacity ...... 121 CachingHTTPDocuments...... 121 SettingtheHTTPCacheRefreshInterval...... 122 SettingtheHTTPCacheExpirationPolicy...... 123 ReportingHTTPAccessestotheRemoteServer...... 123 CachingFTPandGopherDocuments ...... 124 SettingFTPandGopherCacheRefreshIntervals...... 124 ConfiguringtheCache...... 125 SettingtheCacheDefault...... 126 CachingPagesRetrievedUsingHTTPS...... 126 CachingPagesthatRequireAuthentication ...... 127 CachingQueries...... 127 SettingtheMinimumandMaximumCacheFileSizes ...... 128 SettingtheCacheBehaviorforClientInterruptions ...... 128 SettingtheCacheBehaviorforFailedOriginServerConnections ...... 128 AddingandModifyingCachePartitions ...... 129 AddingandModifyingCacheSections...... 129 SettingtheCacheCapacity ...... 130 EnablingtheCacheMonitorandManager...... 131 AccessingCacheManagerInformation...... 132 CachingLocalHosts...... 132 UsingCacheBatchUpdates ...... 133 CreatingaBatchUpdate...... 133 EditingorDeletingaBatchUpdateConfiguration ...... 134 Using the Cache Command Line Utilities ...... 135 BuildingtheCacheDirectoryStructure...... 135 UpgradingtheCacheStructure...... 136 Upgradinga1.1CacheStructure...... 136 Upgradinga2.0CacheStructure...... 137 RepairingtheCacheURLList...... 138

6 iPlanet Web Proxy Server Administrator’s Guide • March 2001 CleaningtheURLList...... 139 RoutingthroughProxyArrays ...... 140 CreatingaProxyArrayMemberList ...... 143 DeletingProxyArrayMembers ...... 144 EditingProxyArrayMemberListInformation ...... 145 ConfiguringProxyArrayMembers ...... 145 EnablingRoutingThroughaProxyArray...... 146 EnablingaProxyArray...... 147 RedirectingRequestsinaProxyArray...... 148 GeneratingaPACFilefromaPATFile ...... 148 ManuallyGeneratingaPACFilefromaPATFile...... 148 AutomaticallyGeneratingaPACFilefromaPATFile ...... 149 RoutingThroughaParentArray...... 150 ViewingParentArrayInformation ...... 151 RoutingThroughICPNeighborhoods...... 151 Adding Parents to an ICP Neighborhood ...... 154 RemovingParentsfromanICPNeighborhood...... 155 EditingConfigurationsforParentsinanICPneighborhood ...... 155 Adding Siblings to an ICP Neighborhood ...... 156 RemovingSiblingsfromanICPNeighborhood ...... 157 EditingConfigurationsforSiblingsinanICPNeighborhood ...... 157 ConfiguringIndividualICPNeighbors ...... 157 EnablingICP...... 159 EnablingRoutingThroughanICPNeighborhood...... 159

Chapter 10 Filtering Content Through the Proxy ...... 161 FilteringURLs ...... 161 CreatingaFilterFileofURLs...... 162 SettingDefaultAccessforaFilterFile ...... 163 RestrictingAccesstoSpecificWebBrowsers ...... 163 RequestBlocking...... 164 SuppressingOutgoingHeaders ...... 165 FilteringbyMIMEType...... 165 FilteringoutHTMLTags ...... 166

Chapter 11 Using the Client Autoconfiguration File ...... 169 UnderstandingAutoconfigurationFiles ...... 170 WhatDoestheAutoconfigurationFileDo?...... 170 AccessingtheProxyasaWebServer ...... 171 UsingPacFileswithaReverseProxy ...... 172 UsingtheServerManagerFormstoCreateanAutoconfigurationFile ...... 173 CreatingtheAutoconfigurationFileManually...... 175

7 TheFindProxyForURLFunction...... 175 TheFunctionReturnValues ...... 176 JavaScriptFunctionsandEnvironment...... 177 Hostname-basedFunctions...... 178 Related Utility Functions ...... 181 URL/host-name-basedCondition...... 182 Time-basedConditions...... 183 Example1:ProxyAllServersExceptLocalHosts...... 186 Example2:ProxyLocalServersOutsidetheFirewall ...... 186 Example3:ProxyOnlyUnresolvedHosts...... 187 Example4:ConnectDirectlytoaSubnet ...... 187 Example5:BalanceProxyLoadwithdnsDomainIs()...... 188 Example6:BalanceProxyLoadwithshExpMatch() ...... 189 Example7:ProxyingaSpecificProtocol...... 189

Chapter 12MonitoringtheServer’sStatus...... 191 MonitoringtheServerUsingHTTP...... 191 ServerUsage...... 191 ActivityBreakdown ...... 192 Totals...... 192 WorkingwithLogFiles...... 193 ViewingtheErrorLogFile...... 193 ViewinganAccessLogFile...... 194 UnderstandingAccessLogfileSyntax ...... 195 UnderstandingStatusCodes...... 198 SettingAccessLogPreferences...... 200 WorkingwiththeLogAnalyzer...... 202 TransferTimeDistributionReport ...... 203 StatusCodeReport...... 203 DataFlowReport...... 204 RequestsandConnectionsReport...... 204 CachePerformanceReport...... 205 TransferTimeReport...... 207 HourlyActivityReport...... 208 RunningtheLogAnalyzerfromtheServerManager...... 208 RunningtheLogAnalyzerfromtheCommandLine ...... 210 ArchivingLogFiles...... 211 MonitoringtheServerUsingSNMP ...... 212 HowDoesSNMPWork? ...... 213 TheProxyServerMIB...... 214 Installing Subagents on AIX ...... 215 EnablingtheSubagent...... 215 Starting,Stopping,andRestartingtheSubagent...... 216

8 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Chapter 13ProxyErrorLogMessages ...... 217 ProxyErrorMessages...... 218 Catastrophe...... 218 Failure ...... 219 Warning...... 222 Security ...... 222 SOCKSErrorMessages...... 222

Chapter 14 Understanding Encryption and SSL ...... 225 WhatisEncryption? ...... 225 UsingEncryptionintheProxyServer...... 225 WhatisSSL?...... 226 TunnelingSSLthroughtheProxyServer...... 226 WhatisHTTPS?...... 227 EnablingHTTPSProxying ...... 228 EnablingSSLonYourServer...... 229 ActivatingSSL ...... 229 SettingEncryptionPreferences...... 230 SSLVersion...... 230 ClientCertificates...... 230 Ciphers...... 231 KeepingClientsfromCachingSSLFiles ...... 233 ConfiguringSSLTunneling ...... 233 IncreasingServerSecurity ...... 234 WhatisClientAuthentication?...... 235 ClientAuthenticationinaReverseProxy ...... 236 SettingupClientAuthenticationinaReverseProxy...... 236 ProxyAuthenticatesClient ...... 236 ContentServerAuthenticatesProxy ...... 237 ProxyAuthenticatesClientandContentServerAuthenticatesProxy...... 238 EffectsofanSSL-EnabledServer...... 238 SecureURLConstruction ...... 238 SecureServerDocumentRoot ...... 238 TheSecureLog ...... 239 UnprotectedServerDocumentDirectory...... 239 Changestothemagnus.confFile...... 239 Security...... 239 SSL2...... 240 SSL3...... 240 Keyfile...... 240 Certfile ...... 240 Ciphers...... 241 SSL3Ciphers...... 241

9 SSLClientAuth ...... 241

Chapter 15 Tuning Server Performance ...... 243 UsingTimeoutsEffectively...... 243 ReadTimeout...... 243 ProxyTimeout ...... 244 TimeoutAfterInterrupt ...... 244 Keep-AliveTimeout ...... 245 GlobalNetlibTimeout ...... 245 StallTimeoutOverride...... 245 Controlling Up-to-Date Checks ...... 246 SettingtheLast-modifiedFactor...... 246 UsingDNSEffectively...... 246 DeterminingtheNumberofProcesses ...... 248 DisablingKeep-Alives...... 249 UsingSOCKSEffectively...... 249 WorkerThreads...... 249 AcceptThreads ...... 250 TuningFTPListingWidth...... 250 UsingtheCacheEffectively...... 250 OptimizingCacheArchitecture...... 251 TuningtheCache...... 251 Add'lCch-statusValues ...... 251 MmaponInitialWrites...... 252 MmaponCacheUpdates ...... 252 UseSharedMemoryI/O...... 253 NotifyNumChanges...... 253 NotifyBlkLimit ...... 253 C-monTickInterval...... 254 MaxMmapSize ...... 254 MinSyncInterval...... 254 NotifyBlkChunk/Proc...... 255 FsFullRetryAfter ...... 256 UpdateAfterPercent...... 256 SyncDumpTicks ...... 257 Byte-Ranges...... 257 SingleAccept...... 257 TuningtheGarbageCollector...... 257 GcURLDBInterval...... 257 GcNapLength...... 258 HardGcNapCount ...... 258 SoftGcNapCount...... 259 HardGcMaxEntries...... 259

10 iPlanet Web Proxy Server Administrator’s Guide • March 2001 GcDirChunk ...... 260 GcHiMarginPercent ...... 260 GcLoMarginPercent ...... 261 GcExtraMarginPercent...... 261 GcLeaveFsFullPercent...... 262

Chapter 16ConfiguringtheProxyManually...... 263 Themagnus.confFile ...... 264 Theobj.confFile...... 265 TheStructureofobj.conf...... 266 DirectiveSyntax ...... 266 ASampleObject ...... 267 RequiredObjectsforobj.conf...... 269 TheDefaultObject ...... 269 HowtheProxyServerHandlesObjects ...... 270 Themime.typesFile ...... 271 TheadmpwFile...... 273 Thesocks5.confFile...... 273 Thebu.confFile...... 274 ObjectBoundaries ...... 274 Examplesofbu.conf...... 275 Theicp.confFile...... 275 Theparray.patFile ...... 276 Theparent.patFile...... 277 ProgrammingtheProxyServer...... 279

Chapter 17CreatingServerPlug-inFunctions...... 281 WhatIstheServerPlug-inAPI? ...... 281 WritingPlug-inFunctions ...... 282 TheServerPlug-inAPIHeaderFiles ...... 283 GettingDataFromtheServer:TheParameterBlock ...... 286 PassingParameterstoServerApplicationFunctions...... 286 Parameter-manipulatingFunctions...... 286 DataStructuresandDataAccessFunctions...... 287 ApplicationFunctionStatusCodes ...... 288 ReportingErrorstotheServer...... 289 SettinganHTTPResponseStatusCode ...... 289 ErrorReporting...... 290 CompilingandLinkingYourCode ...... 290 LoadingYourSharedObject ...... 291 UsingYourPlug-inFunctions...... 292

11 Appendix A ServerPlug-inAPIFunctionDefinitions...... 293 cache_digest(declaredinlibproxy/cache.h)...... 293 cache_filename(declaredinlibproxy/cutil.h)...... 294 cache_fn_to_dig(declaredinlibproxy/cutil.h)...... 294 ce_free(declaredinlibproxy/cache.h)...... 294 ce_lookup(declaredinlibproxy/cache.h)...... 295 cif_load(declaredinlibproxy/cif.h)...... 296 cif_clear(declaredinlibproxy/cif.h)...... 297 cif_load_all_data(declaredinlibproxy/cif.h)...... 297 cif_load_cif(declaredinlibproxy/cif.h)...... 298 cif_read_entry(declaredinlibproxy/cif.h)...... 298 cif_stat_entries(declaredinlibproxy/cif.h)...... 299 cif_write_entry(declaredinlibproxy/cif.h)...... 299 cinfo_find(declaredinbase/cinfo.h)...... 300 condvar_init(declaredinbase/crit.h)...... 301 condvar_notify(declaredinbase/crit.h)...... 301 condvar_terminate(declaredinbase/crit.h)...... 302 condvar_wait(declaredinbase/crit.h)...... 302 crit_enter(declaredinbase/crit.h)...... 303 daemon_atrestart(declaredinnetsite.h)...... 303 fast_dump_cif(declaredinlibproxy/cif.h)...... 304 fast_get_cif_entry_for(declaredinlibproxy/cif.h)...... 304 fast_load_cif(declaredinlibproxy/cif.h)...... 305 fast_put_cif_entry(declaredinlibproxy/cif.h)...... 306 filebuf_buf2sd(declaredinbase/buffer.h)...... 306 filebuf_close(declaredinbase/buffer.h)...... 307 filebuf_getc(declaredinbase/buffer.h)...... 307 filebuf_open(declaredinbase/buffer.h)...... 308 filebuf_open_nostat(declaredinbase/buffer.h)...... 309 FREE(declaredinnetsite.h)...... 310 fs_blks_available(declaredinlibproxy/fs.h)...... 310 fs_blk_size(declaredinlibproxy/fs.h)...... 311 func_exec(declaredinframe/func.h)...... 311 func_find(declaredinframe/func.h)...... 312 http_dump822(declaredinframe/http.h)...... 313 http_hdrs2env(declaredinframe/http.h)...... 313 #http_scan_headers(declaredinframe/http.h)...... 314 http_set_finfo(declaredinframe/http.h)...... 314 http_start_response(declaredinframe/http.h)...... 315 http_status(declaredinframe/http.h)...... 316 http_uri2url(declaredinframe/http.h)...... 317 log_error(declaredinframe/log.h)...... 317 magnus_atrestart(declaredinnetsite.h)...... 318

12 iPlanet Web Proxy Server Administrator’s Guide • March 2001 make_log_time(declaredinlibproxy/util.h)...... 319 MALLOC(declaredinnetsite.h)...... 320 netbuf_buf2sd(declaredinbase/buffer.h)...... 320 netbuf_close(declaredinbase/buffer.h)...... 321 netbuf_getc(declaredinbase/buffer.h)...... 321 netbuf_grab(declaredinbase/buffer.h)...... 322 netbuf_open(declaredinbase/buffer.h)...... 323 net_ip2host(base/net.h)...... 323 net_read(declaredinbase/net.h)...... 324 net_socket(declaredinbase/net.h)...... 324 net_write(declaredinbase/net.h)...... 325 param_create(declaredinbase/pblock.h)...... 326 param_free(declaredinbase/pblock.h)...... 326 pblock_copy(declaredinbase/pblock.h)...... 327 pblock_create(declaredinbase/pblock.h)...... 328 pblock_dup(declaredinbase/pblock.h)...... 328 pblock_find(declaredinbase/pblock.h)...... 329 pblock_findlong(declaredinlibproxy/util.h)...... 329 pblock_findval(declaredinbase/pblock.h)...... 330 pblock_free(declaredinbase/pblock.h)...... 330 pblock_nlinsert(declaredinlibproxy/util.h)...... 331 pblock_nninsert(declaredinbase/pblock.h)...... 332 pblock_nvinsert(declaredinbase/pblock.h)...... 332 pblock_pb2env(declaredinbase/pblock.h)...... 333 pblock_pblock2str(declaredinbase/pblock.h)...... 334 pblock_pinsert(declaredinbase/pblock.h)...... 335 pblock_remove(declaredinbase/pblock.h)...... 335 pblock_replace_name(declaredinlibproxy/util.h)...... 336 pblock_str2pblock(declaredinbase/pblock.h)...... 336 PERM_FREE(declaredinnetsite.h)...... 337 PERM_MALLOC(declaredinnetsite.h)...... 338 PERM_STRDUP(declaredinnetsite.h)...... 338 protocol_dump822(declaredinframe/protocol.h)...... 339 protocol_finish_request(declaredinframe/protocol.h)...... 339 protocol_handle_session(declaredinframe/protocol.h)...... 340 protocol_hdrs2env(declaredinframe/protocol.h)...... 340 protocol_parse_request(declaredinframe/protocol.h)...... 341 protocol_scan_headers(declaredinframe/protocol.h)...... 341 protocol_set_finfo(declaredinframe/protocol.h)...... 342 protocol_start_response(declaredinframe/protocol.h)...... 343 protocol_status(declaredinframe/protocol.h)...... 344 protocol_uri2url(declaredinframe/protocol.h)...... 345 protocol_uri2url_dynamic(declaredinframe/protocol.h)...... 346

13 REALLOC(declaredinnetsite.h)...... 347 request_create(declaredinframe/req.h)...... 347 request_free(declaredinframe/req.h)...... 348 request_header(declaredinframe/req.h)...... 348 request_stat_path(declaredinframe/req.h)...... 349 request_translate_uri(declaredinframe/req.h)...... 350 sem_grab(declaredinbase/sem.h)...... 351 sem_init(declaredinbase/sem.h)...... 351 sem_release(declaredinbase/sem.h)...... 352 sem_terminate(declaredinbase/sem.h)...... 352 sem_tgrab(declaredinbase/sem.h)...... 353 session_create(declaredinbase/session.h)...... 353 session_free(declaredinbase/session.h)...... 354 session_maxdns(declaredinbase/session.h)...... 355 shexp_casecmp(declaredinbase/shexp.h)...... 355 shexp_cmp(declaredinbase/shexp.h)...... 356 shexp_match(declaredinbase/shexp.h)...... 358 shexp_valid(declaredinbase/shexp.h)...... 358 shmem_alloc(declaredinbase/shmem.h)...... 359 shmem_free(declaredinbase/shmem.h)...... 360 STRDUP(declaredinnetsite.h)...... 360 systhread_attach(declaredinbase/systhr.h)...... 361 systhread_current(declaredinbase/systhr.h)...... 361 systhread_getdata(declaredinbase/systhr.h)...... 362 systhread_init(declaredinbase/systhr.h)...... 363 systhread_newkey(declaredinbase/systhr.h)...... 363 systhread_setdata(declaredinbase/systhr.h)...... 364 systhread_sleep(declaredinbase/systhr.h)...... 364 systhread_start(declaredinbase/systhr.h)...... 365 systhread_terminate(declaredinbase/systhr.h)...... 365 systhread_timerset(declaredinbase/systhr.h)...... 366 system_errmsg(declaredinbase/file.h)...... 366 system_fclose(declaredinbase/file.h)...... 367 system_flock(declaredinbase/file.h)...... 368 system_fopenRO(declaredinbase/file.h)...... 368 system_fopenRW(declaredinbase/file.h)...... 369 system_fopenWA(declaredinbase/file.h)...... 369 system_fread(declaredinbase/file.h)...... 370 system_fwrite(declaredinbase/file.h)...... 371 system_fwrite_atomic(declaredinbase/file.h)...... 371 system_gmtime(declaredinbase/file.h)...... 372 system_localtime(declaredinbase/file.h)...... 373 system_ulock(declaredinbase/file.h)...... 374

14 iPlanet Web Proxy Server Administrator’s Guide • March 2001 system_unix2local(declaredinbase/file.h)...... 374 util_can_exec(declaredinbase/util.h)...... 375 util_chdir2path(declaredinbase/util.h)...... 375 util_does_process_exist(declaredinlibproxy/util.h)...... 376 util_env_create(declaredinbase/util.h)...... 377 util_env_find(declaredinbase/util.h)...... 377 util_env_free(declaredinbase/util.h)...... 378 util_env_replace(declaredinbase/util.h)...... 378 util_env_str(declaredinbase/util.h)...... 379 util_get_current_gmt(declaredinlibproxy/util.h)...... 379 util_get_int_from_aux_file(declaredinlibproxy/cutil.h)...... 380 util_get_long_from_aux_file(declaredinlibproxy/cutil.h)...... 380 util_get_string_from_aux_file(declaredinlibproxy/cutil.h)...... 381 util_get_int_from_file(declaredinlibproxy/cutil.h)...... 381 util_getline(declaredinbase/util.h)...... 382 util_get_long_from_file(declaredinlibproxy/cutil.h)...... 383 util_get_string_from_file(declaredinlibproxy/cutil.h)...... 383 util_grab_lock(declaredinlibproxy/cutil.h)...... 384 util_hostname(declaredinbase/util.h)...... 385 util_is_mozilla(declaredinbase/util.h)...... 385 util_is_url(declaredinbase/util.h)...... 386 util_itoa(declaredinbase/util.h)...... 386 util_later_than(declaredinbase/util.h)...... 387 util_make_filename(declaredinlibproxy/cutil.h)...... 387 util_make_gmt(declaredinlibproxy/util.h)...... 388 util_make_local(declaredinlibproxy/util.h)...... 388 util_make_lockname(declaredinlibproxy/cutil.h)...... 389 util_make_printable(declaredinlibproxy/cutil.h)...... 389 util_move_dir(declaredinlibproxy/util.h)...... 390 util_move_file(declaredinlibproxy/util.h)...... 391 util_parse_http_time(declaredinlibproxy/util.h)...... 391 util_put_int_to_file(declaredinlibproxy/cutil.h)...... 392 util_put_long_to_file(declaredinlibproxy/cutil.h)...... 392 util_put_string_to_aux_file(declaredinlibproxy/cutil.h)...... 393 util_put_string_to_file(declaredinlibproxy/cutil.h)...... 393 util_release_lock(declaredinlibproxy/cutil.h)...... 394 util_sect_id(declaredinlibproxy/cutil.h)...... 394 util_sh_escape(declaredinbase/util.h)...... 395 util_snprintf(declaredinbase/util.h)...... 395 util_sprintf(declaredinbase/util.h)...... 396 util_strcasecmp(declaredinbase/systems.h)...... 397 util_strncasecmp(declaredinbase/systems.h)...... 398 util_uri_check(declaredinlibproxy/util.h)...... 398

15 util_uri_escape(declaredinbase/util.h)...... 399 util_uri_is_evil(declaredinbase/util.h)...... 400 util_uri_parse(declaredinbase/util.h)...... 400 util_uri_unescape(declaredinbase/util.h)...... 401 util_url_cmp(declaredinlibproxy/util.h)...... 401 util_url_fix_hostname(declaredinlibproxy/util.h)...... 402 util_url_has_FQDN(declaredinlibproxy/util.h)...... 402 util_vsnprintf(declaredinbase/util.h)...... 403 util_vsprintf(declaredinbase/util.h)...... 403

Appendix B ServerDataStructures...... 405 TheSessionDataStructure ...... 405 TheParameterBlock(pblock)DataStructure ...... 405 ThePb_entryDataStructure...... 406 ThePb_paramDataStructure...... 406 TheClientParameterBlock...... 406 TheRequestDataStructure...... 407 TheStatDataStructure...... 407 TheSharedMemoryStructure,Shmem_s...... 408 TheNetbufDataStructure...... 408 TheFilebufferDataStructure ...... 408 TheCinfoDataStructure ...... 408 TheSYS_NETFDDataStructure...... 409 TheSYS_FILEDataStructure ...... 409 TheSEMAPHOREDataStructure ...... 409 TheSockaddr_inDataStructure...... 409 TheCONDVARDataStructure...... 409 TheCRITICALDataStructure...... 410 TheSYS_THREADDataStructure ...... 410 TheCacheEntryDataStructure...... 410 TheCacheStateDataStructure ...... 411 TheConnectModeDataStructure...... 412

Appendix C Proxy Configuration Files ...... 413 Themagnus.confFile...... 414 Certfile...... 415 Ciphers ...... 415 DNS...... 416 ErrorLog ...... 416 Keyfile...... 416 LDAPConnPool...... 417 LoadObjects ...... 417 MaxProcs...... 417

16 iPlanet Web Proxy Server Administrator’s Guide • March 2001 PidLog ...... 418 Port...... 418 ProcessLife...... 419 RootObject...... 419 Security ...... 420 ServerName...... 420 SSLClientAuth ...... 421 SSL2 ...... 421 SSL3 ...... 421 SSL3Ciphers ...... 421 User ...... 422 Theobj.confFile...... 422 AddLog ...... 423 flex-log(startingproxylogging)...... 424 AuthTrans...... 425 proxy-auth(translatingproxyauthorization)...... 425 Connect ...... 427 DNS ...... 428 dns-config(suggesttreatingcertainhostnamesasremote)...... 428 your-dns-function(aplug-indnsfunctionyoucreate)...... 430 Error...... 431 Filter...... 432 Init...... 433 Initfunctionorderinobj.conf...... 434 Calling Init functions ...... 434 flex-init(startingtheflex-logaccesslogs)...... 435 icp-init(initializesICP)...... 438 init-batch-update(startingbatchupdates)...... 439 init-cache(startingthecachingsystem)...... 440 init-dns-cache(startingdnscaching)...... 442 init-clf(startingtheCommonLogFilesubsystem)...... 443 init-partition(specifyingcachepartitions) ...... 444 init-proxy(startingthenetworksoftwareforproxy) ...... 445 init-proxy-auth(specifyingtheauthenticationstrategy) ...... 447 init-proxy-certs (loading the default certificate database)...... 447 init-sockd(startingtheSOCKDfeature)...... 448 init-urldb(settinguptheURLdatabase)...... 450 load-modules(loadingsharedobjectmodules)...... 451 load-types(loadingMIME-typemappings)...... 452 pa-init-parent-array(initializingaparentarraymember) ...... 453 pa-init-proxy-array(initializingaproxyarraymember) ...... 454 tune-proxy(tuningserverperformance)...... 456

17 tune-cache(tuningcacheperformance) ...... 457 tune-gc(tuninggarbagecollectorperformance)...... 460 NameTrans...... 463 assignname(associatingtemplateswithpath)...... 463 map(mappingURLstomirrorsites) ...... 464 pac-map(mappingURLstoalocalfile)...... 464 pat-map(mappingURLstoalocalfile) ...... 465 pfx2dir(replacingpathprefixeswithdirectorynames)...... 465 ObjectType ...... 466 cache-enable(enablingcaching)...... 466 cache-setting(specifyingcachingparameters) ...... 468 force-type(assigningMIMEtypestoobjects) ...... 469 http-config(usingkeep-alivefeature)...... 470 java-ip-check(checkingIPaddresses)...... 470 type-by-extension(determiningfileinformation)...... 471 PathCheck...... 471 check-acl(attachinganACLtoanobject)...... 472 deny-service(denyingclientaccess)...... 472 require-proxy-auth(requiringproxyauthentication)...... 473 url-check(checkingURLsyntax)...... 474 Route...... 474 icp-route(routingwithICP)...... 474 pa-enforce-internal-routing(enforcinginternaldistributedrouting) ...... 474 pa-set-parent-route(settingahierarchicalroute) ...... 475 set-proxy-server(usinganotherproxytoretrievearesource) ...... 475 set-socks-server(usingaSOCKSservertoretrievearesource) ...... 475 unset-proxy-server(unsettingaproxyroute) ...... 476 unset-socks-server(unsettingaSOCKSroute) ...... 476 Service...... 476 proxy-retrieve(retrievingdocumentswiththeproxy)...... 477 send-file(sendingtextfilecontentstoclient)...... 477 deny-service(denyingaccesstoaresource)...... 478 Thesocks5.confFile ...... 478 Authentication/BanHostEntries...... 479 RoutingEntries ...... 480 VariablesandFlags...... 480 AvailableSettings...... 481 ProxyEntries...... 487 AccessControlEntries...... 488 SpecifyingPorts ...... 489 Thebu.confFile...... 489 Accept...... 489 Connections ...... 489

18 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Count ...... 490 Days ...... 490 Depth ...... 490 Objectboundaries...... 490 Reject ...... 491 Source...... 491 Time...... 491 Type ...... 492 Theicp.confFile...... 492 add_parent (adding parent servers to an ICP neighborhood) ...... 492 add_sibling(addingsiblingserverstoanICPneighborhood) ...... 493 server(configuringthelocalproxyinanICPneighborhood)...... 494

Glossary...... 497

19 20 iPlanet Web Proxy Server Administrator’s Guide • March 2001 List of Figures

Figure1-1 ServerAdministrationpage...... 33 Figure2-1 TheProxy’sServerManagermainforms...... 41 Figure6-1 Chainingproxiestogether ...... 80 Figure7-1 Areverseproxyappearstobetherealcontentserver...... 92 Figure7-2 Secureclientconnectiontoproxy ...... 93 Figure7-3 Secureproxyconnectiontocontentserver ...... 94 Figure 7-4 Secure client connection to proxy and secure proxy connection to content server . . . 94 Figure7-5 Proxyusedforloadbalancing...... 96 Figure8-1 SOCKSv5 ...... 102 Figure9-1 Proxydocumentretrieval...... 116 Figure9-2 Exampleofacachestructure...... 117 Figure9-3 ClienttoProxyRouting...... 141 Figure9-4 ProxytoProxyRouting...... 142 Figure9-5 AnICPexchange ...... 153 Figure 14-1 With an SSL connection, the proxy can’t view the data it transfers...... 226 Figure 14-2 The proxy establishes the secure connection if the client doesn’t support HTTPS. . . 228 Figure16-1 InternaliconsforMIMEtypes ...... 272 Figure17-1 Thehierarchyofserverplug-inAPIheaderfiles ...... 283

21 22 iPlanet Web Proxy Server Administrator’s Guide • March 2001 List of Tables

Table3-1 Resourceregularexpressionwildcardpatterns ...... 43 Table3-2 Regularexpressionsandtheirmeanings...... 44 Table 4-1 Suggested number of processes based on average request service time and number of requests 58 Table9-1 UsingtheCacheExpirationandCacheRefreshsettingswithHTTP ...... 122 Table11-1 SampleURIsandcorrespondingURLs ...... 171 Table11-2 FindProxyForURLReturnValues...... 176 Table11-3 BalanceProxyLoad...... 188 Table12-1 Thelastlineofthesampleaccesslogfilehasseveralcomponents...... 194 Table12-2 StatusCodes...... 198 Table15-1 ProcessesperUser...... 248 Table 17-1 Header files in the base directory ...... 284 Table17-2 Statuscodesusedwithprotocol_status ...... 289 Table17-3 Optionsforlinking...... 291 Table C-1 Calling functions of the
 directive...... 434 TableC-2 Optionsforflex-logging ...... 436 TableC-3 Cachecapacityandthenumberofsections...... 441

23 24 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Preface

Welcome to iPlanet Web Proxy Server and the Internet. iPlanet provides open software that lets people and companies exchange information and conduct commerce over the Internet and other global networks. iPlanet Web Proxy Server is a high-performance server software product. It is designed for replicating and filtering access to web-based content.

What iPlanet Web Proxy Server Provides The rapid growth of clients (web browsers such as Netscape Navigator) and servers fortheWorldWideWebandcorporateintranets has opened new opportunities for sharing information, collaborating, and developing network-oriented applications. At the same time, for network administrators this growth has raised new issues about network congestion and security, about how to ensure fast and reliable service for mission-critical applications, and about how to control access to restricted network resources. iPlanet Web Proxy Server is designed to address these problems. For companies that do business on the Internet or the web, a proxy server can act as a transparent intermediary between individual clients and the servers that contain the information the clients want. A proxy server allows an organization or company to provide controlled Internet access for internal users who would otherwise be blocked by a security firewall; a proxy server working in reverse can also let the organization regulate access from external clients, as a refinement to firewall security protection. iPlanet Web Proxy Server has an added advantage—it provides replication-on-demand by intelligently caching frequently accessed documents, thereby conserving network bandwidth and dramatically increasing response time. This important feature makes iPlanet Web Proxy Server valuable even for companies that have full web access. iPlanet Web Proxy Server is the first commercial proxy server to provide caching. The server’s content filtering capabilities let you fine-tune access control (for example, by the individual user or server trying to gain access), and provide the ability to track who accesses which server, and whether or not they are successful.

25 What iPlanet Web Proxy Server Provides

iPlanet Web Proxy Server enhances network security and reliability and provides advanced server management features that let you create intelligent proxy networks that are totally transparent to users. iPlanet Web Proxy Server is fully compatible with Netscape Navigator, the other servers in Netscape SuiteSpot, and other HyperText Transfer Protocol (HTTP) clients and servers. iPlanet Web Proxy Server offers these features: •Itprovidesproxying; that is, safe passage through the firewall for secure and unsecure protocols. The Unix version of the proxy server proxies HTTP, FTP, Gopher, Secure Sockets Layer (SSL), HyperText Transfer Protocol-Secure (HTTPS), and Netscape News Transfer Protocol-Secure (NNTPS). iPlanet Web Proxy Server also provides a SOCKS v5 daemon for the generic tunneling of many other protocols and applications, including streaming media. •Itprovidesreplication; it caches documents by writing them to a local file system. If a document is requested more than once, subsequent requests are faster because the proxy doesn’t have to contact the remote server repeatedly. Replication can dramatically reduce network traffic and associated costs. iPlanet Web Proxy Server also provides distributed caching so that multiple proxy servers can operate as a single logical cache for load-balancing and failover, and dynamic proxy routing so that the proxy server can query other caches to determine if a document is available. •Ifusedasareverse proxy, it can help your host machine handle a high volume of requests while reducing their effect on the host machine’s performance. A reverse proxy lets the content server reside safely inside the firewall while the reverse proxy acts as a server outside the firewall. The Unix proxy server can also be used as a secure reverse proxy so that all information is securely transferred between clients, proxy, and content server. •Itcanfilter client transactions by controlling access to remote servers and protocols and by limiting access to specific documents or sites based on user names, URLs (Universal Resource Locators), and client host names (or IP [Internet Protocol] addresses). •Itprovidesflexible logging of client transactions, including client host names or IP addresses, access dates and times, accessed URLs, byte counts of all transferred data, routing information, and the success of transactions. • It provides key server management features such as remote management, SNMP (Simple Network Management Protocol), advanced logging and reporting, cluster management of user and group information through LDAP v3, automatic proxy configuration and proxy scripting, and the server plug-in API (Application Programming Interface).

26 iPlanet Web Proxy Server Administrator’s Guide • March 2001 What’s in This Book?

• Itenablesyoutosetupcontent filtering by URL, and it provides access control by user, IP address, host name or domain, and web content. •Itprovidesvirus screening to prevent any viruses from infecting your internal network.

What’s in This Book? This book contains information about how the proxy server works and explains how to start, configure, and use it. This book will help you to maintain the server, understand its internal workings, and customize its functions. The book is divided into two parts. Part 1 discusses the administration of the proxy server and the second part explains how to program the server. For information on how to install the proxy server, see the iPlanet Web Proxy Server 3.6 Installation Guide foryourplatform. For information on the administration server that comes with your proxy server, see Managing Netscape Servers.

Conventions Used in This Book These conventions are used in this book: Monospaced font. Monospaced type is used for text that you should type. It is also used for examples of code and for directories and filenames.

Italic. Italic text is used to introduce new terms and to represent variable information.

|. The vertical bar is used as a separator for user interface elements. For example, “choose Server Status|Log Preferences” means you click the Server Status button in the Server Manager and then click the Log Preferences link.

Contacting iPlanet Technical Support For product-specific Technical Support assistance, please see the Product Support Page for iPlanet Web Proxy Server at: http://www.iplanet.com/support/technical_resources/proxy

Preface 27 Contacting iPlanet Technical Support

For general Technical Support assistance, please see the iPlanet Technical Support Page at: http://www.iplanet.com/support Other useful iPlanet information can be found at the following Internet locations: • iPlanet release notes and other documentation: http://docs.iplanet.com/docs/manuals/ • iPlanet product status: http://www.iplanet.com/support/technical_resources/ • iPlanet Professional Services information: http://www.iplanet.com/services • iPlanet developer information: http://developer.iplanet.com/ • iPlanet learning solutions: http://www.iplanet.com/learning/index.html • iPlanet product data sheets: http://www.iplanet.com/products/index.html

28 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Part 1

Administering the Proxy Server

Chapter 1, “Starting the Administration and Proxy Servers” Chapter 2, “Managing Your Server” Chapter 3, “Managing Templates and Resources” Chapter 4, “Configuring Server Preferences” Chapter 5, “Controlling Access to Your Server” Chapter 6, “Proxying and Routing URLs” Chapter7,“ReverseProxy” Chapter8,“UsingSOCKSv5” Chapter 9, “Caching” Chapter 10, “Filtering Content Through the Proxy” Chapter 11, “Using the Client Autoconfiguration File” Chapter 12, “Monitoring the Server’s Status” Chapter 13, “Proxy Error Log Messages” Chapter 14, “Understanding Encryption and SSL” Chapter 15, “Tuning Server Performance” Chapter 16, “Configuring the Proxy Manually”

Administering the Proxy Server 29 30 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Chapter 1

Starting the Administration and Proxy Servers

The proxy server’s installation process installs two servers, an administration server and a proxy server. This chapter explains the different methods for starting and stopping both of these servers. For information on installing the proxy server, see the iPlanet Web Proxy Server 3.6 Installation Guide.

Starting and Stopping the Administration Server To start and configure your proxy server, you need to have an administration server running on your machine. For more information about the administration server, see Managing Netscape Servers.

Starting the Administration Server The administration server starts automatically when you finish installing the proxy server. However, there may be instances when you need to stop and start it. To start the administration server: 1. At the command prompt, change to the server root directory. 2. Type ./start-admin. Once you have started the administration server, you need to connect to it. Using a browser that supports frames and JavaScript, such as Netscape Navigator 4.0, enter the following URL for the administration server: http://servername.sub_domain.domain:port_number

31 Using the Server Administration Page

In the above URL, use the administration server’s port number (not the port number for the proxy server) that you specified during installation. You will be prompted for a user name and password. Type the administration server user name and password you specified during the installation. The Server Administration page appears. For more information on the Server Administration page, see “Using the Server Administration Page” on page 34.

Stopping the Administration Server To stop the administration server: 1. At the command prompt, change to the server root directory. 2. Type ./stop-admin.

Using the Server Administration Page When you start the administration server, you see the Server Administration page screen, as shown in Figure 1-1.

32 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Using the Server Administration Page

Figure 1-1 Server Administration page

From the Server Administration page, you can perform the following tasks: • Configure the administration server • Choose a server to configure • Start and stop a proxy server • Install another proxy server on this machine • Migrate from an earlier version of the proxy server • Remove a server

Chapter 1 Starting the Administration and Proxy Servers 33 Starting and Stopping iPlanet Web Proxy Server

Starting and Stopping iPlanet Web Proxy Server Once you have started the administration server, you can start your proxy server. There are several ways to start and stop the proxy server. The following sections discuss these methods.

Starting the Proxy Server You can start the proxy server in one of the following ways:

Using the Server Administration Page From the Server Administration page, you can start the proxy server by using one of the following options:

Option 1

Click the On/Off button next to the server you want to start.

Option 2 1. Click the name of the proxy server you want to start. 2. Choose System Settings|Start/Stop the server. 3. Click Start.

Manually

NOTE If your proxy server is installed on a port number less than 1024, you need to be running as root to start the server manually.

To restart the proxy server from the command line: 1. If the proxy port number is less than 1024, log in as root or superuser. If the proxyportnumberisgreaterthan1024,loginwiththeproxy’suseraccount.

34 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Starting and Stopping iPlanet Web Proxy Server

2. At the command line prompt, go to the proxy’s root directory and type the following: server root/proxy-id/start server root is the directory where you installed the server. The above start script has two command line arguments:

❍ -p XX (where XX is a port number) starts the proxy on a specific port number. This overrides the setting in magnus.conf.

❍ -i runs the proxy in inittab mode, so that if the proxy process is ever killed or crashes, inittab restarts the proxy server for you. It also prevents the proxy from putting itself in a background process. 3. Press Enter.

NOTE If the proxy is already running, you must stop it to use the start command. Also, if the proxy startup is unsuccessful, you should kill the process before trying to restart the proxy (see the troubleshooting section of the iPlanet Web Proxy Server 3.6 Installation Guide).

Restarting the Proxy Server Once installed, the proxy server and its child processes run constantly, waiting and handling requests. If your computer crashes or is taken offline, the server processes are lost. There are several ways you can restart the server: • Automatically restart it from inittab. • Automatically restart it when the machine reboots with the system RC scripts. In other words, use other daemons in /etc/rc.local for BSD-based systems, or /ect/rc2.d/S99proxy directory for SVR4 systems. Because the installation formscannoteditthe/etc/rc.local, /etc/re2.d/S99proxy or /etc/inittab files, you have to edit these files yourself. • Manually soft start it.

Restarting with inittab To restart the proxy server with inittab, put the following text on one line in the /etc/inittab file. The syntax is: proxy:2:respawn:server root/proxy-id/start -i

Chapter 1 Starting the Administration and Proxy Servers 35 Starting and Stopping iPlanet Web Proxy Server

server root is the directory where you installed the server. You’ll need to remove this line before you stop the server (see the Troubleshooting section of the iPlanet Web Proxy Server 3.6 Installation Guide).

NOTE If you are using a version of Unix not derived from System V (such as SunOS 4.1.3), you won’t be able to use the inittab option.

Restarting with the System RC Scripts If you choose to use /etc/rc.local, or your system’s equivalent, place the following line in that directory: server root/proxy-id/start server root is the directory where you installed the server.

Soft Starting the Proxy If the proxy is running and you want to restart it so that it uses an updated configuration, type: server root/proxy-id/restart server root is the directory where you installed the server. This script finds the parent process ID (in the logs/pid file), and sends the hang-up (-HUP) signal with this process ID.

The Start-Up Process The following events occur when you start your proxy server. 1. The administrator starts the proxy server. 2. The proxy reads the configuration files. 3. The proxy calls the init functions. 4. If caching is enabled for your proxy, the proxy calls the init-cache function. This function causes the proxy server to create an additional process, the cache monitor. This process will fork another process, the cache manager. Both processes have the name “ns-proxy.” 5. If the proxy server is running as root, the cache monitor and cache manager processes change their user id so that they don’t have root privileges. 6. The proxy server creates the listen socket to accept connections.

36 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Starting and Stopping iPlanet Web Proxy Server

7. The proxy changes the uid in the parent process. 8. The proxy forks child processes. Because the server is not multithreaded inside processes, there are no worker threads.

Stopping the Proxy Server You can stop a server in one of the following ways:

Using the Server Administration Page From the Server Administration page screen, you can stop the proxy server by using one of the following options:

Option 1

Click the On/Off button next to the server you want to stop.

Option 2 1. Click the name of the proxy server you want to stop. 2. Choose System Settings|Start/Stop the server. 3. Click Stop.

Manually If you used inittab to start the server, you need to remove the line from /etc/inittab before you stop the server. Otherwise, the server restarts automatically after it is stopped. To stop the server manually, log in as root or become superuser, or if you started the proxy using the proxy’s user account, log in as that user. Type the following at the command-line prompt: server root/proxy-id/stop server root is the directory where you installed the server.

Chapter 1 Starting the Administration and Proxy Servers 37 Starting and Stopping iPlanet Web Proxy Server

38 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Chapter 2

Managing Your Server

This chapter describes how to manage your iPlanet Web Proxy Server by using the Server Manager forms. Once you have installed and started your administration and proxy servers, you can use the Server Manager forms to configure your proxy server. For information on installing and starting the administration server and proxy server, see the iPlanet Web Proxy Server 3.6 Installation Guide.

Overview You can configure the proxy server by using the web-based administration forms or by editing the configuration files. The administration server runs a collection of web forms and CGI (Common Gateway Interface) scripts. The Server Administration page is the main web form that lets you configure the administration server or choose another server to configure. The Server Manager forms let you configure the server you select on the Server Administration page.

Using the Server Manager The Server Manager is a collection of forms that lets you configure and administer your proxy server. To access the Server Manager, you choose the server you want to configure from the Server Administration page. For information on accessing the Server Administration page, see the Installation Guide. The Server Manager is shown in Figure 2-1. You can use the Server Manager from any remote computer as long as it has permission to access the administration server.

39 Using the Server Manager

To access the Server Administration page and use the Server Manager: 1. Using a browser that supports frames and JavaScript, such as Netscape Navigator 4.0 or later, enter the URL for the administration server. The URL has the following format: http://servername.domain.domain:port_number/ For example, http://atomic.acmecorp.com:1357 Use the port number for the administration server that you specified during installation; this is not the port number for the proxy server.

NOTE If you are already on the Server Administration page, skip directly to step 3.

2. You’ll be prompted for a user name and password. Type the administration server user name and password that you specified during installation. The Server Administration page appears. 3. Click the button containing the name of the proxy server you want to configure. The Server Manager appears, as shown in Figure 2-1.

40 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Using the Server Manager

Figure 2-1 The Proxy’s Server Manager main forms

Click a button category to view its list of links.

Click a link to view the form that contains its options.

Forms appear here with buttons and options you use to configure the proxy server. After applying the form, you’ll get a confirmation message.

4. To configure specific aspects of your iPlanet Web Proxy Server, click a button at the top of the form, and then choose a link in the left frame. The form appears in the frame on the right.

NOTE You must save and apply your changes in order for the proxy server to begin using them. After you submit certain forms, you’ll see a form that allows you to save and apply your changes. Choosing the Save option does not restart your proxy server, however, choosing Save and Apply does restart the server.

You can return to the Server Administration page by clicking the Admin button in the upper-right corner of the Server Manager.

Chapter 2 Managing Your Server 41 Using the Server Manager

42 iPlanet Web Proxy Server Administrator’s Guide • March 2001 Chapter 3

Managing Templates and Resources

Templates allow you to group URLs together so that you can configure how the proxy handles them. You can make the proxy behave differently depending on the URL the client tries to retrieve. For example, you might require the client to authenticate (type in a user name and password) when accessing URLs from a specific domain. Or, you might deny access to URLs that point to image files. You can configure different cache refresh settings based on the file type (keep some files in the cache longer than others).

What is a Template? A template is a collection of URLs, called resources. A resource might be a single URL, a group of URLs that have something in common, or an entire protocol. You name and create a template and then you assign URLs to that template by using regular expressions. This means that you can configure the proxy server to handle requests for various URLs differently. Any URL pattern you can create with regular expressions can be included in a template. Table 3-1 lists the default resources and provides some ideas for other templates.

Table 3-1 Resource regular expression wildcard patterns Regular expression pattern What it configures ftp://.* All FTP requests http://.* All HTTP requests https://.* All secure HTTP requests gopher://.* All Gopher requests connect://.*:443 All SSL (secure) transactions to HTTPS port. http://home\.iplanet\.com.* All documents on the home.iplanet.com web site.

43 What is a Template?

Table 3-1 Resource regular expression wildcard patterns Regular expression pattern What it configures .*\.gif.* Any URL that includes the string .gif .*\.edu.* Any URL that includes the string .edu http://.*\.edu.* Any URL going to a computer in the .edu domain

Understanding Regular Expressions iPlanet Web Proxy Server allows you to use regular expressions to identify resources. Regular expressions specify a pattern of character strings. In the proxy server, regular expressions are used to find matching patterns in URLs. Here is an example of a regular expression: [a-z]*://[^:/]*\.abc\.com.*> This regular expression would match any documents from the .abc.com domain. The documents could be of any protocol and could have any file extension. Table 3-2 contains regular expressions and their corresponding meanings.

Table 3-2 Regular expressions and their meanings Expression Meaning . Matches any single character except a newline. x? Matches zero or one occurrences of regular expression x. x* Matches zero or more occurrences of regular expression x. x+ Matches one or more occurrences of regular expression x. x{n,m} Matches the character x where x occurs at least n times but no more than m times. x{n,} Matches the character x where x occurs at least n times. x{n} Matches the character x where x occurs exactly n times. [abc] Matches any of the characters enclosed in the brackets. [^abc] Matches any character not enclosed in the brackets. [a-z] Matches any characters within the range in the brackets. x Matches the character x where x is not a special character. \x Removes the meaning of special character x.

44 iPlanet Web Proxy Server Administrator’s Guide • March 2001 What is a Template?

Table 3-2 Regular expressions and their meanings Expression Meaning "x" Removes the meaning of special character x. xy Matches the occurrence of regular expression x followed by the occurrence of regular expression y. x|y Matches either the regular expression x or the regular expression y. ^ Matches the beginning of a string. $ Matches the end of a string. (x) Groups regular expressions.

This example illustrates how you can use some of the regular expressions in Table 3-2. [a-z]*://([^.:/]*[:/]|.*\.local\.com).*" • [a-z]* matches a document of any protocol. • :// matches a (:) followed by (//). • [^.:/]*[:/] matches any character string that does not include a (.),(:) or (/), and is followed by either a (:) or a (/). It therefore matches host names that are not fully qualified and hosts with port numbers. • |.*\.local\.com does not match fully qualified domain name host names such as local.com but does match documents in the .local.com domain. • .*" matches documents with any file extension.

NOTE As noted in Table 3-2, the backslash can be used to escape or remove the meaning of special characters. Characters such as the period and question mark have special meanings, and therefore, must be escaped if they are used to represent themselves. The period, in particular, is found in many URLs. So, to remove the special meaning of the period in your regular expression, you need to precede it with a backslash.

Chapter 3 Managing Templates and Resources 45 What is a Template?

Understanding Wildcard Patterns You can create lists of wildcard patterns that enable you to specify which URLs can be accessed from your site. Wildcards can be in the form of regular expressions or shell expressions, depending on usage. As a general rule: • Use regular expressions for any pattern that matches destination URLs. This includes