Fix typo
[users/lunar/check_tor.git] / README
1 ===========================================
2 check_tor.py: a Nagios check for Tor relays
3 ===========================================
4
5 check_tor.py is a collection of Nagios checks that can be used by operators of
6 Tor relays to ensure that their participations to the network are running
7 properly.
8
9 It has only be tested on Debian Squeeze, so far. Patches to support other
10 plateforms are highly welcome.
11
12 Usage
13 =====
14
15 Usage: check_tor.py [options]
16
17 Bridges connectivity
18 --------------------
19
20 To test if a bridge can be used to join the Tor network, specify its address
21 using the --bridge option. The test will configure Tor to use the given bridge
22 to retrieve the Tor project homepage.
23
24 To ensure that the bridge matches a known fingerprint use the --fingerprint
25 option.
26
27 If the bridge is reachable using a pluggable transport, specify its type using
28 the --transport option. The only type currently supported is `obfs2`.
29
30 Examples:
31
32     check_tor.py --bridge=198.51.100.25:443
33     check_tor.py --bridge=198.51.100.25:38472 --transport=obfs2
34     check_tor.py --bridge=198.51.100.25:443 --fingerprint=C755A900D3C087B4075F29E31B3F9ADA6CB84B8C
35
36 Entry node connectivity
37 -----------------------
38
39 To test if a relay can be used to join the Tor network, specify its fingerprint
40 using the --entry option. The test will configure Tor to use the given entry
41 node to retrieve the Tor project homepage.
42
43 Examples:
44
45     check_tor.py --entry=C755A900D3C087B4075F29E31B3F9ADA6CB84B8C
46
47 Middle node connectivity
48 ------------------------
49
50 To test if a relay can be used as a middle node, specify its fingerprint
51 using the --middle option. The test will create a Tor circuit using
52 one guard node, the given node and a random exit node. This circuit will be
53 used to retrieve the Tor project homepage.
54
55 Examples:
56
57     check_tor.py --middle=C755A900D3C087B4075F29E31B3F9ADA6CB84B8C
58
59 Exit node connectivity
60 ----------------------
61
62 To test if a relay can be used as an exit node, specify its fingerprint
63 using the --exit option. The test will configure Tor to use the given exit
64 node to retrieve the Tor project homepage.
65
66 Examples:
67
68     check_tor.py --exit=C755A900D3C087B4075F29E31B3F9ADA6CB84B8C
69
70 Tor data directory
71 ------------------
72
73 check_tor.py will create a temporary directory by default to hold Tor data.
74 This makes the checks longer to run, as Tor will need to download more
75 information in order to bootstrap.
76
77 To use the same data directory on every run, please specify a (writable)
78 directory using the --datadir option.
79
80 Example:
81
82     check_tor.py --datadir=/var/lib/nagios/check_tor --bridge=198.51.100.25:443 
83
84 Known issues
85 ============
86
87 The current code will leak a DNS resolution query to www.torproject.org when
88 it retrieves the homepage to verify that circuits can be built properly.
89 This is due to a limitation of pycurl 7.19 which does not expose a way
90 to ask a configured SOCKS proxy to perform hostname resolution.
91
92 Dependencies
93 ============
94
95  * Tor
96    <https://www.torproject.org/>
97  * (optional) obfsproxy
98    <https://www.torproject.org/projects/obfsproxy.html>
99  * pycurl
100    <http://pycurl.sourceforge.net/>
101  * Stem
102    <https://stem.torproject.org/>
103
104 On Debian, you can issue the following command:
105
106     apt-get install tor python-pycurl obfsproxy
107
108 Stem did not have a stable release yet and needs to be cloned in the same
109 directory as check_tor.py:
110
111     git clone git://git.torproject.org/stem.git
112
113 Author
114 ======
115
116 Jérémy Bobbio <lunar@debian.org>
117
118 Thanks to Damian Johnson for Stem and his code advices.
119
120 Contributions are highly welcome.
121
122 License
123 =======
124
125 This program is free software: you can redistribute it and/or modify
126 it under the terms of the GNU General Public License as published by
127 the Free Software Foundation, either version 3 of the License, or
128 (at your option) any later version.
129
130 This program is distributed in the hope that it will be useful,
131 but WITHOUT ANY WARRANTY; without even the implied warranty of
132 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
133 GNU General Public License for more details.
134
135 You should have received a copy of the GNU General Public License
136 along with this program.  If not, see <http://www.gnu.org/licenses/>.