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: https://gitlab.com/shared-puppet-modules-group/concat - the apt module https://gitlab.com/shared-puppet-modules-group/apt or https://github.com/puppetlabs/puppetlabs-apt/ 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 ", my_family => '' } 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 => '', 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::onion_service { "onion_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. Functions ========= This module comes with 2 functions specific to tor support. They require the base32 gem to be installed on the master or wherever they are executed. onion_address ------------- This function takes a 1024bit RSA private key as an argument and returns the onion address for a hidden service for that key. generate_onion_key ------------------ This function takes a path (on the puppetmaster!) and an identifier for a key and returns an array containing the matching onion address and the private key. The private key either exists under the supplied `path/key_identifier` or is being generated on the fly and stored under that path for the next execution.