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.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 README.md (limited to 'README.md') 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(-) (limited to 'README.md') 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 From d5c17a1c842bbec4d0172895d715f5ce48fb7068 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 1 Nov 2017 16:47:02 -0400 Subject: *ListenAddress (OR, DNS, Trans, etc.) are deprecated since 0.2.3.x-alpha --- README.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 2f2ebf2..7186ab7 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,10 @@ exit policies, etc. ## Upgrade Notice + * All of the `listen_address` variables have been deprecated, since they have + been deprecated in tor since 0.2.3.x-alpha. Please read the new tor man page + if you were using those variables. + * 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` @@ -111,16 +115,10 @@ directly to the tor::daemon in your manifests, e.g.: To configure tor socks support, you can do the following: tor::daemon::socks { "listen_locally": - listen_addresses => [ '127.0.0.1' ]; + port => 0, + policies => 'your super policy'; } -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: @@ -136,7 +134,6 @@ 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', @@ -148,7 +145,6 @@ 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 @@ -194,7 +190,6 @@ An example directory configuration: tor::daemon::directory { 'ssh_directory': port => '80', - listen_addresses => '192.168.0.1', port_front_page => '/etc/tor/tor.html'; } -- cgit v1.2.3 From 7170dae37787ad213ace30648a5929a1171f7529 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 1 Nov 2017 17:06:53 -0400 Subject: document the new transport plugin mechanism --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 7186ab7..b44f7e3 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ * [Configuring hidden services](#configuring-hidden-services) * [Configuring directories](#configuring-directories) * [Configuring exit policies](#configuring-exit-policies) + * [Configuring transport plugins](#configuring-transport-plugins) * [Polipo](#polipo) * [Munin](#munin) @@ -202,6 +203,23 @@ To configure exit policies, you can do the following: reject => "*:*"; } +## Configuring transport plugins + +To configure transport plugins, you can do the following: + + tor::daemon::transport_plugins { "obfs4": + ext_port => '80', + servertransport_plugin => 'obfs4 exec /usr/bin/obfs4proxy', + } + +If you wish to use `obfs4proxy`, you will also need to install the required +Debian package, as the puppet module will not do it for you. + +Other options for transport plugins are also available but not defined by +default: + + $servertransport_listenaddr #Set a different address for the transport plugin mechanism + $servertransport_options #Pass a k=v parameters to the transport proxy # Polipo -- cgit v1.2.3 From 01cfa7e013179f17d981ef8ca9822a8c3bd727ff Mon Sep 17 00:00:00 2001 From: Micah Anderson Date: Sat, 7 Oct 2017 13:39:12 -0400 Subject: add v3 hidden service support --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index b44f7e3..2cf89df 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,15 @@ To configure a tor hidden service you can do something like the following: ports => 22; } -The `HiddenServiceDir` is set to the `${data_dir}/${name}`. +The `HiddenServiceDir` is set to the `${data_dir}/${name}`, but you can override +it with the parameter `datadir`. + +If you wish to enable v3-style hidden services to correspond with the v2-style +hidden services (the same configuration will be applied to both), you can pass +the parameter `v3 => true`. The default is `false`. + +If you wish to enable single-hop onion addresses, you can enable them by +passing `single_hop => true`. The default is `false`. ## Configuring directories -- cgit v1.2.3