diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 214 |
1 files changed, 0 insertions, 214 deletions
@@ -1,214 +0,0 @@ -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 { 'tor::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. - |