VOCP Command Shells -- Managing Your Systems through the Telephone

Patrick Deegan

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:

http://www.vocpsystem.com/

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" boxes.

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:

http://www.vocpsystem.com/command_shells.php

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:

• exit -- As described above, exit simply reads the program's exit status.
• output -- With the return value set to output, VOCP reads one or more lines of numerical output (consisting of numbers and periods only). This format can be useful for reading things like IP addresses, as demonstrated in the example ip.pl script included with VOCP.
• file -- Your program may print one or more audio file paths to standard out. These files are played to the user in sequence. For example, printing:

  /path/to/servtemp.rmd
  /path/to/60.rmd
  /path/to/5.rmd
  /path/to/degrees.rmd
  

  would presumably play a message to the effect that "the current server temperature is sixty-five degrees". (The audio files should be in the RMD format required by your voice modem, but VOCP will convert other formats, such as au and wav, appropriately.)

• sendfax -- If the selection outputs the path to a g3 fax file and has its return set to sendfax, you can implement a dynamic fax-on-demand box. After running the selection, VOCP will instruct vgetty to go into fax mode and send the file specified by your program. You must of course be capable of receiving a fax at your location for this option to be useful.
• tts -- Text-to-speech output (tts) offers the most flexibility but requires that you install the Festival text-to-speech engine. For selections with a return set to tts, VOCP reads the text output from your program, converts it to audio using Festival, and plays it for the caller. Text-to-speech may be used to hear system status, read Web pages or anything else (see the sample sysstat.pl and webfetch.pl scripts, included with VOCP). The only requirement is that your program output plain text on standard out.

Installation

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.

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:

voice_devices ttyS1

http://www.cstr.ed.ac.uk/projects/festival/

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

$ pvftormd US_Robotics 1 file.pvf file.rmd

$ vm play -H file.rmd

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 as:

S1:345:respawn:/usr/local/sbin/vgetty ttyS1

Configuration

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:

voice_devices  ttyS1
voice_shell    /usr/bin/perl
call_program   /etc/mgetty+sendfax/vocp/vocp.pl

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 and vm).

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" setting.

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 list.

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 selection.

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.

Security

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 for modifications.

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 passwords.
• 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 feedback.
• 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 selections.
• 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, through Psychogenic.

Conclusion

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 in 2001.