Frontpage - Dante - Download - Status - Support - Modules - Docs - Links - Survey - GDPR

Config
- Introduction
- Client
- Server
- Authentication
- Bandwidth
- Chaining
- CPU/RT
- Hostid
- IPv6
- Libwrap
- Logging
- Monitors
- Redirection
- Redundancy
- Session
- Socket options
- Capacity estimation
- Upgrade

Upgrading

This page describes changes in the configuration file syntax and application behavior that might require changes to config files.

In the case of syntax changes, there will generally be backwards compatibility preserved for at least one major release. Using the old syntax in these cases will typically result in a warning being logged, but the old syntax can still be used as before.

Exceptions to this rule will be noted in these upgrade instructions.

For a set of instruction on how to replace a running Dante server with a new version, see the separate Server upgrade steps page.

Upgrading to 1.4.x

The 1.4.x release has syntax changes and various new functionality additions.

Added features

IPv6 - The Dante server now supports IPv6. This should have little practical consequences for existing setups that do not require IPv6 support, but we recommend reading the IPv6 configuration page for some notes on IPv4-only configurations.
Especially if the machine you run Dante on has IPv6-addresses configured on its network interfaces and either Dante's internal or external interfaces are set to something other than IP-addresses, the IPv6 configuration page should be read.
Monitoring - Support for generic monitoring of data traffic. This can be used to create alerts for various situations, such as no traffic being forwarded, that might indicate that there is a server or network problem. Please see the traffic monitoring page for details on how to use this functionality.
Monitoring is disabled by default.
Session limits - The functionality from the session module, previously only available to customers who purchased it, has now been expanded and merged into the public version of Dante. This can be used to limit the max number of sessions/connections and to limit the rate of new sessions/connections. Supports for per-IP limits is now also included. Please see the session limitation configuration page for details on how to enable this functionality.
Session limits are disabled by default.

NOTE: The old session module code is no longer needed and should no longer be compiled with Dante.
Real-time scheduling support - Real-time scheduling priority and CPU affinity options are now settable from the server config file.
Please see the CPU real-time scheduling configuration page for information on how to use this functionality and the Real-time scheduling functionality analysis report for information about how this functionality can be used.

Currently only available on the Linux platform.
Generic API for setting socket options - General API for setting socket options on sockets used by Dante made available in sockd.conf.
Information on how to configure this functionality can be found in the Socket options configuration page.
Improved logging of possible network/server problems - Possibility to configure Dante to log system errors and DNS-errors at a specified log-level (debug/warning/alert/etc.) in certain cases.
For details, please see the server logging configuration page.
HOSTID (proprietary TCP extension) support - Support for an out-of-band method for specifying the original client address when traversing one or more proxies.
More information can be found in the hostid documentation page.
Client-rule method override - The "socksmethod" keyword can now aslo be set in client-rules.
It is used to override the default preference for what SOCKS-method Dante should select for which clients. This makes it possible to by default have Dante use e.g., the preference "gssapi, username, none", but for some client-ranges use a different preference, e.g., "none username gssapi".
New tcpinfo log value - Used to report more extensive statistics about sessions.
This includes TCP_INFO on supported platforms.
Android support - Cross compilation.
Support for cross compilation of client library for Android (system name 'arm-linux-androideabi').
LDAP module updates (Dante 1.4.3) - New functionality has been added to the LDAP module.
New functionality includes a new ldapauth authentication method that can be used along with the username authentication method to verify a username/password, and PAC group based authorization. Please contact sales@inet.no if you have purchased an LDAP module for an earlier version of Dante to get a copy of the new version.

Syntax changes

This major release has some changes in syntax due to some potentially confusing and inconsistent aspects in the old syntax, as well as additions due to changes resulting from added and modified functionality.

Socket buffering

For versions prior to 1.4.x, the following syntax is used:

socket.recvbuf.udp: 1024

socket.sendbuf.udp: 1024

socket.recvbuf.tcp: 1024

socket.sendbuf.tcp: 1024

For version 1.4.x, the above configuration should be changed to be as follows:

internal.udp.so_rcvbuf: 1024
external.udp.so_rcvbuf: 1024

internal.udp.so_sndbuf: 1024
external.udp.so_sndbuf: 1024

internal.tcp.so_rcvbuf: 1024
external.tcp.so_rcvbuf: 1024

internal.tcp.so_sndbuf: 1024
external.tcp.so_sndbuf: 1024

The old syntax is no longer supported.

Rule syntax changes

The following changes have been made to the rule and method syntax for socks rules:

The global method keyword, used to specify SOCKS methods, is now called socksmethod.
The method keyword in client-rules, used to specify TCP-based, non-SOCKS methods, is now called clientmethod.
The method keyword in socks-rules, used to specify SOCKS methods, is now called socksmethod.
The socks-rules rules are now prefixed with socks.

For versions prior to 1.4.x, the following syntax is used:

clientmethod: authmethod1
method: authmethod2 authmethod3

client block {
        from: 192.0.2.0/24 to: 0.0.0.0/0
        log: error
        user: baduser
        method: authmethod1
}

client pass {
        from: 192.0.2.0/24 to: 0.0.0.0/0
        log: error
        method: authmethod1
}

block {
       from: 0.0.0.0/0 to: www.example.org
       command: bind connect udpassociate
       log: error
       user: baduser
       method: authmethod3
}

pass {  
        from: 0.0.0.0/0 to: 0.0.0.0/0
        command: bind connect udpassociate
        log: error
        method: authmethod2
}

For version 1.4.x, the above configuration should be changed to be as follows:

clientmethod: authmethod1
socksmethod: authmethod2 authmethod3 #this line is changed

client block {
        from: 192.0.2.0/24 to: 0.0.0.0/0
        log: error
        user: baduser
        clientmethod: authmethod1 #this line is changed
}

client pass {
        from: 192.0.2.0/24 to: 0.0.0.0/0
        log: error
        socksmethod: authmethod1 #this line is changed
}

socks block { #this line is changed
       from: 0.0.0.0/0 to: www.example.org
       command: bind connect udpassociate
       log: error
       user: baduser
       socksmethod: authmethod3 #this line is changed
}

socks pass { #this line is changed
        from: 0.0.0.0/0 to: 0.0.0.0/0
        command: bind connect udpassociate
        log: error
        socksmethod: authmethod2 #this line is changed.
}

The old syntax is still supported, but this backwards compatibility will likely be removed in a later major release.

PAM authentication syntax changes

In Dante 1.4.0, the name of the PAM authentication method was changed from simply pam, into either pam.address (for IP/hostname-only based PAM authentication, with no username/passwords exchanged) or pam.username (for username/password based PAM authentication). The old pam keyword semantics determined the correct meaning based on context, but this excluded some use-cases, and this keyword was thus deprecated.

For most users, the correct replacement for pam will be pam.username. Assuming the following PAM configuration:

method: pam

The replacement for username/password based authentication will be as follows:

method: pam.username

Or, with also the method keyword updated (see above):

socksmethod: pam.username

For more information on PAM, see the PAM authentication page.

Server idle child management

The "child.maxidle" option has been removed because the server now always removes idle children.

The old syntax is still accepted by the parser but has no practical effect on the server behavior. This backwards compatibility will likely be removed in a later major release.

Session limits

The syntax for maxsessions has changed from "maxsessions: <value>" to "session.max: <value>".

Changed behavior

Dante behavior that has changed in this version.

Miscellaneous changes

Default for the maximum number of clients a single i/o process can handle has been increased from 8 to 32.
Reduction in overall memory consumption at the expense of allocating extra memory dynamically in the very rare, perhaps non-existing, cases where the extra memory is needed.
Please note that this is only used for non-critical memory allocations, where failure to allocate the memory will not create serious problems for the Dante server it self. It may however lead to certain very large logmessages being discarded, for customers using the log: data keyword.
Customers negatively affected by this, please contact us.

Improved syntax checking

Syntax checking has been improved to better detect invalid or likely incorrect server configurations.

This can result in some configurations that have previously been accepted or accepted with warnings by Dante, to now cause an error on startup, preventing the Dante server from starting up until the configuration error has been fixed.

Direct route fallback

Fallback to direct (non-proxy) routes now defaults to off in the client, as well as in the server.

To keep previous behaviour in the client, with direct route fallback for destinations with no matching route, set SOCKS_DIRECTROUTE_FALLBACK to "yes" in the environment, or ./configure with the --enable-drt-fallback option.

Direct fallback is enabled if there are no routes configured, and disabled otherwise.

External rotation route configurations

The server is more strict about not using any other addresses than the ones specified for the external interface in sockd.conf ("external:"). Before it would in some cases just print a warning, but still use the non-configured address, assuming it was a minor configuration error. Now the request will be blocked too, which can prevent communication with certain external sites.

This only applies to configurations where "external.rotation" is set to "route".

Disabling of libwrap in configure

The "--disable-libwrap" option has been renamed "--without-libwrap".

The old syntax is still supported, but this backwards compatibility will likely be removed in a later major release.

SIGINFO/SIGUSR logging

SIGINFO/SIGUSR1 output is now logged at level info instead of level debug.

Session limit rule interaction

Session limits are now by default inherited by from lower level ACL-rules. E.g., a session limit set in a client-rule will now be inherited by the socks-rule matching the same client, whereas before, the socks-rule would reset any session limits previously set. To keep the old behavior, "session.inheritable: no" must be added to each rule using session limits.

The syntax for maxsessions has also changed from "maxsessions: <value>" to "session.max: <value>".

Server I/O timeout

The default timeout for tcp i/o (timeout.io.tcp) has been changed from 84000 to 0. A value of 0 means that the kernels default value will be used, which in most cases will mean no timeout.

The old behavior can be restored by adding the following line to the server configuration file:

timeout.io.tcp: 84000

Removed features

Use of hostname aliases in configuration files

In the server, the IPv6-compatible getnameinfo(3) and getaddrinfo(3) functions are now used instead of gethostbyaddr(3) and gethostbyname(3). The newer functions do not return hostname aliases (but only IP-address aliases), so any sockd.conf which depends on hostname aliases will no longer work. IP-address aliases continue to work as before.

The "clear" GSSAPI encoding is no longer enabled by default

GSSAPI "clear" is no longer enabled by default, as it is not part of the SOCKS GSSAPI standard.

To have the GSSAPI encoding-type "clear" available, it is now necessary to explicitly set the "gssapi.enctype" in rules and/or routes as needed. E.g. adding the below line would match what was the default in previous versions of Dante:

gssapi.enctype: clear integrity confidentiality

The new default is: "gssapi.enctype: integrity confidentiality"