doc/TUNING

   1 Most operating systems limit an amount of TCP sockets that can be used
   2 simultaneously. It is possible for a busy Tor relay to run into these
   3 limits, thus being unable to fully utilize the bandwidth resources it
   4 has at its disposal. Following system-specific tips might be helpful
   5 to alleviate the aforementioned problem.
   6
   7 Linux
   8 -----
   9
  10 Use 'ulimit -n' to raise an allowed number of file descriptors to be
  11 opened on your host at the same time.
  12
  13 FreeBSD
  14 -------
  15
  16 Tune the following sysctl(8) variables:
  17  * kern.maxfiles - maximum allowed file descriptors (for entire system)
  18  * kern.maxfilesperproc - maximum file descriptors one process is allowed
  19    to use
  20  * kern.ipc.maxsockets - overall maximum numbers of sockets for entire
  21    system
  22  * kern.ipc.somaxconn - size of listen queue for incoming TCP connections
  23    for entire system
  24
  25 See also:
  26  * https://www.freebsd.org/doc/handbook/configtuning-kernel-limits.html
  27  * https://wiki.freebsd.org/NetworkPerformanceTuning
  28
  29 Mac OS X
  30 --------
  31
  32 Since Mac OS X is BSD-based system, most of the above hold for OS X as well.
  33 However, launchd(8) is known to modify kern.maxfiles and kern.maxfilesperproc
  34 when it launches tor service (see launchd.plist(5) manpage). Also,
  35 kern.ipc.maxsockets is determined dynamically by the system and thus is
  36 read-only on OS X.
  37
  38 OpenBSD
  39 -------
  40
  41 Because OpenBSD is primarily focused on security and stability, it uses default
  42 resource limits stricter than those of more popular Unix-like operating systems.
  43
  44 OpenBSD stores a kernel-level file descriptor limit in the sysctl variable
  45 kern.maxfiles. It defaults to 7,030. To change it to, for example, 16,000 while
  46 the system is running, use the command 'sudo sysctl kern.maxfiles=16000'.
  47 kern.maxfiles will reset to the default value upon system reboot unless you also
  48 add 'kern.maxfiles=16000' to the file /etc/sysctl.conf.
  49
  50 There are stricter resource limits set on user classes, which are stored in
  51 /etc/login.conf. This config file also allows limit sets for daemons started
  52 with scripts in the /etc/rc.d directory, which presumably includes Tor.
  53
  54 To increase the file descriptor limit from its default of 1,024, add the
  55 following to /etc/login.conf:
  56
  57 tor:\
  58         :openfiles-max=13500:\
  59         :tc=daemon:
  60
  61 Upon restarting Tor, it will be able to open up to 13,500 file descriptors.
  62
  63 This will work *only* if you are starting Tor with the script /etc/rc.d/tor. If
  64 you're using a custom build instead of the package, you can easily copy the rc.d
  65 script from the Tor port directory. Alternatively, you can ensure that the Tor's
  66 daemon user has its own user class and make a /etc/login.conf entry for it.
  67
  68 High-bandwidth relays sometimes give the syslog warning:
  69
  70 /bsd: WARNING: mclpools limit reached; increase kern.maxclusters
  71
  72 In this case, increase kern.maxclusters with the sysctl command and in the file
  73 /etc/sysctl.conf, as described with kern.maxfiles above. Use 'sysctl
  74 kern.maxclusters' to query the current value. Increasing by about 15% per day
  75 until the error no longer appears is a good guideline.
  76
  77 Disclaimer
  78 ----------
  79
  80 Do note that this document is a draft and above information may be
  81 technically incorrect and/or incomplete. If so, please open a ticket
  82 on https://gitlab.torproject.org or post to tor-relays mailing list.
  83
  84 Are you running a busy Tor relay? Let us know how you are solving
  85 the out-of-sockets problem on your system.