NAME

RAS::HiPerARC.pm - PERL Interface to 3Com/USR Total Control HiPerARC

Version 1.03, June 9, 2000

SYNOPSIS

RAS::HiPerARC is a PERL 5 module for interfacing with a 3Com/USR Total Control HiPerARC remote access server. Using this module, one can very easily construct programs to find a particular user in a bank of ARCs, disconnect users, get usage statistics, or execute arbitrary commands on a ARC.

PREREQUISITES AND INSTALLATION

This module uses Jay Rogers' Net::Telnet module. If you don't have Net::Telnet, get it from CPAN or this module won't do much for you.

Installation is easy, thanks to MakeMaker:

1. "perl Makefile.PL && make && make test"

2. If the tests worked all right, "make install"

3. Check out the examples in this documentation.

DESCRIPTION

At this time, the following methods are implemented:

creating an object with new

Use the new() method to create a new object.

Example:
   use RAS::HiPerARC;
   $foo = new RAS::HiPerARC(
      hostname => 'dialup1.example.com',
      login => '!root',
      password => 'mysecret',
   );

The following variables are useful: hostname - The hostname of the router to connect to login - The login name to get a command-line on the router password - The password to the login name supplied prompt - See below

Since there's no point in dynamically changing the hostname, login, etc. these settings are static and must be supplied to the constructor. No error will be returned if these settings are not specified (except for the hostname, which is required), but your program will likely not get very far without at least a hostname and a correct password.

Prompt handling has been vastly improved. If a prompt is not specified, a reasonable default is assumed that should work just fine. If you want to specify a prompt, supply a regular expression without delimiters or anchors that represents your router's prompt, e.g. prompt => 'hiper>' If you get errors about a bad match operator or a bad delimiter, you likely have a bad prompt string.

printenv

This is for debugging only. It prints to STDOUT a list of its configuration hash, e.g. the hostname, login, and password. The printenv method does not return a value.

Example:
   $foo->printenv;

run_command

This takes a list of commands to be executed on the ARC, executes the commands, and returns a list of references to arrays containg the text of each command's output.

Repeat: It doesn't return an array, it returns an array of references to arrays. Each array contains the text output of each command. Think of it as an array-enhanced version of PERL's `backtick` operator.

Example:
   # Execute a command and print the output
   $command = 'list conn';
   ($x) = $foo->run_command($command);
   print "Output of command \'$command\':\n", @$x ;

Example:
   # Execute a string of commands
   # and show the output from one of them
   (@output) = $foo->run_command('list interface','list con');
   print "Modems:\n@$output[0]\n\n";;
   print "Current connections:\n@$output[1]\n\n";;

usergrep

Supply a username as an argument, and usergrep will return an array of ports on which that user was found (or an empty array, if they're not found). If no username is supplied, returns undefined. Internally, this does a run_command('list connections') and parses the output.

Example:
   @ports = $foo->usergrep('gregor');
   print "User gregor was found on ports @ports\n";

userkill

This does a usergrep, but with a twist: it disconnects the user by resetting the modem on which they're connected. Like usergrep, it returns an array of ports to which the user was connected before they were reset or an empty array if they weren't found. An undef is returned if no username was supplied.

Examples:
   @foo = $foo->userkill('gregor');
   print "Gregor was on ports @foo - HA HA!\n" if @ports ;

   @duh = $foo->userkill('-');
   print "There were ", scalar(@duh), " ports open.\n";

portusage

This returns an array consisting of 2 items: The 1st element is the number of ports. The rest is a list of users who are currently online.

Examples:
   ($ports,@people) = $foo->portusage;
   print "There are $ports total ports.\n";
   print "There are ", scalar(@people), "people online.\n";
   print "They are: @people\n";

   ($ports,@people) = $foo->portusage;
   print "Ports free: ", $ports - scalar(@people), "\n";
   print "Ports used: ", scalar(@people), "\n";
   print "Ports total: ", $ports, "\n";

userports

This returns a hash with the key of each item being a username. The value of each item is an array of the ports that that username is currently using. This provides some information that a simple usergrep() lacks.

Example:
   %userports = $foo->userports;
   foreach $user (keys(%userports)) {
     foreach $port (@{$userports{$user}}) {
          print "User: $user is on $port\n";
      }
   }

EXAMPLE PROGRAMS

portusage.pl - Prints a summary of port usage on a bank of modems

use RAS::HiPerARC; $used = $total = 0; foreach ('arc1.example.com','arc2.example.com','arc3.example.com') { $foo = new RAS::HiPerARC( hostname => $_, login => '!root', password => 'mysecret' );

local($ports,@ports) = $foo->portusage;
$total += $ports;
$used += scalar(@ports);
}

print "$used out of $total ports are in use.\n";

###

usergrep.pl - Finds a user on a bank of modems

($username) = @ARGV; die "Usage: $0 <username>\nFinds the specified user.\n" unless $username ;

use RAS::HiPerARC; foreach ('arc1.example.com','arc2.example.com','arc3.example.com') { $foo = new RAS::HiPerARC( hostname => $_, login => '!root', password => 'mysecret' );

@ports = $foo->usergrep($username);
(@ports) && print "Found user $username on $_ ports @ports\n";
}

###

userkill.pl - Kick a user off a bank of modems. Makes a great cron job. ;)

($username) = @ARGV; die "Usage: $0 <username>\nDisconnects the specified user.\n" unless $username ;

use RAS::HiPerARC; foreach ('arc1.example.com','arc2.example.com','arc3.example.com') { $foo = new RAS::HiPerARC( hostname => $_, login => '!root', password => 'mysecret' );

@ports = $foo->userkill($username);
(@ports) && print "$_ : Killed ports @ports\n";
}

CHANGES IN THIS VERSION

1.03 Added userports() method. Added better prompt support (YAY!). Made error messages more useful.

1.02 Fixed portusage() to only count Up interfaces. The ARC remembers modems even when they've been removed, and this accounts for that oddity. Cleaned up the code substantially. Fixed the prompt-matching code so that a prompt mismatch will cause run_command() to return instead of hanging in a loop.

1.01 Added a test suite. Corrected some errors in the documentation. Improved error handling a bit.

AUTHORS, MAINTAINERS, AND CONTACT INFO

RAS::HiPerARC uses the Net::Telnet module by Jay Rogers <jay@rgrs.com> - thank you, Jay!

Gregor Mosheh <stigmata@blackangel.net> wrote RAS::HiPerARC originally, but the prompt handling needed some help in case people cuztomized their prompts.

Luke Robins <luker@vicnet.net.au> and Todd Caine <todd_caine@eli.net> helped out substantially with the prompt handling with RAS::AS5200 and the changes were carried over into RAS::HiPerARC. Thank you, Luke and Todd!

The maintainer of RAS::HiPerARC is Gregor Mosheh, at the address above.

BUGS

Since we use this for port usage monitoring, new functions will be added slowly on an as-needed basis. If you need some specific functionality let me know and I'll see what I can do. If you write an addition for this, please send it in and I'll incororate it and give credit.

LICENSE AND WARRANTY

Where would we be if Larry Wall were tight-fisted with PERL itself? For God's sake, it's PERL code. It's free!

This software is hereby released into the Public Domain, where it may be freely distributed, modified, plagiarized, used, abused, and deleted without regard for the original author.

Bug reports and feature requests will be handled ASAP, but without guarantee. The warranty is the same as for most freeware: It Works For Me, Your Mileage May Vary.

cpanm RAS::HiPerARC

perl -MCPAN -e shell
install RAS::HiPerARC