-
Notifications
You must be signed in to change notification settings - Fork 6
/
DEBUGGING.txt
182 lines (131 loc) · 6.44 KB
/
DEBUGGING.txt
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
Reporting a bug
---------------
If you're reporting a bug in shtoom, please make sure you run
the script 'scripts/shtoominfo.py' and include this in your
bug report (feel free to hide the IP addresses if you'd prefer).
Debugging
---------
Some notes on helping you debug shtoom. There's a bit more
attitude in this file than you might think necessary. I
apologise - many of these problems are a source of some
frustration and annoyance to me, so this venting is probably
healthy for me <wink>
Testing
-------
Some test addresses to try calling:
sip:[email protected] -- An echo test
sip:[email protected]:5085 -- Another echo test
See also the section later titled "Test Harness"
Firewalls
---------
Firewalls are the absolute BANE of VoIP and SIP. If the firewall is well
designed and modern, it should work just fine. If not... well, we'll
come to some possible solutions to that.
You should run the script 'shtoominfo.py' (in the scripts directory).
This will report the particular sort of NAT you're using. In particular,
note that any firewall that's a Symmetric NAT without UPnP support will
require you to use an outbound proxy for things to work. A UDP Blocked
NAT means that you're probably not going to be able to make any calls at
all.
If your firewall is, for instance, a linux box, and you feel comfortable
enough with it, you can force a NAT solution with the option
'force_rtp_port' to force shtoom to use a particular RTP port, then
manually set your firewall to forward this port back to your machine.
This is kind of hacky, but works.
If you're looking at a firewall, the thing you are looking for is
"stateful UDP filtering". That is, if a UDP packet goes out, it lets
the reply back in. There's a bunch of firewalls that will do this, but
_only_ for DNS packets. Wonderful. Shtoom should detect what sort of
firewall you are using.
Shtoom also works with UPnP gateways (such as Microsoft's Internet
Connection Sharing, and many off-the-shelf firewall appliances.) It
works fine with the boxes I've tested against, but I only have access
to a limited number of these. If you are having difficulties, send
me debugging (including a packet trace of shtoom communications
with the firewall). If this is all a bit beyond you, and you really
want it fixed, arrange for me to get access to one of the firewalls in
question-- either a login on a box behind the firewall, or else talk to
me about sending me one of the devices in question.
Sound
-----
The next big issue with shtoom is getting audio to work. There's a
simple script 'shreadder.py' that uses the shtoom audio layer to
test with. It reads from the audio device and writes audio back to
it, spitting out some numbers about the power level of the audio.
Use this to test your audio setup. Note that under ALSA on Linux,
all audio devices start muted. Use alsamixer to unmute them. (Yes,
this is stupid, no, I don't know why they made that choice).
The shtoominfo.py script, mentioned already, should dump out which
audio interfaces are available.
Notes on sound drivers under Linux
----------------------------------
ALSA is preferred in all cases. It Just Works. Sound drivers before
ALSA on Linux are somewhere between a shambles and a bloody shambles.
There are some sound drivers that are just screwed. Non ALSA drivers
having problems:
i810_audio
trident
<insert your dodgy sound driver here>
If you have one of these, you're boned. Install ALSA. If you
can't/won't upgrade to a Linux 2.6 kernel, find a version of
ALSA for your system.
For Redhat/Fedora users, look at the Planet CCRMA project,
http://www-ccrma.stanford.edu/
It provides packaged versions of ALSA and the like.
Debian users should look for the alsa-base package. I've been advised
that "dpkg-reconfigure alsa-base" will allow you to set it up and
select your sound card (for instance).
For others, go to http://www.alsa-project.org/
Yes, in theory it _should_ be possible to make your existing sound
driver work. But I'm not willing to spend the time to do so -- there's
far more useful things I can be working on. If you want to try and
figure out your sound driver, and contribute fixes or documentation
on how to make it work, please, do so! I will happily include the
documentation here, and credit you for it. Previously, shtoom failed
on systems where the device could only be opened in stereo(!?). There's
now code in shtoom.audio.ossaudio to deal with these broken drivers.
This happens even with some ALSA drivers!
Determining your sound driver
-----------------------------
On Linux, you can use this command:
/sbin/lsmod | grep soundcore
For ALSA, it will produce something like
soundcore 10720 1 snd
The 'snd' is the base ALSA module. For non-ALSA, you'll get
something like
soundcore 10720 1 i810_audio
Sound drivers under Windows
---------------------------
Under Windows, we use the PortAudio package. By default, this
uses the default windows sound device. You can alter this through
the control panel. There's also some environment variables you can
set to choose a different device:
XXX TODO.
Echo Problems
-------------
If you're having a shocking echo problem under ALSA, check you've
not got 'Capture' enabled for something you shouldn't have. The
only thing that should have 'Capture' on in alsamixer is 'Mic'.
Hit 'space' to toggle the 'Capture' flag. See the alsamixer manpage for
more. There's now an ALSA mixer interface, and shtoom will warn and fix
the ALSA mixer setting soon. See also:
http://people.redhat.com/~alexl/files/why-alsa-sucks.png
Unsorted Notes
--------------
exarkun reports, on selecting the correct sound driver under ALSA:
my card is "ALi Corporation M5451". w/ oss, it was using the trident
driver. There is also an alsa driver for trident cards, but it does
not work. The "ALi M5451" alsa driver does, though.
Test Harness
------------
The script 'shtoom/test/harness.py' is a test harness for running
the phone. It will bring up the phone, and accepts all the normal
arguments and options - calling anything will connect to a special
network layer that echoes back audio. In addition, every 5 seconds it
checks for a file called 'call.txt' in the current directory, and checks
it's modification time. If there's no call running, it simulates an
incoming call. If there's a call, it simulates the remote end hanging
up. Example::
% PYTHONPATH=`pwd` python shtoom/test/harness.py --ui qt &
% touch call.txt # a new incoming call
% touch call.txt # hang it up.