.\" $Id: sockd.conf.5,v 1.108.2.5 2010/05/24 16:38:13 karls Exp $ .\" .\" Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, .\" 2008, 2009, 2010 .\" Inferno Nettverk A/S, Norway. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. The above copyright notice, this list of conditions and the following .\" disclaimer must appear in all copies of the software, derivative works .\" or modified versions, and any portions thereof, aswell as in all .\" supporting documentation. .\" 2. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by .\" Inferno Nettverk A/S, Norway. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Inferno Nettverk A/S requests users of this software to return to .\" .\" Software Distribution Coordinator or sdc@inet.no .\" Inferno Nettverk A/S .\" Oslo Research Park .\" Gaustadalléen 21 .\" NO-0349 Oslo .\" Norway .\" .\" any improvements or extensions that they make and grant Inferno Nettverk A/S .\" the rights to redistribute these changes. .\" .TH SOCKD.CONF 5 "January, 2009" .SH NAME sockd.conf \- \fBDante\fP server configuration file syntax .SH DESCRIPTION The configuration file for the \fBDante\fP server controls both access controls and logging. It is divided into three parts; server settings, rules, and routes. A line can be commented using the standard comment character \fB#\fP. .SH SERVER SETTINGS The server settings control the generic behaviour of the server. Each keyword is separated from it's value by a \fB':'\fP character. .IP \fBchild.maxidle\fP Maintains a rough max on how many children of each type can remain idle, waiting for clients. This is used to reduce the amount of idle processes after a "client burst" has passed. The default is \fBno\fP (no maximum), which is the recommended value for high load environments, but it can be set to "yes" if it is desirable to limit the process count, though note that setting it to "yes" may decrease performance. .\" .IP \fBchild.maxrequests\fP .\" Maintains a max on the total number of clients a child process will .\" serve before exiting. After having served the given number of .\" clients, the child process will exit. .\" .\" The only reason for the existence of this option is to work around buggy .\" behaviour in external libraries used by the the \fBDante\fP server, .\" which may end up leaking resources or create other problems when having .\" run to long. The default value is \fB0\fP, meaning no limit. .\" .IP \fBclientmethod\fP A list of acceptable authentication methods for client-rules, in order of preference. These are the authentication methods that can be checked before the socks-negotiation has completed. Supported values are \fBnone\fP, \fBgssapi\fP, \fBrfc931\fP and \fBpam\fP. For all methods except \fBgssapi\fP, that means the authentication will be based on solely on the IP-address of the client, possibly in combination with a \fBrfc931\fP ("ident") lookup. This list is used as the default for all coming rules until changed. Then the changed list is used as the default for the next rules. The default value is all methods that may be necessary for the later socks-based authentication, as specified in the socks-method line. Normally you should not need to set this variable. Any credentials provided during this pass will also be available for use in later socks-rules, when the socks-request from the client is evaluated. .IP \fBcompatibility\fP With the \fBsameport\fP keyword, the server attempts to use the same port on the server and the client. This functionality is the default, but when this option is given it will also be done with privileged ports. The \fBreuseaddr\fP keyword might solve problems when the bind extension is used but the effects of enabling \fBreuseaddr\fP is currently unknown, do not enable it unless you understand the effects. The \fBdraft-5.05\fP keyword will enable usage of parts of the socks v5-05 draft. The only feature from this draft that \fBDante\fP supports is the "USECLIENTSPORT" extension. Note that there is a conflicting interpretation of this extension, so enabling it might prevent clients using the conflicting interpretation from working correctly. This only affects udp. .IP \fBtimeout.negotiate\fP The number of seconds a client can spend negotiating with the \fBDante\fP server for a socks session before \fBDante\fP will close the connection to the client. The default is 30. Set it to 0 for forever, though that is strongly discouraged. .IP \fBtimeout.io\fP The number of seconds an established connection can be idle. The default is 86400 (24 hours). Set it to 0 for forever. See also the "-n" option in the sockd(8) manpage. Individual timeouts can be set for tcp and udp by suffixing io with ".", i.e. \fBtimeout.io.tcp\fP or \fBtimeout.io.udp\fP .IP \fBdebug\fP Print debug info to the logs. The value sets the debug level. .IP \fBexternal\fP The address to be used for outgoing connections. The address given may be either a IP address or an interface name. Can be given multiple times for different addresses. .IP \fBexternal.rotation\fP If more than one external address is given, this governs which address is selected. Valid values are \fBnone\fP (the default) and \fBroute\fP. The latter might require you to set \fBuser.privileged\fP to \fBroot\fP, and will try to determine what local address would normaly be selected by the kernel for connecting to the given destination. If that address is listed amongst the external addresses, the \fBDante\fP server will connect out from that address. Note that \fBroute\fP might create problems for ftp-clients using active ftp if the \fBDante\fP bind extension is enabled for the ftp-client. .IP \fBinternal\fP The internal addresses. Connections will only be accepted on these addresses. The address given may be either a IP address or an interface name. .IP \fBlogoutput\fP This value controls where the server sends logoutput. It can be either \fBsyslog\fP[/\fBfacility\fP], \fBstdout\fP, \fBstderr\fP, a filename, or a combination. The default is nowhere. .IP \fBmethod\fP Also known as the socks-method line. A list of acceptable authentication methods for socks-rules, in order of preference. Supported values are \fBusername\fP, \fBnone\fP, \fBrfc931\fP and \fBpam\fP. This list is used as the default for all coming rules until changed. Then the changed list is used as the default for the next rules. The default is no methods, which means all socks-requests will be blocked. If a method is not set in this list it will never be selected. See the section on methods for a explanation of the different methods and their meaning. .IP \fBsrchost\fP With the \fBnomismatch\fP keyword, the server will not accept connects from addresses having a mismatch between DNS address and hostname. Default is to accept them. With the \fBnounknown\fP keyword, the server will not accept connects from addresses without a DNS record. Default is to accept them. With the \fBcheckreplyauth\fP keyword, the server will check that the authentication on bind-replies and udp-replies matches that which is set in the rule and global method. Normally, authentication is not desired on these replies, as they are replies sent to the socks-clients, from non-socks clients, and thus only a limited set of authentication methods are possible. These methods are the methods not involving the socks protocol; \fBrfc931\fP and \fBpam\fP (using only the ipaddress and portnumber). Default is not to check the authentication on replies. .IP \fBudp.connectdst\fP Enables or disables whether the server should attempt connecting udp sockets to the destination. Valid values are \fByes\fP and \fBno\fP. The default is \fByes\fP, which improves udp performance, but may not be compatible with some udp-based application protocols as it means the server can only receive packets from the destination address. .IP \fBUserids\fP On platforms providing a privilege-model supported by \fBDante\fP, the \fBDante\fP server does not use userid-switching via the seteuid(2) system call. On other platforms, it is prudent to set the userid to be used by the \fBDante\fP server to appropriate values. The \fBDante\fP server can use two different userids, three if compiled with libwrap support. They are as follows: .IP \fBuser.privileged\fP Username which will be used for doing privileged operations. If you need special privileges to read the sockd.conf file or to write the sockd.pid file (you can create it manually before starting sockd), have anything in your configuration that requires binding privileged tcp/udp ports (ports below 1024), or use some sort of password-based authentication, this probably needs to be set to root. If not, you can probably set it to the same value as \fBuser.unprivileged\fP. .IP \fBuser.unprivileged\fP User which the server runs as most of the time. This should be an id with as little privileges as possible. .IP \fBuser.libwrap\fP User used to execute libwrap commands. Normally this should be the same as \fBuser.unprivileged\fP .SH MODULES The following modules are supported by \fBDante\fP. Modules are purchased separately from Inferno Nettverk A/S. See the \fBDante\fP homepage for more information. .IP \fBbandwidth\fP The \fBbandwidth\fP module gives you control over how much bandwidth the Dante server uses on behalf of different clients. .IP \fBredirect\fP The \fBredirect\fP module gives you control over what addresses the server will use on behalf of the client, aswell as allowing you to redirect client requests to a different addresses. .IP \fBsession\fP The \fBsession\fP module gives you control over the number of sessions that can be created by different socks users. .SH AUTHENTICATION METHODS The \fBDante\fP server supports the following authentication methods. Some installations of \fBDante\fP may support only a subset of these. .IP \fBnone\fP This method requires no form of authentication. .IP \fBusername\fP This method requires the client to provide a username and password. This must match the username and password given in the system passwordfile. .IP \fBgssapi\fP This method requires the setup of a Kerberos environment and can provide strong encryption and authentication. .IP \fBrfc931\fP This method requires the client host to provide a rfc931 ("ident") reply for the connecting client. This must match a username given in the system passwordfile. .IP \fBpam\fP This method requires the available clientdata to match against the pam database. .SH ADDRESSES Each address field can consist of a IP address (and where meaningful, a netmask, separated from the IP address by a '\fB/\fP' sign.), a hostname, a domainname (designated so by the leading '\fB.\fP'), or an interface name. Each address can be followed by a optional \fBport\fP specifier. .SH RULES There are two sets of rules and they work at different levels. Rules prefixed with \fBclient\fP are checked first and are used to see if the client is allowed to connect to the \fBDante\fP server. We will call them "client-rules". It is recommended that these do not use hostnames but only IP addresses, both for security and performance reasons. These rules work at the TCP level. The other rules, which we will call "socks-rules" are a level higher and are checked after the client connection has been accepted by the client-rules. The socks-rules are used to evaluate the socks request that the client sends. Both set of rules start with a \fBpass\fP/\fBdeny\fP keyword (the client-rules have "client" prefixed to the \fBpass\fP/\fBdeny\fP keyword) which determines if connections matching the rule are to pass or be blocked. Both set of rules also specify a \fBfrom\fP/\fBto\fP address pair which gives the addresses the rule will match. In both contexts, \fBfrom\fP means the clients address. In the client-rule context, \fBto\fP means the address the request is accepted on, i.e. the address the \fBDante\fP server listens on. In the socks-rule context, \fBto\fP means the client's destination address, as formulated in the client's proxy request. Both set of rules are evaluated on a "first match is best match" basis. That means, the first rule matched for a particular client or socks request is the rule that will be used. In addition to the addresses there is a set of optional keywords which can be given. There are two forms of keywords, conditions and actions. For each rule, all conditions are checked and if they match the request, the actions are executed. The list of condition keywords is: \fBclientcompatibility\fP, \fBcommand\fP, \fBfrom\fP, \fBmethod\fP, \fBprotocol\fP, \fBproxyprotocol\fP, \fBto\fP, \fBuser\fP. The list of actions keywords is: \fBbandwidth\fP, \fBlibwrap\fP, \fBlog\fP, \fBmaxsessions\fP, \fBredirect\fP, and \fBudp.portrange\fP. The format and content of the rules is identical, but client-rules may contain only a subset of the socks-rules. More concrete, they may not contain any keywords related to the socks protocol. .IP The contents of a \fBclient-rule\fP is: .IP \fBbandwidth\fP The clients matching this rule will all share the given amount of bandwidth, measured in bytes per second. Requires the bandwidth module. .IP \fBclientcompatibility\fP Enables certain options for compatibility with broken clients. Valid values are: \fBnecgssapi\fP, for compatibility with clients implementing GSSAPI the NEC socks way. .IP \fBfrom\fP The rule applies to requests coming from the address given as value. .IP \fBgroup\fP The user must belong to one of the groups given as value. Note that if gssapi-based authentication is used, the username as provided to the \fBDante\fP server normally includes the Kerberos domain. The name must be listed on the same form here and in the system groupfile (usually /etc/passwd) if it is to be used. .IP \fBgssapi.enctype\fP Which encryption to enforce for GSSAPI-authenticated communication. Possible values are \fBclear\fP, \fBintegrity\fP, or \fBconfidentiality\fP. The default is to accept whatever the client offers. .IP \fBgssapi.keytab\fP Value for keytab to use. The default is "FILE:/etc/sockd.keytab". .IP \fBgssapi.servicename\fP Which servicename to use when involving GSSAPI. Default is "rcmd". .IP \fBlibwrap\fP The server will pass the line to libwrap for execution. .IP \fBlog\fP Used to control logging. Accepted keywords are \fBconnect\fP, \fBdisconnect\fP, \fBdata\fP, \fBerror\fP and \fBiooperation\fP. The default is no logging. .IP \fBmaxsessions\fP Limit the number of active sessions allowed by this rule to the given value. Requires the session module. .IP \fBmethod\fP Require that the connection be "authenticated" using one of the given methods. .IP \fBport\fP Parameter to \fBfrom\fP, \fBto\fP and \fBvia\fP. Accepts the keywords \fBeq/=, neq/!=, ge/>=, le/<=, gt/>, lt/<\fP followed by a number. A portrange can also be given as "port - ", which will match all port numbers within the range and . The default is all ports. .IP \fBpam.servicename\fP Which servicename to use when involving pam. Default is "sockd". .IP \fBto\fP The rule applies to requests going to the address given as value. .IP \fBuser\fP The user must match one of the names given as value. If no \fBuser\fP value is given for a rule requiring usernames, the effect will be the same as listing every user in the passwordfile. Note that if gssapi-based authentication is used, the username as provided to the \fBDante\fP server normally includes the Kerberos domain. The name must be listed on the same form here if it is to be used. .IP The contents of a \fBsocks-rule\fP is: .IP \fBbandwidth\fP The clients matching this rule will all share the given amount of bandwidth, measured in bytes per second. Requires the bandwidth module. .IP \fBcommand\fP The rule applies to the given commands. Valid commands are \fBbind\fP, \fBbindreply\fP, \fBconnect\fP, \fBudpassociate\fP and \fBudpreply\fP. Can be used instead of, or to complement, \fBprotocol\fP. The default is all commands valid for the protocols allowed by the rule. .IP \fBfrom\fP The rule applies to requests coming from the address given as value. .IP \fBgroup\fP The user must belong to one of the groups given as value. .IP \fBlibwrap\fP The server will pass the line to libwrap for execution. .IP \fBlog\fP Used to control logging. Accepted keywords are \fBconnect\fP, \fBdisconnect\fP, \fBdata\fP and \fBiooperation\fP. .IP \fBmaxsessions\fP Limit the number of active sessions allowed by this rule to the given value. Requires the session module. .IP \fBmethod\fP Require that the connection be established using one of the given methods. \fBmethod\fP always refers to the source part of the rule. Valid values are the same as in the global \fBmethod\fP line. .IP \fBpam.servicename\fP What servicename to use when involving pam. Default is "sockd". .IP \fBport\fP Parameter to \fBfrom\fP, \fBto\fP and \fBvia\fP. Accepts the keywords \fBeq/=, neq/!=, ge/>=, le/<=, gt/>, lt/<\fP followed by a number. A portrange can also be given as "port - ", which will match all port numbers within the range and . The default is all ports. .IP \fBprotocol\fP The rule applies to the given protocols. Valid values are \fBtcp\fP and \fBudp\fP. The default is all supported protocols. .IP \fBproxyprotocol\fP The rule applies to requests using the given proxy protocol. Valid proxy protocols are \fBsocks_v4\fP and \fBsocks_v5\fP. The default is all supported proxy protocols. .IP \fBredirect\fP The source and/or destination can be redirected using the \fBredirect\fP statement. Requires the redirect module. The syntax of the redirect statement is as follows: .D1 \fBredirect\fP from: \fBADDRESS\fP .D1 \fBredirect\fP to: \fBADDRESS\fP The semantics of \fBfrom\fP and \fBto\fP vary according to \fBcommand\fP. See the redirect manual for detailed information. .IP \fBto\fP The rule applies to requests going to or using the address given as value. Note that the meaning of this address is affected by \fBcommand\fP. .IP \fBudprange\fP The argument to this keyword is two portnumbers, separated by a dash ('-'). They specify the udp port-range that will be used between the socks-client and the Dante-server for udp packets. Note that this has no relation to the udp port-range used between the Dante-server and external, non-socks, clients/servers. .IP \fBuser\fP The user must match one of the names given as value. If no \fBuser\fP value is given for a rule requiring usernames, the effect will be the same as listing every user in the passwordfile. .SH ROUTES The routes are specified with a \fBroute\fP keyword. Inside a pair of parenthesis ({}) a set of keywords control the behavior of the route. See socks.conf(5) for a description. This is used to perform so-called "server-chaining", where one socks-server connects to another socks-server further upstream. Note that at present, server-chaining is only supported for the \fBconnect\fP command. .SH EXAMPLES See the example directory in the distribution. .SH FILES .nf .ta \w 1 /etc/sockd.conf \fBDante\fP server configuration file. /etc/passwd file used when checking username/passwords. .fi .SH AUTHORS For inferno Nettverk A/S: Michael Shuldman Karl-Andre' Skevik .SH SEE ALSO sockd(8), socks.conf(5), hosts_access(5) .Pp Information about new releases and other related issues can be found on the .Nm \fBDante\fP WWW home page: http://www.inet.no/dante/