Command Shells -- Managing Your Systems through the Telephone
Imagine you're out for a night on the town or just driving through
the countryside, then your pager goes off or your cell phone rings
telling you something's wrong at work. If you are responsible for
one or more systems, this will eventually happen. But with a little
forethought, VOCP, and a telephone, you can still solve the problem
no matter where you are.
VOCP was released in 2000 under the GPL and is available at:
VOCP uses a computer and voice modem to implement a call answering
and voice messaging system. It offers a suite of command line, graphical,
and Web interfaces for configuration, control, and access (Figure
1). You can use VOCP to create a tree of boxes for menus, voicemail,
pagers, faxing, and the like.
VOCP answers incoming calls and places callers in the "root" box,
usually comprised of a greeting message and menu. Callers may navigate
the system tree, moving from box to box, by entering choices with
their touch-tone keypad. VOCP supports a number of different box
types, and this article will focus on the boxes with the greatest
potential value for the systems administrator -- the "command shell"
These "command shell" boxes allow administrators to interact with
the system -- running programs and hearing their output. If you
can run it on the command line or script it, you can now do it through
any DTMF telephone. VOCP can accommodate any number of distinct
command shells and provides fine-grained control over the executables
that are available and under which privileges they run.
The VOCP User Interface
A VOCP user accesses the network through a series of phone-activated
menus known as boxes. A command shell is a specific box type that
acts like a restricted shell. These boxes aren't available through
the public call flow tree, access is instead restricted in a manner
similar to voicemail message retrieval. After a person has logged
into a command shell box, a limited set of commands are available,
through the selections configured for this box by the VOCP administrator.
Each selection executes a single program. At a minimum, a selection
consists of a program to run and a return value specifying the output
format. The box has an owner, and all programs executed through
the box will run with the privileges of that owner.
After a caller has successfully logged into a command shell, she
may choose to run any of the available selections using the telephone
keypad. Each selection may accept caller input and will provide
some type of response.
A selection may request caller input before running the associated
executable. The caller input will be passed to the program as its
final argument. User input can be interpreted as raw DTMF (0-9,A-D
and *) or as text. For example, a script might be created to send
an email notification to an arbitrary user, and a command-line argument
associated with the script would specify the user that should receive
the notification. Through the telephone, each letter is selected
by entering the DTMF key on which it resides, followed by its position
on that key. For example, pressing "21" is equivalent to entering
the letter "a"; thus, to send a message to "fred", the caller would
enter "33 72 32 31" using the telephone's keypad. The process is
described in detail at:
Because VOCP is designed to operate over the telephone, any VOCP-related
output must be transmitted to the user in audio format. In the simplest
case, VOCP reads the program's numeric exit status. Although the exit
status might be sufficient in instances where your interest is restricted
to whether the command has succeeded or not, it quickly becomes inadequate
in more complex scenarios, such as querying the system for status
information. This is where VOCP's text-to-speech support really shines.
VOCP uses the return value associated with the menu selection
to determine how to interpret the output. Valid return values include:
VOCP requires vgetty (the voice extension to the mgetty+sendfax
package), Perl, a Unix-type computer, and a voice modem that
is supported by vgetty.
To begin, any older mgetty installation should be removed.
Get the latest version of mgetty+sendfax (http://www.leo.org/~doering/mgetty/)
and VOCP (http://www.vocpsystem.com/). You may install
mgetty+sendfax and vgetty by following the directions within
but, if you are unsure of your modem's compatibility, it is
best to include our "force_detect" vgetty patch. Unpack VOCP,
change into the vocp-X.X.X/prog/dependencies/mgetty-patch/,
and run install_patched_vgetty.pl as root.
After vgetty has been installed, edit the /usr/local/etc/mgetty+sendfax/voice.conf
file and set the "voice_devices" parameter to the device used
by your modem, for example:
If you want to use text-to-speech, retrieve the Festival Speech
Synthesis System from:
Then, install it according to the instructions and make note of
the location where you've installed it.
To install VOCP, determine the RMD format to use with your
modem. Convert a wave file to PVF format using mgetty's wavtopvf
program, or select a PVF file from the vocp-X.X.X/messages directory
and convert it to RMD with the pvftormd utility. Use:
$ pvftormd -L
to list acceptable RMD formats and compression methods. Convert
the pvf file by specifying a format suitable for your modem. For
$ pvftormd US_Robotics 1 file.pvf file.rmd
is suitable for many USR voice modems. Test the resulting rmd
file with your modem with vgetty's vm program. Try:
$ vm play -H file.rmd
and listen in on the handset connected to your voice modem. If
vm fails or doesn't sound right, check the /var/log/vgetty.ttySX
and /var/log/vm.log files for errors and try another of the available
RMD formats or compression methods. Make note of the RMD format
and compression combination that sounds best.
As root, run the install_vocp.pl script from within the top-level
vocp-X.X.X directory. VOCP requires a few Perl modules to run,
such as Modem::Vgetty. If these are unavailable, you will be
asked whether you want to install them. Say "y" and the installation
script will fetch and install them all through CPAN.
If this is a first-time installation, the script will convert
the system messages from their Portable Voice Format (pvf) to
the appropriate Raw Modem Date (rmd) format for your modem.
You will need to specify which of the available formats to select;
use the values determined above.
If you've installed Festival, say "y" to the "Do you wish
to use Text-to-speech" question and indicate the full path to
its bin/text2wave program. You will also be prompted for the
name of a VOCP group to create. Enter a valid group name or
press enter to accept the default value (vocp).
Arrange for vgetty to listen for incoming calls and be re-spawned
on termination. Under Linux, this involves adding a line such
to /etc/inittab and running init q as root, forcing init
to reread its configuration file. In this example, the modem is
on ttyS1; adjust the device appropriately for your setup. Verify
that vgetty is indeed running and check the /var/log/vgetty.ttySX
log file to ensure your modem was correctly recognized. The installation
process is fully described on the VOCP site if you encounter any
Begin by ensuring that vgetty is correctly configured. The
important vgetty configuration files are mgetty.config and voice.conf.
Both files usually reside in /usr/local/etc/mgetty+sendfax/
and are well documented. The most important parameters are the
voice_devices, voice_shell, and call_program
in voice.conf. Use:
adjusting the voice_devices parameter to the location of your
VOCP is configured using two distinct files: vocp.conf, which
is used to store general parameters, and boxes.conf, which determines
the call tree layout and command shell selections.
Open /etc/vocp/vocp.conf in your favorite editor, and you
will see that it has a simple format and is also extensively
self-documented. The most important parameters you need to set
are rmdformat, rmdcompression, and rmdsample,
which are modem dependent and specify the exact format to use
when creating audio files (as determined above using pvftormd
To represent arbitrary call trees and ensure flexibility,
the boxes.conf file contains an XML description of the system.
You can create this file by hand, based on the included example
and documentation, but it is much easier to use the /usr/local/vocp/bin/boxconf.pl
GUI. BoxConf presents a simple graphical interface that allows
you to maintain your VOCP system box configuration. (Note that
you must have Perl Tk installed to use it.)
Listing 1 shows a portion of the boxes.conf file produced
by boxconf.pl. It describes box number 600 of type "command"
(a command shell box). When logged into this box, only two selections
will be available: 100 and 200. Entering "100#" will cause the
system to prompt the caller for input. Assuming the user enters
"33723231#", the selection will be run as "sendemail.sh fred",
since the "input" element is set to "text". Both selections
will be executed as user "nobody", thanks to the box "owner"
You may notice that there is no means of authenticating users
in the configuration. Because other portions of VOCP, such as
the message retrieval GUI, require access to the box configuration,
it has been split into two files: boxes.conf and boxes.conf.shadow,
much as in the standard shadow password mechanism. While boxes.conf
is legible by all, the boxes.conf.shadow file contains the (optionally
crypted) passwords and must be readable only by root and members
of the vocp group created during installation.
To create a command shell box, launch boxconf.pl as root (Figure
2). Click on the "New Box" button, select "command" for the
box type, and click "Ok". Enter a unique box number, select
a box owner, enter a password, and click "Ok". The new command
shell box number will appear in the list near the bottom of
the window. To make selections available from within this command
shell, double-click the box number then hit the "New Selection"
button. In the window that appears, enter the selection number,
the program to run, and the type of response VOCP should provide
afterwards. Clicking "Ok" will add the new selection to the
When you are done, File->Save the new configuration. It
is recommended that you save it somewhere other than /etc/vocp
and take a peek inside to ensure everything looks good before
moving the new boxes.conf and boxes.conf.shadow to /etc/vocp/.
Using Command Shells
Once installation is complete, you may use the /usr/local/vocp/bin/vocplocal.pl
script to simulate a call using your keyboard and speakers,
use the Call Center to interact with VOCP through your local
handset, or simply call in to test your setup. Normal navigation
through the system involves listening to menus and entering
single digit input to make selections.
To retrieve voicemail or interact with the command shells,
callers may access the login menu at any time by entering *999#.
At the prompt, enter the box number optionally followed by the
pound sign (#). Enter the password after the system has requested
it. You should now be logged into the command shell. Unless
disabled in vocp.conf, entering 9# will provide a listing of
available selections using Festival's text-to-speech.
Enter the number of the selection you want to run. Depending
on its setup, you may be prompted for input. The selection will
run and play its response, after which you may enter another
Enter 0# to exit the shell and terminate the call, or 001#
to return to the root box (from which you may navigate the system
or log into another box).
Typical uses include querying the system for various information,
such as which processes are running and who is logged in. System
load and free memory or disk space are all easily reported using
selections with text-to-speech. You can also use command shells
to start and stop services, or even (gasp!) reboot the server.
The possibilities are endless -- if you can script it, you can
run it through a command shell selection.
Additionally, automated monitoring processes may be set up
to use the VOCP delivery agent such that they will send periodic
messages or alerts to your voicemail, pager, or email box.
Because command shells allow a user to run programs on the
VOCP host, special considerations apply when creating these
boxes. To begin, all programs available through the command
shells must be located in the commanddir, specified in vocp.conf
(/var/spool/voice/commands by default). You can either move
the program into the directory, or make a softlink residing
in the commanddir that points to the program to run. It may
be a good idea to have an automated process monitor this directory
Some guidelines to command shell creation are:
- Select box owners judiciously -- Follow the principle of
least privilege and set the box owner to a user with only
the privileges required to run the selections. Create command
boxes as needed, with higher privileged commands available
in their own boxes; the caller can run selections in one box,
log into another to run special commands, and return to the
original box afterwards (similar to using the su command).
- Keep passwords safe -- Ensure the boxes.conf.shadow file
has the correct permissions (0440 or 0640), and crypt the
- Use text passwords -- VOCP expects passwords to be entered
using the DTMF keys and long strings of numbers are difficult
to remember, so there is a tendency to select short and easy
passwords. You can get around this by specifying passwords
as text strings. Text passwords are entered in the same manner
as text input to selections.
- Be careful of the selections you make available within
the command boxes --Although you wouldn't make the mistake
of having rm -rf / as an available selection, ponder
the effects of each selection you make available, especially
if it accepts user input.
- Use restrictLoginFrom -- Get a modem that supports
caller ID (CND), subscribe to the service, and set the restrictLoginFrom
option for command shell boxes. The restrictLoginFrom
box parameter allows you to specify a regular expression that
the call origin number must match in order to access the box.
If you know you'll only be calling from one or a few distinct
numbers, you can make the regex very strict. For example,
setting restrictLoginFrom to ^(5551212|5551234)$
will allow access only for calls from 555-1212 and 555-1234.
Here are a few additional suggestions that will make using
VOCP command shells more enjoyable and productive.
- Take the time to install Festival. Text-to-speech output
is the most helpful and flexible way to return meaningful
- Try to anticipate situations in which you will be using
the command shells, and set the selections accordingly. Allow
some flexibility where warranted by accepting input for your
- Although selection input is useful, don't expect to write
your thesis through the telephone: two digits per letter will
get tiresome quickly.
- Look at the example command shell scripts included with
VOCP in the vocp-X.X.X/commands/ directory. Some may be useful
"as is"; all may help you in creating your own.
- Heed the security indications above.
The VOCP Web site is packed with information to help you install,
set up, and use VOCP. There is also a thriving user community
available through the vocp-users mailing list in case you need
some advice or an extra hand. Finally, the creators of VOCP
are available for commercial support and site-specific customizations,
You can use VOCP to monitor systems and perform administrative
tasks, no matter where you are. In this article, I've focused
on the VOCP command shell setup and modes of operation. How
exactly you use the command shells will depend on the specific
issues you want to address and where you strike the balance
between selection flexibility and simplicity. I haven't touched
upon all the other uses you may have for the voice messaging
system, but you can find out more on the Web site. The creators
of VOCP are always looking for ways to improve it, so if you
have a suggestion or particular problem you think should be
addressed, let them know.
Patrick Deegan came into contact with Linux while studying
at McGill University. The world lost a physicist that day, and
it gained a passionate software developer and free software
author. Pat is currently CTO of Psychogenic Inc, which he co-founded