-
Notifications
You must be signed in to change notification settings - Fork 3
/
README
executable file
·230 lines (184 loc) · 10.9 KB
/
README
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
Copyright (c) 2006-2007, Joseph B. Kowalski
See LICENSE for licensing information
WARNING: This file is slightly out of date. For a more accurate install with
versions 4.0 and onwards, please see the INSTALL file.
PLEASE NOTE: You must agree to the terms and conditions for GeoLite and for JPGraph to use this software to its fullest extent. If you do not agree to the appropriate terms and licenses that are provided with this release, then you may not use those pieces of software. Basically, this means that "as-is" this software cannot be used commercially.
TorStatus - Tor Network Status
You may download the most current version at:
http://project.torstatus.kgprog.com/
To setup the 'TorStatus' Web Application, follow these instructions:
1) Create the MySQL database that the application will use. In the default
install directory, there is a MySQL script file that can be used to create
the initial database exactly as it needs to be. The default database name is
"TorNetworkStatus", but you can change this to be any name you want as long as
it's reflected correctly in the config file. For development, MySQL 5 on Linux
was used.
2) Create a database user that has access to the database created in step 1
above. The user will need select, update, insert, and delete rights on the
database.
3) Place files in appropriate directory to be served by a PHP enabled web
server. IMPORTANT NOTE: You'll want the "web" subdirectory created when you
extracted this archive to be web root for the site. Apache 2 on Linux with
PHP 5 were used for development. The PHP installation must support GD and
MySQL. You may need to re-compile PHP if you don't have support for these
options compiled in. See the PHP official website if you need help with this.
Setup "index.php" to be the default index page if desired.
4) Download and install the JPGraph PHP graphing libraries. All you should
need to do is download the free version (Make sure you're in compliance with
the software's license, of course) and extract it to somewhere that your web
server can access. For simplicity, it is recommended that you place the files
in the "web/jpgraph" subdirectory that was created when you extracted this
archive. Of course, you can put them anywhere, but you'll have to edit the
config file to reflect the correct path. No other setup or customization of
JPGraph is necessary.
5) Download and install the MaxMind GeoIP PHP API and the GeoLite Country
database. All you should need to do is download the "geoip.inc" file from the
PHP API section and the latest "GeoIP.dat" GeoLite country database file (Make
sure you're in compliance with the software's license, of course) and place
the two files in a location that PHP can access. For simplicity, it is
recommended that you place the files in the "geoip" subdirectory that was
created when you extracted this archive. Of course, you can put them anywhere,
but you'll have to edit the config file to reflect the correct paths. No other
setup or customization of JPGraph is necessary.
6) Make sure you have a local Tor server setup and running properly. This
application gets its data by connecting to the control port of a local Tor
server. If you have not already done so, you will need to enable the
"ControlPort" option in your Tor config file. Please see the Tor website if
you need help doing this. This application supports connecting to the control
port both in the default way (No authentication), and using
"HashedControlPassword" authentication. If you wish to use
"HashedControlPassword" authentication, make sure it's setup properly in your
Tor config file as well. Also, some of the functionality this application
makes use of when talking to the control port of the Tor server was only
recently implemented, in Tor 0.1.2.3-alpha. So, the local Tor server will
need to be that version or higher. Finally, the Tor server will need to be a
directory mirror. Only directory mirrors have descriptors for all routers on
hand, which this application requires.
6) Copy "config_template.php" to "config.php". Edit this file to be correct
for your environment and your preferences. Here is a run-down of the options:
-- $LocalTorServerIP: The IP address that should be used to connect to the
local Tor server's control port. NOTE: This is not the server's public, or
advertised IP. Since Tor opens up it's control port on the 127.0.0.1 interface
by default, you probably will never need to change this.
-- $LocalTorServerControlPort: The control port you have your Tor server setup
to listen on. Check the Tor config file if you don't know.
-- $LocalTorServerPassword: If you have setup the "HashedControlPassword"
option in your Tor config file, you will need to enter the password
(clear-text) here. If not, leave this option set to null and the default
(No authentication) will be used.
-- $SQL_Server: IP address or hostname of your MySQL server.
-- $SQL_User: Username you setup for the database.
-- $SQL_Pass: Password you setup for the database.
-- $SQL_Catalog: Name of the database. Default is "TorNetworkStatus", but this
may be anything you want.
-- $UsingSquid: Set this if you are currently running a Squid web accelerating
server. You will need to set the other appropriate settings in config.php
under the Squid category for this to work fully.
-- $JPGraph_Path: Set this to the path where you extracted the JPGraph
libraries. Note that this is a web path. It can be absolute or relative. If
using it in a relative way, this path is relative to the "web" subdirectory.
Make sure you leave the trailing slash.
-- $GEOIP_Path: Set this to the path where you placed the MaxMind GeoIP PHP
API file (geoip.inc). Note that this path can be absolute or relative. If it
is used in a relative way, it is relative to the root of this application, one
level up from the "web" subdirectory. Make sure you leave the trailing slash.
-- $GEOIP_Database_Path: Set this to the path where you placed the MaxMind
GeoLite Country database file (GeoIP.dat). Note that this path can be absolute
or relative. If it is used in a relative way, it is relative to the root of
this application, one level up from the "web" subdirectory. Make sure you
leave the trailing slash.
-- $PHP_Path: Set this to the path where the PHP executable resides on your
system. Make sure you leave the trailing slash. This path should be absolute
(From system root).
-- $TNS_Path: Set this to the path where you have extracted the
TorNetworkStatus archive. This is the root of this application, one level up
from the "web" subdirectory. Make sure you leave the trailing slash. This path
should be absolute (From system root).
-- $Cache_Expire_Time: Set this to the amount of time, in seconds, that the
local-cache (MySQL Database) is considered valid. This will allow the
"tns_agent.php" script, described later, know how often to refresh the
database with new information from the local Tor server.
-- $ColumnHeaderInterval: This variable specifies how often a column header
row is inserted into the result set. So, if set to '30', a column header row
will be inserted after every 30 results printed to the screen.
-- $ColumnList_ACTIVE_DEFAULT: This array specifies the default columns that
are active and displayed before a user has done any customization of column
display settings. Note that the order matters here, too. If you remove a
column from this list, you should add it to the "$ColumnList_INACTIVE_DEFAULT"
list, documented below. Likewise, if you add a column to this list, you should
remove it from the "$ColumnList_INACTIVE_DEFAULT" list.
-- $ColumnList_INACTIVE_DEFAULT: This array is the inverse of the
"$ColumnList_ACTIVE_DEFAULT" array, defined above. Columns listed in this
array will not be displayed by default.
Valid options for the "$ColumnList_ACTIVE_DEFAULT" and
"$ColumnList_INACTIVE_DEFAULT" arrays are:
'Bandwidth'
'Contact'
'CountryCode'
'DirPort'
'Fingerprint'
'Hostname'
'IP'
'LastDescriptorPublished'
'Platform'
'ORPort'
'Uptime'
'Authority'
'BadDir'
'BadExit'
'Exit'
'Fast'
'Guard'
'Hibernating'
'Named'
'Stable'
'Running'
'Valid'
'V2Dir'
-- $LocalTimeZone: This is simply a string where you can specify your time
zone, so that the "Cache Last Updated" field at the bottom of the page makes
sense to users in other time zones, since that field is in local time.
Whatever you enter here is appended to the end of the "Cache Last Updated"
field.
-- $OffsetFromGMT: This is a positive or negative number, in seconds,
representing how far off the web server is from GMT. So, if you are in the
Pacific Standard Time (PST) zone which is GMT -8:00, for example, you would
enter -28800 (8 hours in seconds) in this field. This variable is used for
various time calculations during the execution of the application.
-- $DNSEL_Domain: If you are running the DNSEL server component (See
"README_DNSEL" for details) and wish to advertise it on the web site, set
this variable to the full domain name for which the DNSEL server is
authoritative for. This value should match what you set in the
"DNSELServer.properties" file for "config_DNSEL_Domain". If you leave this set
to 'null', no DNSEL server link will be displayed on the site.
-- $Hidden_Service_URL: If you are also making the TorNetworkStatus site
available as a Tor Hidden Service and wish to advertise this on the site,
enter the URL of the Hidden Service here. If you leave this set to 'null', no
Hidden Service link will be displayed on the site.
-- $TorNetworkStatus_Version: A version string which displays at the bottom
of each page.
7) Setup a way for scheduled local-cache (database) refreshes to take place.
You have two options here. Number one is to simply run the "tns_agent.php"
file using stand-alone PHP, and allow it to continue running in the
background. On Unix type systems, you'll probably want to start this as a
background task. The file will run the update process at whatever interval
you've specified in the config file. Number two is to either manually run the
"tns_update.php" file using stand-alone PHP periodically (not recommended), or
use some other task scheduling mechanism to run it, such as cron. If you do
things this way, the refresh interval you've specified in the config file
will have no bearing. It will be up to you to setup your task scheduling
mechanism at the interval you want.
8) Set up the cgi-bin directory to be an actual cgi-bin directory with your
webserver. TorStatus will point to /cgi-bin/perlgraph/plot.pl to create Perl
based graphs.
9) You're done! Load the site in a browser, and if all is well, it should
work.
10) Optionally, it may make you feel better to delete the "sql" subdirectory.
Everything else is required.
Best regards,
Joe Kowalski
NOTE: This application was developed using Linux, Apache 2, MySQL 5, and PHP
5. The application may work fine in other environments, but I have not tested
this.
NOTE: This product includes GeoLite data created by MaxMind, available from
http://www.maxmind.com/.