From e006d181a856644c63e08bfa957b39f4e1b6216f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Thu, 5 Oct 2017 17:13:44 -0400 Subject: listen_addresses is an array --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index 188acca..e4b8f88 100644 --- a/README +++ b/README @@ -178,7 +178,7 @@ Configuring directories An example directory configuration: tor::daemon::directory { 'ssh_directory': - port => 80, listen_address => '192.168.0.1', + port => 80, listen_addresses => '192.168.0.1', port_front_page => '/etc/tor/tor.html' } -- cgit v1.2.3 From 382ae61aeecb8c07075809731a4a02629f349e81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 11 Oct 2017 16:55:02 -0400 Subject: replace the shared concat module (deprecated) by the puppetlabs one --- README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README b/README index e4b8f88..0ee45a3 100644 --- a/README +++ b/README @@ -40,7 +40,7 @@ Dependencies This module needs: -- the concat module: git://labs.riseup.net/shared-concat +- the concat module: https://github.com/puppetlabs/puppetlabs-concat.git Usage ===== -- cgit v1.2.3 From a8c13d73fbc7af65b5b6c5059e9d4246f5984472 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 11 Oct 2017 17:24:20 -0400 Subject: markdownify the README --- README | 214 ----------------------------------------------------------- README.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+), 214 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 0ee45a3..0000000 --- a/README +++ /dev/null @@ -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: https://github.com/puppetlabs/puppetlabs-concat.git - -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::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_addresses => '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. - diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b1288d --- /dev/null +++ b/README.md @@ -0,0 +1,224 @@ +# tor + +#### Table of Contents + +* [Overview](#overview) + * [Upgrade Notice](#upgrade-notice) +* [Dependencies](#dependencies) +* [Usage](#usage) + * [Installing tor](#installing-tor) + * [Configuring SOCKS](#configuring-socks) + * [Installing torsocks](#installing-torsock) + * [Configuring relays](#configuring-relays) + * [Configuring the control](#configuring-control) + * [Configuring hidden services](#configuring-hidden-services) + * [Configuring directories](#configuring-directories) + * [Configuring exit policies](#configuring-exit-policies) +* [Polipo](#polipo) +* [Munin](#munin) + +# Overview + +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://github.com/puppetlabs/puppetlabs-concat.git) + +# 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::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_addresses => '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 it's +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. -- cgit v1.2.3 From 3a9a7cca01cdcdefc84256fdffbedfdaa3944f9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 11 Oct 2017 17:30:17 -0400 Subject: a few markdown fixes --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 8b1288d..2f2ebf2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ * [Usage](#usage) * [Installing tor](#installing-tor) * [Configuring SOCKS](#configuring-socks) - * [Installing torsocks](#installing-torsock) + * [Installing torsocks](#installing-torsocks) * [Configuring relays](#configuring-relays) * [Configuring the control](#configuring-control) * [Configuring hidden services](#configuring-hidden-services) @@ -134,15 +134,15 @@ version installed. 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 => ''; - } + 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: @@ -166,8 +166,8 @@ shown: ## Configuring the control -To pass parameters to configure the ControlPort and the HashedControlPassword, -you would do something like this: +To pass parameters to configure the `ControlPort` and the +`HashedControlPassword`, you would do something like this: tor::daemon::control { "foo-control": port => '80', -- cgit v1.2.3