Merge remote-tracking branch 'shared/master'
[puppet_tor.git] / README.md
1 # tor
2
3 #### Table of Contents
4
5 * [Overview](#overview)
6   * [Upgrade Notice](#upgrade-notice)
7 * [Dependencies](#dependencies)
8 * [Usage](#usage)
9   * [Installing tor](#installing-tor)
10   * [Configuring SOCKS](#configuring-socks)
11   * [Installing torsocks](#installing-torsocks)
12   * [Configuring relays](#configuring-relays)
13   * [Configuring the control](#configuring-control)
14   * [Configuring onion services](#configuring-onion-services)
15   * [Configuring directories](#configuring-directories)
16   * [Configuring exit policies](#configuring-exit-policies)
17   * [Configuring transport plugins](#configuring-transport-plugins)
18 * [Functions](#functions)
19 * [Munin](#munin)
20
21 # Overview<a name="overview"></a>
22
23 This module tries to manage tor, making sure it is installed, running, has
24 munin graphs if desired and allows for configuration of relays, onion services,
25 exit policies, etc.
26
27 ## Upgrade Notice<a name="upgrade-notice"></a>
28
29  * All of the `listen_address` variables have been deprecated, since they have
30    been deprecated in tor since 0.2.3.x-alpha. Please read the new tor man page
31    if you were using those variables.
32
33  * Previously, if you did not set the `$outbound_bindaddress` variable, it was
34    being automatically set to the `$listen_address variable`. Now this is not
35    being done and instead you will need to set the `$outbound_bindaddress`
36    explicitly for it to be set.
37
38  * The `tor::relay{}` variables `$bandwidth_rate` and `$bandwidth_burst` were
39    previously used for the tor configuration variables `RelayBandwidthRate` and
40    `RelayBandwidthBurst`, these have been renamed to `$relay_bandwidth_rate`
41    and `$relay_bandwidth_burst`. If you were using these, please rename your
42    variables in your configuration.
43
44  * The variables `$bandwidth_rate` and `$bandwidth_burst` are now used for the
45    tor configuration variables `BandwidthRate` and `BandwidthBurst`. If you
46    used `$bandwidth_rate` or `$bandwidth_burst` please be aware that these
47    values have changed and adjust your configuration as necessary.
48
49  * The `$tor_ensure_version` was converted to a parameter for the tor and
50    `tor::daemon` classes.
51
52  * The `$torsocks_ensure_version` was converted to a parameter for the
53    `tor::torsocks` class.
54
55  * The options that used to be settable with the `tor::daemon::global_opts`
56    define now are parameters for the `tor::daemon class`, and
57    `tor::daemon::global_opts` was removed accordingly.
58
59
60 # Dependencies<a name="dependencies"></a>
61
62 This module needs:
63
64  * the [concat module](https://github.com/puppetlabs/puppetlabs-concat.git)
65
66 # Usage<a name="usage"></a>
67
68 ## Installing tor<a name="installing-tor"></a>
69
70 To install tor, simply include the 'tor' class in your manifests:
71
72     class { 'tor': }
73
74 You can specify the `$version` class parameter to get a specific version installed.
75
76 However, if you want to make configuration changes to your tor daemon, you will
77 want to instead include the `tor::daemon` class in your manifests, which will
78 inherit the `tor` class from above:
79
80     class { '::tor::daemon': }
81
82 You have the following class parameters that you can specify:
83
84     data_dir    (default: '/var/lib/tor')
85     config_file (default: '/etc/tor/torrc')
86     use_bridges (default: 0)
87     automap_hosts_on_resolve (default: 0)
88     log_rules   (default: ['notice file /var/log/tor/notices.log'])
89
90 The `data_dir` will be used for the tor user's `$HOME`, and the tor
91 `DataDirectory` value.
92
93 The `config_file` will be managed and the daemon restarted when it changed.
94
95 `use_bridges` and `automap_hosts_on_resolve` are used to set the `UseBridges`
96 and `AutomapHostsOnResolve` torrc settings.
97
98 The `log_rules` can be an array of different Log lines, each will be added to
99 the config, for example the following will use syslog:
100
101     class { '::tor::daemon':
102         log_rules => [ 'notice syslog' ],
103     }
104
105 If you want to set specific options for the tor class, you may pass them
106 directly to the tor::daemon in your manifests, e.g.:
107
108     class { '::tor::daemon':
109       use_munin                 => true,
110       automap_hosts_on_resolve  => 1,
111     }
112
113 ## Configuring SOCKS<a name="configuring-socks"></a>
114
115 To configure tor socks support, you can do the following:
116
117     tor::daemon::socks { "listen_locally":
118       port     => 0,
119       policies => 'your super policy';
120     }
121
122 ## Installing torsocks<a name="installing-torsocks"></a>
123
124 To install torsocks, simply include the `torsocks` class in your manifests:
125
126     class { 'tor::torsocks': }
127
128 You can specify the `$version` class parameter to get a specific version installed.
129
130 # Configuring relays<a name="configuring-relays"></a>
131
132 An example relay configuration:
133
134     tor::daemon::relay { "foobar":
135       port             => '9001',
136       address          => '192.168.0.1',
137       bandwidth_rate   => '256',
138       bandwidth_burst  => '256',
139       contact_info     => "Foo <collective at example dot com>",
140       my_family        => '<long family string here>';
141     }
142
143 You have the following options that can be passed to a relay, with the defaults
144 shown:
145  
146     $port                    = 0,
147     $portforwarding          = 0,     # PortForwarding 0|1, set for opening ports at the router via UPnP.
148                                       # Requires 'tor-fw-helper' binary present.
149     $bandwidth_rate          = '',    # KB/s, defaulting to using tor's default: 5120KB/s
150     $bandwidth_burst         = '',    # KB/s, defaulting to using tor's default: 10240KB/s
151     $relay_bandwidth_rate    = 0,     # KB/s, 0 for no limit.
152     $relay_bandwidth_burst   = 0,     # KB/s, 0 for no limit.
153     $accounting_max          = 0,     # GB, 0 for no limit.
154     $accounting_start        = [],
155     $contact_info            = '',
156     $my_family               = '', # TODO: autofill with other relays
157     $address                 = "tor.${domain}",
158     $bridge_relay            = 0,
159     $ensure                  = present
160     $nickname                = $name
161
162 ## Configuring the control<a name="configuring-control"></a>
163
164 To pass parameters to configure the `ControlPort` and the
165 `HashedControlPassword`, you would do something like this:
166
167     tor::daemon::control { "foo-control": 
168       port                    => '80',
169       hashed_control_password => '<somehash>',
170       ensure                  => present;
171     }
172
173 Note: you must pass a hashed password to the control port, if you are going to
174 use it.
175
176 ## Configuring onion services<a name="configuring-onion-services"></a>
177
178 To configure a tor onion service you can do something like the following:
179
180     tor::daemon::onion_service { "onion_ssh":
181       ports => 22;
182     }
183
184 The `HiddenServiceDir` is set to the `${data_dir}/${name}`, but you can override
185 it with the parameter `datadir`.
186
187 If you wish to enable v3-style onion services to correspond with the v2-style
188 onion services (the same configuration will be applied to both), you can pass
189 the parameter `v3 => true`. The default is `false`.
190
191 If you wish to enable single-hop onion addresses, you can enable them by
192 passing `single_hop => true`. The default is `false`.
193
194 Onion services used to be called hidden services, so an old interface
195 `tor::daemon::hidden_service` is still available, with the feature
196 set of that time.
197
198 ## Configuring directories<a name="configuring-directories"></a>
199
200 An example directory configuration:
201
202     tor::daemon::directory { 'ssh_directory':
203       port             => '80',
204       port_front_page  => '/etc/tor/tor.html';
205     }
206   
207 ## Configuring exit policies<a name="configuring-exit-policies"></a>
208
209 To configure exit policies, you can do the following:
210  
211     tor::daemon::exit_policy { "ssh_exit_policy":
212       accept => "192.168.0.1:22",
213       reject => "*:*";
214     }
215
216 ## Configuring transport plugins<a name="configuring-transport-plugins"></a>
217
218 To configure transport plugins, you can do the following:
219
220     tor::daemon::transport_plugins { "obfs4":
221       ext_port                => '80',
222       servertransport_plugin  => 'obfs4 exec /usr/bin/obfs4proxy',
223     }
224
225 If you wish to use `obfs4proxy`, you will also need to install the required
226 Debian package, as the puppet module will not do it for you.
227
228 Other options for transport plugins are also available but not defined by
229 default:
230
231     $servertransport_listenaddr  #Set a different address for the transport plugin mechanism
232     $servertransport_options     #Pass a k=v parameters to the transport proxy
233
234 # Functions<a name="functions"></a>
235
236 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.
237
238 ## onion_address
239
240 This function takes a 1024bit RSA private key as an argument and returns the onion address for an onion service for that key.
241
242 ## generate_onion_key
243
244 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.
245
246 # Munin<a name="munin"></a>
247
248 If you are using `munin`, and have the puppet munin module installed, you can
249 set the `use_munin` parameter to `true` when defining the `tor::daemon` class
250 to have graphs setup for you.