msutrace

This command provides filter and trace capability for MSUs passing through the IP7 GPLs. This command provides a view of MSU data as it exists in the PSTN network and its corresponding format as it exists in the IP network.

Options

Options and option parameters that are underlined indicate that a value must be specified for that option or parameter. For example, the msutrace command option -a has the parameter action. The action that the command is to take can be specified, as in the command msutrace -a acttrace. Do not enter the underlined option or parameter; enter a value for the information represented by the underlined option or parameter.

-a action

Action option.

Range:

acttrace: Activate (turn on) MSU tracing
clrtrace: Clear all data from trace buffers
dacttrace: Deactivate (turn off) MSU tracing
chgfilter: Change filter used to indicate which MSUs are placed in the trace buffers

-g get option

Get option.

Range:

config: Displays the current command settings: trace ON/OFF status, filter settings, and trace buffers used/available
trace: Displays contents of trace buffers containing captured MSU data

-h help

This option displays help information about the command.

Range:

full

If full is specified, the detailed version of the help information is displayed.

If full is not specified (just -h), the simple verion of the help information is displayed.

-m mode

This option specifies which MSUs are captured.

Range:

normerr: trace only MSUs with normalization errors
all: trace all MSUs regardless of MSU contents

-p point code type

This option specifies which type of point code is contained in the filter key, when the key contains a DPC or OPC.

Range:: ansi, itui, itun, itun24, itun16, ituis, ituns
Default:: ansi

-k filter key

The -k, -c, and -p options are used to specify the filter key used to determine which MSUs will have data placed in the trace buffers.

Range:

-k filter key [-p] [-c pcType]

The syntax for the filter key portion of the -kfilter key option is specified as a single string parameter with up to five colon-separated fields. The filter key can contain one or more of the following fields:

n-c-m—ANSI DPC in the format network-cluster-member
no-co-mo—ANSI OPC in the format network-cluster-member
z-a-i—ITU-I DPC in the format zone-area-id
zo-ao-io—ITU-I OPC in the format zone-area-id
un-sna-mna---16-bit ITU-N DPC in the format unit number-sub number area-main number area
msa-ssa-sp—24-bit ITU-N DPC in the format main sigaling area-sub signaling area-signaling point
nnnnn—ITU-N DPC
nnnnn-gc—ITU-N DPC with Group Code when the Duplicate Point Code feature is ON
no—ITU-N OPC
no-gc—ITU-N OPC with Group Code when the Duplicate Point Code feature is ON
s—SI (Service Indicator)
cs—CIC Start value (start of the CIC range)
ce—CIC End value (end of the CIC range)
n—SSN (Subsystem Number)

These examples show valid formats:

n-c-m:s:n—For DPC, SI, SSN type routing keys. The network, cluster and member (n-c-m) are in the range 0-255. The service indicator (s) is 3 or sccp. The subsystem (n) is in the range 0-255.
n-c-m:s—For DPC, SI type routing keys. The network, cluster and member (n-c-m) are in the range 0-255. The service indicator (s) is in the range 0-2, 4, or 6-15. There is no subsystem number. As a default, counts for all routing keys within the option combination are displayed.
n-c-m:s:no-co-mo:cs:ce—For DPC, SI, CIC type routing keys. The DPC network, cluster and member (n-c-m) are in the range 0-255. The service indicator (s) is 5 or isup. There is no subsystem. The OPC network, cluster and member (no-co-mo) are in the range 0-255. The starting circuit identification code (cs) and ending circuit identification code (ce) are in the range 0 - 16363.
z-a-i—For DPCN and DPCI routing keys, the zone, area and ID (z-a-i) are in the range of 000-007 (zone and ID) and 000-255 (area).
msa-ssa-sp—For 24-bit DPCN routing keys, the main signaling area, sub signaling area and signaling point (msa-ssa-sp) are in the range of 000-255.
un-sna-mna---For 16-bit DPCN routing keys, the unit number, sub number area and main number area (un-sna-mna) are in the range of 0-127, 0-15, 0-31 respectively.

-t

This option specifies the routing key type (IPGWx only).

-x rc

This option generates a routing key report using routing context.

Example

pass:loc=1105:cmd="msutrace -h"

pass:loc=1105:cmd="msutrace -h full"

pass:loc=1105:cmd="msutrace -g config"

pass:loc=1315:cmd="msutrace -g trace"

pass:loc=1105:cmd="msutrace -a clrtrace"

pass:loc=1105:cmd="msutrace -a acttrace"

pass:loc=1105:cmd="msutrace -a chgfilter -p ansi -k 3-3-3:5:4-4-4:10:1000"

pass:loc=1105:cmd="msutrace -a chgfilter -p itui -t partial -k 1-3-3:5:2-4-4"

pass:loc=1105:cmd="msutrace -a chgfilter -p itun -t partial -k 1536:5"

pass:loc=1105:cmd="msutrace -a chgfilter -m normerr"

pass:loc=1105:cmd="msutrace -a chgfilter -m all"

pass:loc=1105:cmd="msutrace -a chgfilter -p ansi -k 1-1-1:5:2-2-2:10:1000"

Dependencies

If no options are specified, the simple version of the help information is displayed.

The point code type defaults to ANSI when the -p option is not specified.

The -p option is allowed only on key types that contain a DPC or OPC.

Notes

The msutrace command is executed through the pass command.

The mustrace command captures the data portion of the PSTN packet, starting at the SIO bytes.

The msutrace command captures the entire M3UA or SUA packet. This includes the M3UA or SUA header and additional data stored inside system buffer chain elements. The msutrace command currently does not support the trace and capture of M3UA / SUA SSNM (Class 2) messages.

The msutrace command captures data in trace buffers. If the set of trace buffers becomes full with captured MSU data after MSU tracing is activated, no more data capturing will take place. The -aclrtrace option must be specified to reset (clear) the content of the trace buffers. After the trace buffers are empty again, msutrace will restart capturing qualified MSUs.

If MSU tracing is activated with the -a acttrace option before a properly formatted filter key is entered, the msutrace command will not capture any data due to lack of a proper filter. When the -a chgfilter option is specified to enter a properly formatted filter, the msutrace command will start capturing qualified MSUs.

Output

Note:

The msutrace pass command exists on the IPLIMI cards as a debug-only pass command. All command syntax and output are identical to the SS7IPGW and IPGWI commands described in this section.

Both brief and full versions of IPGW reports can be requested. A full report is requested by including the -f in the command line.

This example shows a brief help report:

pass:loc=1305:cmd="msutrace -h"

    Usage: msutrace [-a action_cmd] [-g get_cmd]
                    [ [-x rc] | [-k [rtkey] [-p pctype] [-t keytype]] ]
                    [-m mode] [-h [full]]

    Options:
        -a    action_cmd: an Action Command
        -g    get_cmd: a Get Command
        -x    routing key report using routing context
        -k    routing key report using MTP3 parameters
              rtkey :: ([dpc][:si][:opc | :ssn][:cics][:cice])
        -p    pctype :: (ANSI, ITUI, ITUN, ITUN24, ITUN16, ITUIS, ITUNS)
        -t    routing key type
              keytype :: (<full>, partial, default)            
        -m    mode: mode for qualifying MSUs captured=[normerr | all]
        -h    displays this message (brief or full)

    get_cmd:        [config | trace]
        config      config
        trace       trace

    action_cmd:     [acttrace | chgfilter | clrtrace | dacttrace]
        acttrace    acttrace
        chgfilter   chgfilter [<fltrkey>] | [-m mode] (at least 1 required)
                              (valid fltrkey should be present either before
                               specifying mode or in the same command)
        clrtrace    clrtrace
        dacttrace   dacttrace

    <fltrkey>:      [ [-x rc] | [-k [rtkey] [-p pctype] [-t keytype]] ]
                    (see 'msutrace -h full' for complete description)

    MSUTRACE command complete
;

This example shows a full help report:

pass:loc=1305:cmd="msutrace -h full"


    Usage: msutrace [-a action_cmd] [-g get_cmd]
                    [ [-x rc] | [-k [rtkey] [-p pctype] [-t keytype]] ]
                    [-m mode] [-h [full]]

    Options:
        -a    action_cmd: an Action Command
        -g    get_cmd: a Get Command
        -x    routing key report using routing context
        -k    routing key report using MTP3 parameters
              rtkey :: ([dpc][:si][:opc | :ssn][:cics][:cice])
        -p    pctype :: (ANSI, ITUI, ITUN, ITUN24, ITUN16, ITUIS, ITUNS)
        -t    routing key type
              keytype :: (<full>, partial, default)
        -m    mode: mode for qualifying MSUs captured = [normerr | all]
        -h    displays this message (brief or full)

    get_cmd:        [config | trace]
        config      Display the current MSUTRACE settings:
                    trace On/Off status, filter settings, and
                    trace buffers used/available.
                    ex:  msutrace -g config
        trace       Display content of trace buffers containing captured
                    MSU data
                    ex:  msutrace -g trace

    action_cmd:     [acttrace | chgfilter | clrtrace | dacttrace  ]
        acttrace    Activate (turn-on) MSU-tracing.
                    ex:  msutrace -a acttrace
        chgfilter   chgfilter [<fltrkey>] | [-m mode] (at least 1 required)
                              (valid fltrkey should be present either before
                               specifying mode or in the same command)
                    Change filter used to qualify which MSUs are placed in
                    trace buffers:
                    Flow of command should be
                    Either entering filter key before specifying mode :
                    ex: To trace MSUs based on MSU content:
                        msutrace -a chgfilter <fltrkey>
                    ex: To only trace MSUs with Normalization errors:
                        msutrace -a chgfilter -m normerr
                    ex: To trace all MSUs regardless of error conditions:
                        msutrace -a chgfilter -m all
                    Or entering filter key along with mode:
                    ex: To trace MSUs based on MSU content
                           with Normalization errors:
                        msutrace -a chgfilter <fltrkey> -m normerr
                    ex: To trace MSUs based on MSU content
                           regardless of error conditions:
                        msutrace -a chgfilter <fltrkey> -m all

        clrtrace    Clear all data from trace buffers.
                    ex:  msutrace -a clrtrace

        dacttrace   Deactivate (turn-off) MSU-tracing.
                    ex:  msutrace -a dacttrace

        -k option details:

        Use the -p option along with -k to specify the SS7 network
        domain and point code format for the network. The SS7IPGW
        default pctype is ANSI. The IPGWI and IPLIMI
        default pctype is ITUI.

        For IPSG both ANSI and ITU network point code formats are
        eligible for trace when the default filter or an SI only
        filter is specified. The IPSG default pctype is ANSI when the
        filter contains OPC or DPC and the -p option is not specified.

            Network  PC Format Notes
            -------  --------- --------------------------------------
            ANSI     N-C-M
            ITUN     N         Non-Spare ITU National, no group code
            ITUN     N-GC      Non-Spare ITU National with group code
            ITUI     Z-A-I     Non-Spare ITU International
            ITUN24   N-C-M     Non-Spare ITU National, 24-bits
            ITUN16   U-S-M     Non-Spare ITU National, 16-bits
            ITUNS    N         Spare ITU National, no group code
            ITUNS    N-GC      Spare ITU National with group code
            ITUIS    Z-A-I     Spare ITU International

        Use the -t option along with -k to specify certain MTP3 and
        user part MSU fields as wildcards for the routing key or LS.

        SS7 Traffic Partition              RTKEY/MTP3 Parameter Example
        ---------------------------------  ----------------------------
        Any User Part to DPC 1-1-1         -k 1-1-1    -t partial
        SCCP to DPC 1-1-1                  -k 1-1-1:3  -t partial
        ISUP to DPC 1-1-1                  -k 1-1-1:5  -t partial
        TUP to DPC 1-1-1                   -k 1-1-1:4  -t partial
        QBICC to DPC 1-1-1                 -k 1-1-1:13 -t partial
        SI [0-2,6-12,14,15] to DPC 1-1-1   -k 1-1-1:SI
        SCCP SSN 5 to DPC 1-1-1            -k 1-1-1:3:5
        ISUP to DPC 1-1-1 from OPC 2-2-2   -k 1-1-1:5:2-2-2  -t partial
        TUP to DPC 1-1-1 from OPC 2-2-2    -k 1-1-1:4:2-2-2  -t partial
        QBICC to DPC 1-1-1 from OPC 2-2-2  -k 1-1-1:13:2-2-2 -t partial
        ISUP CIC 1 to 1-1-1 from 2-2-2     -k 1-1-1:5:2-2-2:1
        TUP CIC 1 to 1-1-1 from 2-2-2      -k 1-1-1:4:2-2-2:1
        QBICC CIC 1 to 1-1-1 from 2-2-2    -k 1-1-1:13:2-2-2:1
        ISUP CIC 0-5 to 1-1-1 from 2-2-2   -k 1-1-1:5:2-2-2:0:5
        TUP CIC 0-5 to 1-1-1 from 2-2-2    -k 1-1-1:4:2-2-2:0:5
        QBICC CIC 0-5 to 1-1-1 from 2-2-2  -k 1-1-1:13:2-2-2:0:5
        Default Routing Key                -k                 -t default
        Any User Part to DPC=LS APC        -x LS RCONTEXT      (IPSG Only)

;

    tekelecstp 10-03-06 19:41:33 EST  EAGLE5 42.0.9

    MSUTRACE command complete

;

This example shows the current settings of the msutrace command options: trace ON/OFF status, filter settings, and trace buffers that are used and available:

pass:loc=1105:cmd="msutrace -g config"


Command Accepted - Processing
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    pass:loc=1105:cmd="msutrace -g config"
    Command entered at terminal #1.
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    PASS: Command sent to card
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command in progress
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE configurations

    Trace = On

    Trace buffers: 2 of 3 contain captured MSU data

    MSUTRACE: filter settings
    DPCA        SI SSN OPCA        CICS       CICE        MODE
    055-055-055 13 *** 016-006-006 1234567890 1234567890  normerr

;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command complete
;

This example shows the current settings of the msutrace command options: trace ON/OFF status, filter settings, and trace buffers that are used and available, when the filter key specifies an ITU-I spare point code:

pass:loc=1105:cmd="msutrace -g config"


Command Accepted - Processing
    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    pass:loc=1105:cmd="msutrace -g config"
    Command entered at terminal #1.
;
    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    PASS: Command sent to card
;
    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    MSUTRACE command in progress
;
    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    MSUTRACE configurations

    Trace = On

    Trace buffers: 3 of 3 USED

    MSUTRACE: filter settings
       DPCI        SI SSN     OPCI        CICS       CICE        MODE
     s-2-011-1     2  ***     ****        ****       ****        all  
;
    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    MSUTRACE command complete
;

This example shows the current settings of the msutrace command when an IPSG card is used:

pass:loc=1304:cmd="msutrace -g config"

    rlghncxa03w 08-01-29 11:31:09 EST  EAGLE 38.0.0

    MSUTRACE: Configurations

    MSU Tracing is off

    Trace buffers: 0 of 3 USED

    MSUTRACE: filter settings

       DPCA        SI SSN    OPCA        CICS      CICE      MODE
       004-004-004 ** *** ****           ****      ****      all

;

This example shows a trace with a DPC-only filter key specified via the –x <rcontext>option:.

pass:loc=1304:cmd="msutrace -a acttrace"

    rlghncxa03w 08-01-29 11:31:09 EST  EAGLE 38.0.0

    MSUTRACE command complete
;

This example shows the captured trace buffer for an IPSG card:

pass:loc=1304:cmd="msutrace -g trace"


    rlghncxa03w 08-01-29 11:31:09 EST  EAGLE 38.0.0

    ----------
    BUFFER:  0
    ----------
    Filter used:

       DPCA        SI SSN    OPCA        CICS      CICE      MODE
       004-004-004 ** *** ****           ****      ****      all

    Timestamp:  08-01-21  16:06:17.420
    Direction:  Tx
    Error Code:  0

    PSTN DATA
    ---------
    85 04 04 04 05 05 05 00 00 00 00 6e 01 00 f9 e3      ...........n....
    33 c7 00 00 1d 00 00 00 00 10 00 12 00 14 00 16      3...............
    00 18 00 1a 00 1c 00 1e 00                           .........

    IP DATA
    -------
    01 00 01 01 00 00 00 44 00 06 00 08 00 00 00 04      .......D........
    02 10 00 31 00 05 05 05 00 04 04 04 05 02 00 00      ...1............
    00 00 00 6e 01 00 f9 e3 33 c7 00 00 1d 00 00 00      ...n....3.......
    00 10 00 12 00 14 00 16 00 18 00 1a 00 1c 00 1e      ................
    00 00 00 00                                          ....


    MSUTRACE command complete
;

This example retrieves contents of the trace buffers. The example contains 1 stored trace buffer for a transmitted M3UA PDU.

pass:loc=1303:cmd="msutrace -g trace"


Command Accepted - Processing
    eagle10202 01-01-19 10:20:56 GMT  EAGLE5 31.6.0
    pass:loc=1303:cmd="msutrace -g trace"
    Command entered at terminal #4.
;

    eagle10202 01-01-19 10:20:56 GMT  EAGLE5 31.6.0
    PASS: Command sent to card
;

    eagle10202 01-01-19 10:20:56 GMT  EAGLE5 31.6.0

    MSUTRACE command in progress
;

    eagle10202 01-01-19 10:20:56 GMT  EAGLE5 31.6.0

    ----------
    BUFFER:  0
    ----------
    Filter used:

    DPCA        SI SSN OPCA        CICS      CICE      MODE
    001-001-001 5  *** 001-001-002 0         100       all

    Timestamp:  02-06-07  08:40:29.435
    Direction:  Tx
    Error Code:  0

    PSTN DATA
    ---------
    85 01 01 01 02 01 01 b2 00 00 01 00 00 00 00 03      ................
    05 00 02 80 80 0d 00 00 21 43 65 87 09 21 43 65      ........!Ce..!Ce
    87 09 01                                             ...

    IP DATA
    -------
    01 00 01 01 00 00 00 3c 02 00 00 08 00 00 00 01      .......<........
    02 10 00 2b 00 01 01 02 00 01 01 01 05 02 00 b2      ...+............
    00 00 01 00 00 00 00 03 05 00 02 80 80 0d 00 00      ................
    21 43 65 87 09 21 43 65 87 09 01 00                  !Ce..!Ce....


    MSUTRACE command complete
;

This example retrieves contents of the trace buffers with ITU-I spare point codes. The example contains 3 stored trace buffers.

pass:loc=1317:cmd="msutrace -g trace"


Command Accepted - Processing
    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    pass:loc=1317:cmd="msutrace -g trace"
    Command entered at terminal #4.
;

    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0
    PASS: Command sent to card
;

    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0

    MSUTRACE command in progress

;

    eagle20003 05-01-27 10:16:03 EST  EAGLE5 31.12.0

    ----------
    BUFFER:  0
    ----------
    Filter used:

       DPCI        SI SSN    OPCI        CICS       CICE      MODE
     s-2-011-1     2  ***    ****        ****       ****      all

    Timestamp:  05-01-26  10:33:14.330
    Direction:  Tx
    Error Code:  0

    PSTN DATA
    ---------
    02 59 50 16 a2 80 03 83 ce 46 0a 00 00 00            .YP......F....

    IP DATA
    -------
    54 41 4c 49 6d 74 70 33 0e 00 02 59 50 16 a2 80      TALImtp3...YP...
    03 83 ce 46 0a 00 00 00                              ...F....

    ----------
    BUFFER:  1
    ----------
    Filter used:

      DPCI        SI SSN    OPCI        CICS       CICE      MODE
    s-2-011-1     2  ***    ****        ****       ****      all

    Timestamp:  05-01-26  10:33:14.335
    Direction:  Tx
    Error Code:  0

    PSTN DATA
    ---------
    02 59 50 16 a2 80 84 04 c8 46 0a 00 00 00            .YP......F....

    IP DATA
    -------
    54 41 4c 49 6d 74 70 33 0e 00 02 59 50 16 a2 80      TALImtp3...YP...
    84 04 c8 46 0a 00 00 00                              ...F....

    ----------
    BUFFER:  2
    ----------
    Filter used:

       DPCI        SI SSN    OPCI        CICS       CICE      MODE
     s-2-011-1     2  ***    ****        ****       ****      all

    Timestamp:  05-01-26  10:33:14.340
    Direction:  Tx
    Error Code:  0

    PSTN DATA
    ---------
    02 59 50 16 f2 80 01 81 c1 46 0f 00 00 00            .YP......F....

    IP DATA
    -------
    54 41 4c 49 6d 74 70 33 0e 00 02 59 50 16 f2 80      TALImtp3...YP...
    01 81 c1 46 0f 00 00 00                              ...F....


    MSUTRACE command complete

;

This example clears the contents of the trace buffers:

pass:loc=1105:cmd="msutrace -a clrtrace"


Command Accepted - Processing

    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    pass:loc=1105:cmd="msutrace -a clrtrace"
    Command entered at terminal #1.
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    PASS: Command sent to card
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command in progress
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command completed
;

This example activates MSU tracing:

pass:loc=1105:cmd="msutrace -a acttrace"


Command Accepted - Processing

    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    pass:loc=1105:cmd="msutrace -a acttrace"
    Command entered at terminal #1.
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    PASS: Command sent to card
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command in progress
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command completed
;

This example deactivates MSU tracing:

pass:loc=1105:cmd="msutrace -a dacttrace"


Command Accepted - Processing

    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    pass:loc=1105:cmd="msutrace -a dacttrace"
    Command entered at terminal #1.
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    PASS: Command sent to card
;
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command in progress
;   4.0.0
    eagle20003 99-11-27 10:16:57 EST  EAGLE5 31.6.0
    MSUTRACE command completed
;

Examples for Entering a Filter Key

The output shown at the end of these command examples is the same for each example, except for the echo of the entered command.

Command with the -a chgfilter option to insert a fully specified ANSI PC CIC filter key.