Tor Command syntax

gAtO wAnT’s – just the simple command syntax -from the OG-OR Roger Dingledine -Nick Mathewson the Tor gods.

href=”http://manpages.ubuntu.com/manpages/hardy/man8/tor.8.html#contenttoc6″>

 

NAME

       tor - The second-generation onion router

SYNOPSIS

       tor [OPTION value]...

DESCRIPTION

       tor  is  a connection-oriented anonymizing communication service. Users
       choose a source-routed path through a set of  nodes,  and  negotiate  a
       "virtual  circuit"  through  the  network, in which each node knows its
       predecessor and successor, but no  others.  Traffic  flowing  down  the
       circuit is unwrapped by a symmetric key at each node, which reveals the
       downstream node.

       Basically  tor  provides  a  distributed  network  of  servers  ("onion
       routers"). Users bounce their TCP streams -- web traffic, ftp, ssh, etc
       -- around the routers, and recipients, observers, and even the  routers
       themselves have difficulty tracking the source of the stream.

OPTIONS

       -h, -help Display a short help message and exit.

       -f FILE
              FILE   contains   further   "option   value"   pairs.  (Default:
              /etc/tor/torrc)

       --hash-password
              Generates a hashed password for control port access.

       --list-fingerprint
              Generate your keys and output your nickname and fingerprint.

       --verify-config
              Verify the configuration file is valid.

       --nt-service
              --service [install|remove|start|stop]  Manage  the  Tor  Windows
              NT/2000/XP  service.   Current  instructions  can  be  found  at
              http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#WinNTService

       --list-torrc-options
              List all valid options.

       --version
              Display Tor version.

       Other options can be specified either on the command-line (--option
              value),  or  in  the configuration file (option value).  Options
              are case-insensitive.

       BandwidthRate N bytes|KB|MB|GB|TB
              A token bucket limits the average incoming  bandwidth  usage  on
              this  node  to the specified number of bytes per second, and the
              average outgoing bandwidth usage to that same value. (Default: 3
              MB)

       BandwidthBurst N bytes|KB|MB|GB|TB
              Limit the maximum token bucket size (also known as the burst) to
              the given number of bytes in each direction. This  value  should
              be at least twice your BandwidthRate. (Default: 6 MB)

       MaxAdvertisedBandwidth N bytes|KB|MB|GB|TB
              If set, we will not advertise more than this amount of bandwidth
              for our BandwidthRate. Server operators who want to  reduce  the
              number  of clients who ask to build circuits through them (since
              this is proportional to  advertised  bandwidth  rate)  can  thus
              reduce the CPU demands on their server without impacting network
              performance.

       ConnLimit NUM
              The minimum number of file descriptors that must be available to
              the Tor process before it will start. Tor will ask the OS for as
              many file descriptors as the OS will allow (you can find this by
              "ulimit -H -n"). If this number is less than ConnLimit, then Tor
              will refuse to start.

              You probably don’t need to adjust this.  It  has  no  effect  on
              Windows since that platform lacks getrlimit(). (Default: 1000)

       ControlPort Port
              If set, Tor will accept connections on this port and allow those
              connections to control the Tor process  using  the  Tor  Control
              Protocol (described in control-spec.txt).  Note: unless you also
              specify one of  HashedControlPassword  or  CookieAuthentication,
              setting  this  option will cause Tor to allow any process on the
              local host to control it. This option is required for  many  Tor
              controllers; most use the value of 9051.

       ControlListenAddress IP[:PORT]
              Bind  the  controller listener to this address. If you specify a
              port, bind to  this  port  rather  than  the  one  specified  in
              ControlPort.  We  strongly  recommend  that you leave this alone
              unless you know what you’re doing, since giving attackers access
              to   your   control  listener  is  really  dangerous.  (Default:
              127.0.0.1) This directive can be  specified  multiple  times  to
              bind to multiple addresses/ports.

       HashedControlPassword hashed_password
              Don’t  allow any connections on the control port except when the
              other  process  knows  the  password  whose  one-way   hash   is
              hashed_password.   You  can  compute  the  hash of a password by
              running "tor --hash-password password".

       CookieAuthentication 0|1
              If this option is set to 1, don’t allow any connections  on  the
              control  port  except  when  the  connecting  process  knows the
              contents of a file named "control_auth_cookie", which  Tor  will
              create  in  its  data  directory.   This  authentication methods
              should only be used on systems with  good  filesystem  security.
              (Default: 0)

       DataDirectory DIR
              Store working data in DIR (Default: /var/lib/tor)

       DirServer [nickname] [flags] address:port fingerprint
              Use a nonstandard authoritative directory server at the provided
              address and port, with  the  specified  key  fingerprint.   This
              option  can  be  repeated many times, for multiple authoritative
              directory servers.  Flags are separated by spaces, and determine
              what  kind of an authority this directory is.  By default, every
              authority is authoritative for current ("v2")-style directories,
              unless  the  "no-v2"  flag  is  given.   If  the  "v1"  flags is
              provided, Tor will use this server as an authority for old-style
              (v1)  directories  as  well.  (Only directory mirrors care about
              this.)  Tor will use this server  as  an  authority  for  hidden
              service information if the "hs" flag is set, or if the "v1" flag
              is set and the "no-hs" flag is not set.  If a flag "orport=port"
              is  given,  Tor  will  use the given port when opening encrypted
              tunnels to the dirserver.  If no dirserver line  is  given,  Tor
              will  use  the  default directory servers.  NOTE: this option is
              intended for setting up a  private  Tor  network  with  its  own
              directory   authorities.    If   you   use   it,   you  will  be
              distinguishable from other users, because you won’t believe  the
              same authorities they do.

       FetchHidServDescriptors 0|1
              If set to 0, Tor will never fetch any hidden service descriptors
              from the rendezvous directories. This option is only  useful  if
              you’re  using  a Tor controller that handles hidserv fetches for
              you.  (Default: 1)

       FetchServerDescriptors 0|1
              If set to 0, Tor will never fetch any network  status  summaries
              or server descriptors from the directory servers. This option is
              only useful if  you’re  using  a  Tor  controller  that  handles
              directory fetches for you.  (Default: 1)

       FetchUselessDescriptors 0|1
              If  set  to 1, Tor will fetch every non-obsolete descriptor from
              the authorities that it hears about. Otherwise,  it  will  avoid
              fetching  useless  descriptors, for example for routers that are
              not  running.   This  option  is  useful  if  you’re  using  the
              contributed  "exitlist"  script to enumerate Tor nodes that exit
              to certain addresses.  (Default: 0)

       Group GID
              On startup, setgid to this group.

       HttpProxy host[:port]
              Tor will make all its directory requests through this  host:port
              (or  host:80  if  port is not specified), rather than connecting
              directly to any directory servers.

       HttpProxyAuthenticator username:password
              If defined, Tor will use this username:password for  Basic  Http
              proxy authentication, as in RFC 2617. This is currently the only
              form of Http proxy authentication that Tor supports;  feel  free
              to submit a patch if you want it to support others.

       HttpsProxy host[:port]
              Tor  will  make  all  its  OR  (SSL)  connections  through  this
              host:port (or host:443 if  port  is  not  specified),  via  HTTP
              CONNECT  rather  than  connecting  directly to servers.  You may
              want to set FascistFirewall to restrict the  set  of  ports  you
              might  try  to  connect  to,  if  your  Https  proxy only allows
              connecting to certain ports.

       HttpsProxyAuthenticator username:password
              If defined, Tor will use this username:password for Basic  Https
              proxy authentication, as in RFC 2617. This is currently the only
              form of Https proxy authentication that Tor supports; feel  free
              to submit a patch if you want it to support others.

       KeepalivePeriod NUM
              To  keep  firewalls  from  expiring  connections, send a padding
              keepalive cell every NUM seconds on open connections that are in
              use.  If the connection has no open circuits, it will instead be
              closed after NUM seconds of idleness. (Default: 5 minutes)

       Log minSeverity[-maxSeverity] stderr|stdout|syslog
              Send all messages between minSeverity  and  maxSeverity  to  the
              standard  output  stream,  the  standard error stream, or to the
              system log. (The "syslog" value  is  only  supported  on  Unix.)
              Recognized  severity  levels  are debug, info, notice, warn, and
              err.  We advise using "notice" in  most  cases,  since  anything
              more  verbose  may  provide sensitive information to an attacker
              who obtains the logs.  If only one severity level is given,  all
              messages  of  that  level  or  higher will be sent to the listed
              destination.

       Log minSeverity[-maxSeverity] file FILENAME
              As above, but send log messages to  the  listed  filename.   The
              "Log"  option may appear more than once in a configuration file.
              Messages are sent to all the  logs  that  match  their  severity
              level.

       OutboundBindAddress IP
              Make  all  outbound  connections  originate  from the IP address
              specified.  This is only useful when you have  multiple  network
              interfaces,  and  you  want all of Tor’s outgoing connections to
              use a single one.

       PidFile FILE
              On startup, write our PID to FILE.  On  clean  shutdown,  remove
              FILE.

       ProtocolWarnings 0|1
              If  1,  Tor will log with severity ’warn’ various cases of other
              parties not following the Tor specification. Otherwise, they are
              logged with severity ’info’. (Default: 0)

       RunAsDaemon 0|1
              If  1,  Tor  forks and daemonizes to the background. This option
              has no effect on Windows; instead you should use  the  --service
              command-line option. (Default: 0)

       SafeLogging 0|1
              If  1,  Tor  replaces  potentially sensitive strings in the logs
              (e.g. addresses) with the string [scrubbed]. This way  logs  can
              still   be  useful,  but  they  don’t  leave  behind  personally
              identifying information about  what  sites  a  user  might  have
              visited. (Default: 1)

       User UID
              On startup, setuid to this user.

       HardwareAccel 0|1
              If  non-zero,  try  to  use  crypto  hardware  acceleration when
              available. This is untested and probably buggy. (Default: 0)

       AvoidDiskWrites 0|1
              If non-zero, try to write to disk less frequently than we  would
              otherwise.  This is useful when running on flash memory or other
              media that support only a limited number of  writes.   (Default:
              0)

       TunnelDirConns 0|1
              If  non-zero, when a directory server we contact supports it, we
              will build a one-hop circuit and make  an  encrypted  connection
              via its ORPort. (Default: 0)

       PreferTunneledDirConns 0|1
              If  non-zero, we will avoid directory servers that don’t support
              tunneled directory connections, when possible. (Default: 0)

CLIENT OPTIONS

       The following  options  are  useful  only  for  clients  (that  is,  if
       SocksPort is non-zero):

       AllowInvalidNodes entry|exit|middle|introduction|rendezvous|...
              If  some  Tor  servers  are  obviously  not  working  right, the
              directory authorities can manually mark them as invalid, meaning
              that  it’s  not  recommended  you  use  them  for  entry or exit
              positions in your circuits. You can opt  to  use  them  in  some
              circuit  positions,  though. The default is "middle,rendezvous",
              and other choices are not advised.

       CircuitBuildTimeout NUM
              Try for at most NUM  seconds  when  building  circuits.  If  the
              circuit  isn’t  open  in  that time, give up on it.  (Default: 1
              minute.)

       CircuitIdleTimeout NUM
              If we have keept a clean (never used)  circuit  around  for  NUM
              seconds, then close it. This way when the Tor client is entirely
              idle, it can expire all of its circuits, and then expire its TLS
              connections.  Also,  if  we  end up making a circuit that is not
              useful for exiting any of the requests we’re receiving, it won’t
              forever  take up a slot in the circuit list.  (Default: 1 hour.)

       ClientOnly 0|1
              If set to 1, Tor will under no circumstances run  as  a  server.
              The  default  is to run as a client unless ORPort is configured.
              (Usually, you don’t need to set this; Tor  is  pretty  smart  at
              figuring  out whether you are reliable and high-bandwidth enough
              to be a useful server.)  (Default: 0)

       ExcludeNodes nickname,nickname,...
              A list of nodes to never use when building a circuit.

       EntryNodes nickname,nickname,...
              A list of preferred nodes to  use  for  the  first  hop  in  the
              circuit.    These   are   treated  only  as  preferences  unless
              StrictEntryNodes (see below) is also set.

       ExitNodes nickname,nickname,...
              A list of preferred nodes  to  use  for  the  last  hop  in  the
              circuit.    These   are   treated  only  as  preferences  unless
              StrictExitNodes (see below) is also set.

       StrictEntryNodes 0|1
              If 1, Tor will never use  any  nodes  besides  those  listed  in
              "EntryNodes" for the first hop of a circuit.

       StrictExitNodes 0|1
              If  1,  Tor  will  never  use  any nodes besides those listed in
              "ExitNodes" for the last hop of a circuit.

       FascistFirewall 0|1
              If 1, Tor will only create outgoing connections to  ORs  running
              on  ports that your firewall allows (defaults to 80 and 443; see
              FirewallPorts).  This will allow you to  run  Tor  as  a  client
              behind  a firewall with restrictive policies, but will not allow
              you to run as a server behind such a firewall.  This  option  is
              deprecated; use ReachableAddresses instead.

       FirewallPorts PORTS
              A  list  of  ports  that your firewall allows you to connect to.
              Only  used  when  FascistFirewall  is  set.   This   option   is
              deprecated; use ReachableAddresses instead. (Default: 80, 443)

       ReachableAddresses ADDR[/MASK][:PORT]...
              A  comma-separated  list  of  IP  addresses  and ports that your
              firewall allows you to connect to. The  format  is  as  for  the
              addresses  in  ExitPolicy,  except  that  "accept" is understood
              unless  "reject"   is   explicitly   provided.    For   example,
              ’ReachableAddresses  99.0.0.0/8,  reject  18.0.0.0/8:80,  accept
              *:80’ means that your firewall allows connections to  everything
              inside  net  99,  rejects  port  80  connections  to net 18, and
              accepts connections to port  80  otherwise.   (Default:  ’accept
              *:*’.)

       ReachableDirAddresses ADDR[/MASK][:PORT]...
              Like  ReachableAddresses,  a  list  of addresses and ports.  Tor
              will   obey   these   restrictions   when   fetching   directory
              information,  using  standard  HTTP  GET  requests.  If  not set
              explicitly then the value of  ReachableAddresses  is  used.   If
              HttpProxy  is  set  then  these connections will go through that
              proxy.

       ReachableORAddresses ADDR[/MASK][:PORT]...
              Like ReachableAddresses, a list of  addresses  and  ports.   Tor
              will  obey  these restrictions when connecting to Onion Routers,
              using  TLS/SSL.   If  not  set  explicitly  then  the  value  of
              ReachableAddresses  is  used.  If  HttpsProxy  is set then these
              connections will go through that proxy.

              The     separation     between     ReachableORAddresses      and
              ReachableDirAddresses   is   only   interesting   when  you  are
              connecting through proxies (see HttpProxy and HttpsProxy).  Most
              proxies  limit  TLS  connections  (which  Tor uses to connect to
              Onion Routers) to port 443, and some  limit  HTTP  GET  requests
              (which  Tor uses for fetching directory information) to port 80.

       LongLivedPorts PORTS
              A list of ports for services  that  tend  to  have  long-running
              connections  (e.g.  chat  and  interactive shells). Circuits for
              streams that use  these  ports  will  contain  only  high-uptime
              nodes,  to reduce the chance that a node will go down before the
              stream is finished.  (Default: 21, 22, 706,  1863,  5050,  5190,
              5222, 5223, 6667, 6697, 8300)

       MapAddress address newaddress
              When a request for address arrives to Tor, it will rewrite it to
              newaddress before processing it. For example, if you always want
              connections  to  www.indymedia.org  to exit via torserver (where
              torserver is  the  nickname  of  the  server),  use  "MapAddress
              www.indymedia.org www.indymedia.org.torserver.exit".

       NewCircuitPeriod NUM
              Every  NUM  seconds  consider  whether  to  build a new circuit.
              (Default: 30 seconds)

       MaxCircuitDirtiness NUM
              Feel free to reuse a circuit that was first  used  at  most  NUM
              seconds  ago, but never attach a new stream to a circuit that is
              too old.  (Default: 10 minutes)

       EnforceDistinctSubnets 0|1
              If 1, Tor will not put two servers whose IP addresses  are  "too
              close"  on  the same circuit.  Currently, two addresses are "too
              close" if they lie in the same /16 range. (Default: 1)

       RendNodes nickname,nickname,...
              A list of preferred nodes to use for the  rendezvous  point,  if
              possible.

       RendExcludeNodes nickname,nickname,...
              A list of nodes to never use when choosing a rendezvous point.

       SocksPort PORT
              Advertise  this  port  to  listen  for  connections  from Socks-
              speaking applications.  Set this to 0 if you don’t want to allow
              application connections. (Default: 9050)

       SocksListenAddress IP[:PORT]
              Bind  to  this  address  to  listen  for connections from Socks-
              speaking applications. (Default: 127.0.0.1) You can also specify
              a port (e.g. 192.168.0.1:9100).  This directive can be specified
              multiple times to bind to multiple addresses/ports.

       SocksPolicy policy,policy,...
              Set an entrance policy for this server, to limit who can connect
              to  the  Socks  ports.   The policies have the same form as exit
              policies below.

       SocksTimeout NUM
              Let a socks connection wait NUM  seconds  handshaking,  and  NUM
              seconds unattached waiting for an appropriate circuit, before we
              fail it.  (Default: 2 minutes.)

       TestVia nickname,nickname,...
              A list of nodes to prefer for  your  middle  hop  when  building
              testing   circuits.   This   option   is  mainly  for  debugging
              reachability problems.

       TrackHostExits host,.domain,...
              For each value in the  comma  separated  list,  Tor  will  track
              recent connections to hosts that match this value and attempt to
              reuse the same exit node for each. If  the  value  is  prepended
              with  a  ’.’, it is treated as matching an entire domain. If one
              of the values is just a ’.’, it  means  match  everything.  This
              option  is  useful  if you frequently connect to sites that will
              expire all your authentication cookies (ie log you out) if  your
              IP  address  changes.  Note  that  this  option  does  have  the
              disadvantage of making it more clear that  a  given  history  is
              associated  with  a  single user. However, most people who would
              wish to observe this will observe it through  cookies  or  other
              protocol-specific means anyhow.

       TrackHostExitsExpire NUM
              Since exit servers go up and down, it is desirable to expire the
              association between host and exit server after NUM seconds.  The
              default is 1800 seconds (30 minutes).

       UseEntryGuards 0|1
              If  this  option  is  set  to  1,  we pick a few long-term entry
              servers, and try to stick with them.  This is desirable  because
              constantly changing servers increases the odds that an adversary
              who owns some servers will observe a  fraction  of  your  paths.
              (Defaults to 1.)

       NumEntryGuards NUM
              If  UseEntryGuards  is  set to 1, we will try to pick a total of
              NUM routers as long-term entries for our circuits.  (Defaults to
              3.)

       SafeSocks 0|1
              When  this  option  is  enabled,  Tor  will  reject  application
              connections that use unsafe variants of the  socks  protocol  --
              ones that only provide an IP address, meaning the application is
              doing a DNS resolve first.  Specifically, these are  socks4  and
              socks5 when not doing remote DNS.  (Defaults to 0.)

       TestSocks 0|1
              When  this  option  is enabled, Tor will make a notice-level log
              entry for each connection to the Socks port  indicating  whether
              the  request  used  a  safe socks protocol or an unsafe one (see
              above entry on SafeSocks).  This helps to determine  whether  an
              application   using   Tor  is  possibly  leaking  DNS  requests.
              (Default: 0)

       VirtualAddrNetwork Address/bits
              When a controller asks for a virtual (unused) address  with  the
              MAPADDRESS  command,  Tor  picks an unassigned address from this
              range.  (Default: 127.192.0.0/10)

              When providing proxy server service to a  network  of  computers
              using   a  tool  like  dns-proxy-tor,  change  this  address  to
              "10.192.0.0/10"     or     "172.16.0.0/12".      The     default
              VirtualAddrNetwork   address  range  on  a  properly  configured
              machine will route to the loopback interface.  For local use, no
              change to the default VirtualAddrNetwork setting is needed.

       AllowNonRFC953Hostnames 0|1
              When  this  option  is disabled, Tor blocks hostnames containing
              illegal characters (like @ and :) rather than sending them to an
              exit  node  to be resolved.  This helps trap accidental attempts
              to resolve URLs and so on.  (Default: 0)

       FastFirstHopPK 0|1
              When this option is enabled and we aren’t running as  a  server,
              Tor  skips  the  public  key  step for the first hop of creating
              circuits.  This is safe  since  we  have  already  used  TLS  to
              authenticate  the  server  and to establish forward-secure keys.
              Turning  this  option  off  makes   circuit   building   slower.
              (Default: 1)

       TransPort PORT
              If  non-zero,  enables  transparent  proxy  support  on PORT (by
              convention, 9040).  Requires OS support for transparent proxies,
              such as BSDs’ pf or Linux’s IPTables.  If you’re planning to use
              Tor as a transparent proxy for a network, you’ll want to examine
              and  change  VirtualAddrNetwork from the default setting. You’ll
              also want to set the TransListenAddress option for  the  network
              you’d like to proxy.  (Default: 0).

       TransListenAddress IP[:PORT]
              Bind   to   this   address   to  listen  for  transparent  proxy
              connections.   (Default:  127.0.0.1).   This   is   useful   for
              exporting a transparent proxy server to an entire network.

       NATDPort PORT
              Allow  old  versions  of  ipfw  (as  included in old versions of
              FreeBSD, etc.) to send connections through Tor  using  the  NATD
              protocol.   This  option  is  only  for  people  who  cannot use
              TransPort.

       NATDListenAddress IP[:PORT]
              Bind to this address to listen for NATD connections.   (Default:
              127.0.0.1).

       SERVER OPTIONS

       The  following  options are useful only for servers (that is, if ORPort
       is non-zero):

       Address address
              The IP or fqdn of this  server  (e.g.  moria.mit.edu).  You  can
              leave this unset, and Tor will guess your IP.

       AssumeReachable 0|1
              This option is used when bootstrapping a new Tor network. If set
              to 1, don’t  do  self-reachability  testing;  just  upload  your
              server descriptor immediately. If AuthoritativeDirectory is also
              set, this  option  instructs  the  dirserver  to  bypass  remote
              reachability  testing  too  and  list  all  connected servers as
              running.

       ContactInfo email_address
              Administrative contact information for server. This  line  might
              get picked up by spam harvesters, so you may want to obscure the
              fact that it’s an email address.

       ExitPolicy policy,policy,...
              Set an exit policy for this server. Each policy is of  the  form
              "accept|reject  ADDR[/MASK][:PORT]".   If  /MASK is omitted then
              this policy just applies to the host given.  Instead of giving a
              host  or  network  you  can  also use "*" to denote the universe
              (0.0.0.0/0).  PORT can be a single port number, an  interval  of
              ports  "FROM_PORT-TO_PORT",  or  "*".   If PORT is omitted, that
              means "*".

              For  example,  "accept  18.7.22.69:*,reject  18.0.0.0/8:*,accept
              *:*"  would  reject  any  traffic  destined  for  MIT except for
              web.mit.edu, and accept anything else.

              To specify  all  internal  and  link-local  networks  (including
              0.0.0.0/8,    169.254.0.0/16,    127.0.0.0/8,    192.168.0.0/16,
              10.0.0.0/8, and 172.16.0.0/12), you can use the "private"  alias
              instead  of an address.  These addresses are rejected by default
              (at the beginning of your exit policy), along with  your  public
              IP  address,  unless  you set the ExitPolicyRejectPrivate config
              option to 0. For example, once you’ve done that, you could allow
              HTTP  to  127.0.0.1  and block all other connections to internal
              networks with  "accept  127.0.0.1:80,reject  private:*",  though
              that  may  also  allow connections to your own computer that are
              addressed to its public (external) IP address. See RFC 1918  and
              RFC 3330 for more details about internal and reserved IP address
              space.

              This directive can be specified multiple times so you don’t have
              to put it all on one line.

              Policies are considered first to last, and the first match wins.
              If you want to _replace_ the default exit policy, end your  exit
              policy  with  either  a  reject *:* or an accept *:*. Otherwise,
              you’re _augmenting_ (prepending to) the default exit policy. The
              default exit policy is:
                   reject *:25
                   reject *:119
                   reject *:135-139
                   reject *:445
                   reject *:465
                   reject *:563
                   reject *:587
                   reject *:1214
                   reject *:4661-4666
                   reject *:6346-6429
                   reject *:6699
                   reject *:6881-6999
                   accept *:*

       ExitPolicyRejectPrivate 0|1
              Reject  all private (local) networks, along with your own public
              IP address, at the beginning of  your  exit  policy.  See  above
              entry on ExitPolicy. (Default: 1)

       MaxOnionsPending NUM
              If  you  have  more  than  this  number of onionskins queued for
              decrypt, reject new ones. (Default: 100)

       MyFamily nickname,nickname,...
              Declare that this Tor server is controlled or administered by  a
              group  or organization identical or similar to that of the other
              named servers.  When two servers both declare that they  are  in
              the  same  ’family’,  Tor  clients will not use them in the same
              circuit.  (Each server only needs to list the other  servers  in
              its  family; it doesn’t need to list itself, but it won’t hurt.)

       Nickname name
              Set the server’s nickname to ’name’. Nicknames must be between 1
              and   19   characters  inclusive,  and  must  contain  only  the
              characters [a-zA-Z0-9].

       NumCPUs num
              How many processes to use at  once  for  decrypting  onionskins.
              (Default: 1)

       ORPort PORT
              Advertise  this  port to listen for connections from Tor clients
              and servers.

       ORListenAddress IP[:PORT]
              Bind to this IP address  to  listen  for  connections  from  Tor
              clients  and  servers.  If you specify a port, bind to this port
              rather than the one specified in ORPort. (Default: 0.0.0.0) This
              directive  can  be  specified multiple times to bind to multiple
              addresses/ports.

       PublishServerDescriptor 0|1
              If set to 0, Tor will act as a server  if  you  have  an  ORPort
              defined,   but  it  will  not  publish  its  descriptor  to  the
              dirservers. This option is useful if  you’re  testing  out  your
              server,  or  if  you’re  using  a  Tor  controller  that handles
              directory publishing for you.  (Default: 1)

       RedirectExit pattern target
              Whenever an outgoing connection tries to connect  to  one  of  a
              given set of addresses, connect to target (an address:port pair)
              instead.  The address pattern is given in the same format as for
              an  exit  policy.   The  address  translation applies after exit
              policies are applied.   Multiple  RedirectExit  options  can  be
              used: once any one has matched successfully, no subsequent rules
              are considered.  You can specify that no redirection  is  to  be
              performed  on  a  given  set  of  addresses by using the special
              target string "pass", which prevents subsequent rules from being
              considered.

       ShutdownWaitLength NUM
              When we get a SIGINT and we’re a server, we begin shutting down:
              we close listeners and start refusing new  circuits.  After  NUM
              seconds,   we   exit.  If  we  get  a  second  SIGINT,  we  exit
              immediately.  (Default: 30 seconds)

       AccountingMax N bytes|KB|MB|GB|TB
              Never send more than the specified number of bytes  in  a  given
              accounting  period,  or  receive  more  than  that number in the
              period.  For example, with AccountingMax set to 1 GB,  a  server
              could  send  900  MB and receive 800 MB and continue running. It
              will only hibernate once one of the two reaches 1 GB.  When  the
              number of bytes is exhausted, Tor will hibernate until some time
              in the next accounting period.   To  prevent  all  servers  from
              waking at the same time, Tor will also wait until a random point
              in each period before waking up.  If  you  have  bandwidth  cost
              issues,  enabling  hibernation  is  preferable  to setting a low
              bandwidth, since it provides users with  a  collection  of  fast
              servers  that are up some of the time, which is more useful than
              a set of slow servers that are always "available".

       AccountingStart day|week|month [day] HH:MM
              Specify how long accounting periods last.  If  month  is  given,
              each accounting period runs from the time HH:MM on the dayth day
              of one month to the same day and time of  the  next.   (The  day
              must  be  between  1 and 28.)  If week is given, each accounting
              period runs from the time HH:MM of the dayth day of one week  to
              the same day and time of the next week, with Monday as day 1 and
              Sunday as day 7.  If day is given, each accounting  period  runs
              from  the  time HH:MM each day to the same time on the next day.
              All times are local, and given in 24-hour  time.   (Defaults  to
              "month 1 0:00".)

       ServerDNSResolvConfFile filename
              Overrides  the  default DNS configuration with the configuration
              in filename.  The file format is the same as the  standard  Unix
              "resolv.conf"  file  (7).  This option, like all other ServerDNS
              options, only affects name  lookup  that  your  server  does  on
              behalf  of clients.  Also, it only takes effect if Tor was built
              with  eventdns  support.   (Defaults  to  use  the  system   DNS
              configuration.)

       ServerDNSSearchDomains 0|1
              If  set  to  1,  then  we will search for addresses in the local
              search domain.  For example, if this  system  is  configured  to
              believe it is in "example.com", and a client tries to connect to
              "www", the client will be connected to "www.example.com".   This
              option  only affects name lookup that your server does on behalf
              of clients, and only takes effect if Tor was build with eventdns
              support.  (Defaults to "0".)

       ServerDNSDetectHijacking 0|1
              When  this  option  is  set  to  1, we will test periodically to
              determine whether our local nameservers have been configured  to
              hijack  failing  DNS  requests (usually to an advertising site).
              If they are, we will attempt to correct this.  This option  only
              affects  name lookup that your server does on behalf of clients,
              and only takes effect if Tor was build  with  eventdns  support.
              (Defaults to "1".)

       ServerDNSTestAddresses address,address,...
              When  we’re  detecting DNS hijacking, make sure that these valid
              addresses aren’t getting redirected.  If they are, then our  DNS
              is  completely  useless,  and  we’ll  reset  our  exit policy to
              "reject *:*".  This option only affects name  lookup  that  your
              server  does  on behalf of clients, and only takes effect if Tor
              was build with eventdns support.  (Defaults to  "www.google.com,
              www.mit.edu, www.yahoo.com, www.slashdot.org".)

       ServerDNSAllowNonRFC953Hostnames 0|1
              When  this  option  is  disabled,  Tor  does  not try to resolve
              hostnames containing illegal characters (like @  and  :)  rather
              than  sending  them  to an exit node to be resolved.  This helps
              trap accidental attempts to resolve URLs and so on.  This option
              only  affects  name  lookup  that  your server does on behalf of
              clients, and only takes effect if Tor was  build  with  eventdns
              support.  (Default: 0)

DIRECTORY SERVER OPTIONS

       The  following  options are useful only for directory servers (that is,
       if DirPort is non-zero):

       AuthoritativeDirectory 0|1
              When this option is set to 1, Tor operates as  an  authoritative
              directory   server.    Instead  of  caching  the  directory,  it
              generates its own list of good servers, signs it, and sends that
              to the clients.  Unless the clients already have you listed as a
              trusted directory, you probably do not want to set this  option.
              Please coordinate with the other admins at tor-ops@freehaven.net
              if you think you should be a directory.

       V1AuthoritativeDirectory 0|1
              When this option is set in addition  to  AuthoritativeDirectory,
              Tor  also generates a version 1 directory (for Tor clients up to
              0.1.0.x).   (As  of  Tor  0.1.1.12  every   (v2)   authoritative
              directory still provides most of the v1 directory functionality,
              even without this option set to 1.  This however is expected  to
              change in the future.)

       VersioningAuthoritativeDirectory 0|1
              When  this  option  is  set  to 1, Tor adds information on which
              versions of Tor are still believed safe for use to the published
              directory.    Each   version  1  authority  is  automatically  a
              versioning authority; version 2 authorities provide this service
              optionally.  See RecommendedVersions, RecommendedClientVersions,
              and RecommendedServerVersions.

       NamingAuthoritativeDirectory 0|1
              When this option is set to 1, then the server advertises that it
              has  opinions  about  nickname-to-fingerprint bindings.  It will
              include these opinions in its published network-status pages, by
              listing  servers  with  the  flag  "Named"  if a correct binding
              between that nickname and fingerprint has been  registered  with
              the  dirserver.   Naming  dirservers  will  refuse  to accept or
              publish descriptors that contradict a registered  binding.   See
              approved-routers in the FILES section below.

       HSAuthoritativeDir 0|1
              When  this  option is set in addition to AuthoritativeDirectory,
              Tor  also  accepts  and  serves  hidden   service   descriptors.
              (Default: 0)

       DirPort PORT
              Advertise the directory service on this port.

       DirListenAddress IP[:PORT]
              Bind  the  directory  service  to this address. If you specify a
              port, bind to  this  port  rather  than  the  one  specified  in
              DirPort.  (Default:  0.0.0.0)  This  directive  can be specified
              multiple times to bind to multiple addresses/ports.

       DirPolicy policy,policy,...
              Set an entrance policy for this server, to limit who can connect
              to the directory ports.  The policies have the same form as exit
              policies above.

       RecommendedVersions STRING
              STRING is a  comma-separated  list  of  Tor  versions  currently
              believed to be safe. The list is included in each directory, and
              nodes which pull down the directory learn whether they  need  to
              upgrade.  This option can appear multiple times: the values from
              multiple lines are spliced together.   When  this  is  set  then
              VersioningAuthoritativeDirectory should be set too.

       RecommendedClientVersions STRING
              STRING  is  a  comma-separated  list  of  Tor versions currently
              believed to be safe for clients to  use.   This  information  is
              included  in version 2 directories.  If this is not set then the
              value of RecommendedVersions is used.  When  this  is  set  then
              VersioningAuthoritativeDirectory should be set too.

       RecommendedServerVersions STRING
              STRING  is  a  comma-separated  list  of  Tor versions currently
              believed to be safe for servers to  use.   This  information  is
              included  in version 2 directories.  If this is not set then the
              value of RecommendedVersions is used.  When  this  is  set  then
              VersioningAuthoritativeDirectory should be set too.

       DirAllowPrivateAddresses 0|1
              If  set  to 1, Tor will accept router descriptors with arbitrary
              "Address" elements. Otherwise, if the address is not an IP or is
              a  private IP, it will reject the router descriptor. Defaults to
              0.

       AuthDirBadExit AddressPattern...
              Authoritative directories only.  A set of address  patterns  for
              servers  that  will be listed as bad exits in any network status
              document this authority  publishes,  if  AuthDirListBadExits  is
              set.

       AuthDirInvalid AddressPattern...
              Authoritative  directories  only.  A set of address patterns for
              servers that will never be listed  as  "valid"  in  any  network
              status document that this authority publishes.

       AuthDirReject AddressPattern...
              Authoritative  directories  only.  A set of address patterns for
              servers that will never be listed at all in any  network  status
              document  that  this  authority  publishes, or accepted as an OR
              address in any descriptor  submitted  for  publication  by  this
              authority.

       AuthDirListBadExits 0|1
              Authoritative directories only.  If set to 1, this directory has
              some opinion about which nodes are  unsuitable  as  exit  nodes.
              (Do  not  set  this  to 1 unless you plan to list nonfunctioning
              exits as bad; otherwise, you are effectively voting in favor  of
              every declared exit as an exit.)

       AuthDirRejectUnlisted 0|1
              Authoritative  directories  only.   If  set  to 1, the directory
              server rejects  all  uploaded  server  descriptors  that  aren’t
              explicitly  listed  in  the  fingerprints  file.  This acts as a
              "panic button" if we get Sybiled. (Default: 0)

HIDDEN SERVICE OPTIONS

       The following options are used to configure a hidden service.

       HiddenServiceDir DIRECTORY
              Store data files for  a  hidden  service  in  DIRECTORY.   Every
              hidden service must have a separate directory.  You may use this
              option multiple times to specify multiple services.

       HiddenServicePort VIRTPORT [TARGET]
              Configure a virtual port VIRTPORT for a hidden service.  You may
              use this option multiple times; each time applies to the service
              using the most recent hiddenservicedir.  By default, this option
              maps  the  virtual  port to the same port on 127.0.0.1.  You may
              override the target port,  address,  or  both  by  specifying  a
              target of addr, port, or addr:port.

       HiddenServiceNodes nickname,nickname,...
              If  possible, use the specified nodes as introduction points for
              the hidden service. If this is left unset, Tor will be smart and
              pick some reasonable ones; most people can leave this unset.

       HiddenServiceExcludeNodes nickname,nickname,...
              Do  not  use  the specified nodes as introduction points for the
              hidden service. In normal use there is no reason to set this.

       PublishHidServDescriptors 0|1
              If set to 0, Tor will run any hidden services you configure, but
              it won’t advertise them to the rendezvous directory. This option
              is only useful if you’re using a  Tor  controller  that  handles
              hidserv publishing for you.  (Default: 1)

       RendPostPeriod N seconds|minutes|hours|days|weeks
              Every  time  the  specified  period  elapses,  Tor  uploads  any
              rendezvous service descriptors to the directory  servers.   This
              information  is also uploaded whenever it changes.  (Default: 20
              minutes)

SIGNALS

       Tor catches the following signals:

       SIGTERM
              Tor will catch this, clean up and sync to disk if necessary, and
              exit.

       SIGINT Tor  clients  behave  as with SIGTERM; but Tor servers will do a
              controlled slow  shutdown,  closing  listeners  and  waiting  30
              seconds  before  exiting.  (The delay can be configured with the
              ShutdownWaitLength config option.)

       SIGHUP The signal instructs Tor to reload its configuration  (including
              closing and reopening logs), fetch a new directory, and kill and
              restart its helper processes if applicable.

       SIGUSR1
              Log statistics about current connections, past connections,  and
              throughput.

       SIGUSR2
              Switch  all  logs  to loglevel debug. You can go back to the old
              loglevels by sending a SIGHUP.

       SIGCHLD
              Tor receives this signal when one of its  helper  processes  has
              exited, so it can clean up.

       SIGPIPE
              Tor catches this signal and ignores it.

       SIGXFSZ
              If  this signal exists on your platform, Tor catches and ignores
              it.

FILES

       /etc/tor/torrc
              The configuration file, which contains "option value" pairs.

       /var/lib/tor/
              The tor process stores keys and other data here.

       DataDirectory/cached-status/*
              The most recently downloaded network status  document  for  each
              authority.  Each file holds one such document; the filenames are
              the hexadecimal  identity  key  fingerprints  of  the  directory
              authorities.

       DataDirectory/cached-routers and cached-routers.new
              These  files  hold downloaded router statuses.  Some routers may
              appear more than  once;  if  so,  the  most  recently  published
              descriptor  is used.  The ".new" file is an append-only journal;
              when it gets too large,  all  entries  are  merged  into  a  new
              cached-routers file.

       DataDirectory/state
              A set of persistent key-value mappings.  These are documented in
              the file.  These include:
            - The current entry guards and their status.
            - The current bandwidth accounting  values  (unused  so  far;  see
            below).
            - When the file was last written
            - What version of Tor generated the state file
            - A short history of bandwidth usage, as produced  in  the  router
            descriptors.

       DataDirectory/bw_accounting
              Used to track bandwidth  accounting  values  (when  the  current
              period  starts  and  ends; how much has been read and written so
              far this period).  This file is obsolete, and the  data  is  now
              stored  in  the  ’state’ file as well.  Only used when bandwidth
              accounting is enabled.

       DataDirectory/control_auth_cookie
              Used for cookie authentication with the controller.  Regenerated
              on  startup.   See control-spec.txt for details.  Only used when
              cookie authentication is enabled.

       DataDirectory/keys/*
              Only used by servers.  Holds identity keys and onion keys.

       DataDirectory/fingerprint
              Only used by servers.  Holds the  fingerprint  of  the  server’s
              identity key.

       DataDirectory/approved-routers
              Only   for   naming   authoritative   directory   servers   (see
              NamingAuthoritativeDirectory).   This  file  lists  nickname  to
              identity bindings.  Each line lists a nickname and a fingerprint
              separated by whitespace.   See  your  fingerprint  file  in  the
              DataDirectory  for  an example line.  If the nickname is !reject
              then descriptors  from  the  given  identity  (fingerprint)  are
              rejected  by this server. If it is !invalid then descriptors are
              accepted but marked in the directory as not valid, that is,  not
              recommended.

       HiddenServiceDirectory/hostname
              The  <base32-encoded-fingerprint>.onion  domain  name  for  this
              hidden service.

       HiddenServiceDirectory/private_key
              The private key for this hidden service.

SEE ALSO

       privoxy(1), tsocks(1), torify(1)

       https://www.torproject.org/

BUGS

       Plenty, probably. Tor is still in development. Please report them.

AUTHORS

       Roger Dingledine <arma@mit.edu>, Nick Mathewson <nickm@alum.mit.edu>.