Asterisk Project 1
Due Friday, April 20, via blackboard or email.
You will each be given administrative access to your own instance of an Ubuntu
linux system running Asterisk. You can run it either on the Loyola
server (eg cs446j.cslabs.luc.edu), or you can make a copy of the
virtual disk and run it under VMware on your own machine. The
department has a group license for VMware.
If you're using the departmental machine, all you have to do to turn it
in is let me know it's ready. If you're doing this on your own machine,
send me all the Asterisk *.conf files you modified; typically, this
will be sip.conf and extensions.conf. You can use ls -lt | head to list the 10 most-recently-modified files, to see if you changed anything else.
Connecting
Your first task is, of course, to figure out how to call in to your
Asterisk server. I recommend using a softphone such as Ekiga (note that
I don't necessarily recommend Ekiga itself). You will not be asked
to do any two-way communication; you will simply be creating extensions
with voice menu systems; therefore, for most work you won't need to be
able to handle sound input. You will, however, need to be able to
record
voice samples for use as system prompts. I use the linux utility Sound
Recorder; there is also a WinXP utility of the same name under Programs
=> Accessories => Entertainment. I assume either it or an
improved version is available under Win7. Finally, using any of several
speech-synthesis tools would be an option.
The Asterisk servers are configured to support a predefined SIP connection with username softphone and password sipsecr3t. You will have to configure your softphone with these two parameters and the name or IP address of your Asterisk server. The softphone will then initiate the registration process with Asterisk.
Each account corresponds to one channel or extension. You will eventually want to
create multiple accounts/channels/extensions for testing different
extensions. I've also created accounts softphone1, softphone2 and ekiga.
Most sound-recording utilities save sound as 16-bit wav. You will need
to convert that to ulaw; I recommend using the "sox" sound-conversion
program. To use sox to convert from foo.wav to foo.ulaw, use
sox foo.wav -r 8000 -t ul foo.ulaw
Sox will figure out things like the sampling rate of foo.wav and whether it is 16-bit, etc.
The Project Itself
You are to take the magic-number example in the Asterisk notes and
modify it to support the following features. The features are roughly
in increasing order of complexity. The existing source is in
extensions.conf in the [dbdemo] context (section); all your changes
should be made in this context only (or create a new context). The
extension to reach this is 2004.
1. Implement a passcode system.
Before you can get access to your magic number, let alone set it, you
have to provide your passcode. Of course, the account has to be entered
first, so that the system knows which passcode to work with. Passcodes
should be set up initially in the Asterisk database system; you'll use
a separate table from the magic-number table; see the database
information below. Some accounts may not have passcodes; your system
should handle that option in a reasonable manner.
Note that a "finished" version here implies some structural changes to the prompt system: you should authenticate first
(account number and then passcode), and only then be allowed to reach a
menu where you can set and get the magic number. My existing menu
allows you to set your account at any point.
While you are doing this, you should also adjust the prompt system to
better make a distinction between accounts that have a magic number
already (in which case it is read), or accounts which do not yet have
magic.
2. Add support for allowing a user to change his or her passcode.
3. Add support to allow the user to change to a new account
(with new passcode) without hanging up. Perhaps the easiest way to do
this is a special option in the main menu to "start over".-rw-r--r-- 1 root root 4831838208 2012-03-26 19:27 cs446-0-flat.vmdk
-rw-r--r-- 1 root root 515 2012-03-26 19:27 cs446-0.vmdk
-rwxr-xr-x 1 root root 2725 2012-03-26 19:21 cs446-0.vmx
-rw-r--r-- 1 root root 30 2012-03-26 19:27 STATUS.ok
4. Currently the initial default account is 2000. Have it instead be the user's extension, using caller-ID to get the extension,
if this caller-ID information is available. Design this option so it is
quick and easy to use. If the caller-ID information is not
available, use no initial account (or 2000, if you can't get the
no-initial-account thing to work). Note that the most
common arrangement in Asterisk is for the extension caller-ID number to
be set in
the sip.conf file, as part of the definition of a given channel. You
can use substring operators to get the last four digits of the
caller-ID number, if you wish, or just use 4-digit extensions
exclusively.
All voice prompts should spell out all options; there should be no
"hidden" options. That said, you don't have to be wordy; you can just
say things like "one for setting account; two for passcode, three for
magic". Use the built-in recordings by Allison as appropriate.
Appropriate initial entries in the database should be made from the Asterisk command line. Handy commands:
- database show
- database put table key value
- database get table key
- database del table key.
The following entries have been pre-entered:
account
|
magic
|
4001
|
123454321
|
4002
|
4294967297
|
4003
|
37
|
Documentation
Almost all the Asterisk features you will need are described here: http://ofps.oreilly.com/titles/9780596517342/asterisk-DP-Deeper.html; see also my Asterisk notes.
- extension scripting
- variables
- subroutines
- AstDB (Asterisk Database). All tables have only two attributes:
⟨key,value⟩. Thus, you will need two databases, eg MagicDB and
PasswordDB, with both using the account number as the key.
To reach the Asterisk command line, type the command asterisk -r as root. Use ^D or exit to exit. To reload extensions.conf, go to the asterisk command line and type dialplan reload. To reload any changes to sip.conf, use sip reload. Note that it is not "extensions reload".
Working on your server
Whether you use VMware or the Loyola virtual machines, you will log in
as account "cs446". The Asterisk files are in /etc/asterisk, symlinked
to your local subdirectory "asterisk"; you should be able to edit the
files directly as user cs446.
To access the Asterisk command line (eg to reload, or to watch
messages), you will need to be root. Do this with "sudo bash", or just
"sudo asterisk -r".
If you have installed your Asterisk server locally, under VMware, you
will have access to the full graphical-user interface. Log in as user
cs446, and create one terminal window with root privileges. You may
wish to install the "guest additions" package appropriate for your
virtual machine; if not, you'll have to use a special key option to
"release" the mouse from the virtual machine. For VirtualBox users it's
usually the right Ctrl key; for VMware users it's Ctrl-Alt. If you forget this, you can't get your mouse free from the virtual machine!
The files for the virtual machine are at hopper.cs.luc.edu:/homes/users/cs/students/cs446:
-rw-r--r-- 1 root root 4831838208 2012-03-26 19:27 cs446-0-flat.vmdk
-rw-r--r-- 1 root root 515 2012-03-26 19:27 cs446-0.vmdk
-rwxr-xr-x 1 root root 2725 2012-03-26 19:21 cs446-0.vmx
-rw-r--r-- 1 root root 30 2012-03-26 19:27 STATUS.ok
The first one (the virtual-disk image) is quite large! Don't try downloading on a slow link.
If you are working on the Loyola-hosted servers, you will need to use
the command-line interface at least to some degree. You may wish to
enable ssh public-key authentication, so you can (a) log in more easily
and (b) log in at all from outside Loyola. See Using SSH at Loyola.
To edit files (eg extensions.conf), one approach is to do the editing on your home machine and then use scp
to copy the file over to your server as needed. If you are running an
"X server" (eg natively under linux or else using cygwin-X), you can do
the following: log in to your Asterisk server with
ssh -X -l cs446 uvid.cslabs.luc.edu
Then you can run the gedit editor on your Asterisk server and it will display on your home desktop:
gedit extensions.conf &
Some further notes
1. How to install the .vdmk files under VirtualBox: create a new vm,
choose "use existing virtual disk", and choose cs446-0.vmdk as your
virtual disk. (The actual data is in cs446-0-flat.vmdk, but that
doesn't specify the disk "information". Yes, they should have used a
different file extension.)
2. Choose "Host-only Networking for the guest system. "Bridged
Networking" may also work. When I did this, my host (windows) system
had IP address 192.168.56.1, and my Asterisk server (the VirtualBox
guest) had IP address 192.168.56.101. Note that you can only change the
networking type when the virtual machine is off. Select the machine in
the VirtualBox Manager, and go to Settings ⟶ Network ⟶ Attaached to.The current Attached_to setting might be NAT; change that to Host-only Adapter.
3. To start a terminal in the Asterisk (Ubuntu) VM, go to the "Dash
home" (top icon in the lefthand icon strip), and type "terminal".
4. I also installed cygwin + openssh on my Windows box, so I could use ssh:
ssh -l cs446 192.168.56.101
5. In ekiga (on windows), I filled in: Name: softphone, Registrar: 192.168.56.101, User: softphone, Password: sipsecr3t
6. In windows firewall, I was finally able to create a rule allowing any and all communication to host 192.168.56.101. I created a new Inbound Rule (named ekiga-vbox), with Action "Allow the connection" in the general tab, and then, in the scope tab, I set Remote IP address to 192.168.56.101. This allows any traffic from the Asterisk server to reach windows.
However, I might not in fact need that rule. I had already created a rule allowing program ekiga
to accept inbound traffic. And the very first RTP packet (these are the
troublesome ones) went from Windows to Asterisk, after which the
Windows Firewall will allow reverse RTP traffic as well.
7. Alas! In the asterisk sip.conf, in the context for [softphone]
(and the others, if you use them), I had to create a rule to allow
connections from 192.168.56.1; I had not anticipated this when i set things up initially. This change is essential.
8. When I call with ekiga, I still get "error while opening audio input
device". That's because the laptop I was using doesn't have a mic
plugged in. But I don't need one!
permit=192.168.0.0/255.255.0.0
This goes with the other permit statments, after the deny 0.0.0.0/0.0.0.0.
9. If you try using Wireshark on Windows to examine network traffic,
the VirtualBox Host-only Adapter will probably show up as "Sun"
(original vendor of VirtualBox).