TL1 commands and the TL1 protocol, explained

TL1 at a glance

Full name

Transaction Language 1

Origin

Bellcore, 1984

Standard

Telcordia GR-831-CORE (language), GR-833 (surveillance and maintenance messages)

Used on

SONET, SDH, DWDM and OTN network elements

Message types

Input, response, acknowledgement, autonomous

Typical transport today

SSH, with login handled inside the TL1 session

Sources: Wikipedia, Transaction Language 1; DPS Telecom TL1 tutorial. Checked 4 October 2026.

What TL1 is, and why it's still here

Bellcore built TL1 in 1984 so the Regional Bell Operating Companies could manage network elements from different vendors with one language. Telcordia's GR-831 defines it. It is plain ASCII, readable by a person at a terminal and parseable by an operations support system, which was exactly the brief.

The brief aged. The protocol didn't go anywhere. Transport gear has a long service life, operators don't rip out working optical networks to get a nicer API, and vendors kept shipping TL1 on new platforms because their customers' OSS stacks already spoke it. Ciena says its 6500 family is deployed in over a thousand networks with more than 250,000 nodes in operation, and it is managed over TL1. Cisco has retired the ONS 15454, and plenty of them are still carrying traffic.

So if you work anywhere near optical transport, you will meet TL1. Usually at 2am, usually through a gateway.

Anatomy of a TL1 command

Every TL1 input message has the same shape. Fields are positional and separated by colons, and the message ends with a semicolon:

VERB-MODIFIER:TID:AID:CTAG::PARAMETERS;

Here's a real one, pulling inventory for one slot on a named shelf:

RTRV-EQPT:NE-DUBLIN-01:SLOT-1:CTAG42;

• RTRV, the verb. What you want done. RTRV retrieves, ENT creates, ED edits, DLT deletes, ACT activates.
• EQPT, the modifier. What you want it done to. Some commands take two modifiers, as in RTRV-ALM-ALL.
• NE-DUBLIN-01, the target identifier (TID). Which network element should answer. Leave it empty and the NE you are connected to answers. Behind a gateway, the TID is how you reach a remote NE.
• SLOT-1, the access identifier (AID). Which part of that NE. ALL is common.
• CTAG42, the correlation tag (CTAG). Any tag you choose. The NE echoes it in the response, and that is how you match answers to questions.

Empty fields still need their colons. RTRV-SYS:::CTAG001; means “no TID, no AID, CTAG001”. Drop a colon and every field after it shifts one place left. The NE will tell you so, eventually, with a DENY.

Responses, acknowledgements and alarms

TL1 has four kinds of message, and a client has to cope with all of them arriving on the same session.

Responses

A response repeats who answered and when, then your CTAG and a completion code. COMPLD means it worked. DENY means it didn't, and the next line carries a four-letter reason.

RTRV-ALM-ALL:::CTAG004;
   CIENA-LAX-1001 26-06-07 11:42:30
M  CTAG004 COMPLD
   "SLOT-2:MN,CONTBUS,SA,,,,:\"Intermittent equipment communication\""
   "SLOT-7:MJ,T-LOS,NSA,,,,:\"Loss of signal\""
;

The M marks a response to a command. Each quoted line is one record. The lone ; closes the message.

Acknowledgements

If a command will take more than about two seconds, the NE may send an acknowledgement first so you don't give up on it. The common ones are IP (in progress) and PF (printout follows), both meaning wait for the real response. OK, NA (no acknowledgement), NG (no good) and RL (repeat later) also exist. A client that treats any line containing your CTAG as the answer will read IP as the result and move on.

Autonomous messages

The NE can also speak without being asked. Alarms and events arrive as autonomous messages, tagged with their own ATAG instead of your CTAG, at any point in the session, including halfway through a long retrieval. The second line starts with an alarm code: *C critical, ** major, * minor, A for a non-alarm event.

   CIENA-LAX-1001 26-06-07 11:44:02
** 0871 REPT ALM EQPT
   "SLOT-7:MJ,T-LOS,NSA,,,,:\"Loss of signal\""
;

Illustrative autonomous alarm in GR-833 style.

This is where most home-grown TL1 scripts fall over. Matching on the CTAG, not on “the next thing that came back”, is the whole fix.

Common TL1 commands

Verbs and modifiers are standardised in shape, not in coverage. Most NEs support the first group. The second group exists everywhere but the exact modifiers depend on the vendor and platform, so check the NE's own TL1 reference before you run anything that changes state.

Everything in the top half is safe to run against production. Everything in the bottom half is not something you want a typo in.

Example login:

ACT-USER::admin:CTAG002::admin;
   CIENA-LAX-1001 26-06-07 11:42:18
M  CTAG002 COMPLD
   /*AUTHTYPE=LOCAL*/
   /*USERID=ADMIN*/
;

In ACT-USER the AID field carries the username and the parameter block carries the password. The /* */ lines are comments.

TL1 error codes you'll see first

A DENY comes with a four-letter code. The first letter tells you the category (I for input, P for privilege, and so on). These are the ones that turn up early:

Treat every DENY as a failure, with its code recorded. A denied response saved as a backup is worse than no backup, because it looks like one.

Vendor dialects: Ciena 6500, Cisco ONS 15454, Infinera DTN-X

The grammar is shared. Everything around it varies. These are the differences that mattered when we wrote drivers for each.

Ciena 6500

Records are mostly KEY=VALUE, which makes parsing kind. Gateway NEs front remote NEs, and you list them with RTRV-NE-LIST. That list leaves out the gateway itself. A routed response carries the remote NE's name in its header, so you can confirm where the answer came from.

Ciena 6500 TL1 GNE/RNE routing, with session output

Cisco ONS 15454

Network inventory comes from RTRV-MAP-NETWORK, and its records are positional with no keywords at all: address, node name, product, in that order. The gateway lists itself first. The prompt is <. Cisco has retired the platform, which hasn't stopped it carrying traffic.

Infinera DTN-X

The prompt is >, not <, so a client waiting for < waits forever. RTRV-TIDMAP pages its answer across several blocks, with the prompt appearing between them. Stop reading at the first prompt and the remaining pages sit in the socket and break CTAG matching for every command after. Routed replies carry the gateway's name, not the remote NE's, so the header can't confirm routing.

Dialect notes from rConfig's TL1 driver references: Ciena 6500, Cisco ONS 15454, Infinera DTN-X.

Getting a TL1 session

On current platforms TL1 usually runs over SSH. The catch is that SSH only gets you a session. Authentication happens inside it, with ACT-USER, and until that returns COMPLD the NE refuses everything with PLNA.

Older shelves often expose TL1 on raw TCP or telnet ports instead. The port numbers vary by vendor and release, so take them from the NE's own TL1 documentation, not from a forum post.

Behind a gateway, you open one session to the gateway and reach remote NEs by putting their name in the TID. One session, many NEs.

TL1 vs SNMP vs NETCONF

They overlap less than people assume.

On a lot of transport kit, TL1 is still the only interface that exposes everything. SNMP tells you something is wrong. TL1 tells you what's in the slot.

From TL1 commands to TL1 configuration management

Running RTRV-EQPT by hand is fine for one shelf. Doing it every night across a few hundred, through gateways, matching CTAGs, recording every DENY, and keeping a diffable history per NE is a different job. That's the job we built rConfig's TL1 drivers for.

rConfig 8.3 and later collects from Ciena 6500, Cisco ONS 15454 and Infinera DTN-X over TL1, stores each retrieval as a version, and puts the optical estate in the same inventory as the routers.

Further reading

• Wikipedia, Transaction Language 1
• DPS Telecom TL1 tutorial
• Ciena 6500 TL1 driver
• Cisco ONS 15454 TL1 driver
• Infinera DTN-X TL1 driver
• Ciena TL1 examples
• Ciena 6500 TL1 GNE/RNE routing, with session output
• Why we simulate the Ciena 6500

If you're automating TL1 yourself, rConfig Sim will stand up simulated Ciena, Cisco and Infinera NEs for you to break things against. It's open source.