![]() | |
Sun Java System Web Proxy Server 4.0.1 Configuration File Reference |
Chapter 7
Other Server Configuration FilesThis chapter summarizes the important configuration files not discussed in other chapters. Configuration files that should never be modified are not listed in this module.
The following configuration files are described in alphabetical order:
certmap.confPurpose
Configures how a certificate, designated by name, is mapped to an LDAP entry, designated by issuerDN.
Location
<Install_Root>/bin/https/install/misc
<Install_Root>/userdb
Syntax
certmap name issuerDN
name:property1 [value1]
name:property2 [value2]
...The default certificate is named default, and the default issuerDN is also named default. Therefore, the first certmap defined in the file must be as follows:
certmap default default
You can use # at the beginning of a line to indicate a comment.
See Also
Sun Java System Web Proxy Server 4.0.1 Administration Guide
The following table describes properties in the certmap.conf file. The left column lists the property names. The second column from the left lists allowed values. The third column from the left lists default values. The right column lists property descriptions.
dbswitch.confPurpose
Specifies the LDAP directory that Sun Java System Web Proxy Server uses.
Location
<Install_Root>/userdb
Syntax
directory name LDAP_URL
name:property1 [value1]
name:property2 [value2]
...The default contents of this file are as follows:
directory default null:///none
Edit the file as follows for anonymous binding over SSL:
directory default ldaps://directory.sun.com:636:/dc%3Dcom
Edit the file as follows for anonymous binding not over SSL:
directory default ldap://directory.sun.com:389:/dc%3Dcom
The following table describes properties in the dbswitch.conf file. The left column lists the property names. The second column from the left lists allowed values. The third column from the left lists default values. The right column lists property descriptions.
Deployment DescriptorsPurpose
Configures features specific to the Sun Java System Web Proxy Server for deployed web applications.
Location
The META-INF or WEB-INF directory of a module or application.
generated.instance.aclPurpose
Sets permissions for access to the server instance. This is the default ACL file; you can create and use others.
Location
Install_Root/httpacl
See Also
Sun Java System Web Proxy Server 4.01 Administration Guide
password.confPurpose
By default, the Sun Java System Web Proxy Server prompts the administrator for the SSL key database password before starting up. If you want the Web server to be able to restart unattended, you need to save the password in a password.conf file. Be sure that your system is adequately protected so that this file and the key databases are not compromised.
Location
<Instance_Directory>/config
This file is not present by default. You must create it if you need it.
Syntax
PKCS#11_module_name:password
If you are using the internal PKCS#11 software encryption module that comes with the server, type the following:
internal:password
If you are using a different PKCS#11 module, for example for hardware encryption or hardware accelerators, you will need to specify the name of the PKCS#11 module, followed by the password.
See Also
Sun Java System Web Proxy Server 4.0.1 Administration Guide
*.clfilterPurpose
The files obj.conf.clfilter, magnus.conf.clfilter, and server.xml.clfilter contain filter specifications for cluster management operations.
Location
Instance_Directory/config
bu.confThe optional bu.conf file contains batch update directives. You can use these directives to update many documents at once. You can time these updates to occur during off-peak hours to minimize the effect on the efficiency of the server. The format of this file is described in this section.
Accept
A valid URL Accept filter consists of any POSIX regular expression. It is used as a filter to test URLs for retrieval in the case of internal updates, and determines whether branching occurs for external updates.
This directive may occur any number of times, as separate Accept lines or as comma or white space delimited entries on a single Accept line and is applied sequentially. Default behavior is .*, letting all URLs pass.
Syntax
Accept regular expression
Connections
For the Connections directive, n is the number of simultaneous connections to be used while retrieving. This is a general method for limiting the load on your machine and, more importantly, the remote servers being contacted.
This directive can occur multiple times in a valid configuration, but only the smallest value is used.
Syntax
Connections n
Count
The argument n of the Count directive specifies the total maximum number of URLs to be updated via this process. This is a simple safeguard for limiting the process and defaults to a value of 300. This directive can occur multiple times in a valid configuration, but only the smallest value is used.
Syntax
Count n
Depth
The Depth directive lets you ensure that, while enumerating, all collected objects are no more than a specified number of links away from the initial URL. The default is 1.
Syntax
Depth depth
Object boundaries
The Object wrapper signifies the boundaries between individual configurations in the bupdate.conf file. It can occur any number of times, though each occurrence requires a unique name.
All other directives are only valid when inside Object boundaries.
Syntax
<Object name=name>
...
</Object>Reject
A valid URL Reject filter consists of any POSIX regular expression. It is used as a filter to test URLs for retrieval in the case of internal updates, and determines whether branching occurs for external updates.
This directive may occur any number of times, as separate Reject lines or as comma or white space delimited entries on a single Reject line, and is applied sequentially. Default behavior is no reject for internal updates and .* (no branching, get single URL) for recursive updates.
Syntax
Reject regular expression
Source
In the Source directive, if the argument is the keyword internal, it specifies batch updates are to be done only on objects currently in the cache (and a directive of Depth 1 is assumed); otherwise, you specify the name of a URL for recursive enumeration.
This directive can occur only once in a valid configuration.
Syntax
Source internal
Source URL
Type
This function lets you control the updating of mime types that the proxy caches. This directive can occur any number of times, in any order.
Syntax
Type ignore
Type inline
Type mime_type
Parameters
ignore means that updates will act on all MIME types that the proxy currently caches. This is the default behavior and supersedes all other Type directives if specified.
inline means that in-lined data is updated as a special type, regardless of any later MIME type exclusions, and are meaningful only when doing recursive updates.
mime-type is assumed to be a valid entry from the system mime-types file, and is included in the list of MIME types to be updated. If the proxy doesn’t currently cache the given MIME type, the object may be retrieved but is not cached.
icp.confThis file is used to configure the Internet Cache Protocol (ICP) feature of your server. There are three functions in the icp.conf file, and each can be called as many times as necessary. Each function should be on a separate line. The three functions are add_parent, add_sibling, and server.
add_parent
The add_parent function identifies and configures a parent server in an ICP neighborhood.
Syntax
add_parent name=name icp_port=port number
proxy_port=port number mcast_address=IP address ttl=number round=1|2
Parameters
name specifies the name of the parent server. It can be a dns name or an IP address.
icp_port specifies the port on which the parent listens for ICP messages.
proxy_port specifies the port for the proxy on the parent.
mcast_address specifies the multicast address the parent listens to. A multicast address is an IP address to which multiple servers can listen. Using a multicast address allows a proxy to send one query to the network that all neighbors listening to that multicast address can receive, therefore eliminating the need to send a query to each neighbor separately.
ttl specifies the time to live for a message sent to the multicast address. ttl controls the number of subnets a multicast message will be forwarded to. If the ttl is set to 1, the multicast message will only be forwarded to the local subnet. If the ttl is 2, the message will go to all subnets that are one hop away.
round specifies in which polling round the parent will be queried. A polling round is an ICP query cycle. Possible values are:
Example
add_parent name=proxy1 icp_port=5151 proxy_port=3333 mcast_address=189.98.3.33 ttl=3 round=2
add_sibling
The add_sibling function identifies and configures a sibling server in an ICP neighborhood.
Syntax
add_sibling name=name icp_port=port number proxy_port=port number mcast_address=IP address ttl=number round=1|2
Parameters
name specifies the name of the sibling server. It can be a dns name or an IP address.
icp_port specifies the port on which the sibling listens for ICP messages.
proxy_port specifies the port for the proxy on the sibling.
mcast_address specifies the multicast address the sibling listens to. A multicast address is an IP address to which multiple servers can listen. Using a multicast address allows a proxy to send one query to the network that all neighbors listening to that multicast address can receive, therefore eliminating the need to send a query to each neighbor separately.
ttl specifies the time to live for a message sent to the multicast address. ttl controls the number of subnets a multicast message will be forwarded to. If the ttl is set to 1, the multicast message will only be forwarded to the local subnet. If the ttl is 2, the message will go to all subnets that are one hop away.
round specifies in which polling round the sibling will be queried. A polling round is an ICP query cycle. Possible values are:
Example
add_sibling name=proxy2 icp_port=5151 proxy_port=3333 mcast_address=190.99.2.11 ttl=2 round=1
server
The server function identifies and configures the local proxy in an ICP neighborhood.
Syntax
server bind_address=IP address mcast=IP address num_servers=number icp_port=port number default_route=name default_route_port=port number no_hit_behavior=fastest_parent|default timeout=seconds
Parameters
bind_address specifies the IP address to which the server will bind. For machines with more than one IP address, this parameter can be used to determine which address the ICP server will bind to.
mcast the multicast address to which the neighbor listens. A multicast address is an IP address to which multiple servers can listen. Using a multicast address allows a proxy to send one query to the network that all neighbors who are listening to that multicast address can see, therefore eliminating the need to send a query to each neighbor separately.
If both a multicast address and bind address are specified for the neighbor, the neighbor uses the bind address to communicate with other neighbors. If neither a bind address nor a multicast address is specified, the communication subsystem will decide which address to use to send the data.
num_servers specifies the number of processes that will service ICP requests.
icp_port specifies the port number to which the server will listen.
default_route tells the proxy server where to route a request when none of the neighboring caches respond. If default_route and default_route_port are set to “origin,” the proxy server will route defaulted requests to the origin server. The meaning of default_route is different depending on the value of no_hit_behavior. If no_hit_behavior is set to default, the default_route is used when none of the proxy array members return a hit. If no_hit behavior is set to fastest_parent, the default_route value is used only if no parent responds.
default_route_port specifies the port number of the machine specified as the default_route. If default_route and default_route_port are set to “origin,” the proxy server will route defaulted requests to the origin server.
no_hit_behavior specifies the proxy’s behavior whenever none of the neighbors returns a “HIT” for the requested document. Possible values are:
timeout specifies the maximum number of milliseconds the proxy will wait for an ICP response.
Example
server bind_address=198.4.66.78 mcast=no num_servers=5 icp_port=5151 default_route=proxy1 default_route_port=8080 no_hit_behavior=fastest_parent timeout=2000
socks5.confThe proxy uses <Install_Root>/<Instance_Directory>/config/socks5.conf to control access to the SOCKS proxy server SOCKD and its services. Each line defines what the proxy does when it gets a request that matches the line.
When SOCKD receives a request, it checks the request against the lines in
<Install_Root>/<Instance_Directory>/config/socks5.conf. When it finds a line that matches the request, the request is permitted or denied based on the first word in the line (permit or deny). Once it finds a matching line, the daemon ignores the remaining lines in the file. If there are no matching lines, the request is denied. You can also specify actions to take if the client’s identd or user ID is incorrect by using #NO_IDENTD: or #BAD_ID as the first word of the line. Each line can be up to 1023 characters long.There are five sections in the socks5.conf file. These sections do not have to appear in the following order. However, because the daemon uses only the first line that matches a request, the order of the lines within each section is extremely important. The five sections of the socks5.conf file are:
- ban host/authentication - identifies the hosts from which the SOCKS daemon should not accept connections and which types of authentication the SOCKS daemon should use to authenticate these hosts
- routing - identifies which interface the SOCKS daemon should use for particular IP addresses
- variables and flags - identifies which logging and informational messages the SOCKS daemon should use
- proxies - identifies the IP addresses that are accessible through another SOCKS server and whether that SOCKS server connects directly to the host
- access control - specifies whether the SOCKS daemon should permit or deny a request
When the SOCKS daemon receives a request, it sequentially reads the lines in each of these five sections to check for a match to the request. When it finds a line that matches the request, it reads the line to determine whether to permit or deny the request. If there are no matching lines, the request is denied.
Authentication/Ban Host Entries
There are two lines in authentication/ban host entries. The first is the authentication line.
Syntax
auth source-hostmask source-portrange auth-methods
Parameters
source-hostmask identifies which hosts the SOCKS server will authenticate.
source-portrange identifies which ports the SOCKS server will authenticate.
auth-methods are the methods to be used for authentication. You can list multiple authentication methods in order of your preference. In other words, if the client does not support the first authentication method listed, the second method will be used instead. If the client does not support any of the authentication methods listed, the SOCKS server will disconnect without accepting a request. If you have more than one authentication method listed, they should be separated by commas with no spaces in between. Possible authentication methods are:
The second line in the authentication/ban host entry is the ban host line.
Syntax
ban source-hostmask source-portrange
Parameters
source-hostmask identifies which hosts are banned from the SOCKS server.
source-portrange identifies from which ports the SOCKS server will not accept requests.
Example
auth 127.27.27.127 1024 u,-
ban 127.27.27.127 1024Routing Entries
Syntax
route dest-hostmask dest-portrange interface/address
Parameters
dest-hostmask indicates the hosts for which incoming and outgoing connections must go through the specified interface.
dest-portrange indicates the ports for which incoming and outgoing connections must go through the specified interface.
interface/address indicates the IP address or name of the interface through which incoming and outgoing connections must pass. IP addresses are preferred.
Example
route 127.27.27.127 1024 le0
Variables and Flags
Syntax
set variable value
Parameters
variable indicates the name of the variable to be initialized.
value is the value to set the variable to.
Example
set SOCKS5_BINDPORT 1080
Available Settings
The following settings are those that can be inserted into the variables and flags section of the socks5.conf file. These settings will be taken from the administration forms, but they can be added, changed, or removed manually as well.
SOCKS5_BINDPORT
The SOCKS5_BINDPORT setting sets the port at which the SOCKS server will listen. This setting cannot be changed during rehash.
Syntax
set SOCKS5_BINDPORT port-number
Parameters
port-number is the port at which the SOCKS server will listen.
Example
set SOCKS5_BINDPORT 1080
SOCKS5_PWDFILE
The SOCKS5_PWDFILE setting is used to look up user name/password pairs for user name/password authentication.
Syntax
set SOCKS5_PWDFILE full-pathname
Parameters
full-pathname is the location and name of the user name/password file.
Example
set SOCKS5_PWDFILE /etc/socks5.passwd
SOCKS5_LOGFILE
The SOCKS5_LOGFILE setting is used to determine where to write log entries.
Syntax
set SOCKS5_LOGFILE full-pathname
Parameters
full-pathname is the location and name of the SOCKS logfile.
Example
set SOCKS-5_LOGFILE /var/log/socks5.log
SOCKS5_NOIDENT
THe SOCKS5_NOIDENT setting disables Ident so that SOCKS does not try to determine the user name of clients. Most servers should use this setting unless they will be acting mostly as a SOCKS4 server. (SOCKS4 used ident as authentication.)
Syntax
set SOCKS5_NOIDENT
Parameters
None.
SOCSK5_DEMAND_IDENT
The SOCKS5_DEMAND_IDENT setting sets the Ident level to “require an ident response for every request”. Using Ident in this way will dramatically slow down your SOCKS server. If neither SOCKS5_NOIDENT or SOCKS5_DEMAND_IDENT is set, then the SOCKS server will make an Ident check for each request, but it will fulfill requests regardless of whether an Ident response is received.
Syntax
set SOCSK5_DEMAND_IDENT
Parameters
None.
SOCKS5_DEBUG
The SOCKS5_DEBUG setting causes the SOCKS server to log debug messages. You can specify the type of logging your SOCKS server will use.
If it’s not a debug build of the SOCKS server, only number 1 will work.
Syntax
set SOCSK5_DEBUG number
Parameters
number determines the number of the type of logging your server will use. Possible values are:
Example
set SOCKS5_DEBUG 2
SOCKS5_USER
The SOCKS5_USER setting sets the user name to use when authenticating to another SOCKS server. This is used when SOCKS server is routed through another down stream SOCKS server which requires authentication.
Syntax
set SOCKS5_USER user-name
Parameters
user-name is the user name the SOCKS server will use when authenticating to another SOCKS server.
Example
set SOCKS5_USER mozilla
SOCKS5_PASSWD
The SOCKS5_PASSWD setting sets the password to use when authenticating to another SOCKS server. It is possible for a SOCKS server to go through another SOCKS server on its way to the Internet. In this case, if you define SOCKS5_USER, sockd will advertise to other SOCKS servers that it can authenticate itself with a user name and password.
Syntax
set SOCKS5_PASSWD password
Parameters
password is the password the SOCKS server will use when authenticating to another SOCKS server.
Example
set SOCKS5_PASSWD m!2@
SOCKS5_NOREVERSEMAP
The SOCKS5_NOREVERSEMAP setting tells sockd not to use reverse DNS. Reverse DNS translates IP addresses into host names. Using this setting can increase the speed of the SOCKS server.
If you use domain masks in the configuration file, the SOCKS server will have to use reverse DNS, so this setting will have no effect.
Syntax
set SOCKS5_NOREVERSEMAP
Parameters
None.
SOCKS5_HONORBINDPORT
The SOCKS5_HONORBINDPORT setting allows the client to specify the port in a BIND request. If this setting is not specified, the SOCKS server ignores the client’s requested port and assigns a random port.
Syntax
set SOCKS5_HONORBINDPORT
Parameters
None.
SOCKS5_ALLOWBLANKETBIND
The SOCKS5_ALLOWBLANKETBIND setting allows the client to specify an IP address of all zeros (0.0.0.0) in a BIND request. If this setting is not specified, the client must specify the IP address that will be connecting to the bind port, and an IP of all zeros is interpreted to mean that any IP address can connect.
Syntax
set SOCKS5_ALLOWBLANKETBIND
Parameters
None.
SOCKS5_WORKERS
The SOCKS5_WORKERS setting tunes the performance of the SOCKS server by adjusting the number of worker threads. Worker threads perform authentication and access control for new SOCKS connections. If the SOCKS server is too slow, you should increase the number of worker threads. If it is unstable, decrease the number of worker threads.
The default number of worker threads is 40, and the typical number of worker threads falls between 10 and 150.
Syntax
set SOCKS5_WORKERS number
Parameters
number is the number of worker threads the SOCKS server will use.
Example
set SOCKS5_WORKERS 40
SOCKS5_ACCEPTS
The SOCKS5_ACCEPTS setting tunes the performance of the SOCKS server by adjusting the number of accept threads. Accept threads sit on the SOCKS port listening for new SOCKS requests. If the SOCKS server is dropping connections, you should increase the number of accept threads. If it is unstable, decrease the number of accept threads.
The default number of accept threads is 1, and the typical number of accept threads falls between 1 and 10.
Syntax
set SOCKS5_ACCEPTS number
Parameters
number is the number of accepts threads the SOCKS server will use.
Example
set SOCKS5_ACCEPTS 1
LDAP_URL
The LDAP-URL setting sets the URL for the LDAP server.
Syntax
set LDAP-URL URL
Parameters
URL is the URL for the LDAP server used by SOCKS.
Example
set LDAP-URL ldap://name:8180/0=Netscape,c=US
LDAP_USER
The LDAP-USER setting sets the user name that the SOCKS server will use when accessing the LDAP server.
Syntax
set LDAP-USER user-name
Parameters
user-name is the user name SOCKS will use when accessing the LDAP server.
Example
set LDAP-USER uid=admin
LDAP_PASSWD
The LDAP-PASSWD setting sets the password that the SOCKS server will use when accessing the LDAP server.
Syntax
set LDAP-PASSWD password
Parameters
password is the password SOCKS will use when accessing the LDAP server.
Example
set LDAP-PASSWD T$09
SOCKS5_TIMEOUT
The SOCKS5-TIMEOUT setting specifies the idle period that the SOCKS server will keep a connection alive between a client and a remote server before dropping the connection.
Syntax
set SOCKS5_TIMEOUT time
Parameters
time is the time, in minutes, SOCKS will wait before timing out. The default value is 10. The value can range from 10 to 60, including both these values.
Example
set SOCKS5_TIMEOUT 30
Proxy Entries
Syntax
proxy-type dest-hostmask dest-portrange proxy-list
Parameters
proxy-type indicates the type of proxy server. This value can be:
dest-hostmask indicates the hosts for which the proxy entry applies.
dest-portrange indicates the ports for which the proxy entry applies.
proxy-list contains the names of the proxy servers to use.
Example
socks5 127.27.27.127 1080 proxy1
Access Control Entries
Syntax
permit|deny auth-type connection-type source-hostmask dest-hostmask source-portrange dest-portrange [LDAP-group]
Parameters
auth-type indicates the authentication method for which this access control line applies.
connection-type indicates the type of command the line matches. Possible command types are:
source-hostmask - indicates the hosts for which the access control entry applies.
dest-hostmask indicates the hosts for which the access control entry applies.
source-portrange indicates the ports for which the access control entry applies.
dest-portrange is the port number of the destination.
LDAP-group is the group to deny or permit access to. This value is optional. If no LDAP group is identified, the access control entry applies to everyone.
Example
permit u c - - - [0-1023] group1
Specifying Ports
You will need to specify ports for many entries in your socks5.conf file. Ports can be identified by a name, number, or range. Ranges that are inclusive should be surrounded by brackets (i.e. [ ]). Ranges that are not inclusive should be in parentheses.
parray.patThe parray.pat (PAT) file describes each member in the proxy array of which the proxy you are administering is a member. The PAT file is an ASCII file used in proxy to proxy routing. It contains proxy array members’ machine names, IP addresses, ports, load factors, cache sizes, etc.
Syntax
Proxy Array Information/1.0
ArrayEnabled: number
ConfigID: ID number
ArrayName: name
ListTTL: minutes
name IPaddress proxyport URLforPAT infostring state time status loadfactor cachesizeParameters
Proxy Array Information is version information.
ArrayEnabled specifies whether the proxy array is enabled or disabled. Possible values are:
ConfigID is the identification number for the current version of the PAT file. The proxy server uses this number to determine whether the PAT file has changed.
ArrayName is the name of the proxy array.
ListTTL specifies how often the proxy should check the PAT file to see if it has changed. This value is specified in minutes.
name is the name of a specific member of the proxy array.
IPaddress is the IP address of the member.
proxyport is the port at which the master proxy accepts HTTP requests.
URLforPAT is the URL of the PAT file that the member will poll the master proxy for.
infostring is version information.
statetime is the amount of time the member has been in its current state.
status specifies whether the member is enabled or disabled.
loadfactor is an integer that reflects the number of requests that should be routed through the member.
cachesize is the size of the member’s cache.
Example
Proxy Array Information/1.0
ArrayEnabled: 1
ConfigID: 1
ArrayName: parray
ListTTL: 10
proxy1 200.29.186.77 8080 http://pat SunJavaSystemWebProxy/4 0 on 100 512
proxy2 187.21.165.22 8080 http://pat SunJavaSystemWebProxy/4 0 on 100 512
parent.patThe parent.pat file is the Proxy Array Table file that contains information about an upstream proxy array. This file has the same syntax as the parray.pat file.