1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
# 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-torsocks)
* [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)
* [Configuring transport plugins](#configuring-transport-plugins)
* [Polipo](#polipo)
* [Munin](#munin)
# Overview<a name="overview"></a>
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<a name="upgrade-notice"></a>
* 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`
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<a name="dependencies"></a>
This module needs:
* the [concat module](https://github.com/puppetlabs/puppetlabs-concat.git)
# Usage<a name="usage"></a>
## Installing tor<a name="installing-tor"></a>
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<a name="configuring-socks"></a>
To configure tor socks support, you can do the following:
tor::daemon::socks { "listen_locally":
port => 0,
policies => 'your super policy';
}
## Installing torsocks<a name="installing-torsocks"></a>
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<a name="configuring-relays"></a>
An example relay configuration:
tor::daemon::relay { "foobar":
port => '9001',
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,
$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<a name="configuring-control"></a>
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<a name="configuring-hidden-services"></a>
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}`, 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<a name="configuring-directories"></a>
An example directory configuration:
tor::daemon::directory { 'ssh_directory':
port => '80',
port_front_page => '/etc/tor/tor.html';
}
## Configuring exit policies<a name="configuring-exit-policies"></a>
To configure exit policies, you can do the following:
tor::daemon::exit_policy { "ssh_exit_policy":
accept => "192.168.0.1:22",
reject => "*:*";
}
## Configuring transport plugins<a name="configuring-transport-plugins"></a>
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<a name="polipo"></a>
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<a name="munin"></a>
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.
|
