.TH SOCKD.CONF 5 "May 6, 1996"
.SH NAME
sockd.conf \- SOCKS server configuration file
.SH SYNOPSIS
\fB/etc/sockd.conf\fP
.SH DESCRIPTION
The file \fB/etc/sockd.conf\fP is used to control access
to SOCKS proxy server \fIsockd\fR and its services. (See \fIsockd\fP(8).)
Permission and denial of a service
request can be decided based on various combinations of the requesting
host, the destination host, the type of service (destination port number),
as well as the requesting user.  A line in \fB/etc/sockd.conf\fP can be
up to 1023 characters long.  Each line may contain the following fields
in the indicated order:

.in +1
\fIaction [\fB?=\fIuse_identd] [\fB*=\fIuserlist] src_addr src_mask [dst_addr dst_mask] [op dst_port] [ : shell_cmd ]\fR

.in -1
Spaces and tabs separate the fields. Fields enclosed in square brackets
are optional. Blank
lines are allowed. Except for lines that start with \fB#NO_IDENTD:\fP or
\fB#BAD_ID:\fP, everything from the first appearance of \fB#\fP to
the end of the line is considered comment and thus ignored by \fIsockd\fP
during normal validation.

The \fIaction\fR field
must be either \fBpermit\fP or \fBdeny\fP
and indicates the action to be taken if a request matches the conditions
specified in that line. 

The \fIuse_identd\fR field, when present, must be \fBI\fP, \fBi\fP, or
\fBn\fP, and is used to specify whether \fIidentd\fR verification should be
employed for the current line. \fB?=I\fP demands the use of
\fIidentd\fR for verifying the user's identity, denying access if connection 
to client's \fIidentd\fR fails or if the result does not match the user-id
reported by the client program. \fB?=i\fP also specifies the use of
\fIidentd\fR, but denies access only if client's \fIidentd\fR reports a user-id
different from what the client program claims. \fB?=n\fP turns off the
use of \fIidentd\fP. For the line in which these fields are used, they
override the global \fIidentd\fR setting, which is determined by options
\fB-I\fP and \fB-i\fP on the \fIsockd\fR command line.

The \fIuserlist\fR field, when present, consists of
one or more user-ids or filenames, with comma as separator. No spaces
or tabs are allowed in the list. The user-ids should be ids of users on the
requesting host, not those on the destination host or the SOCKS server host.
The filenames must be full pathnames with the leading \fB/\fP. Inside
the specified files, user-ids may be listed one or several per line,
with any combination of blanks, tabs, and commas as separators. The
appearance of \fB#\fP marks the remainder of the line as comment. Each
line in the files may be up to 1023 characters long.
If the \fB*=\fIuserlist\fR field is omitted, the line applies to all user-ids.

The \fIsrc_addr\fR and \fIdst_addr\fR fields either specify IP addresses
of hosts, networks, or subnets in the usual dotted form, e.g.,
\fB129.201.4.0\fP, or a domain name, e.g., \fBinternic.net\fP.
The \fIsrc_mask\fR and \fIdst_mask\fR fields
are masks for the corresponding IP addresses. 
Bits in these masks that are set to 0 indicate the bit positions
to be ignored during comparisons of IP addresses.
So, specifying 255.255.255.255 in the mask demands an exact match with the
specified IP address field, whereas 0.0.0.0 in the mask
causes a match no matter what IP address is specified.
The contents of the
mask fields are ignore, though they must still be supplied (use 0.0.0.0),
if domain names are used for the corresponding address fields. If the domain
name starts with a period, it specifies a zone and matches all domain names
within that zone, otherwise it matches only the domain name itself. For
example, \fBxyz.com\fP matches only xyz.com, while
\fB.xyz.com\fP matches not only xyz.com, but also abc.xyz.com and
this.and.that.xyz.com, among others. The special symbol \fBALL\fP
(which must be entirely in uppercase) matches everything. Domain names
are otherwise case-insensitive.

If the
\fIdst_addr dst_mask\fP pair is omitted, the line applies to all
destination hosts.

The \fIop\fR field must be
\fBeq\fP, \fBneq\fP, \fBlt\fP, \fBgt\fP, \fBle\fP, or \fBge\fP,
for the condition of equal, not equal, less than, greater than,
less than or equal, and greater than or equal, respectively.
The \fIdst_port\fR field can be either a port number, e.g., 23,
or the equivalent service name as specified in the file /etc/services,
e.g., \fBtelnet\fP for port number 23. If this pair is omitted, the
line applies to all services, i.e., all destination port numbers.

For example, consider the line

.in +1
permit *=root,clivep 128.103.4.10 255.255.255.255 179.200.20.0 255.255.255.0 le 1023

.in -1
To match the conditions indicated in this line, a request must come
from a user named 'root' or 'clivep' on the host whose IP address is
128.103.4.10 exactly, the destination host must have 179.200.20 in the
first three bytes of its IP address (the last byte
doesn't matter), and the service must use a port number
less than or equal to 1023 on the destination host. Since the \fIaction\fR
field is \fBpermit\fP, such requests will be granted.

When a request is received by \fIsockd\fR, it checks against the lines
in file \fB/etc/sockd.conf\fP, one line at a time. Once it finds a line
with conditions that are matched by the request, the request is either
granted or denied based on the \fIaction\fR field of that line. The
remaining lines of file \fB/etc/sockd.conf\fP are skipped. If no matching
line is found in the entire file, the request is denied.

Be very careful how you order the lines in file \fB/etc/sockd.conf\fP.
The following two lines in the indicated order

.nf
.in +1
deny	*=abxyz	128.140.13.24  0.0.0.0
permit		128.140.13.24  0.0.0.0

.fi
.in -1
disallow all requests by user 'abxyz' from host 128.140.13.24, but
allow all requests by other users from the same host. Switch the order
of the two lines and even requests by user 'abxyz' are granted.

The \fIshell_cmd\fR field specifies a command string that is executed
when the conditions on that line are satisfied. The following substitutions
occur before the string is presented to the Borne shell for execution:
.nf
.in +1

%A -- replaced by the client host's domainname if known, by its IP address otherwise
%a -- replaced by the client host's IP address
%c -- replaced by "connect" or "bind", the command \fIsockd\fP is asked to execute
%p -- replaced by the process id of \fIsockd\fP
%S -- replaced by the service name (e.g., ftp) if known, by the destination port number otherwise
%s -- replaced by the destination port number
%U -- replaced by the user-id reported by \fIidentd\fP
%u -- replaced by the user-id reported by the client program
%Z -- replaced by the destination host's domainname if known, by its IP address otherwise
%z -- replaced by the destination host's IP address
%% -- replaced by a single %

.fi
.in -1
Several shell commands can be strung together in the usual way. For example,
.nf

.in +1
/usr/ucb/finger @%A | /usr/ucb/mail -s 'SOCKS: rejected %u@%A to %Z (%S)' root root@%A

.in -1
.fi
will \fIfinger\fP the client host and pipe the result into an email message
for superusers at the server host and the client host with an appropriate
Subject line. Most often this feature is used with a \fBdeny\fP line, but
it can be used with \fBpermit\fP also.

Although there is an implied 'deny all' at the end of the configuration file,
you may supply one explicitly so as to take some specific action when requests
are so rejected, e.g., (in one continuous line),
.nf
.in +1

deny 0.0.0.0 0.0.0.0 : /usr/ucb/finger @%A |
 /usr/ucb/mail -s 'SOCKS: rejected %u@%A to %Z (%S)' root root@%A

.fi
.in -1
You may also specify in \fB/etc/sockd.conf\fP commands to be executed when
\fIsockd\fP cannot connect to client's \fIidentd\fP or when the user-ids
reported by the client programs and the client's \fIidentd\fP do not match.
These special entries must have \fB#NO_IDENTD:\fP and \fB#BAD_ID:\fP at the very
beginning of the line, followed by the shell commands to be executed. For
example:
.nf
.in +1

#NO_IDENTD: /usr/ucb/mail -s 'Please run identd on host %A' root@%A
#BAD_ID: finger @%A | /usr/ucb/mail -s '%U pretends to be %u on %A' root root@%A

.fi
.in -1
Strictly speaking, \fIsockd\fP has no concept of inside/outside, it
does know which is the requesting host and which the destination
and that is the basis of its access control. Therefore it can be used
to facilitate
access from outside world into your internal networks as well. Needless to
say, you have to take extreme caution if you choose to do so. If you
don't need that kind of access, it is recommended that you specifically
deny such connections in \fBsockd.conf\fR. For example, if the Class B
IP network 129.1 is your internal network, use

.nf
.in +1
deny	0.0.0.0  0.0.0.0	129.1.0.0  255.255.0.0
.fi
.in -1

as the first line of your \fBsockd.conf\fP to protect your inside hosts
from all attempts of access from the outside world through SOCKS.
If your internal network consists of several IP networks, you have to use
one such line for each of them. In that case, it may be more
convenient to use domain name instead, for instance,

.nf
.in +1
deny    0.0.0.0  0.0.0.0        .myowm.com  0.0.0.0
.fi
.in -1

or

.nf
.in +1
deny    ALL  0.0.0.0        .myown.com  0.0.0.0
.fi
.in -1

may be used, assuming that myown.com is your domain.

Though the use of domain names can be very convenient and can also
reduce start-up overhead by reducing the number of lines in the configuration
file, you should be very careful with your DNS (Domain Name System) setup.
Here are some details that you should know.

The original information the SOCKS server has of the source or the destination
host is in the form of its IP address. The SOCKS server does a reverse DNS 
lookup to find the domain name correspodning to that IP address. It then
does a normal DNS loopkup to translate the domain name back to an IP address.
If the two IP addresses match, the SOCKS server retains both the domain
name and the IP address as identifier of the host, and will use whichever as
appropriate when it checkes the configuration file.
If either of the two DNS lookups fails or if the two IP addresses do not
match, SOCKS server retains only the original IP address as the only
identifier of the host, with the consequence that it will not match any
line in the configuration file which specifies a domain name (other than 
\fBALL\fP) in the corresponding address field.

Suppose now you add a new host to your internal network before updating your
nameserver's data with both the \fBA\fP record and the \fBPTR\fP record of
the new host. 
When the SOCKS server receives a request with the IP address of the new
host as its destination, at least one of the DNS lookups will fail.
Consequently it will not be protected by lines in which the domain name
is used in the destination address field.

So, if you want to use domain name in the configuration file, be very
sure that you always keep your DNS information up-to-date. It's
probably a good idea to update your DNS data before adding a new host
to your network. Also make sure that your SOCKS server always queries
a nameserver which has the most up-to-date information of your internal
network.

You have the option of using the frozen configuration file \fB/etc/sockd.fc\fP
instead of \fB/etc/sockd.conf\fP. The frozen file is produced by
\fImake_sockdfc\fR and is essentially the memeory image of the parsed
configuration file. Using it can reduce the start-up delay of the SOCKS server
since it eliminates the need for parsing.

When the SOCKS server starts, it always looks for the frozen configuration
first and reverts to the unfrozen version only if no frozen configuration
is found. All modifications to the configuration must be done on
the plain-text, unfrozen file. Be sure that you run \fImake_sockdfc\fR
every time after you modify /etc/sockd.conf or your SOCKS server would be
using the frozen version of an older configuration.
.SH SEE ALSO
\fIdump_sockdfc\fP(8), \fImake_sockdfc\fP(8),
\fIsockd\fP(8),
\fIsocks.conf\fP(5), \fIsockd.fc\fP(5),