puppet module for managing tor
==============================

This module tries to manage tor, making sure it is installed, running, has munin
graphs if desired and allows for configuration of relays, hidden services, exit
policies, etc.

! Upgrade Notice !

 the tor::relay{} variables $bandwidth_rate and $bandwidth_burst were previously
 used for the tor configuration variables RelayBandwidthRate and
 RelayBandwidthBurst, these have been renamed to $relay_bandwidth_rate and
 $relay_bandwidth_burst. If you were using these, please rename your variables in
 your configuration.

 The variables $bandwidth_rate and $bandwidth_burst are now used for the tor
 configuration variables BandwidthRate and BandwidthBurst. If you used
 $bandwidth_rate or $bandwidth_burst please be aware that these values have
 changed and adjust your configuration as necessary.


Usage
=====

Installing tor
--------------

To install tor, simply include the 'tor' class in your manifests:

    include tor

You can specify $tor_ensure_version and $torsocks_ensure_version to get a
specific version installed.

However, if you want to make configuration changes to your tor daemon, you will
want to instead include the 'tor::daemon' class in your manifests, which will
inherit the 'tor' class from above:

    include tor::daemon

You have the following tor global variables that you can adjust in your node scope:

$data_dir    = '/var/lib/tor'
$config_file = '/etc/tor/torrc'
$log_rules   = 'notice file /var/log/tor/notices.log'

The $data_dir will be used for the tor user's $HOME, and the tor DataDirectory
value. The $config_file will be managed and the daemon restarted when it
changed.

The $log_rules can be an array of different Log lines, each will be added to the
config, for example the following will use syslog:

  tor::daemon::global_opts { "use_syslog": log_rules => [ 'notice syslog' ]; }

Configuring socks
-----------------

To configure tor socks support, you can do the following:

  tor::daemon::socks { "listen_locally": listen_addresses => [ '127.0.0.1' ]; }

this will setup the SocksListenAddress to be 127.0.0.1. You also can pass the
following options to tor::daemon::socks:

$port = 0       - SocksPort
$listen_address - can pass multiple values to configure SocksListenAddress lines
$policies       - can pass multiple values to configure SocksPolicy lines


Configuring relays
==================

An example relay configuration:

 tor::daemon::relay { "foobar":
   port => 9001, listen_addresses => '192.168.0.1', address => '192.168.0.1',
   bandwidth_rate => '256', bandwidth_burst => '256', contact_info => "Foo <collective at example dot com>",
   my_family => '<long family string here>'
 }

You have the following options that can be passed to a relay, with the defaults shown:
 
$port                    = 0,
$listen_addresses        = [],
$bandwidth_rate          = '',    # KB/s, defaulting to using tor's default: 5120KB/s
$bandwidth_burst         = '',    # KB/s, defaulting to using tor's default: 10240KB/s
$relay_bandwidth_rate    = 0,     # KB/s, 0 for no limit.
$relay_bandwidth_burst   = 0,     # KB/s, 0 for no limit.
$accounting_max          = 0,     # GB, 0 for no limit.
$accounting_start        = [],
$contact_info            = '',
$my_family               = '', # TODO: autofill with other relays
$address                 = "tor.${domain}",
$bridge_relay            = 0,
$ensure                  = present
$nickname                = $name

Configuring the control 
-----------------------

To pass parameters to configure the ControlPort and the HashedControlPassword,
you would do something like this:

 tor::daemon::control { "foo-control": 
  port => '80', hashed_control_password => '<somehash>',
  ensure => present 
}

Note: you must pass a hashed password to the control port, if you are going to
use it.


Configuring hidden services
---------------------------

To configure a tor hidden service you can do something like the following:

 tor::daemon::hidden_service { "hidden_ssh": ports => 22 }

The HiddenServiceDir is set to the ${data_dir}/${name}.

Configuring directories
-----------------------

An example directory configuration:

 tor::daemon::directory { 'ssh_directory':
   port => 80, listen_address => '192.168.0.1', 
   port_front_page => '/etc/tor/tor.html'
 }
  
Configuring exit policies
--------------------------

To configure exit policies, you can do the following:
 
tor::daemon::exit_policy { "ssh_exit_policy":
        accept => "192.168.0.1:22",
        reject => "*:*";
      }
    }


Polipo
======

Polipo support can be enabled by doing:

    include tor::polipo

this will inherit the tor class by default, remove privoxy if its installed, and
install polipo, making sure it is running.
  

Munin
=====

If you are using munin, and have the puppet munin module installed, you can set
the variable $use_munin = true to have graphs setup for you.