The Kermit Project |
612 West 115th Street, New York NY 10025 USA • firstname.lastname@example.org
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.
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:
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 directoryit 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/bashin 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 directoryIt 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 +
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
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.
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).
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:
You can delete the cbx.zip file if you wish.
- 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.
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.
This lets you watch the dialog with the Digi box and CBX in real time.
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.
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.
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.