NAME

Device::Router::RTX - interact with Yamaha RTX routers

SYNOPSIS

    use utf8;
    use FindBin '$Bin';
    use Device::Router::RTX;
    my $rtx = Device::Router::RTX->new (
        address => '12.34.56.78',
        password => 'pwd',
        admin_password => 'admin_pwd',
    );
    $rtx->connect ();

VERSION

This documents Device::Router::RTX version 0.06 corresponding to git commit 2dbe79580bfdf0991b02f9caaf8ba6483fc0a2ec released on Wed Jan 25 13:03:47 2017 +0900.

DESCRIPTION

This module allows one to automate some interactions with Yamaha RTX routers.

METHODS

new

    my $rtx = Device::Router::RTX->new (
        address => '12.34.56.78',
    );

Create a new object for communicating with the router. The IP address of the router is compulsory. If the router has a password set, you also need to supply a password. For some commands, you need to set the administrator password.

This does not open a telnet connection to the router. Use "connect" to open the telnet connection.

The fields which may be supplied to new are

address

The IP address of the router on your subnet.

password

If your router has a password set, supply it here.

admin_password

If your router has an administrator password set, supply it here.

config

The name of your configuration file. If you supply this, it reads it using "read_config".

verbose

Print debugging messages.

connect

    $rtx->connect ();

Connect to the router. This dies if there is an error. If you need to debug the telnet connection, see the source code of the module which contains extensive debugging code (commented out for the production version).

get_config

    $rtx->get_config ("config");

Get the router's configuration file and put it into the file config. This uses TFTP (trivial FTP). It dies on error. If you have not set an administrator password in "new" but your router requires one, this will fail with an error "Access violation".

read_config

    $rtx->read_config ("config");

Read a router configuration file from the specified local file.

Not every option of the router is specified.

save

    $rtx->save ();

Save an altered configuration to the router's permanent memory.

command

    $rtx->command ($command);

Send a command to the router specified by $command, and save it.

wake

   $rtx->wake (<LAN>,<MAC>);

Send a "wake-on-lan" ("wol") packet to the specified MAC address on the specified LAN (give the number of the LAN, e.g. 1-3 for RTX1000 routers). There is no return value.

arp

    my $arp = $rtx->arp ();

Read the router's arp table. The return value is the undefined value if the command fails, or an array reference containing hash references if it succeeds. The hash references have four fields, lan (the number of the local area network), ip (the IP address), mac (the MAC address) and ttl (time to live).

The following example shows retrieving MAC and IP from the router:

    use Device::Router::RTX;
    my $rtx = Device::Router::RTX->new (address => '12.34.56.78',);
    my $arp = $rtx->arp();
    if ($arp) {
        for my $entry (@$arp) {
            print "MAC: $entry->{mac} IP: $entry->{ip}.\n";
        } 
    } 

TESTING

The default module test does nothing except try to load the module and then exit. There is an extra test in the file extratests/connecting-test.t which actually tries to connect to the router and do a few things. You can either edit this file to insert the password and IP address of your router, or you can set the following environment variables:

RTX_ADDRESS

Set this to the IP address of your router.

RTX_PASSWORD

Set this to the user password of your router. If the router's password is unset, set this to an empty string.

RTX_ADMIN_PASSWORD

This is the administrator password.

When you run the test, and some environment variables are incorrectly set, then run the test again shortly afterwards, or if you run the test when you already have a telnet session open, you may find that the telnet connection is refused. This is a limitation of the device itself, so close all connections, wait for a short time, and try again.

SEE ALSO

About RTX routers

Yamaha's router site

The manufacturer's Japanese-language site. I'm not aware of an English language site.

Yamaha RTX1000 router

A guide to some of the router's commands by Ben Bullock (author of this module).

Getting started with Yamaha Routers by Simon Gibson at Denphone

A guide to some commands.

Other Perl modules

Net::MAC::Vendor

This allows you to look up the vendor for a MAC, which is quite useful when looking at an arp table generated by "arp", and trying to work out what device a particular MAC address represents.

DEPENDENCIES

Net::Telnet

Net::TFTP

Carp

DISCLAIMER

The author of this Perl module is not and has never been affiliated with Yamaha Corporation. The author cannot take any responsibility for what happens to your router or other security systems if you use this module. Please carefully evaluate the source code before operating, and use this code only at your own risk.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2012-2017 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.

cpanm Device::Router::RTX

perl -MCPAN -e shell
install Device::Router::RTX