summaryrefslogtreecommitdiff
path: root/README
blob: baafe84a773999cc49f68b065e748b7eb0d82cd5 (plain)
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
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 !

 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.


Usage
=====

Installing tor
--------------

To install tor, simply include the 'tor' class in your manifests:

    include tor

You can specify $tor_ensure_version and $torsocks_ensure_version 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:

    include tor::daemon

You have the following tor global variables that you can adjust in your node scope:

$data_dir    = '/var/lib/tor'
$config_file = '/etc/tor/torrc'
$log_rules   = '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.

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:

  tor::daemon::global_opts { "use_syslog": log_rules => [ 'notice syslog' ]; }

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


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 <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,
$listen_addresses        = [],
$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 => '<somehash>',
  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_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 variable $use_munin = true to have graphs setup for you.