# Sockd configuration file

    daemon {
        negotiate-file      "filename";
      [ directory           "dirname"; ]
      [ umask               number; ]
      [ listen-address     { ifaddr; ...}; ]
      [ service             "name"; ]
      [ port                number; ]
      [ name                "name"; ]
      [ inetdsec-file       "filename"; | none; ]
      [ pre-fork            number; ]
      [ dns-helper          number; ]
      [ listen              { min, max }; ]
      [ client              { min, max }; ]
      [ user                [ "user name" | number ]; ]
      [ group               [ "group name" | number ]; ]
      [ poll                time spec; ]
      [ flags               { [ v4-only; | no-keepalive; ] }; ]
    };

The daemon directive specifies global information about the daemon. The various options mean:

negotiate-file | Name of the negotiation file. This file is used by the various listeners to determine who listens.
directory | Set working directory for sockd. Default is /var/opt/socks
umask | Set umask for sockd. Default is 0o002.
listen-address | Interface address(es) to listen on. Default is every configured (UP) interface, and INADDR_ANY (to catch any late additions).
service | Service name used in searching inetdsec-file. Default is the service corresponding to port. If neither service nor port is specified, the service and port socks are used.
port | Port number to listen on. Default is the port corresponding to service.
name | Name used in syslog calls.
inetdsec-file | Full path to inetd.sec. Default is none.
pre-fork | Number of listening demons to initially start.
dns-helper | Number of dns helper porocesses. Only applies to non-threaded platforms.
listen | Minimum and maximum listening daemons.
client | Minimum number of clients before a daemon stops listening, and maximum number of clients for a daemon. (It forks when it gets to the maximum.)
user | User name for daemons. If a name is used and group is not specified, then the primary group for user is used.
group | Group name for daemons.
poll | Maximum time before a daemon checks to see if it should (or should not) be listening.
flags | Any flags for daemon. v4-only disables all socks v5 functionality. (XXX -This will not be in the production version.) no-keepalive disables TCP keepalives for TCP connections (which are on by default.

The logic for a daemon to decide if it should listen is:
if (number of clients < client.min) listen
else if (number of clients == client.max) unlisten
else if (at least listen.min daemons have less clients and I'm not the only listener) unlisten()

When a daemon gets client.max clients, it forks. If there are then listen.max potential listeners, the child process will never listen.

    [ logging {
        [ facility          "syslog facility"; ]
        [ level             number; ]
        [ usage-log         "filename"; ]
        [ dump-prefix       "path"; ]
        [ debug             number; ]
    }; ]

The logging section has the following directives:

facility | One of the names from syslog.conf, such as local0.
level | logging level. Currently, 2 or higher gives you a usage log, under two gives you nothing.
usage-log | file name of usage log. If not specified, level is forced to 0.
dump-prefix | Prefix used for dumping configuration and clients in response to appropriate signals. The actual file name has 'conf' or 'client' and the daemon pid appended to it.

    [ default {
        [ timeout           time spec; ]
        [ setup-timeout     time spec; ]
        [ bufsize           number; ]
    }; ]

Defaults can be overridden for specific clients. The defaults are: timeout 2h; setup-timeout 15m; bufsize 32768;

    [ env {
        NAME=value;  ...
    }; ]

Specify global environment variables. These are accessed from method specific routines using getEnv(). If value contains spaces or semicolons, it must be enclosed in quotes. The ping and traceroute commands rely on the environment variables PING and TRACEROUTE (respectively), in order to work. If not defined, then the client is told that the command is not supported. Suggested values are:

    PING="/usr/sbin/ping %z";
    TRACEROUTE="/usr/sbin/traceroute %z";

Which use the destination IP address as the only argument to the command.

    route {
        { IP4/IP4 ifaddr }; |
        { IP4/number ifaddr }; |
        { default ifaddr };
        ...
    };

Routes must be specified. If the requested destination address lives on a particular route, as specified by the address/mask, then ifaddr is used in the bind call. mask can either be a CIDR mask length, or a traditional netmask. default is equivalent to 0.0.0.0/0.

    method-list {
        { name "method"; number number; library "file name"; [ env { NAME=value; ... }; ] }; |
        { name "method"; number number; internal; [env { NAME=value; ... }; ] };
        ...
    };

The method list defines all of the methods available to the clients. internal indicates that the method is built in (in the method list in method.c), otherwise the library name must be specified. Socks V4 support requires that the "v4" method be defined. Method numbers 0-127 are IANA assigned, 128-254 are reserved for private methods. (255 is not a legal method number.) Method specific environment variables can be specified, and are found
before the global environment variables.

    client-method {
        { src { hostlist }; method { "method"; ... }; };
        ...
    };

For socks clients in hostlist, the client specified method list is compared against methods, and the first match is taken. If no match is found, the request is denied.

    client {
        permit|deny|skip request {
              src  { hostlist };
            [ user { "user"; ... }; ]
            [ dest { hostlist };    ]
            [ port { portlist };    ]
            [ cmd "command string"; ]
            [ timeout time spec;    ]
            [ bufsize number;       ]
        };
        ...
    };

The first rule which matches the client request is used. permit grants the client's request, deny denies the request, and skip causes rule parsing to skip the next rule and continue (after possibly assigning new buffer size and timeout, as well as command execution - as specified by this rule.) Each of the specified components must match. request is one of connect, bind, udp-associate, ping, or traceroute. src and user refer to the requesting host and user, dest and port refer to the requested destination. cmd specifies a command to be executed when the rule is matched. timeout and bufsize override the global defaults when the rule is matched.

    ifaddr:
        "ifname"; | hostaddr;

Interface names take precidence over hostnames, and use the IP address bound to that interface (at the time the config file is read.)

    hostlist: (one or more of the following:)
        IP4/IP4; | IP4/number; | IP4; | default; | "name";
        ...

If multiple hosts (or host ranges) are specified, they are 'or' clauses.

    hostaddr:
        IP4; | host; | "hostname";

In order to use host or a name, there must be only one IP address for the name given. host uses the result of gethostname() as the name of the host.

    portlist:
        port; | port-port;
        ...

One or more ports.

    port:
        number; | "name";
        ...

    time spec:
        number[wdhms]...;

Time can be specified either as a number (of seconds), or as a collection of numbers and multipliers. For example, 1d2h specifies 1 day, 2 hours.

    number:
        decimal_number | 0xhex_number |  0ooctal_number

Numbers can be specified in decimal, hex, or octal.

    command string:

When a ruleset is matched, a command can be executed. This is done by forking and executing the command in the child process. The following escapes are available in command strings:

%A | Name of source host
%a | IP address of source host
%c | Request type (command).
%p | Process id of sockd
%S | destination service name
%s | destination port number
%u | user name
%Z | Destination host name
%z | destination host address