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
|
arm (anonymizing relay monitor) - Terminal status monitor for Tor relays.
Developed by Damian Johnson (www.atagar.com - atagar@torproject.org)
All code under the GPL v3 (http://www.gnu.org/licenses/gpl.html)
Project page: www.atagar.com/arm
Description:
Command line application for monitoring Tor, providing real time status
information such as the current configuration, bandwidth usage, message log,
connections, etc. This uses a curses interface much like 'top' does for system
usage. The application is intended for command-line aficionados, ssh
connections, and anyone with a tty terminal for checking their relay's status.
Releases should be stable so if you manage to make it crash (or have a feature
request) then please let me know!
The project was originally proposed in 2008 by Jacob and Karsten:
http://archives.seul.org/or/dev/Jan-2008/msg00005.html
An interview by Brenno Winter discussing the project is available at:
http://www.atagar.com/arm/HFM_INT_0001.mp3
Requirements:
Python 2.5
TorCtl (this is included with arm)
Tor is running with an available control port. This means either...
... starting Tor with '--controlport <PORT>'
... or including 'ControlPort <PORT>' in your torrc
It's also highly suggested for the control port to require authentication.
This can be done either with a cookie or password:
* Cookie Authentication - Controllers authenticate to Tor by providing the
contents of the control_auth_cookie file. To set this up...
- add "CookieAuthentication 1" to your torrc
- either restart Tor or run "pkill -sighup tor"
- this method of authentication is automatically handled by arm, so you
can still start arm as you normally would
* Password Authentication - Attaching to the control port requires a
password. To set this up...
- run "tor --hash-password <your password>"
- add "HashedControlPassword <hashed password>" to your torrc
- either restart Tor or run "pkill -sighup tor"
- when starting up arm will prompt you for this password
For full functionality this also needs:
- To be ran with the same user as tor to avoid permission issues with
connection resolution and reading the torrc.
- Common *nix commands including:
* ps
* a method of connection resolution (any of the following):
* sockstat
* netstat
* ss
* lsof
* procstat
* tail
* pwdx
* ulimit
* pgrep or pidof
* host (if dns lookups are enabled)
This is started via 'arm' (use the '--help' argument for usage).
-------------------------------------------------------------------------------
FAQ:
> Why is it called 'arm'?
Simple - because it makes the command short and memorable. Terminal
applications need to be easy to type (like 'top', 'ssh', etc), and anything
longer is just begging command-line aficionados to alias it down. I chose the
meaning of the acronym ('anonymizing relay monitor') afterward.
> If you're listing connections then what about exit nodes? Won't this include
people's traffic?
No. Potential client and exit connections are specifically scrubbed of
identifying information. Be aware that it's highly discouraged for relay
operators to fetch this data, so please don't.
> Is it harmful to share the information provided by arm?
Not really, but it's discouraged. The original plan for arm included a special
emphasis that it wouldn't log any data. The reason is that if a large number of
relay operators published the details of their connections then correlation
attacks could break Tor user's anonymity. Just show some moderation in what you
share and it should be fine.
> Is there any chance that arm will leak data?
No. Arm is a completely passive listener, fetching all information from either
Tor or the local system.
> When arm starts it gives "Unable to resolve tor pid, abandoning connection
listing"... why?
If you're running multiple instances of Tor then arm needs to figure out which
pid belongs to the open control port. If it's running as a different user (such
as being in a chroot jail) then it's probably failing due to permission issues.
Arm still runs, just no connection listing or ps stats.
> The bandwidth graph isn't showing up
Some terminals, most notably screen sessions on Gentoo, appear to have a bug
where highlighted spaces aren't rendered. A reported workaround is to set:
TERM="rxvt-unicode"
> There's borders like 'mwqqqqqqqqj'
If you're getting something that looks like...
http://www.atagar.com/arm/images/acs_display_failure.png
then you're encountering a bug between ncurses and your terminal where
alternate character support (ACS) is unavailable. For more information see...
http://invisible-island.net/ncurses/ncurses.faq.html#no_line_drawing
Unfortunately there doesn't seem to be a way for arm to automatically detect
and correct this. To work around some of the issues set this in your armrc...
features.acsSupport false
> When I press enter in the connection panel to get details some of the
information is either missing or outdated. Why is this?
There are two sources of information about Tor relays: their consensus and
descriptor entries.
The consensus entry is provided on an hourly basis by the Tor directory
authorities (special relays that keep track of all the relays in the network).
The consensus has information like the nickname, flags, and in newer Tor
versions a summarized exit policy.
The descriptor entry, however, is published by the relays themselves and has
information like their platform, contact information, family, public keys,
exit policy, etc. These are much larger than the consensus entries and don't
change unless the relay changes their configuration.
Everyone in the Tor network (both relays and users) need the consensus entries
to operate. However, only users (not relays) need the descriptor entries.
Tor will fetch both the consensus and descriptors for all of the currently
active relays when it first starts. But to save bandwidth only the consensus
entries are updated after this unless...
a. 'FetchUselessDescriptors 1' is set in your torrc
b. the directory service is provided ('DirPort' defined)
c. you use Tor as a client
This means that some of the information on the connection page (like the
platform and contact information) might be missing or stale due to missing
descriptors. This isn't important to most users, but if you need this
information then this is simple to fix with the above.
-------------------------------------------------------------------------------
Layout:
./
arm - startup script
install - installation script
arm.1 - man page
armrc.sample - example arm configuration file with defaults
ChangeLog - revision history
LICENSE - copy of the gpl v3
README - um... guess you figured this one out
setup.py - distutils installation script for arm
src/
__init__.py
starter.py - parses and validates commandline parameters
prereq.py - checks python version and for required packages
version.py - version and last modified information
test.py - method for starting tests and demos
settings.cfg - attributes loaded for parsing tor related data
torConfigDesc.txt - fallback descriptions of Tor's configuration options
uninstall - removal script
cli/
graphing/
__init__.py
graphPanel.py - (page 1) presents graphs for data instances
bandwidthStats.py - tracks tor bandwidth usage
psStats.py - tracks system information (such as cpu/memory usage)
connStats.py - tracks number of tor connections
connections/
__init__.py
connPanel.py - (page 2) lists the active tor connections
circEntry.py - circuit entries in the connection panel
connEntry.py - individual connections to or from the system
countPopup.py - displays client locale or exit port counts
descriptorPopup.py - displays raw descriptor and consensus entries
entries.py - common parent for connPanel display entries
menu/
__init__.py
menu.py - provides an interactive menu
item.py - individual items within the menu
actions.py - handlers for menu selections
__init__.py
controller.py - main display loop, handling input and layout
headerPanel.py - top of all pages, providing general information
popups.py - toolkit providing display popups
wizard.py - provides the relay setup wizard
logPanel.py - (page 1) displays tor, arm, and torctl events
configPanel.py - (page 3) editor panel for the tor configuration
torrcPanel.py - (page 4) displays torrc and validation
interpretorPanel.py - (page 5) interpretor for control port access
util/
__init__.py
conf.py - loading and persistence for user configuration
connections.py - service providing periodic connection lookups
enum.py - enumerations for ordered collections
hostnames.py - service providing nonblocking reverse dns lookups
log.py - aggregator for application events
panel.py - wrapper for safely working with curses subwindows
procTools.py - queries process & system information from /proc contents
procName.py - renames our process to a friendlier name
sysTools.py - helper for system calls, providing client side caching
textInput.py - expands the capabilities of text input fields
torConfig.py - functions for working with the torrc and config options
torInterpretor.py - provides a shell around raw control port access
torTools.py - TorCtl wrapper, providing caching and derived information
uiTools.py - helper functions for presenting the user interface
|
