TL1

The TL1 protocol is used by network operators to manage optical and other networking equipment produced by multiple vendors. Although it is has a terse and unusual command syntax, it was created with the intent of being useful for interactive, command-line-like use.

This library offers a small set of utility classes intended for automating TL1 sessions. It was initially created in 2017 to interact with BTI 7200 devices, but it aspires to be useful for anything that speaks TL1.

tl1 is tested on Ruby 2.3 and 2.4 but probably works on anything newer than 2.0. It has no other formal dependencies, but to make it useful, you probably need Net::SSH::Telnet (https://github.com/duke-automation/net-ssh-telnet), see Connecting below.

Add this line to your application's Gemfile:

gem 'tl1'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tl1

The first step is to instantiate some sort of I/O object to handle the lower-level communications with the target device. The TL1 protocol rides on top of other networking protocols such as SSH or telnet, but TL1 doesn't have any methods to open a socket. Instead, you will probably want to use Net::SSH::Telnet (or perhaps Net::Telnet) to establish an interactive sesssion, and pass that object in to TL1::Session.new:

require 'net/ssh/telnet'
require 'tl1'
ssh = Net::SSH::Telnet.new(
  'Host' => hostname,
  'Port' => port,
  'Username' => username,
  'Password' => password
)
tl1 = TL1::Session.new(ssh)

If you are (carefully!) using Telnet instead of SSH, you can substitute Net::Telnet for Net::SSH::Telnet. If neither of those works for you, you can try using any IO subclass (for example a pipe) in conjunction with expect from the standard library, which adds an #expect method to IO. The only methods needed on the object passed to TL1::Session.new are #write and #expect.

If you need to log in, change modes, or take any other action to prime the target device to speak TL1, outside of the TL1 protocol, do that before calling TL1::Session.new. ACT-USER, CANC-USER, and other session management actions that occur within the TL1 protocol should be done via the TL1::Session.

In tl1, commands are objects that define a format for constructing an input message (the "command") and a format for reading an output message (the "response"). The syntax of the format string is intended to be close to the documentation supplied by the vendor.

A handful of sample commands for the BTI 7200 platform are defined in tl1/platforms/bti.rb.

A new command can be defined using TL1::Command.new:

RTRV_EQPT = TL1::Command.new(
  'RTRV-EQPT',
  '<aid>:<type>:ID=<id>,C1=<custom1>,C2=<custom2>,C3=<custom3>:<pst>,<sst>'
)
tl1.cmd(RTRV_EQPT)

The first argument to TL1::Command.new is an input message format: in its simplest form, a command string to be sent to the target device.

The second argument to TL1::Command.new is an output message format. Records in the output message are extracted and converted into hashes according to the format string. Records are divided into fields, which are separated by colons, may be further separated by commas, and if separated by commas, may be labeled with a keyword. If the second argument is omitted (or nil), the raw output for that command will be returned as a string, with no parsing.

Examples of each type of field are given above. aid and type are simple strings. id, custom1, custom2, and custom3 are keyword-labeled strings sharing a single field, and separated by commas within that field. pst and sst are strings sharing a single field and separated by commas within that field.

When TL1::Session#cmd is called with a TL1::Command argument, the command's defined input message is sent to the session's underlying IO, and the received output message is processed according to the output format string.

An output message for the RTRV_EQPT command might look like this:

   bti7200hoge 17-08-31 16:29:53
M  100 COMPLD
   "MS-1:BT7A51AR::IS-NR,"
   "D40MD-0-2:BT7A37AA::,"
;
BTI7000>

And then the returned array of records for that output message will look like this:

[
  { aid: 'MS-1', type: 'BT7A51AR', pst: 'IS-NR', sst: '' },
  { aid: 'D40MD-0-2', type: 'BT7A37AA', pst: '', sst: '' }
]

Note that the keyword-labeled fields are missing (because their keywords are missing), while other fields that are empty are present and represented as empty strings.

Some commands will accept arguments. For example, a more complete implementation of RTRV_EQPT will accept an aid to narrow the query:

RTRV_EQPT = TL1::Command.new(
  'RTRV-EQPT:<tid>:<aid>:<ctag>',
  '<aid>:<type>:ID=<id>,C1=<custom1>,C2=<custom2>,C3=<custom3>:<pst>,<sst>'
)
tl1.cmd(RTRV_EQPT, aid: 'MS-1')
# => [{ aid: 'MS-1', type: 'BT7A51AR', pst: 'IS-NR', sst: '' }]

The input and output format strings have the same syntax. Items in angle brackets are optional variables, unbracketed text is literal. It's common for vendors to specify a field as "mandatory" or "optional", but we don't make any attempt to distinguish between them here; in effect, all fields are treated as optional.

Most fields will be variables, but occasionally there will be a literal field. In the following command definition, the first field of the output format is a literal representing the empty string (""), and the last field is a literal representing the string "asdf":

RTRV_ROUTE_CONN = Command.new(
  'RTRV-ROUTE-CONN',
  ':<ipaddr>,<mask>,<nexthop>:COST=<cost>,ADMINDIST=<admindist>:asdf'
)

Literals don't affect the output of parsing, but they will raise an exception if the output message has text in that field that does not exactly match the literal. In the above command definition, all output records are required to start with ":" and end with ":asdf".

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/bjmllr/tl1 . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Please include tests with any pull request. If you need help with testing, please open an issue.

The gem is available as open source under the terms of the GNU General Public License version 3.