Asterisk Project 1
Due Friday, April 26, 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 with Ekiga
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 (although let me know if you find something better). You will not be
asked to do any two-way communication; you will simply be creating auto-answer
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 will be configured to support a predefined SIP
connection with username ekiga and password sipsecr3t
(there are also accounts softphone1 and softphone2
with the same password). 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.
You do not need an ekiga.net account.
Ekiga is not available for the mac; mac users might consider iSoftPhone,
SJPhone, Telephone or X-Lite.
Each SIP account corresponds to one channel or extension. You might
eventually want to create multiple accounts/channels/extensions for testing
different extensions.
To add an Asterisk account, use the Accounts => Add a SIP Account option.
When creating an account for ekiga (or another softphone) your registrar
should be your Asterisk server; you may enter either the IP address or the
DNS name.
When placing a call from ekiga, you probably have to make sure the DNS name
of your Asterisk server appears in the upper box, eg sip:2004@pdordal.cslabs.luc.edu.
This is highlighted in yellow in the screenshot at left; the "sip:2004" at
the top of the righthand window is wrong.
Sound Files
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.
You will also need to make sure there is only one channel
in your sound file. Normally low-end sound-recording utilities do create
single-channel files by default (you really need at least two microphones to
make a dual-channel file!), but otherwise I believe the sox option to force
a single channel is -c 1.
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.
0. [corrected] Currently the server reads you your magic
number whenever you log in
press "1". Change this so the magic number is read to you only
- when you request it by pressing 2
- just after you enter a new magic number, for confirmation (optional)
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.
One way to do this (the way I did it initially) is to set a numeric flag
PassCodeOK, or simply to demand a passcode (to be read with Read() at the
beginning of the [dbdemo] start extension.
Another way, however, is to create a second context (the
things like [dbdemo])
[dbdemo]
start: your account is ....
press 1 to log in to this account, 2
to change accounts
1: enter your passcode: ....
....
goto(dbauthorized,
start, 1) ;; logged in ok
2: enter your account number: ....
[dbauthorized] ;; only here if logged
in; account is
start: press 1 to get your magic number, 2 to set your
magic number, or 3 to change your account
1: (more or less as before)
2: (more or less as before)
3: goto(dbdemo, start, 1)
2. Add support for allowing a user to change
his or her passcode. (In the two-context example above, this would probably
go in the [dbauthorized] context).
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".
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.
5. I am working on one or two additional requirements for graduate
students. Note later: I never did come up with anything concrete,
but graduate students should try to organize the whole system so that it
sounds like a "real" auto-attendant system, with clear prompts for
selections and entries.
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 Smith as appropriate.
Appropriate initial entries in the database should be made from the Asterisk
command line, which you reach from the bash command line with asterisk
-r. Handy commands:
- database show
- database put table key value (eg database put dbdemo 4001
123454321)
- database get table key
- database del table key.
You can create new "tables" dynamically (you will probably need this to
create initial passwords).
The following entries have been pre-entered into the dbdemo "table".
account
|
magic
|
4001
|
123454321
|
4002
|
429811
|
4003
|
37
|
| 4004 |
59 |
Here is a link to the original extensions.conf,
in case edit yours extensively and decide you need to start over.
Documentation
An early edition of the book Asterisk: The Definitive Guide is on sakai. You
will need only a little of it:
- 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.
Most if not all of the information you will need is in Chapter 10: Deeper
Into the Dialplan of The Definitive Guide; there is also some more basic
information in Chapter 6. The GotoIf() function is documented in Chapter 10,
as is the Asterisk Database. You should not need
subroutines or macros.
Here is a simple example using variables and substrings:
exten => 2011,1,Answer()
same => n,Set(NUM=123456789)
same => n,Set(SNUM=${NUM:4:3})
same => n,SayDigits(${SNUM})
This reads back the 3 digits starting at position 4 (counting from 0): "5 6
7". Note that to use a variable you need both the $ and the {} around the
variable name.
If you look at the existing extension 2004, there is a line
exten => 2004,1,Goto(dbdemo,start,1)
This means that if you dial 2004 you go to the start
extension in context [dbdemo], which begins further up.
Any digits you press other than as read by the Read() command will
be interpreted as "extensions" in this context. If you look at the [dbdemo]
context, an extension of "1" tells you the account, an extension of "2"
tells you the magic, and an extension of "3" sets the magic.
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; note that it is not "extensions reload". To reload any
changes to sip.conf, use sip 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 connect to the server, use the Windows Remote Desktop. From home, you
will need to do this through the Loyola VPN. Once you log into the VPN, you
should be able to contact your server at its designated IP address. Note
that you can specify the window size when you log in, and you should plan on
using at least a 600x800 screen size. You should not, however, use
the maximum window size. You should also specify 16-bit color instead of
32-bit color, for performance reasons. Note that the color depth and window
size must be set in Windows Remote Desktop before connecting.
For some operations (in particular for connecting to the Asterisk console,
but possibly also for moving image files), you will need to be the
superuser, or root. I recommend having one terminal be
root (you create terminal windows with CNTL-ALT-T) and one be your regular
account. You become root with the command sudo bash, which
will prompt you for your password.
If you upload a sound file to your cs446 directory, you may need to copy it
to the correct location (Asterisk/sounds/en) with your root
window. Use, eg, cp mysound.ulaw asterisk/sounds/en.
To access the Asterisk command line (eg to reload, or to watch messages),
you will need to be root. Do this from your root window,
above, or just "sudo asterisk -r".
To edit files, the simplest editor is gedit, which you can
start from your regular-account window as
gedit extensions.conf &
If you are interested in installing your Asterisk server locally, under
VMware, let me know and I will supply the files (one of which, the
virtual-disk image, will be about 4 GB). This too will give you 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!
If you are working on the Loyola-hosted servers, you can if you prefer use
the command-line interface using ssh. 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.