.\" $Id: sockd.conf.5,v 1.187.4.4.2.2.4.2 2019/01/09 16:52:18 karls Exp $ .\" .\" Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, .\" 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2017 .\" 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 .\" Gaustadalleen 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 DANTED.CONF 5 "July 29 2013" .SH NAME danted.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. Note that server settings \fBmust\fP come before rules and routes. A line can be commented out 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 its value by a \fB':'\fP character. The following keywords are available: .\" .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 .\" behavior in external libraries used by 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, listed in order of preference. These are authentication methods that are to be checked immediately after the SOCKS client has connected to \fBDante, and \fBbefore\fP any socks-negotiation has started. Supported values are \fBpam.address\fP, \fBpam.any\fP, \fBnone\fP, and \fBrfc931\fP . For all methods the authentication will be based on solely on the IP-address of the client, possibly in combination with a \fBrfc931\fP ("ident") lookup towards the host the client is running on. 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. The default value for this keyword is all methods that may be necessary for the later socks-based authentication methods, as specified as values to the global socksmethod keyword. Normally you should not need to set this keyword, as \fBDante\fP will set it to the correct value by it self. .IP \fBcompatibility\fP With the \fBsameport\fP keyword, the server attempts to use the same port on the server's external side as the client used on the server's internal side. This is normally the default, but when this option is given it will be done with privileged ports also, meaning if a client connects to \fBDante\fP from a privileged port, \fBDante\fP will attempt to connect to the target destination from a privileged port too. There can be security issues involved with this, so normally this option should not be set. 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. Only affects UDP. .IP \fBcpu\fP The CPU settings for the various type of \fBDante\fP processes. Note that the possibility for configuring these settings depend on the platform \fBDante\fP is running on. Not all platforms may provide support for these type of CPU settings. There are four process types: \fBmother, negotiate, request\fP, and \fBio\fP. The currently supported options are: \fBschedule\fP.: /. Example: \fBcpu.schedule.mother: SCHED_FIFO/20\fP The above requests that the kernel schedules the mother process(es) using a first-in, first-out policy, at priority 20. The default is to not request any specific scheduling. \fBmask\fP.: [cpu id 1 ...]/any. Example: \fBcpu.mask.mother: any\fP Example: \fBcpu.mask.io: 0 1\fP The mask gives control over the CPU/cores on which the different process types will run. Specifying the default (\fBall\fP) allows the process type to run on any CPU id. Specifying one or more numeric CPU id limits the process to that set of CPUs. The cpu keywords (\fBschedule\fP and \fBmask\fP) should in most cases not be necessary. If they are to be used, the \fBio\fP processes are where most of the work is done and adjusting the priority or CPU usage is what is likely to have the most significant performance effect client performance and overhead from the server. The other processes are primarily used during connection/session establishment and changes to settings for the non-io process types will primarily affect these operations. The default is to not limit processes to any specific cpu. .IP \fBdebug\fP Print debug info to the logs. The value sets the debug level. .IP \fBerrorlog\fP This value can be set to receive only error-related logoutput. Note that this does not include client-specific errors, but only more serious "global" errors. The possible values are the same as for the \fBlogoutput\fP keyword mentioned below. The intent is to have a special place that only serious errors are logged so that they can discovered quickly. The default is to not have any special place to log errors. .IP \fBexternal\fP The address to be used for outgoing connections. The address given may be either an IP address or an interface name. Can be given multiple times for different addresses. .IP \fBexternal.log..error\fP See \fBinternal.log..error\fP. This option has an identical syntax and semantics, but applies to error related to the external interface side. .IP \fBexternal.protocol\fP By default \fBDante\fP will use the address families specified and available, and there is no need to set this keyword. In some cases the operator may however wish to specify an address in a form that may include more than one address family, yet not wish for Dante to use all the address families available for that address form. This will typically happen if the operator wishes to specify that Dante should use the addresses on a network interface card which has both IPv4 and IPv6 addresses configured, yet the operator wishes Dante to only use one of these two address families. The operator can then specify the address family he wants Dante too look for when expanding the interface name for IP-addresses to use. Valid values for this keyword are: \fBipv4\fP and \fBipv6\fP, indicating that Dante should only use the IPv4 address family or only the IPv6 address family, respectively. The default is to use both families, if available. A corresponding keyword exists for the internal side (see \fBinternal.protocol\fP). .IP \fBexternal.rotation\fP If more than one external address is given, this governs which of the given addresses is selected as the source address for outgoing connections/packets. Note that regardless of which external rotation value is used, all external addresses that are to be used must be listed via the \fBexternal\fP keyword first. Valid values are \fBnone\fP (the default), \fBroute\fP, and \fBsame-same\fP. \fBnone\fP indicates the first address on the list of external addresses should be used. \fBroute\fP indicates the kernels routing table should be consulted to find out what the source address for a given destination will be, and might require you to set \fBuser.privileged\fP to \fBroot\fP. 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. \fBsame-same\fP indicates the source address for a given destination should be the same address as the \fBDante\fP server accepted the clients connection on. .IP \fBinternal\fP The internal addresses. Connections will only be accepted on these addresses. The address given may be either an IP address or an interface name. .IP \fBinternal.log..error\fP Specifies that certain system call failures, listed as symbolic errno values, or certain dns failures, listed as symbolic libresolv failure-codes, should be logged, possibly an extra time, at the log-level \fBlog-level\fP. Note that this only applies to errors on the internal interface side only. A corresponding keyword exists for the external side (see \fBexternal.log\fP). In addition to the standard errno and getaddrinfo(3) error symbols, the following special symbols are accepted: .RS .IP \fBno-route\fP Any error related to no route. .IP \fBdns-any\fP Any error related to DNS/hostname-resolving. .IP \fBsystem-any\fP Any system error. I.e., any errno value. .RE .IP \fBinternal.protocol\fP See \fBexternal.protocol\fP. This option has an identical syntax and semantics, but applies to the internal interface, for addresses to listen to connections from clients on. .IP \fBlibwrap.hosts_access\fP If the server is compiled with libwrap support, determines whether the \fBhosts_access()\fP function should be used for access control. When enabled by setting this value to \fByes\fP, the libwrap library determines if TCP connections or UDP packets should be immediately dropped or not, typically by consulting \fB/etc/hosts.allow\fP and \fB/etc/hosts.deny\fP. These checks are applied to all traffic, before the rule processing starts. The default value is \fBno\fP (disabled). .IP \fBlogoutput\fP This value controls where the server sends logoutput. It can be set to \fBsyslog\fP[/\fBfacility\fP], \fBstdout\fP, \fBstderr\fP, a filename, or a combination. The default is nowhere. Note that if \fBerrorlog\fP is also set, there will be a overlap between what is logged there (errors only), and what will be logged here (errors, and everything else). .IP \fBsocksmethod\fP A list of acceptable authentication methods for socks-rules, listed in order of preference. It is thus important that you specify these in the desired order, normally with the more secure methods first. Supported values are \fBbsdauth\fP, \fBgssapi\fP, \fBnone\fP, \fBpam.any\fP, \fBpam.address\fP, \fBpam.username\fP, \fBrfc931\fP, and \fBusername\fP, If a method is not set in this list it will never be selected. The default is no methods, which means all socks-requests will be blocked. See the section on \fBAUTHENTICATION METHODS\fP for an explanation of the different methods and their meaning. .IP \fBsrchost\fP This keyword allows you to configure a few options that relate to the srchost, i.e., the host the \fBDante\fP server accepts the connections from. With the \fBnodnsmismatch\fP keyword, the server will not accept connections from addresses having a mismatch between DNS IP address and hostname. Default is to accept them. With the \fBnodnsunknown\fP keyword, the server will not accept connections 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 socksmethod. Normally, authentication is not desired on 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. The methods possible for TCP are the methods not involving the socks protocol in any way, and are listed in the \fBclientmethod\fP section previously mentioned. For UDP-replies, no methods can be used. Default is not to check the authentication on replies. .IP \fBtimeout.connect\fP The number of seconds the server will wait for a connect initiated on behalf of the socks-client to complete. The default is 30. Setting it to 0 will use the systems default. .IP \fBtimeout.io\fP The number of seconds an established connection can be idle. The default is 0, meaning forever. See also the "\-n" option in the danted(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. Individual timeouts can also be set within rules, using the same syntax. The timeout set in the rule will then override the default timeouts for clients matching the rule. .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.tcp_fin_wait\fP The timeout for the equivalent of TCP's FIN-WAIT-2. The default is 0, which means use the systems default (normally, no timeout). .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. The socket will only remain connected as long as the client only sends UDP packets to one destination address. If packets are sent to multiple destinations the socket will no longer remain connected and replies can be received from any destination. .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, or 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 danted.conf file or to write the danted.pid file (you can create it manually before starting danted), 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. It is recommended that a separate userid is created for this purpose. .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 and may add extra functionality that is not needed by most users. See the \fBDante\fP homepage for more information. .IP \fBbandwidth\fP The \fBbandwidth\fP module gives control over how much bandwidth the \fBDante\fP server uses on behalf of different clients or to different targets. .IP \fBredirect\fP The \fBredirect\fP module gives you control over what addresses the server will use on behalf of the clients, as well as allowing you to redirect client requests to a different addresses. .SH SOCKET OPTIONS The server has support for setting a large number of low-level socket options on both incoming and outgoing traffic. .I Most users will not need to set any of these options, but some might want .I to do it, to enable special network features, or to perform various .I experiments. Options can be set globally as defaults for all traffic, or be set in the access control rules to only affect clients and targets matching the given rule. The socket options that are available vary between platforms, so during configuration and building of the server the options that are available will be determined. Currently, the following options should be detected, when available, for the specified protocol levels: .RS .IP \fBSOCKET\fP so_bindany, so_broadcast, so_debug, so_dontroute, so_jumbo, so_keepalive, so_oobinline, so_priority, so_rcvbuf, so_rcvbufforce, so_rcvlowat, so_sndbuf, so_sndbufforce, so_sndlowat, so_useloopback .RE .RS .IP \fBTCP\fP tcp_cork, tcp_cwnd, tcp_init_cwnd, tcp_keepcnt, tcp_keepidle, tcp_keepintvl, tcp_linger2, tcp_maxrt, tcp_maxseg, tcp_md5sig, tcp_nodelay, tcp_noopt, tcp_nopush, tcp_sack_enable, tcp_stdurg, tcp_syncnt, tcp_window_clamp .RE .RS .IP \fBUDP\fP udp_cork .RE .RS .IP \fBIP\fP ip_auth_level, ip_dontfrag, ip_esp_network_level, ip_esp_trans_level, ip_freebind, ip_ipcomp_level, ip_minttl, ip_mtu_discover, ip_portrange, ip_recvtos, ip_tos, ip_ttl .RE The syntax for setting socket options is as follows: ..