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 !
previously, if you did not set the $outbound_bindaddress variable, it was being
automatically set to the $listen_address variable. Now this is not being done
and instead you will need to set the $outbound_bindaddress explicitly for it to
be set.
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.
The $tor_ensure_version was converted to a parameter for the tor and
tor::daemon classes.
The $torsocks_ensure_version was converted to a parameter for the
tor::torsocks class.
The options that used to be settable with the
tor::daemon::global_opts define now are parameters for the
tor::daemon class, and tor::daemon::global_opts was
removed accordingly.
Dependencies
============
This module needs:
- the concat module: git://labs.riseup.net/shared-concat
Usage
=====
Installing tor
--------------
To install tor, simply include the 'tor' class in your manifests:
class { 'tor': }
You can specify the $ensure_version class parameter 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:
class { '::tor::daemon': }
You have the following class parameters that you can specify:
data_dir (default: '/var/lib/tor')
config_file (default: '/etc/tor/torrc')
use_bridges (default: 0)
automap_hosts_on_resolve (default: 0)
log_rules (default: ['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.
use_bridges and automap_hosts_on_resolve are used to set the
UseBridges and AutomapHostsOnResolve torrc settings.
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:
class { '::tor::daemon':
log_rules => [ 'notice syslog' ],
}
If you want to set specific options for the tor class,
you may pass them directly to the tor::daemon in your manifests,
e.g.:
class { '::tor::daemon':
use_munin => true,
automap_hosts_on_resolve => 1,
}
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
Installing torsocks
-------------------
To install torsocks, simply include the 'torsocks' class in your manifests:
class { 'torsocks': }
You can specify the $ensure_version class parameter to get a specific
version installed.
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 = [],
$portforwarding = 0, # PortForwarding 0|1, set for opening ports at the router via UPnP.
# Requires 'tor-fw-helper' binary present.
$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 use_munin parameter to true when defining the tor::daemon class to have
graphs setup for you.
