Terminal Services Configuration Guide, Cisco IOS XE Release 16.x

Cisco IOS Protocol Translation and Translation by Ruleset

The Cisco IOS software provides protocol translation capability that can be used in many types of networks and translate between incoming connection protocols such as TCP/IP, X.25 packet assembler/disassembler (PAD), and local-area transport (LAT), and a set of outgoing protocols that includes TCP/IP, X.25 PAD, LAT, PPP, and Serial Line Internet Protocol (SLIP). Each translation configuration is entered as a single command line, and users can choose from a lengthy list of options to define configurations for specific environments. For some users, however, it is more important to be able to quickly and efficiently define translation connections for a large number of addresses. The Protocol Translation Ruleset feature provides this capability by defining Cisco IOS protocol translation configurations in a ruleset. The ruleset is defined by using regular expression pattern matching and operations that match or ignore incoming connection requests. Substitute, set, and test string writing operations create the connection configurations based on an incoming address. This combination of pattern matching and string writing operations makes it possible to convert, for example, an IP port number to an X.121 address using just a few statements, rather then enter each configuration statement on a separate line.

The protocol translation capability introduced in the Protocol Translation Ruleset feature for Cisco IOS Release 12.3(8)T supports protocol translation from PAD to TCP and from TCP to PAD. Options are available for translations created in the ruleset to define a maximum number of sessions, require login, match an access list, and that suppress translation information messages on the session.

The Cisco IOS Release 12.3(8)T software will accept both the single-line translate commands (such as translate pad and translate tcp) and their option settings, and protocol translation statements defined in a ruleset, in the same configuration file. The ruleset configuration is applied after the incoming protocol translation connections are tested against the single line translate command configuration, so that you can make use of both the robust protocol translation capability currently available in the Cisco IOS software, and of a protocol translation ruleset that allows quick configuration of a large number of addresses.

The new ruleset environment will seem familiar to users that already know Cisco’s single-line translate commands, in that many of the same keywords that are available for these commands are also used in the protocol translation ruleset. A new global configuration command, translate ruleset, specifies a name for the ruleset, defines the direction of translation, either from PAD to TCP or from TCP to PAD, and starts translate ruleset configuration mode. The translate ruleset configuration mode allows much flexibility in the number of statements accepted on each line. The mode also accepts multiple statements of the same type. The translate ruleset configuration mode provides match and skip commands to create statements that look at incoming connection requests to determine if they are valid, and substitute, set, and test commands for string writing operations that will help configure the translation session.

To assist you with writing statements that configure the connections and options needed for your network, the Protocol Translation Ruleset feature provides the test translate and show translate ruleset privileged EXEC commands. The test translate command is interactive and will step through the command statements to test their validity. The show translate ruleset command displays information about the connection rulesets to help you modify and maintain them.

Cisco Regular Expression Pattern Matching

Table 1 summarizes the basic Cisco IOS regular expression characters and their functions.

The order for matching using the * or + character is longest construct first. Nested constructs are matched from the outside in. Concatenated constructs are matched beginning at the left side. If a regular expression can match two different parts of an input string, it will match the earliest part first.

Regular Expression Pattern Matching in a Protocol Translation Ruleset

Regular expressions for the Protocol Translation Ruleset feature have two uses: They match a text string against a defined pattern, and they can use information from a defined regular expression match operation to create a different string using substitution. These operations are performed by combining the characters described in Table 1 with commands from the translate ruleset configuration mode.

To understand regular expression pattern matching, begin by using Table 1 to interpret the following regular expression statement to match a string starting with the characters 172.18.:

^172\.18\..*

The following regular expression statement matches a five-digit number starting with 10 or 11:

^1[0-1]...$

Consider the following set of actions in a ruleset named B. This ruleset listens for incoming Telnet connections from a particular IP address and port number but ignores (skips) others, decides which PAD destination address the matched incoming connections should be connected to, then finally sets the PAD connection’s X.25 VC idle timer from the first digit of the port number.

translate ruleset B from telnet to pad

match dest-addr ^10.2.2.(..)$ dest-port ^20..$

skip dest-addr ^10.2.2.11$

set pad dest-addr 4444

substitute telnet dest-port ^200(.)$ into pad idle \1

The caret sign anchors a match to the beginning of a string, in this example, 10.2.2 for the destination address and 20 for the destination port.

The parentheses are a powerful tool for the regular expression match operation because they identify groups of characters needed for a substitution. Combined with the substitute...into statement, the parentheses can dynamically create a broad range of string patterns and connection configurations.

In the example, the periods in the parentheses pair can be thought of as placeholders for the characters to be substituted. The dollar sign anchors the substitution match to the end of a string. The backslash preceding the number makes it a literal setting, so no substitution will be done to the idle timer setting.

The test translate ruleset command tests the script, and for the previous example would provide a report like the following:

Translate From: Telnet 10.2.2.10 Port 2000

To: PAD 4444

Ruleset B

0/1 users active

Consider the following, more complex expression:

^172\.18\.(10)\.(.*)$.

This expression matches any string beginning with 172.18. and identifies two groups, one that matches 10 and the other that matches a wildcard character.

Let us say that the regular expression ^172\.18\.(10)\.(.*)$ matched the characters 172.18.10.255 from an incoming connection. Once the match is made, the software places the character groups 10 and 255 into buffers and writes the matched groups using a substitution expression.

Regular expression substitution into the expression 0001172018\1\2 would generate the string 000117201810255.

The regular expression \0 would write the entire matched string, and substitution into the expression 0001\0 would generate the string 0001172.18.10.255.

Error Handling in the Protocol Translation Ruleset

Configuration errors are not detected when translation ruleset commands are entered. They are tested when the connection is attempted or with the test (ruleset) EXEC command. In the following example, the set statement unconditionally sets the PAD’s profile name to a profile that does not exist in the configuration:

set pad profile Bldg-1-5ess

This command would be accepted at the command-line interpreter, and validated only upon a connection attempt or with the test (ruleset) command. When the error is detected, the following messages display:

*%PT-3-PARAMRESULTERR: PT ruleset test protocol pad parameter profile parse error: Bldg-1-5ess.

-Process= "PAD InCall", ipl= 3, pid= 94

*PAD: ruleset translation not generated Cause: 9 Diag: 0

Configuring a PVC for Protocol Translation Rulesets

The protocol translation rulesets make connections only to a PVC that has been reserved for ruleset handling. Perform the following task to reserve the PVCs.

SUMMARY STEPS

1. enable

2. configure terminal

3. interface serial slot / port

4. x25 pvc number translate ruleset name

5. exit

DETAILED STEPS

What to Do Next

Perform the tasks in the section “Creating Protocol Translation Rulesets” to create the protocol translation rulesets that configure protocol translation connections. Your rulesets may be simpler or more complex than those shown in the “Configuration Examples for the Protocol Translation Ruleset Feature” section, depending upon the requirements of your network.

Creating Protocol Translation Rulesets

This section describes how to create the protocol translation rulesets.

Components of a Ruleset

A protocol translation ruleset is defined by using a combination of pattern matching and commands that match or skip incoming connection requests, and then write connection configuration statements using substitute, test, and set operations. For example, telco customers that need many unique connections based on the telephone numbers in an exchange can use rulesets to generate the hundreds of specific commands as connections are established. Each generated command guides the interface and switched virtual circuit (SVC) or PVC assignment based on the incoming IP address and port selection elements.

You create the protocol translation rulesets in translate ruleset configuration mode, which is accessed when you issue the translate ruleset global configuration command. You define the ruleset name and the incoming and outgoing protocols to be translated using commands available in the translate ruleset configuration mode.

Numerous configuration options can be entered as part of the translation ruleset, and these options are described in the command pages for the translate ruleset global configuration command, and the description, match, options, set, skip, substitute, and test translate ruleset configuration commands.

Prerequisites

You must understand how to compose statements using Cisco regular expressions for matching patterns in a translation ruleset. See the instructions for composing regular expressions in the “Regular Expression Pattern Matching in a Protocol Translation Ruleset” section in this document, or the “Related Documents” section.

SUMMARY STEPS

1. enable

2. configure terminal

3. translate use telnet ip-address (used only for Telnet-to-PAD translations statements)

4. translate ruleset name from incoming-protocol to outgoing-protocol

5. description text

6. { match | skip } [ line-number ] incoming-connection-parameter regular-expression [ line-number incoming-connection-parameter regular-expression [ ... ]]

7. substitute [ line-number ] { pad | telnet } variable-parameter reg-exp-match into { pad | telnet } variable-parameter [ reg-exp-write ]

8. test [ line-number ] { pad | telnet } variable-parameter reg-exp-match [ { pad | telnet } variable-parameter reg-exp-match [...]] set { pad | telnet } variable-parameter

9. set [ line-number ] { pad | telnet } variable-parameter [{ pad | telnet } variable-parameter [ ... ]]

10. options rule-option value [ rule-option value […]]

11. exit

DETAILED STEPS

Testing and Maintaining Protocol Translation Rulesets

Perform this task to test and review your protocol translation rulesets.

SUMMARY STEPS

1. enable

2. test translate { pad | telnet | parameter parameter } [ detail ]

3. show translate ruleset [ name ]

DETAILED STEPS

PAD-to-Telnet Translation Ruleset: Example

In the following example, the incoming PAD address 55555 yields Telnet address 10.2.2.1, port 23 (default Telnet port). The local Boolean flag in the substitute statement specifies that Telnet protocol negotiations for PAD connections with destination addresses 55550 through 55555 should be forwarded, not processed.

SVC Conversion with Translation Ruleset Service Selection: Example

The following example shows the selection of the outbound X.25 serial interface and the PAD profile for the Calling application based on the IP port number:

Address Conversion in a Translation Ruleset: Example

The following translation ruleset example reduces the number of statements for converting the IP port number to an X.121 address for the following range of port numbers:

IP Address: 10.10.1.5 10000-19999 to X.121 Address 5559000000-9999
IP Address: 10.10.1.5 20000-29999 to X.121 Address 5559010000-9999
IP Address: 10.10.1.5 30000-39999 to X.121 Address 5559020000-9999
IP Address: 10.10.1.5 40000-49999 to X.121 Address 5559110000-9999
IP Address: 10.10.1.5 50000-59999 to X.121 Address 5559200000-9999

Reserve PVC for Protocol Translation Ruleset: Example

The following example shows how to reserve a PVC for protocol translation ruleset handling, and select the outbound X.25 serial interface and PVC number based on the IP port number:

Displaying Ruleset Configuration Parameters: Example

The following example displays a summary of a configured translate ruleset named Template_1 that includes behavioral parameters, usage statistics, and line numbers for maintaining the configuration:

Testing the Ruleset Configuration Parameters: Example

The following example shows a detailed trace of PAD ruleset configurations:

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.

© 2008 Cisco Systems, Inc. All rights reserved.