ROLM CBX POLLING SCRIPTS

Frank da Cruz
Last update: Thu Mar 17 11:10:10 2011

EXPORT: These scripts are specific to Columbia University, but they are available to anybody who might want to adapt them to their own Rolm CBX installation. You can use them from Unix (where you must have C-Kermit installed) or from Windows (where you must have Kermit 95 installed).

UNIX is recommended, because each Kermit script is "front-ended" by a Unix shell script, and also you can set up cron jobs on Unix to run the scripts automatically according to any desired schedule. In Windows, the scripts can be run by hand, giving them the same arguments that the shells scripts give them in Unix. This would be done at K-95> prompt in a TAKE command. Presumably the shell scripts could be rewritten as Kermit scripts so they could be used in Windows, except for some things like sending email.

Download for UNIX (tar.gz)   Download Windows (Zip)

A series of Kermit scripts has been designed (and some already written) to access the Rolm CBX in a uniform way from a definitive central location, using a single shared “database” of access and authentication information. This suite of scripts is to replace the earlier Procomm Aspect scripts because:

1. Since Procomm is a Windows application, the older scripts tended to be scattered around on different people's desktop PCs.
2. Each Aspect script was full of IP addresses, user IDs, and passwords, and therefore a security risk, especially since Windows itself is so insecure.
3. If an IP address or access info changed, all of the scripts on all of the PCs that use them would have to be changed.
4. Procomm is not portable to non-Windows platforms, and therefore neither are Aspect scripts.
5. Procomm is no longer supported and does not work on newer Windows OS's.

The Kermit scripts are designed to be run either interactively or unattended, e.g. from a cron job. Any version of C-Kermit 8.0 or later or Kermit 95 2.0 or later can be used. For maximum portability, the scripts don't take advantage of any features that were added to Kermit since 2003.

All scripts are in a single directory and they do not need to know the directory name; nothing is hardwired into them. It is not necessary to cd to the scripts directory before running the scripts.

Authentication and addressing information is kept in one single file, called config, which is shared by all scripts. Thus if usernames, passwords, or IP addresses change, or if CBX nodes are added or removed, the change need be made in only one place: the config file.

Each task is started by a shell script, which automatically cds to the correct directory (i.e. the one where it resides), starts the appropriate Kermit script with the appropriate arguments, and then disposes of the results in the desired way, e.g. by emailing them to some address or preparing an extract or reformatting or whatever is desired.

All shell scripts and Kermit scripts should have 750 or 770 permission, so they can't be seen by the public but they can be run (or possibly modified) by group members. And thus they should all be stored with the appropriate group id. The containing directory should be protected in the same way.

If you try to any of these scripts and you get a message like:

-bash: ./fac.sh: /usr/bin/bash: bad interpreter: No such file or directory

it means that the "shebang line" (top line of the script, which indicates the full path of its intended interpreter) doesn't point to where bash is. This is a problem that will occur over and over as you run the script on different computers, and as sysadmins or OS distributors keep moving and changing the directory structure. You'll have to edit the file (in this case, fac.sh) to indicate the path of the bash shell on the computer where you want to run it. For example, using a plain-text editor, change the top line:

#!/usr/bin/bash

in the shell script file (e.g. fac.sh) to:

#!/bin/bash

Likewise, if you get a message like this:

fac.sh: ./poll: /opt/local/bin/kermit: bad interpreter: No such file or directory

It means the top line of a Kermit script (poll in this case) does not indicate the full path of the Kermit executable on the computer where you are trying to run it. Again, you will have to edit the script to indicate the appropriate full path; for example:

#!/opt/local/bin/kermit +

in the shell script file (e.g. fac.sh) to:

#!/usr/bin/kermit +

CURRENT JOB TABLE

Tag	Shell wrapper	Kermit script(s)	Remarks	Status
usr	usr.sh	poll	List of users on given node	Ready to go
fac	fac.sh	poll	List of FAC (billing) codes	Ready to go
ext	ext.sh	exten	List of extensions	Orig version to be converted
lex	lex.sh	poll, lex	LIST LEX, convert to CSV	Ready to go
ffe	ffe.sh	master, poll	Find free extensions	In development

CBX NODE NAMES

For purposes of reference and cross reference, this suite of scripts uses the following identifiers for our CBX nodes:

ID	Location
33w60st	33 West 60th Street
hicom300	Siemens 9006 in Low Library
auduboniii	Audubon III Building at Medical Center
bankstreet	Bank Street College, 112th Street
carltonarms	Carlton Arms, Riverside Drive, 108-108 St.
crf59st	Cardiovascular Research Foundation at Medical Center
crflighthouse	Cardiovascular Research Foundation on East Side
harmonyhall	Harmony Hall, 110th Street.
morningside	Low Library
parkerbuilding	Parker Building, Fort Lee NJ

These names key into tables of access information and are used as identifiers in result filenames. They can be changed, if necessary, to agree with any other node-name-based schemes.

SECURITY

The config file and scripts must be stored in a directory to which only the authorized people have access on a host that is not accessible from the outside world. To avoid the password problem altogether, we could have made secure connections authenticated with SSL, Kerberos, or SSH (these are supported by Kermit), but the terminal servers do not have this capability.

Simply by recording the access info in a single place, this scheme is much more secure (and manageable) than the previous Procomm-based approach, which had a proliferation of scripts on who-knows-how-many different Windows machines, each one full of usernames and passwords.

Nevertheless, if somebody gained access to the script directory, they would then have access to all the CBX nodes. For this reason, provision has also been made to allow the access information to be encrypted by crypt, e.g.:

crypt somekey < config > config.x
rm config

but if we did this each job would have to be submitted by hand so the operator could enter the decryption key. The code for this is already written and we can switch to this method at any time. It is secure because the key is not written to any file, nor is it passed on the command line (and therefore it can't be seen in 'w' or 'ps' listings), nor does the decrypted config file appear anywhere on the disk (except maybe the swap file).

THE POLL SCRIPT

The poll script is designed to make a connection to a CBX node, issue one command at the CBX console, or a series of commands, record the results in a file, and then log out and exit. As long as the result does not need to be parsed or reformatted on the fly, this script is all that's needed to run commands on any CBX node. The command line arguments for the poll script are:

1. Name of the CBX node from the list above.
2. The command or commands to execute on that node (CSL in doublequotes)
3. A 3-letter “tag” to use as a prefix on generated filenames.

Interactive Access
If only the node name is given, an interactive connection is attempted to the node. If the/a port is free, you will be logged in automatically all the way to the CBX's COMMAND: prompt. What you do from there is your business, but you should be sure to log out manually (QUIT at the COMMAND: prompt and then BYE at the %1 prompt) so the port is not left busy. When you use the poll script this way, a session is recorded in the same directory as the poll script with a name like node_user_timestamp.ses. NOTE: typing in this session might be a bit tricky due to TELNET protocol negotiations being mangled by the Digi boxes. Hint: To terminate a command you might have to use Ctrl-J rather than Enter or Carriage Return. Hint 2: To interrupt a runaway script when all else fails, use Ctrl-\ (Control-Backslash) followed by the letter 'u'. This tells Kermit to hang up the connection.

For Windows, I have a Zip archive containing the poll and config scripts, plus a set of icons, one for each switch. To start an interactive session with any switch, just double-click on its icon.

To use these scripts you must install Kermit 95 on your PC if you don't have it already. Then:

• Make a directory (folder) on your desktop called CBX or ROLM or whatever. Change the view to Large or Medium Icons.
• Put the cbx.zip file in it.
• Unzip the cbx.zip file: right-click on its icon, choose "Extract all".
• In the dialog, erase the "cbx" at the end of the destination folder name (so it doesn't hide the scripts in a subdirectory) and then click Extract.

You can delete the cbx.zip file if you wish.

For non-interactive access, all three arguments must be given. The tag allows data files and logs from different jobs to coexist in the same directory without interfering with each other (the three-letter length is just a suggestion, for neatness). The tag can also be used in the poll script itself to add any “conditional execution” for a particular job, when that would be preferable to forking a whole new script.

Example for listing users logged in to the Morningside CBX node:

poll morningside "LI CNFG_USERS" usr

This creates three files:

Filename	Description
usr-morningside-LI_CNFG_USERS.cap	Output captured from LI CNFG_USERS command
usr-morningside.log	Timestamped event log for this job
usr-morningside.ses	Transcript of login sequence for troubleshooting

Example 2, for collecting information about extensions

poll bankstreet "LI EXTEN ALL, LI REXT ALL" ffe

This creates four files:

Filename	Description
ffe-bankstreet-LI_EXTEN_ALL.cap	Output captured from the LI EXTEN ALL command
ffe-bankstreet-LI_REXT_ALL.cap	Output captured from the LI REXT ALL command
ffe-bankstreet.log	Timestamped event log for this job
ffe-bankstreet.ses	Transcript of login sequence for troubleshooting

The capture file is overwritten on each run; old ones are destroyed automatically at the beginning of a run to prevent an old result from being misinterpreted as a new one in case the script fails.

If it is desired to append to the data file instead of overwrite it, this can be handled in the shell-script wrapper; see usr.sh for an example. Also this script shows how to accept a node name as an argument, so it can be run for any node defined in the config file.

The log file is appended to on each run so the history can be reviewed; it's just a few lines per run; it would take about 8 years for a log file to grow to 1MB. It can be deleted or moved or renamed at any time with no harm, the next run will start a new log.

If the poll script fails, the shell script wrapper sends email to that effect to the designated parties.

By default the poll script runs silently. This way it can be invoked from crontab without any special precautions, and it won't generate any mail unless something bad happens. If you want to run it interactively and watch what happens, set the environment variable DEBUG to something (anything), e.g.

  DEBUG=1 usr.sh

This lets you watch the dialog with the Digi box and CBX in real time.

THE LEX SCRIPT

The lex script reads the capture file from a LIST LEX command on any of the switches and produces three CSV files:

Filename	Description
lex-nodename-LI_LEX_exten.csv	Extensions and their attributes.
lex-nodename-LI_LEX_extenAppearance.csv	Extension line appearances.
lex-nodename-LI_LEX_extenGroupAffiliation.csv	Extension group affiliations.

These are the same filenames that were used by the original Perl script but with the prefixes added that are used by all scripts in this suite.

Given a capture file, the lex script can be used on it directly like so:

$ lex capture-file-name node-name

The node name should be one of those from the table of CBX node names above, but need not be; in this case it's just a string that is copied into the CSV files.

To get the LIST LEX report from a switch and produce the CSV files all in one step, you can use the lex.sh script:

$ lex.sh node-name [ range ]

which runs the poll script with a LI LEX command, and then runs the lex script to parse the capture file. In this case the node name must be one of those from the table. If no range is given, all extensions are listed:

$ lex.sh morningside

A range can be given like this:

$ lex.sh bankstreet 40000..49999

If a range is given, it is included in the generated filenames.

THE EXTEN SCRIPT

This is similar to the poll script except it filters and reformats the incoming data on the fly. NOTE: This script is in production but has not yet been adapted to the “new” structure described above.

THE FFE SCRIPT

(in progress...) This script collects whatever information is necessary from all the nodes listed above, that share the Columbia phone number space, to create a list of extensions that are not in use (FFE = Find Free Extensions). A “master” script starts ten simultaneous poll scripts and then waits for them all to finish. The jobs all run at once because the night is not long enough to run them end to end, and also in order to obtain a better snapshot.

On the main 9005 in Low Library ("morningside") the script might take several hours to run, and must be scheduled not impact normal business-hours operation, and also to avoid the nightly CPU cutover that occurs at 3:45am or 4:00am.

In the first implementation, the script will execute two commands on each Rolm/Siemens 9751/9005: LI EXTEN ALL and LI REXT ALL; according to Jim Rios, these two commands are all that are required to get the list of extensions that each 9005 switch knows about. To complete the picture we also have to get a report from the Rolm/Siemens 9006 (Hicom 300), which is completely different from the 9005s, and which houses the production VoIP extensions; the command in this case is “dis-dpln:stn,;”.

The final step, not done yet, is to produce extracts from the capture files, but for that I need to know how to interpret each report.

ISSUES

• Nobody is claiming to have a standard list of names for the switch nodes, so I made up my own list. These names must be used uniformly for the scripts to work.

• Scripts will be run out of serviceberry, dir /netsys/pbx, group-accessible to group 'net'.

• Still need access to (and instructions for) the 9006.

• How often will the job run? Does it need to be a cron job or can it be started by hand?

• What other ACCESS scripts are out there and can we convert them?

• Should there be an effort to erase all copies of the ACCESS scripts from all the PCs where they currently reside?

• Are there similar security accidents-waiting-to-happen within the network groups that can be addressed in a similar manner?

The version of Kermit installed on the Cunix systems is 8.0.201, which is a bit old. I've been careful not to take advantage of any Kermit features added since then, and to work around bugs that were fixed since then. For example, "grep /quiet" isn't quiet in 8.0.201 (which would result in unwanted mail from cron), so I replaced this construction in the poll script with the somewhat more awkward "grep /output:/dev/null", even though "grep /quiet" works right in later Kermit releases.

---

(End)