SOCKD.CONF(5)							File Formats Manual						     SOCKD.CONF(5)

NAME

       sockd.conf - SOCKS server configuration file

SYNOPSIS

       /etc/sockd.conf

DESCRIPTION

       The  file /etc/sockd.conf is used to control access to SOCKS proxy server sockd and its services. (See sockd(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  (destina-
       tion port number), as well as the requesting user.  A line in /etc/sockd.conf can be up to 1023 characters long.  Each line may contain the
       following fields in the indicated order:

	action [?=use_identd] [*=userlist] src_addr src_mask [dst_addr dst_mask] [op dst_port] [ : shell_cmd ]

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

       The action field must be either permit or deny and indicates the action to be taken if a request matches the conditions specified  in  that
       line.

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

       The  userlist 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 /. 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 # marks the remainder of the line as comment.  Each  line  in  the
       files may be up to 1023 characters long.  If the *=userlist field is omitted, the line applies to all user-ids.

       The src_addr and dst_addr fields either specify IP addresses of hosts, networks, or subnets in the usual dotted form, e.g., 129.201.4.0, or
       a domain name, e.g., internic.net.  The src_mask and dst_mask 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  speci-
       fied.   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 cor-
       responding address fields. If the domain name starts with a period, it specifies a zone and matches all domain names within that zone, oth-
       erwise it matches only the domain name itself. For example, xyz.com matches only xyz.com, while .xyz.com matches not only xyz.com, but also
       abc.xyz.com and this.and.that.xyz.com, among others. The special symbol ALL (which must	be  entirely  in  uppercase)  matches  everything.
       Domain names are otherwise case-insensitive.

       If the dst_addr dst_mask pair is omitted, the line applies to all destination hosts.

       The  op	field  must be eq, neq, lt, gt, le, or ge, for the condition of equal, not equal, less than, greater than, less than or equal, and
       greater than or equal, respectively.  The dst_port field can be either a port number, e.g., 23, or the equivalent service name as specified
       in  the	file /etc/services, e.g., telnet for port number 23. If this pair is omitted, the line applies to all services, i.e., all destina-
       tion port numbers.

       For example, consider the line

	permit *=root,clivep 128.103.4.10 255.255.255.255 179.200.20.0 255.255.255.0 le 1023

       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 action field is permit, such  requests
       will be granted.

       When  a	request  is  received by sockd, it checks against the lines in file /etc/sockd.conf, 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 action field of that line.  The  remaining
       lines of file /etc/sockd.conf 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 /etc/sockd.conf.  The following two lines in the indicated order

	deny *=abxyz   128.140.13.24  0.0.0.0
	permit	       128.140.13.24  0.0.0.0

       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 shell_cmd 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:

	%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 sockd is asked to execute
	%p -- replaced by the process id of sockd
	%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 identd
	%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 %

       Several shell commands can be strung together in the usual way. For example,

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

       will  finger the client host and pipe the result into an email message for superusers at the server host and the client host with an appro-
       priate Subject line. Most often this feature is used with a deny line, but it can be used with permit 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),

	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

       You  may also specify in /etc/sockd.conf commands to be executed when sockd cannot connect to client's identd or when the user-ids reported
       by the client programs and the client's identd do not match.  These special entries must have #NO_IDENTD: and #BAD_ID: at the  very  begin-
       ning of the line, followed by the shell commands to be executed. For example:

	#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

       Strictly  speaking, sockd 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 sockd.conf. For example, if the Class B IP network 129.1 is your internal network, use

	deny 0.0.0.0  0.0.0.0	 129.1.0.0  255.255.0.0

       as the first line of your sockd.conf 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 conve-
       nient to use domain name instead, for instance,

	deny	0.0.0.0  0.0.0.0	.myowm.com  0.0.0.0

       or

	deny	ALL  0.0.0.0	    .myown.com	0.0.0.0

       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 configu-
       ration 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 conse-
       quence that it will not match any line in the configuration file which specifies a domain  name	(other	than  ALL)  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 A record and the PTR 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 prob-
       ably 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 /etc/sockd.fc instead of /etc/sockd.conf. The frozen file is produced by
       make_sockdfc 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 con-
       figuration is found. All modifications to the configuration must  be  done  on  the  plain-text,  unfrozen  file.  Be  sure  that  you  run
       make_sockdfc every time after you modify /etc/sockd.conf or your SOCKS server would be using the frozen version of an older configuration.

SEE ALSO

       dump_sockdfc(8), make_sockdfc(8), sockd(8), socks.conf(5), sockd.fc(5),

								    May 6, 1996 						     SOCKD.CONF(5)