diff options
| -rw-r--r-- | README | 161 |
1 files changed, 161 insertions, 0 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. + |