Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SOCKD.CONF(5)		      File Formats Manual		 SOCKD.CONF(5)

NAME
       sockd.conf - Dante server configuration file syntax

DESCRIPTION
       The  configuration  file	for the	Dante server controls both access con-
       trols 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	#.

SERVER SETTINGS
       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:

       clientmethod
	      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  Dante,  and  before  any	socks-negotiation  has
	      started.

	      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.

       compatibility
	      With  the	 sameport 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 Dante from a privileged port,
	      Dante 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 draft-5.05 keyword will enable usage of parts	of  the	 socks
	      v5-05  draft.   The only feature from this draft that Dante sup-
	      ports 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.

       cpu    The  CPU settings	for the	various	type of	Dante processes.  Note
	      that the possibility for configuring these  settings  depend  on
	      the platform Dante is running on.	 Not all platforms may provide
	      support for these	type of	CPU settings.

	      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(s) 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 nu-
	      meric 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 ef-
	      fect client performance and overhead from	the server. The	 other
	      processes	 are  primarily	 used during connection/session	estab-
	      lishment 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.

       debug  Print debug info to the logs.  The value sets the	debug level.

       errorlog
	      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 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.

       external
	      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.

       external.log.<loglevel>.error
	      See internal.log.<loglevel>.error.  This option has an identical
	      syntax and semantics, but	applies	to error related to the	exter-
	      nal interface side.

       external.protocol
	      By default Dante 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 ad-
	      dress 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 oper-
	      ator 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	inter-
	      nal.protocol).

       external.rotation
	      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 ex-
	      ternal  rotation	value is used, all external addresses that are
	      to be used must be listed	via the	external keyword first.

	      Valid values are none (the default), route, and same-same.

	      none indicates the first address on the  list  of	 external  ad-
	      dresses 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.

       internal
	      The  internal  addresses.	  Connections will only	be accepted on
	      these addresses.	The address given may be either	a  IP  address
	      or an interface name.

       internal.log.<loglevel>.error
	      Specifies	 that certain system call failures, listed as symbolic
	      errno values, or certain dns failures, listed as symbolic	libre-
	      solv failure-codes, should be logged, possibly an	extra time, at
	      the log-level log-level.

	      Note that	this only applies to errors on the internal  interface
	      side only.

	      A	corresponding keyword exists for the external side (see	exter-
	      nal.log).

	      In addition to the standard errno	and getaddrinfo(3) error  sym-
	      bols, the	following special symbols are accepted:

	      no-route
		     Any error related to no route.

	      dns-any
		     Any error related to DNS/hostname-resolving.

	      system-any
		     Any system	error.	I.e., any errno	value.

       internal.protocol
	      See  external.protocol.  This option has an identical syntax and
	      semantics, but applies to	the internal interface,	for  addresses
	      to listen	to connections from clients on.

       libwrap.hosts_access
	      If  the  server  is  compiled  with  libwrap support, determines
	      whether the hosts_access() function should be  used  for	access
	      control.	When enabled by	setting	this value to yes, the libwrap
	      library determines if TCP	connections or UDP packets  should  be
	      immediately    dropped   or   not,   typically   by   consulting
	      /etc/hosts.allow and /etc/hosts.deny. These checks  are  applied
	      to  all  traffic,	before the rule	processing starts. The default
	      value is no (disabled).

       logoutput
	      This value controls where	the server sends logoutput.  It	can be
	      set  to syslog[/facility], stdout, stderr, a filename, or	a com-
	      bination.	 The default is	nowhere.  Note	that  if  errorlog  is
	      also  set,  there	will be	a overlap between what is logged there
	      (errors only), and what will be logged here (errors, and	every-
	      thing else).

       socksmethod
	      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 se-
	      cure methods first.

	      Supported	values are bsdauth,  gssapi,  none,  pam.any,  pam.ad-
	      dress, 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.

       srchost
	      This keyword allows you to configure a few options  that	relate
	      to the srchost, i.e., the	host the Dante server accepts the con-
	      nections from.

	      With the nodnsmismatch keyword, the server will not accept  con-
	      nections 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  con-
	      nections from addresses without a	DNS record.  Default is	to ac-
	      cept 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,  au-
	      thentication 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 the methods not involving
	      the socks	protocol in any	way, and are  listed  in  the  client-
	      method  section previously mentioned.  For UDP-replies, no meth-
	      ods can be used.

	      Default is not to	check the authentication on replies.

       timeout.connect
	      The number of seconds the	server will wait for a connect	initi-
	      ated  on behalf of the socks-client to complete.	The default is
	      30.  Setting it to 0 will	use the	systems	default.

       timeout.io
	      The number of seconds an established  connection	can  be	 idle.
	      The  default is 0, meaning forever.  See also the	"-n" option in
	      the sockd(8) manpage.

	      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  de-
	      fault timeouts for clients matching the rule.

       timeout.negotiate
	      The  number  of  seconds a client	can spend negotiating with the
	      Dante server for a socks session before  Dante  will  close  the
	      connection  to  the client.  The default is 30.  Set it to 0 for
	      forever, though that is strongly discouraged.

       timeout.tcp_fin_wait
	      The timeout for the equivalent of	TCP's FIN-WAIT-2.  The default
	      is  0,  which  means use the systems default (normally, no time-
	      out).

       udp.connectdst
	      Enables or disables whether the server should attempt connecting
	      UDP sockets to the destination.  Valid values are	yes and	no.

	      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.

       Userids
	      On platforms providing a privilege-model supported by Dante, the
	      Dante 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 Dante  server  to  appropriate  values.
	      The Dante	server can use two different userids, or three if com-
	      piled with libwrap support.  They	are as follows:

       user.privileged
	      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 re-
	      quires 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  user.un-
	      privileged.

       user.unprivileged
	      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.

       user.libwrap
	      User  used to execute libwrap commands.  Normally	this should be
	      the same as user.unprivileged

MODULES
       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  in-
       formation.

       bandwidth
	      The  bandwidth  module gives control over	how much bandwidth the
	      Dante server uses	on behalf of different clients or to different
	      targets.

       redirect
	      The  redirect  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.

SOCKET OPTIONS
       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 en-
       able 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  de-
       tected, when available, for the specified protocol levels:

	      SOCKET 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

	      TCP    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_no-
		     push,  tcp_sack_enable,  tcp_stdurg, tcp_syncnt, tcp_win-
		     dow_clamp

	      UDP    udp_cork

	      IP     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

       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:

	      ip_portrange
		     ip_portrange_default, ip_portrange_low, ip_portrange_high

       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	speci-
       fied below:

	      ip_tos.dscp
		     af11 af12 af13 af21 af22 af23 af31	af32  af33  af41  af42
		     af43 cs0 cs1 cs2 cs3 cs4 cs5 cs6 cs7 ef

	      ip_tos.prec
		     netcontrol	internetcontrol	critic_ecp flashoverride flash
		     immediate priority	routine

	      ip_tos.tos
		     lowdelay throughput reliability

       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	estab-
       lished, while others can	only be	set after a connection has been	estab-
       lished. 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	deter-
       mined 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	 argu-
       ment.  This is not the recommended approach for setting socket options,
       but represents a	simple way of setting socket options that are not  di-
       rectly supported	by the server, such as local kernel extensions.

AUTHENTICATION METHODS
       The  Dante  server supports the following authentication	methods.  Some
       installations of	Dante may support only a subset	of these, depending on
       platform	support.

       none   This method requires no form of authentication.

       username
	      This  method requires the	client to provide a username and pass-
	      word.  This information must match  the  username	 and  password
	      given in the system password file.

       gssapi This method requires the setup of	a Kerberos environment and can
	      provide strong encryption	and authentication, depending  on  the
	      gssapi settings you choose.

       rfc931 This  method  requires the host the socks	client runs on to pro-
	      vide a rfc931 ("ident") username for the client.	This  username
	      match a username given in	the system password file.

       pam.address
	      IP-based (rhosts)	PAM authentication.

       pam.any
	      Will  try	 to  match against any type of PAM authentication, de-
	      pending on the information that is  currently  available.	  Nor-
	      mally  of	 limited use, and you should instead set the pam-based
	      method(s)	you actually want.

       pam.username
	      Username/password-based  PAM  authentication.   Similar  to  the
	      method  username,	 but the information is	passed to the PAM sub-
	      system for authentication, rather	than Dante  using  the	system
	      password file directly.  When using PAM, be wary of memory leak-
	      ages and other bugs in the external PAM library Dante will  have
	      to use on	your platform.

       bsdauth
	      This method requires the available client	data to	be verified by
	      the BSD Authentication system.  Similar to the method  username,
	      but passed to the	BSD authentication system instead.

ADDRESSES
       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 spe-
       cial 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.

RULES
       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, pro-
       vided 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  key-
       word  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  ad-
       dress 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 how-
       ever  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  ac-
       cepted 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 re-
       quest 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  re-
       quest, 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, redi-
       rect,	timeout.connect,    timeout.negotiate,	  timeout.io,	 time-
       out.tcp_fin_wait, and udp.portrange.

       The format and content of the 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.

	      The contents of a	client-rule can	be:

       bandwidth
	      The clients matching this	rule will all share the	 given	amount
	      of  bandwidth, measured in bytes per second.  Requires the band-
	      width module.

       clientcompatibility
	      Enables certain options for compatibility	with  broken  clients.
	      Valid  values are: necgssapi, for	compatibility with clients im-
	      plementing GSSAPI	the NEC	socks way.

       from   The rule applies to requests coming from the specified address.

       group  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 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.

       gssapi.enctype
	      Which  encryption	to enforce for GSSAPI-authenticated communica-
	      tion.  Possible values are clear,	integrity, or confidentiality.
	      The  default  is	to  accept  whatever  the client offers	except
	      clear, as	clear is not part of the SOCKS GSSAPI standard.

       gssapi.keytab
	      Value    for    keytab	to    use.	The	default	    is
	      "FILE:/etc/sockd.keytab".

       gssapi.servicename
	      Which  servicename  to  use  when	 involving GSSAPI.  Default is
	      "rcmd".

       libwrap
	      The server will pass the specified parameter line	to libwrap for
	      execution.

       log    Used to control logging.	Accepted keywords are connect, discon-
	      nect, data, error, ioop, and tcpinfo.  The default  is  no  log-
	      ging.

       session
	      Control  the  max	 number	 of  sessions or session establishment
	      rate. See	below for details.

       clientmethod
	      Require that the connection be "authenticated" using one of  the
	      given clientmethods.

       pam.servicename
	      Which  servicename  to  use  when	 involving  pam.   Default  is
	      "sockd".

       port   Parameter	to from, to  and  via.	 Accepts  the  keywords	 eq/=,
	      neq/!=,  ge/>=,  le/<=, gt/>, lt/< followed by a number.	A port
	      range can	also be	given as "port <start #>  -  <end  #>",	 which
	      will  match all port numbers within the range <start #> and <end
	      #>.

	      The default is to	match all ports.

       redirect
	      The source and/or	destination can	be redirected using the	 redi-
	      rect statement.  Requires	the redirect module.

	      The syntax of the	redirect statement is as follows:

	      redirect from: ADDRESS

	      See the redirect manual for detailed information.

       socksmethod
	      If  the client offers more than one authentication method, Dante
	      will select the method to	use based on the order the methods are
	      listed  here.   Valid  values  are  the  same  as	 in the	global
	      socksmethod line.	 Normally there	will be	no need	 to  set  this
	      keyword in a client-rule,	but if it is set and the client	offers
	      none of the methods listed, the client will be blocked  at  this
	      stage.

       timeout.negotiate
	      See the global timeout.negotiate option.

       to     The  rule	 applies  to  requests	going  to the address given as
	      value.

       user   The user must match one of the names given as value.  If no user
	      value  is	 given for a rule requiring usernames, the effect will
	      be the same as listing every user	in the password	file.

	      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 contents of a	socks-rule can be:

       bandwidth
	      The  clients  matching this rule will all	share the given	amount
	      of bandwidth, measured in	bytes per second.  Requires the	 band-
	      width module.

       bsdauth.stylename
	      The  name	of the BSD authentication style	to use.	The default is
	      to not specify a value, causing the default system style	to  be
	      used.

       command
	      The  rule	 applies  to  the  given commands.  Valid commands are
	      bind, bindreply, connect,	udpassociate  and  udpreply.   Can  be
	      used instead of, or to complement, protocol.  The	default	is all
	      commands valid for the protocols allowed by the rule.

       from   The rule applies to requests coming from the  address  given  as
	      value.

       group  The user must belong to one of the groups	given as value.

       libwrap
	      The server will pass the line to libwrap for execution.

       log    Used to control logging.	Accepted keywords are connect, discon-
	      nect, data, ioop,	and tcpinfo.

       session
	      Control the max number  of  sessions  or	session	 establishment
	      rate. See

       socksmethod
	      Require  that  the  connection  be  established using one	of the
	      given authentication methods.  A method normally refers  to  the
	      socks  client  part  of  the  rule,  and	thus authenticates the
	      client, and not the target destination (see  checkreplyauth  for
	      information about	authentication the target destination).	 Valid
	      values are the same as in	the global socksmethod line.

       pam.servicename
	      What servicename to use when involving pam.  Default is "sockd".

       port   Parameter	to from, to  and  via.	 Accepts  the  keywords	 eq/=,
	      neq/!=,  ge/>=,  le/<=, gt/>, lt/< followed by a number.	A por-
	      trange can also be given as "port	<start #> -  <end  #>",	 which
	      will  match all port numbers within the range <start #> and <end
	      #>.

	      The default is all ports.

       protocol
	      The rule applies to the given protocols.	Valid values  are  tcp
	      and  udp.	 The default is	all supported protocols	that can apply
	      to the given commands.

       proxyprotocol
	      The rule applies to requests using  the  given  proxy  protocol.
	      Valid proxy protocols are	socks_v4 and socks_v5.	The default is
	      all supported proxy protocols.

       redirect
	      The source and/or	destination can	be redirected using the	 redi-
	      rect statement.  Requires	the redirect module.

	      The syntax of the	redirect statement is as follows:

	      redirect from: ADDRESS

	      redirect to: ADDRESS

	      The semantics of from and	to vary	according to command.  See the
	      redirect manual for detailed information.

       timeout.connect
	      See the global timeout.connect option.

       timeout.io
	      See the global timeout.io	option.

       timeout.tcp_fin_wait
	      See the global timeout.tcp_fin_wait option.

       to     The rule applies to requests going to or using the address given
	      as  value.  Note that the	meaning	of this	address	is affected by
	      command.

       udp.portrange
	      The argument to this keyword is two port numbers,	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 be-
	      tween the	Dante-server and external, non-socks, clients/servers.

       user   The user must match one of the names given as value.  If no user
	      value  is	 given for a rule requiring usernames, the effect will
	      be the same as listing every user	in the password	file.

SESSION
       The session keyword can be used any any rule to limit the number	of ac-
       tive 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 argu-
       ment. 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 con-
       trol  how  the  IP-address is determined. Currently two values are sup-
       ported, 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.

TRAFFIC	MONITORING
       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 en-
       able perform passive monitoring of network traffic, or the lack of net-
       work traffic.

       The  following  example	shows the general monitor syntax, specifying a
       monitor without any monitoring operations:

	monitor	{
	 from: 0.0.0.0/0 to: www.example.org port = 80
	 protocol: tcp
	}

       A monitor can include many of the same keywords that are	 available  in
       the Dante ACL rules. The	following subset is currently supported:

	      from   Normally  specifies  what SOCKS client addresses/networks
		     to	monitor.

	      to     Normally specifies	what target addresses/networks to mon-
		     itor.

	      protocol
		     Can  be used to restrict monitoring to a certain protocol
		     (TCP, UDP or both). Note: only TCP	 should	 be  used  for
		     now.

	      hostid Can be used to restrict monitoring	to only	clients	with a
		     specific hostid value set.

	      hostindex
		     Used along	with the hostid	keyword	to  control  which  of
		     the  two  possible	hostid values will be used when	match-
		     ing.

       NOTE: It	is currently recommended that the protocol keyword  is	always
       specified  and  set to tcp because there	is currently only limited sup-
       port for	monitoring of UDP traffic, and testing of UDP traffic monitor-
       ing 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.

   Data	alarms
       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 indepen-
       dently for each of them:

	      internal.alarm.data.recv
		     Data  received  on	 Dante's internal interface (data sent
		     from the SOCKS clients to Dante).

	      internal.alarm.data.send
		     Data sent out on Dante's internal	interface  (data  sent
		     from Dante	to the SOCKS clients).

	      external.alarm.data.recv
		     Data  received  on	 Dante's external interface (data sent
		     from the target servers to	Dante).

	      external.alarm.data.send
		     Data sent out on Dante's external	interface  (data  sent
		     from Dante	to the target servers).

       The  data.alarm	keyword	takes two parameters: a	byte count and a dura-
       tion in seconds.	The alarm will trigger if the specified	number of sec-
       onds  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 manu-
       ally, 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 ac-
       tive 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.

   Disconnect alarms
       The disconnect alarms are related to connection disconnects and by  us-
       ing  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  net-
       work  interface,	 between  the SOCKS clients and	Dante, and one for the
       external	interface, between the Dante server and	the target servers:

	      internal.alarm.disconnect
		     Connections between SOCKS clients and the Dante server.

	      external.alarm.disconnect
		     Connections between the Dante server and 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 discon-
       nected 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	 trig-
       ger.

       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 dis-
       connects	might be sufficient to achieve the required number of  discon-
       nects  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 to-
       wards a disconnect alarm	on the internal	side.

       A practical consequence of this is that if a large  number  of  connec-
       tions  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 mul-
       tiple alarms are	specified in a monitor rule.

ROUTES
       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
       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.

       The syntax for these routes is the same	as  the	 routes	 used  by  the
       client.	 Please	see socks.conf(5) for information about	the route syn-
       tax.

       There are however some special things one need to be aware of regarding
       serverchaining and routes specified for the server:

	      At  present serverchaining is only supported for the tcp connect
	      command.

	      If the route specifies that a username/password-method should be
	      offered  to  the	upstream  proxy,  Dante	will forward the user-
	      name/password received from it's own client to the  foreign  up-
	      stream proxy, meaning the	upstream proxy will receive the	user's
	      username and password in cleartext from Dante.

	      At present serverchaining	does  not  scale  well	in  Dante  and
	      should not be used for anything but minimal client loads.

EXAMPLES
       See the example/	directory in the distribution.

FILES
       /etc/sockd.conf	 Dante server configuration file.
       /etc/passwd	 systemfile used when doing standard username/password
			 authentication.

AUTHORS
       For inferno Nettverk A/S:
	  Michael Shuldman
	  Karl-Andre' Skevik

SEE ALSO
       sockd(8), socks.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 sup-
       port page: http://www.inet.no/dante/support.html

				 July 29 2013			 SOCKD.CONF(5)

NAME | DESCRIPTION | SERVER SETTINGS | MODULES | SOCKET OPTIONS | AUTHENTICATION METHODS | ADDRESSES | RULES | SESSION | TRAFFIC MONITORING | ROUTES | EXAMPLES | FILES | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sockd.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help