diff options
| -rw-r--r-- | README | 161 | ||||
| -rw-r--r-- | manifests/daemon.pp | 21 | ||||
| -rw-r--r-- | manifests/munin.pp | 2 | ||||
| -rw-r--r-- | templates/torrc.control.erb | 10 | ||||
| -rw-r--r-- | templates/torrc.relay.erb | 14 |
5 files changed, 197 insertions, 11 deletions
@@ -0,0 +1,161 @@ +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. + diff --git a/manifests/daemon.pp b/manifests/daemon.pp index 3a201e4..7661a43 100644 --- a/manifests/daemon.pp +++ b/manifests/daemon.pp @@ -101,9 +101,11 @@ class tor::daemon inherits tor { define relay( $port = 0, $listen_addresses = [], $outbound_bindaddresses = $listen_addresses, - $bandwidth_rate = 0, # KB/s, 0 for no limit. - $bandwidth_burst = 0, # KB/s, 0 for no limit. - $accounting_max = 0, # GB, 0 for no limit. + $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 @@ -121,13 +123,20 @@ class tor::daemon inherits tor { } # control definition - define control( $port = 0, - $hashed_control_password = '', + define control( $port = 0, + $hashed_control_password = '', + $cookie_authentication = 0, + $cookie_auth_file = '', + $cookie_auth_file_group_readable = '', $ensure = present ) { - if $hashed_control_password == '' and $ensure != 'absent' { + if $cookie_authentication == '0' and $hashed_control_password == '' and $ensure != 'absent' { fail("You need to define the tor control password") } + + if $cookie_authentication == 0 and ($cookie_auth_file != '' or $cookie_auth_file_group_readable != '') { + notice("You set a tor cookie authentication option, but do not have cookie_authentication on") + } concatenated_file_part { '04.control': dir => $tor::daemon::snippet_dir, diff --git a/manifests/munin.pp b/manifests/munin.pp index ac2630a..8504f89 100644 --- a/manifests/munin.pp +++ b/manifests/munin.pp @@ -17,7 +17,7 @@ class tor::munin { munin::plugin { [ "tor_connections", "tor_routers", "tor_traffic" ]: ensure => present, - config => "user debian-tor\n env.cookiefile /var/lib/tor/control_auth_cookie", + config => "user debian-tor\n env.cookiefile /var/run/tor/control.authcookie", script_path_in => "/usr/local/share/munin-plugins"; } } diff --git a/templates/torrc.control.erb b/templates/torrc.control.erb index df9513a..336c72d 100644 --- a/templates/torrc.control.erb +++ b/templates/torrc.control.erb @@ -1,6 +1,16 @@ # tor controller <%- if port != '0' then -%> ControlPort <%= port %> +<%- if cookie_authentication != '0' then -%> +CookieAuthentication 1 +<%- if cookie_auth_file != '' then -%> +CookieAuthFile <%= cookie_auth_file %> +<%- end -%> +<%- if cookie_auth_file_group_readable != '' then -%> +CookieAuthFileGroupReadable <%= cookie_auth_file_group_readable %> +<%- end -%> +<%- else -%> HashedControlPassword <%= hashed_control_password %> <%- end -%> +<%- end -%> diff --git a/templates/torrc.relay.erb b/templates/torrc.relay.erb index 2ab34bf..71c94b9 100644 --- a/templates/torrc.relay.erb +++ b/templates/torrc.relay.erb @@ -13,11 +13,17 @@ Nickname <%= nickname %> <%- if address != '' then -%> Address <%= address %> <%- end -%> -<%- if bandwidth_rate != '0' then -%> -RelayBandwidthRate <%= bandwidth_rate %> KB +<%- if bandwidth_rate != '' then -%> +BandwidthRate <%= bandwidth_rate %> KB <%- end -%> -<%- if bandwidth_burst != '0' then -%> -RelayBandwidthBurst <%= bandwidth_burst %> KB +<%- if bandwidth_burst != '' then -%> +BandwidthBurst <%= bandwidth_burst %> KB +<%- end -%> +<%- if relay_bandwidth_rate != '0' then -%> +RelayBandwidthRate <%= relay_bandwidth_rate %> KB +<%- end -%> +<%- if relay_bandwidth_burst != '0' then -%> +RelayBandwidthBurst <%= relay_bandwidth_burst %> KB <%- end -%> <%- if accounting_max != '0' then -%> AccountingMax <%= accounting_max %> GB |