| DANTED.CONF(5) | File Formats Manual | DANTED.CONF(5) |
danted.conf - Dante server configuration file syntax
The configuration file for the Dante server controls both access controls and logging. It is divided into three parts; server settings, rules, and routes.
Note that server settings must come before rules and routes.
A line can be commented out using the standard comment character #.
The server settings control the generic behaviour of the server. Each keyword is separated from its value by a ':' character.
The following keywords are available:
Supported values are pam.address, pam.any, none, and rfc931 .
For all methods the authentication will be based on solely on the IP-address of the client, possibly in combination with a rfc931 ("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 Dante will set it to the correct value by it self.
The draft-5.05 keyword will enable usage of parts of the socks v5-05 draft. The only feature from this draft that Dante 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.
There are four process types: mother, negotiate, request, and io.
The currently supported options are:
schedule.<process type>: <scheduling policy>/<priority>.
Example: cpu.schedule.mother: SCHED_FIFO/20 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.
mask.<process type>: <cpu id 1> [cpu id 1 ...]/any.
Example: cpu.mask.mother: any Example: cpu.mask.io: 0 1
The mask gives control over the CPU/cores on which the different process types will run. Specifying the default (all) 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 (schedule and mask) should in most cases not be necessary. If they are to be used, the io 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.
The possible values are the same as for the logoutput 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.
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: ipv4 and ipv6, 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 internal.protocol).
Valid values are none (the default), route, and same-same.
none indicates the first address on the list of external addresses should be used.
route 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 user.privileged to root. Note that route might create problems for ftp-clients using active ftp if the Dante bind extension is enabled for the ftp-client.
same-same indicates the source address for a given destination should be the same address as the Dante server accepted the clients connection on.
Note that this only applies to errors on the internal interface side only.
A corresponding keyword exists for the external side (see external.log).
In addition to the standard errno and getaddrinfo(3) error symbols, the following special symbols are accepted:
Supported values are bsdauth, gssapi, none, pam.any, pam.address, pam.username, rfc931, and username,
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 AUTHENTICATION METHODS for an explanation of the different methods and their meaning.
With the nodnsmismatch 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 nodnsunknown keyword, the server will not accept connections from addresses without a DNS record. Default is to accept them.
With the checkreplyauth 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 clientmethod section previously mentioned. For UDP-replies, no methods can be used.
Default is not to check the authentication on replies.
Individual timeouts can be set for TCP and UDP by suffixing io with ".<protocolname>", i.e. timeout.io.tcp or timeout.io.udp.
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.
The default is yes, 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.
If not, you can probably set it to the same value as user.unprivileged.
The following modules are supported by Dante. Modules are purchased separately from Inferno Nettverk A/S and may add extra functionality that is not needed by most users. See the Dante homepage for more information.
The server has support for setting a large number of low-level socket options on both incoming and outgoing traffic. Most users will not need to set any of these options, but some might want to do it, to enable special network features, or to perform various 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:
The syntax for setting socket options is as follows:
<direction>.<level>.<option>: <value>
The value field corresponds to the value that the socket option should be set to. For many socket options this is an integer value. The level and option values correspond to the socket names and protocol levels listed above. Both should be in lower-case.
The direction keywords is used to specify whether the socket option should be set for traffic on the internal or the external interface and can have the values internal and external. For example, to set the IP_TOS socket option on outgoing traffic, the following syntax can be used:
external.ip.ip_tos: 0x10
In this example, the argument value (0x10) is specified as a hex value. For some of the socket options the value can also be set symbolically. Currently this is possible for the following options, with the listed values:
The IP_TOS socket option also supports this, but handling this option is somewhat complicated by the same bits having different meanings in different RFCs. Handling this is done with a subfield that indicates the type of argument that should be used. The following subfields are defined and should be added to the name of the socket option as specified below:
When numerical arguments are given to subfields, the values are shifted to apply only to the subfield bit range. The following example shows the different ways of setting IP_TOS to lowdelay on external traffic:
external.ip.ip_tos: 0x10 #base value, numerically external.ip.ip_tos.tos: 0x08 #subfield, numerically external.ip.ip_tos.tos: lowdelay #subfield, symbolically
The first value sets the value directly, the second sets only the TOS bits, which are shifted relative to the base value. The final line sets the TOS value symbolically.
This functionality gives a large amount of control over socket options, but it should not be used without some understanding of how the kernel allows the socket option to be set, and the limitations that apply when the socket options are set as either defaults or in rules.
Setting a socket option in a client pass or socks-rules will cause any defaults to be overridden. Global options are set before bind() is called on internal sockets, or before connect() is called on external sockets. Options set in client rules are also applied before bind() is called on the internal socket, but cannot be set for the external socket. For socks-rules, both external and internal options can be set, but because the socks-request must be interpreted before the rules can be evaluated, socket options can only be set on internal sockets after the connection has been received.
Some socket options must be set before a connection has been established, while others can only be set after a connection has been established. Others can be set at any time.
Socket options that are not listed above can also be set by specifying the socket option name numerically, for example:
external.ip.10: 0x12
In this example the socket option corresponding to the value 10 will be set. These numbers are platform dependent but can typically be determined by looking at the appropriate system header files. Specifying options numerically might result in some warnings, but allows any socket option to be specified, as long as it takes a numerical argument. This is not the recommended approach for setting socket options, but represents a simple way of setting socket options that are not directly supported by the server, such as local kernel extensions.
The Dante server supports the following authentication methods. Some installations of Dante may support only a subset of these, depending on platform support.
Each address field can consist of an IP address (and where required, a netmask, separated from the IP address by a '/' sign), a hostname, a domainname (designated so by the leading '.'), or an interface name.
An IP address can be given on on IPv4 form, IPv6 form, or as the special value 0/0, which matches all IP addresses, be they IPv4 or IPv6. The latter is intended for use in rules that should match both IPv4 and IPv6 clients or targets.
Each address, except the external address, can include an optional port specifier.
There are two sets of rules and they work at different levels. Rules prefixed with client are checked first and are used to see if the client is allowed to connect to the Dante server. We call them "client-rules". These rules will start with client pass for a rule that allows the client, or client block for a rule that blocks the client.
It is recommended that the client-rules do not use hostnames but only IP-addresses, both for security and performance reasons. These rules operate at the TCP level.
The other rules, which we call "socks-rules", are prefixed with socks and operate at the socks protocol level.
These rules will start with socks pass for a rule that allows the client, or socks block for a rule that blocks the client.
These rules are only checked if the client connection has been allowed by the client-rules. The socks-rules are used to evaluate the socks request that the client sends.
While it is less important that these rules use only IP-addresses, provided the client-rules have been configured to only allow access from a pre-defined range of client IP-addresses, it is still recommended.
Both set of rules include a pass or deny keyword. The pass/deny keyword determines whether connections matching the rule are to be passed through or be blocked.
Both the client-rules and the socks-rules also specify a from/to address pair which gives the addresses the rule will match.
In both contexts, from refers to the clients address, i.e., the address the client is connecting to the Dante server from. The to address however refers to different things depending on whether it is used in a client-rule or in a socks-rule.
In the client-rule context, to means the address the request is accepted on, i.e., a address the Dante server listens on.
In the socks-rule context, to means the client's destination address, as expressed in the client's socks request. I.e., the address the Dante server should connect to (for TCP sessions) or send packets to (for UDP session) on behalf of the client.
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, all actions are executed.
The list of condition keywords is: clientcompatibility, clientmethod, command, from, group, socksmethod, protocol, proxyprotocol, to, user.
The list of action keywords is: bandwidth, libwrap, log, session, redirect, timeout.connect, timeout.negotiate, timeout.io, timeout.tcp_fin_wait, and udp.portrange.
The format and content of the keyword as used in client-rules or socks-rules is identical, but client-rules can contain only a subset of the keyword that socks-rules may contain.
Note that if gssapi-based authentication is used, the username as provided to the Dante 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.
The default is to match all ports.
The syntax of the redirect statement is as follows:
See the redirect manual for detailed information.
Note that if gssapi-based authentication is used, the username as provided to the Dante server normally includes the Kerberos domain. The name must be listed on the same form here if it is to be used.
The default is all ports.
The syntax of the redirect statement is as follows:
The semantics of from and to vary according to command. See the redirect manual for detailed information.
The session keyword can be used any any rule to limit the number of active sessions and the rate at which they are established. There are two main commands for this; session.max, that controls the max number of sessions that can be matched, and session.throttle, that controls the connection rate. These commands can be applied both for the total limit for all matching clients and can be set as global defaults or in any of the rule types. The session.max keyword takes a number corresponding to the highest number of allowed simultaneous connections as an argument. The session.throttle keyword takes two number separated by a slash character, with the first representing the number of connections and the latter a time duration in seconds. If more than the specified number of connections are received in the specified number of seconds, additional connections will be dropped.
Stateful session tracking on a per IP-address basis is also supported. For stateful tracking, the limits apply to each connection with a matching IP-address, with the session.state.key keyword is used to control how the IP-address is determined. Currently two values are supported, from and hostid. The former causes the limit to be applied to all hosts with the same source IP-address and the latter to all TCP connections with the same hostid value. If a hostid value is used, the session.state.key.hostindex keyword can be used to choose which of the to hostid values are used, with the first value being the default.
Limits are evaluated first for client rules, then for hostid rules, and finally for socks rules. By default, a limit set in a matching client rule will be used also any subsequent matching hostid or socks rules, unless either of these rules also have session limit keywords. This session inheritance can be disabled in client and hostid rules, causing them to only apply in the rule in which they appear. This is done by setting the session.inheritable to no.
The session keywords must be set in a rule (either client, hostid, or socks), setting them globally is not supported.
The Dante server can be configured to monitor the traffic passing through it, and trigger alarms based on the observed network traffic.
The alarms are specified in so-called monitors. These objects have the same general format as the rules Dante uses for access control and enable perform passive monitoring of network traffic, or the lack of network traffic.
The following example shows the general monitor syntax, specifying a monitor without any monitoring operations:
A monitor can include many of the same keywords that are available in the Dante ACL rules. The following subset is currently supported:
NOTE: It is currently recommended that the protocol keyword is always specified and set to tcp because there is currently only limited support for monitoring of UDP traffic, and testing of UDP traffic monitoring has not been done.
The main function of monitors is to provide a container for one or more alarms, which are specified using a new set of keywords not available for other rules. Alarms specify a condition that will cause Dante to log a warning if the condition is triggered.
Active TCP sessions will at most match one monitor, but multiple alarms can be specified in a single monitor. This makes it possible to specify multiple sets of conditions for the same TCP sessions, depending on what network interface the traffic is transferred on and whether the traffic is being received or transmitted.
Alarms can trigger as a result of periods of no or little data being transmitted, or a large numbers of TCP connections disconnecting during a short period of time, or for other reasons. See below for a complete list of what conditions alarms can be enabled for.
Adding an alarm.data keyword to a monitor will result in warnings being logged if there are periods with too little network traffic.
Dante has four network paths and data alarms can be configured independently for each of them:
The data.alarm keyword takes two parameters: a byte count and a duration in seconds. The alarm will trigger if the specified number of seconds pass with only the specified number of bytes (or less) being transmitted.
The syntax is as follows:
internal.alarm.data.recv: DATALIMIT in INTERVAL
The DATALIMIT is a number that specifies the byte limit. The INTERVAL is a number that specifies the duration. If only DATALIMIT bytes (or less) have been transferred during a period of INTERVAL seconds, an alarm will trigger in Dante.
Data alarms trigger when a period of data idleness has been detected. Once a data alarm has triggered it will remain active until it is cleared. A warning will be logged when the alarm triggers and than again when the alarm condition is cleared. In between these two points no warnings related to this alarm will be logged. This avoids repeating the same alarm/warning multiple times during network problems that last for an extended amount of time. When the alarm is cleared, Dante will also include information about how long the alarm condition lasted.
A data alarm can be cleared in two ways; automatically, once enough data has been transferred in a short enough amount of time, or manually, by sending the Dante server a SIGHUP signal. A SIGHUP will cause all active alarms to be cleared. No log messages indicating that the alarms have cleared will be logged when alarms are cleared in this way.
Once an alarm has been cleared, it can trigger again if enough data is not being transferred.
Note that data alarms will trigger regardless of whether there are active sessions matching the monitor or not; if enough data is not being transmitted or received, a data alarm will trigger. Alarms will trigger also shortly after server startup, if the Dante server does not receive sufficient traffic to prevent the alarms from triggering.
Note that the message indicating that an alarm has cleared is not logged if the alarm was cleared due to a SIGHUP signal being received.
The disconnect alarms are related to connection disconnects and by using the alarm.disconnect keyword the Dante server can log warnings based on the number and rate of terminated connections.
There are two variants of the alarm keyword, one for the internal network interface, between the SOCKS clients and Dante, and one for the external interface, between the Dante server and the target servers:
Each alarm keyword takes three parameters, a minimum count, a ratio value, and a time interval. The following format is used:
internal.alarm.disconnect: MINCOUNT/RATIO in INTERVAL
The MINCOUNT is the minimum number of connections that must be disconnected for the alarm to trigger. The RATIO is used together with the MINCOUNT to express the number of connections, relative to the total number of connections that have existed in the time period, that must be disconnected for the alarm to trigger. The INTERVAL is the time in seconds within which the disconnects must occur for the alarm to trigger.
To set values that are useful, some knowledge about the expected amount of network traffic and number of sessions is required. If the rate of disconnects, as a percentage, is lower than the ratio specified, an alarm will not trigger. Conversely, if the MINCOUNT is set too low, alarms might trigger too frequently because only a small number of disconnects might be sufficient to achieve the required number of disconnects and disconnect ratio at times when there are only a few active sessions.
Only connections that are terminated on the specified interface are counted, i.e., an external.alarm.disconnect alarm will only trigger for connections that are terminated on the network interface between the Dante server and the target server, either by the target server closing the connection to Dante or by Dante receiving a fatal network error from that side of the connection (e.g., a TCP RST packet).
Connections that are closed on the internal interface (by the SOCKS clients) will not count towards a disconnect alarm on the external side. Likewise, connections closed by target servers will not count towards a disconnect alarm on the internal side.
A practical consequence of this is that if a large number of connections are simultaneously closed by both the client and the target server, each connection will only be counted as a disconnect on one of the sides; either the external side or the internal side, depending on which side closes the connection first.
Alarms trigger each time a sufficient number disconnects occur. Each sufficiently large burst of disconnects will result in an alarm, but normally at most one warning per alarm will be logged during each time interval, though this might change in a later version of Dante.
Separate alarms are produced for each distinct alarm keyword when multiple alarms are specified in a monitor rule.
The routes are specified with a route keyword. Inside a pair of curly braces ({}) a set of keywords control the behavior of the route. See dante.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.
The syntax for these routes is the same as the routes used by the client. Please see dante.conf(5) for information about the route syntax.
There are however some special things one need to be aware of regarding serverchaining and routes specified for the server:
See the example/ directory in the distribution.
/etc/danted.conf Dante server configuration file. /etc/passwd systemfile used when doing standard username/password
authentication.
For inferno Nettverk A/S:
Michael Shuldman
Karl-Andre' Skevik
danted(8), dante.conf(5), hosts_access(5)
Information about new releases and other related issues can be found on the Dante WWW home page: http://www.inet.no/dante/
Information about commercial support can be found on the Dante WWW support page: http://www.inet.no/dante/support.html
| July 29 2013 |