This chapter describes using the command line interface (CLI) to manage and monitor your WebRTC Session Controller Media Engine (ME) system.
You can configure, manage, and/or monitor ME using any one of the following interfaces:
Command line interface (CLI)
ME Web-based management system
SNMP (Simple Network Management Protocol)
XML (Extensible Markup Language)
WSDL (Web Services Description Language)
The CLI is a text-based interface that allows you to manage and configure all aspects of ME. Use the CLI to create, edit, and display the ME configuration file. In addition, you can display various components of system status and data. You can access the CLI using a PC or system console, Telnet application, or Secure Shell protocols (SSH1 and SSH2).
The CLI features a quick-start script that allows you to complete basic configuration through prompting. See the Oracle Communications OS-E System Installation and Commissioning Guide for more information.
You access the CLI from a system console (serial connection), Telnet, or SSH.
The following procedure lists the steps for accessing the CLI using a system console attached to ME:
Connect a PC to the ME device by connecting an EIA-232 (RS-232) straight-through serial cable between the console port on the system and the PC COM1 or serial port.
Start a terminal emulator on the PC. Tera Term Pro and HyperTerminal are popular terminal emulation programs.
Configure the terminal emulator for: T100 emulation, or let it autodetect the terminal type. 115200 baud, 8 data bits, no parity bit, 1 stop bit (8/N/1), no flow control.
Press [Enter] on the PC keyboard until the CLI prompt appears: NNOS-E> _
The following procedure lists the steps for accessing the CLI using Telnet, the TCP/IP terminal emulation protocol:
Connect the ME device to a network that the Telnet-client system can reach by connecting a network cable from the Ethernet 0 port on the device to a network patch panel, Ethernet switch, or device.
Configure an IP address for the Ethernet port according to instructions in the Oracle Communications WebRTC Session Controller System Administration Guide.
Start the Telnet client. The default Telnet port is 23 (although you may configure the ME and client for a different port number). At the Telnet prompt, enter open ipaddress, where ipaddress is the IP address of the ME.
Log in using the user name and password that the system administrator assigned to you. username: user1, password: mypassword, NNOS-E>
The following procedure describes how to access the CLI using SSH1 or SSH2 (Secure Shell, a secure Telnet-like terminal emulation protocol). See Supported SSH clients for a list of supported SSH clients.
Connect the system to a network that the SSH client system can reach by connecting a UTP/STP Category 5 network cable from the Management port to a network patch panel or device.
Configure an IP address for the Management port according to the instructions in the Oracle Communications WebRTC Session Controller System Administration Guide.
Start the SSH client and specify the host name or address for the system. If using the password authentication method, the system prompts you for a password. Otherwise, if using a valid public key or no authentication is required, you connect to the system.
Log in using the user name and password that the system administrator assigned to you: username: secureuser1, password: mypassword, NNOS-E>
The ME CLI structure consists of a command hierarchy of configurable objects and properties. When you use the CLI to create, edit, or modify the configuration, the software writes the new configuration to the default file named cxc.cfg.
It is important to understand the states of the ME configuration file: saved, running, and working:
the working config, which keeps a record of configuration edits
the running config, which is used by the system
the saved config, which the system boots from.
Before using the CLI, refer to the Oracle Communications OS-E Management Tools Guide for a description of each state.
The ME configuration file is a hierarchy of objects and properties; objects and properties describe the configuration. You use actions and commands to manipulate the data. Specifically, you open objects with the config command; you configure properties with the set command. Use the delete command to remove object configured settings from the configuration. The following table describes each of these elements.
| Element | Description |
|---|---|
|
Object |
An object is a configuration container that contains properties of a specific configuration class. Objects are available at all configuration levels of the CLI; use the config command to open an object. Some examples of objects are: vsp dial-plan enterprise |
|
Property |
A property is a value for a characteristic of an object. Properties are available at all configuration levels of the CLI; use the set command within an object to change properties. Some examples of properties are: admin apply-to-methods domain-name |
|
Command |
A command is a tool used to change the configuration file. The changes do not affect ME until you save or update the configuration. Commands are available throughout all levels of the CLI. Some examples of commands are: config set reset move |
|
Action |
An action immediately acts on ME and effects one of the components. Actions are only available at the top-level prompt of the CLI. Some examples of actions are: config save dns-lookup |
The following table describes the commands used to edit the configuration. To enter configuration mode, enter config at the top-level command prompt Once in configuration mode, there are some commands (and all actions) that are no longer available to you.
Table 1-2 Configuration-Editing Commands
| Command | Function |
|---|---|
|
config> config object |
Opens the specified object. config> config box config box> config cli config cli> |
|
config object> set property |
Sets the specified property, either setting the value, overwriting a previous or default value, or adding an additional value. config cli> set display paged 24 |
|
config object> delete object |
Deletes your settings for the specified object from the current configuration as well as all objects (and their properties) contained within the deleted object. Anything that you can config, you can delete. For some services (e.g., NTP, SSH, web, etc.), delete kills the service. For some, delete returns the object to its default settings. The following example not only deletes the setting of the default-server (a property of the servers object), but also deletes all configured servers. config servers> delete sip-gateway NNOS-E-1 |
|
config object> remove property |
Removes the specified property from the configuration. You can remove properties that are references to other properties (see Referencing Previously Configured Objects) and properties in a vector. (For properties that fit neither of these descriptions, you simply reset the value.) config lcs test1> remove domain-alias[2] |
|
config object> reset object |
From the specified object, resets all of the properties to their default values. Note that an objects properties also include the properties of all subobjects. For example, resetting the VSP object resets the defaults of the enterprise, servers, and directories properties, as well as the accounting and location service properties and many more. config vsp> reset |
The method you use to save a configuration file effects which configuration file is modified. Saving also may move your position in the hierarchy. The following table describes each method of saving.
Table 1-3 Methods to Save Configuration File
| Command | Description |
|---|---|
|
config save |
Executed at the top-level prompt (NNOS-E>), saves the running config to either the saved config, or if a pathname is supplied, to that file name. You can choose standard, verbose, or XML formats. Standard format only outputs properties with a value different from the default; verbose outputs every property. The files are functionally equivalent. |
|
save |
Executed at the config-level prompt (config>), works the same as config save, above. |
|
|
Executed from within an object (e.g., from config vsp> but not config>), saves changes from the working config to the running config and moves you to the top-level config prompt. You must still save changes to the saved config for them to be available at the next boot. |
|
return |
Executed from within an object, saves changes made in the current object to the working config and moves you up one level in the hierarchy. Changes do not get committed to the running config until you move to the top of the hierarchy. |
|
update |
Not directly accessible, writes changes from the running config to the saved config. The command appears when you try to exit config mode, and is executed by ME when you answer yes to the question: Do you want to update the startup configuration (y or n)? This prompt only appears if you have changed the running config. |
To save the configuration to XML, select the XML format option when using the save or config save commands. You can then import this XML file to other ME devices to create a saved configuration. This will save you time if you have identical configuration settings across ME systems in the cluster. With XML, you can also work on the configuration file offline. In the CLI, XML and ”standard CLI” config files are interchangeable, and the default save location, cxc.cfg (i.e. the startup config), is the same.
The following example saves config file cxc.cfg as XML:
config> save xml
Optionally, you can supply a file name after the format to save the configuration to a named file elsewhere.
The CLI prompt always indicates where you are located in the CLI hierarchy. It does not show a complete object path hierarchy; instead it shows the object (and instance, if applicable) in which you are located. The following table describes the prompts that you can see.
| Description | Prompt | Examples |
|---|---|---|
|
Top-level prompt (default) |
NNOS-E> |
NNOS-E> show sessions |
|
Config-level prompt: object |
config> |
config> config vsp config enterprise> config servers |
|
Config-level prompt: object and instance |
config> |
config servers> config lcs 1 config lcs 1> |
To see a complete object path hierarchy (with property settings) from your current location, use the show command:
config enterprise> show vsp enterprise directories servers federations user-group-policy[1] grpEast "vsp\policies\session-policies\policy default" 3pcc-servers config directories> show vsp enterprise directories admin enabled notes-directory abc phantom abc1 on-failure ignore resolve-on-update false config ldap XYZinc> show vsp enterprise directories ldap XYZinc admin enabled tag test group East domain xyz.com host 0.0.0.0 port 389 transport TCP timeout 15000 ms username password-tag user-settings group-settings ignore-unresolved true ignore-domain true
You can move through the object path hierarchy in a variety of ways. In addition, the CLI returns error messages to indicate the type of ”transgression” it encountered at the command line.
You can move down through the CLI in two ways:
By entering config commands individually, each on a new command line
By entering the object path hierarchy on a single command line.
For example:
NNOS-E> config config> vsp config vsp> config enterprise config enterprise> config servers config servers> config sametime company1 config sametime company1>
Results in the same position as:
NNOS-E> config vsp enterprise servers sametime company1
config sametime company1>
Note that if you make a mistake in your object path entry, the system moves you to the last correctly completed object. For example:
config> config vsp enterprise goof
Invalid class
config enterprise>
There are several commands that move closer to the top-level prompt. The following table describes the commands that allow you to navigate up though the CLI.
Table 1-5 CLI Navigation Commands
| Command | Function |
|---|---|
|
return |
Moves to the previous level in the object hierarchy. If you are at the config> prompt, return is not available. You must use exit to back out to the NNOS-E> prompt. |
|
commit or top |
Moves to the top level configuration prompt (config>). |
|
exit |
Leaves configuration mode and returns to the NNOS-E> prompt. If you have made any changes to the configuration, you are prompted to commit changes before you exit. |
The following table explains the some of the more common messages that the CLI returns in response to navigation problems:
Table 1-6 Common CLI Error Messages
| Message | Meaning |
|---|---|
|
Invalid class |
The object name you supplied either does not exist or is not available at this place in the CLI hierarchy. |
|
Invalid command |
You have entered a command name that does not exist at that point in the hierarchy. This could mean that you have attempted to issue: A set when there are no properties to set A config when there are no objects beneath the current container A command that does not exist. |
|
Invalid object |
The instance of the object you tried to delete or display does not exist. |
|
Invalid property |
The property name you supplied either does not exist or is not available at this place in the CLI hierarchy. |
|
Illegal value |
The value you supplied for a property is not correct. This could occur if you entered the wrong type of value (e.g., entered ”15” instead of ”enabled”). |
|
Required Property is Missing |
You did not supply any value for an object or property that required one. |
|
Too many arguments |
You have tried to enter more values than the current property accepts. |
|
Value is out of range |
The value you supplied for a property is not within the allowable range. |
The following sections describe usage techniques for working with configurations at the command line.
The CLI properties, both required and optional, can be either a variable or one of multiple predefined values. The following example takes a variable, a value that you supply, such as 192.168.100.10:
set ip-address ipAddress
The following example takes a predefined value. Enter one:
set admin {enabled | disabled}
The following example takes both. If you select TLS for your transport protocol, you must enter the path to a certificate on the system:
set transport {TCP | TLS certificateReference}
Some objects have multiple, or compound, properties. For these, you can set more than one property for the object from the same command line configuration. In the following example, you must supply an IP address for the server, but you need not supply a transport protocol or a port, as these have default values:
set server ipAddress [UDP | TCP | TLS] [port]
It is important to note that properties are positional. If you want to set or change a property, you must supply any previous properties, even if they have default values. In the example above, if you wanted to change the port, you must first enter an IP address and transport protocol, even if you are not changing those values.
There are several mechanisms for displaying help in the CLI. You can display a brief summary of the object or property you are setting. You can also display the list of available options from your current position.
Use the question mark character (?) to display a brief summary of the objects or properties available to you. For example, to determine the type of servers you can configure, with a brief description of each, enter the following:
config servers> config ?
configure an object
sametime IBM Lotus Sametime Server
lcs Microsoft Live Communications Server 2005
mcs Nortel MCS
avaya Avaya PBX configuration
sip-gateway SIP Application Server or PSTN Gateway
h323-gateway SIP Application Server or PSTN Gateway
sip-host generic SIP source/destination
dns-group DNS resolved server group
sip-connection SIP connection
Note that you receive the same result by simply typing config [Enter] at the prompt.
When you use the question mark with the set command alone, you display abbreviated help text associated with each property within the current configuration object:
config transport-policy 1> set ?
Configures a transport layer DOS policy
description
admin Sets whether resource is enabled or disabled
select Sets the properties in addition to remoteIP to observe
condition-list Specifies conditional criteria on the database search
threshold Sets the number of unique instances to be a DOS attack
period Specifies how many seconds between database scans,and how many seconds of data to analyze
If there are no properties to set, you receive an error:
config tls> set ?
Invalid command
Note that you receive the same result by simply typing set [Enter] at the prompt.
When you use the question mark with a specific property name, and there are predefined values for the property (an enumeration), you display the values allowed for that property:
config transport-policy 1> set admin ?
Sets whether resource is enabled or disabled
enabled Resource is active
disabled Resource is inactive
If it is not an enumeration, you receive the simple help summary:
config transport-policy 1> set remote-ip-netmask ?
Sets the mask of the remote-ip
config transport-policy 1>
At any point in the CLI you can enter the question mark character to display available commands or options. Note that you can also type just the command and [return] in some cases (as noted) to achieve the same result. When you use the verbose option (-v), the system displays the properties related to the objects being shown.
Note that when you display a list of actions, and in some cases show commands, the output is limited to the services registered with ME. Actions and status providers are only available to you if the service is registered (running). For example, if you do not have the authentication master service enabled, the RADIUS actions do not display. Therefore, an action that would have no effect does not appear as available.
The following table lists the commands available from each.
Table 1-7 Displaying Available Options
| Command | Function |
|---|---|
|
NNOS-E> ? |
Displays the list of actions and global commands available. |
|
NNOS-E> show NNOS-E> show ? |
Displays the set of valid show commands. |
|
config> ? |
Displays the list of CLI commands available at the top level of configuration mode. |
|
config> config config> config ? |
Displays the objects available for configuration from the config> prompt. |
|
config object> ? |
Displays the list of CLI commands available for the specific configuration object. |
|
config object> config config object> config ? |
Displays the objects available for configuration from the specific configuration object. |
|
config object> set config object> set |
Displays the list of properties available for configuration within the specific configuration object. |
The CLI uses the concept of secondary objects and properties to filter out those items that are rarely used. These would be properties for fine-tuning a configuration, and would never be necessary for normal operations.
You cannot view secondary properties through the channels described in Displaying Available Commands and Properties. When you list the available objects or properties, those that are secondary do not display, nor do their settings display in the standard help output. Instead, you must use the help or verbose show command to see the availability. You enter these properties as you would any other. However, command completion is not implemented for them.
The following example displays the standard properties of the DOS transport policy object (help descriptions removed for clarity):
config transport-policy test> set ?
Configures a transport layer DOS policy
description
admin
select
condition-list
threshold
period
Compare the standard list to list available with the help command:
config transport-policy test> help
transport-policy
description
admin
select
remote-ip-netmask
condition-list
threshold
period
inactivity-timeout
The additional properties of remote-ip-netmask and inactivity-timeout are now viewable. To set these, use the standard procedure:
config transport-policy test> set inactivity-timeout 600
The secondary property that was manually set now appears in the regular show output:
config transport-policy test> show
vsp
policies
dos-policies
transport-policy test
description
admin enabled
select
threshold 1000 instances
period 30 seconds
inactivity-timeout 0 days 00:10:00
When you use the show command from the config prompt, the system displays a list of configured objects in the running configuration If you specify the verbose option (-v), the system displays the properties related to the objects being shown. Note that this does not apply to show commands available from the top-level prompt.
At the top-level prompt or the config-level prompt, the show output includes all configured objects. The following example displays all configured objects in the running configuration:
NNOS-E> config show
cluster
box
services
master-services
vsp
external-services
preferences
access
features
NNOS-E>
The following example displays all configured objects and their associated properties:
NNOS-E> config show -v
cluster
name NNOS-E-1
box 1
admin enabled
hostname master
timezone eastern
name
description Acme Packet Net-Net OS-E
contact Jane Doe
location Boston, MA
identifier 00:55:66:00:11:22
interface eth0
admin enabled
mtu 1500
arp enabled
speed 1Gb
duplex half
autoneg enabled
ip a
admin enabled
ip-address static 192.168.100.100/24
---More---
You can also display just a portion of the running config, relevant to the object in which you are currently located. (This also shows you the path to your location.) For example:
config active-directory company1> show
vsp
enterprise
directories
active-directory company1
admin enabled
tag east
domain abcCo.com
.
.
.
The following table summarizes the configuration display commands.
Table 1-8 Displaying the Configuration
| Command | Function |
|---|---|
|
NNOS-E> show NNOS-E> show ? |
Displays the set of valid status (show) commands. |
|
NNOS-E> config show config> show |
Displays a list of all configured objects in the running configuration. |
|
NNOS-E> config show -v config> show -v |
Displays, from the running configuration, a list of all configured objects as well as their associated properties. |
|
config> show object config object> show |
Displays, from the running configuration, the settings of the specified object, which includes immediate subobjects, and parentage, if applicable. |
|
config> show object -v config object> show -v |
Displays, from the running configuration, the contents of the specified object, all its properties (including the properties of subobjects), and parentage, if applicable. |
The CLI uses a command completion feature that automatically finishes typing an object or property name for you. Pressing the keyboard [Tab] or [Spacebar] executes the completion.
Note the following requirements for using command completion:
You must type an entry until it is minimally unique on the command line before pressing [Tab] or [Spacebar]. If there are two commands that begin with the same spelling, the CLI cannot differentiate between the two until you type enough letters to distinguish one from the other.
Note:
You must press [Tab] or [Spacebar] to complete the object or property name. It is not sufficient for the name to be minimally unique for execution.The entry must be a valid object or property in the hierarchy.
The CLI does not auto-complete on user-configured instances or values.
The following example shows use of the auto-completion feature:
config box> con[Spacebar]nfig c[Spacebar] possible completions: cli CLI settings console Console settings config box> config co[Spacebar]nsole [Enter] config console>
In this example, pressing the [Spacebar] after typing con completes the config command line. However, pressing [Spacebar] after typing just c, which was not minimally unique, resulted in prompting for further characters. Entering the minimum unique characters, and then pressing [Spacebar] to complete the string, allows you to press [Enter] to move to into console configuration mode.
If you are entering an object path, you can use the auto-complete feature for each component:
config> con[Spacebar]nfig v[Spacebar]sp en[Spacebar] possible completions: enterprise Enterprise services enum ENUM settings for phone number to URL conversion config> config vsp en_ config> config vsp ent[Spacebar]erprise se[Spacebar]rvers config servers>
References allow you to re-use objects in the system. Therefore, you can define an object once, and then reference it later for other uses. For example, when configuring a DOS transport policy object, you need to include a reference to a condition list. Assuming you had configured a list named ”remoteIP,” you would include it as follows:
config transport-policy> set condition-list vsp policies dos-policies transport-condition-list remoteIP
When you reference an object, you must use the full path name to the object. You can separate objects with backslashes or spaces. For example, either of the following is acceptable:
config transport-policy test> set condition-list vsp\policies\dos-policies\transport-condition-list 2 config transport-policy test> set condition-list vsp policies dos-policies transport-condition-list 1
However, in some cases, quotation marks are required if you are using spaces. This would be true when the configuration is a compound: it includes a reference and other values in a single property. In the example below, you must first specify the peer type (server) and then a reference to that server:
config source-route 192.168.100.100> set peer server ”vsp enterprise servers sip-gateway pstn”
Note the following:
When you are entering a reference, tab completion is available (unless the reference is within quotation marks).
If you enter a path name to a reference that does not exist, the system creates an object of that name and supplies it with default values.
When a property or object requires a string (e.g., user name, directory service instance, etc.) the following rules apply:
Any printable character is acceptable.
If the string contains delimiters (white space or \ character), it must be enclosed in double quotes ””).
If the string contains backslash character ( \ ) and is therefore in quotes, you must use double backslash ( \\ ) to get a single backslash in the result.
Strings are case sensitive (i.e., admin is not the same as Admin).
The following string length limits are advised:
Object names up to 16 characters
Descriptions, usually in quotes, up to 32 characters
Regular expressions up to 128 characters.
A regular expression is a formula for matching strings that follow some pattern. Many of the conditions and predicates require a regular expression entry. ME uses PERL-compliant regular expressions.
You can configure replacement strings in several places throughout the ME configuration. The replacement string can include references to substrings from the source string. A substring in the source string is specified by enclosing it in parenthesis ( ). It is referenced in the destination string via \1 for the first substring, \2 for the second substring, and so on.
For example, if the source string is ”The Quick Brown Fox and your expression is (.*)Quick(.*), and your replacement string is \Fuzzy\2, the result is ”The Fuzzy Brown Fox”.
The following is a list of replacement string tokens along with examples. For each example, assume the input string is ”The Quick Brown Fox”.
Table 1-9 Replacement Strings and Examples
| Replacement string token | Expression | Replacement | Output |
|---|---|---|---|
|
\n The nth substring in the match. |
”(.*)Quick(.*)” |
”\1Fuzzy\2” |
”The Fuzzy Brown Fox” |
|
\n\d The nth substring in the match followed by the digit d. |
”(.*)Quick(.*)” |
”\Fuzzy\2\\7” |
”The Fuzzy Brown Fox7” |
|
\n\\d The nth substring in the match followed by the dth substring in the match. |
”(.*)Quick(.*)” |
”\Fuzzy\2\\1” |
”The Fuzzy Brown FoxThe” |
|
\n\\\ The nth substring in the match followed by a single backslash character. |
”(.*)Quick(.*)” |
”\1Fuzzy\2\\\” |
”The Fuzzy Brown Fox\” |
|
\c An incrementing counter. |
”(.*)Quick(.*)” |
”\c\1\Fuzzy\2\c” |
”1The 2Fuzzy Brown Fox3” |
|
\\ A single backslash character. |
”(.*)Quick(.*)” |
”\\” |
”\” |
Use the expression action to develop and test regular expression match and replacement strings. For more information on this action see the expression description in the Actions chapter.
Refer to one of the following sites for more complete instructions on writing regular expressions:
In policy building, ME uses some predefined relational operators for building conditions lists and predicate statements with elements of the same type. For example, use these operators to define ranges or compare values for equality or inequality. With them, your statements form logical expressions to determine choice, such as inclusion or exclusion, and sometimes action. (For enumerated lists, IP addresses, ports, and regular expressions, you use match and exclude statements.) The operators are as follows:
eq=equal to
ne=not equal to
gt=greater than
lt=less than
ge=greater than or equal to
le=less than or equal to
In addition, you can use match and exclude statements to define the use of the string. A match statement includes values that match the specified string; an exclude statement ignores them.
The ME supports a generic database used to hold named variables. A named variable is a variable paired with a value through the reg-exp header code. This allows you to modify SIP message fields and CDR fields more generically.
When a session is created, a named variable list is automatically created. If any named variables are configured in the default-session-config, they populate this list. All variable names in the named variable list must be unique.
The ME updates the named variable list when any of the following happens.
When the session configuration merge-object is set to merge, the named variables configured in the new session config are appended to the existing named variable list.
When the session configuration merge-named-variables is set to replace, the existing session configuration named variables are replaced by the newly configured named variables.
When the header-settings > named-variable-collector collects new named variables via the reg-exp code.
When you specify or create a named variable list and a named variable of the same name already exists, the ME overwrites the value of the existing variable name.
Note:
Variable names cannot start with a ”$” and you should not use special characters such as ”\”, ”%”, ”#”, ”!”, ”?”, ”[”, ”]”, :&”, ”{”, ”}”, ”@” when naming variables.Available accounting variables are:
$acct.box-id: The box ID.
$acct.digest-realm: The digest realm.
$acct.source-lnp: The source LNP.
$acct.destination-lnp: The destination LNP.
$acct.diversion-header: The diversion header.
$acct.cluster-name: The cluster name.
$acct.radius-caller-id: The radius caller ID.
$acct.request-id: The request ID.
$acct.connected: The connected boolean.
$acct.scan-time: The file scan time.
$acct.file-time: The file time.
$acct.play-time: The file play time.
$acct.disconnect-reason: The disconnect reason.
$acct.final-reason-code: The last response code.
$acct.post-dial-digits: The post-dial digits.
$acct.source-leg-current-jitter: The source leg's current jitter.
$acct.source-leg-max-jitter: The source leg's maximum jitter.
$acct.destination-leg-current-jitter: The destination leg's current jitter.
$acct.destination-leg-max-jitter: The destination leg's maximum jitter.
$acct.source-leg-rtcp-max-jitter: The source leg's RTCP maximum jitter.
$acct.destination-leg-rtcp-max-jitter: The destination leg's RTCP maximum jitter.
$acct.source-leg-avg-jitter: The source leg's RTCP average jitter.
$acct.destination-leg-rtcp-avg-jitter: The destination leg's RTCP average jitter.
$acct.source-leg-rtcp-packets-lost: The source leg's RTCP packets lost.
$acct.desination-leg-rtcp-packets-lost: The destination leg's RTCP packets lost.
$acct.source-leg-rfactor: The source leg's RFactor based on RTCP statistics.
$acct.destination-leg-rfactor: The destination leg's RFactor based on RTCP statistics.
$acct.source-leg-mos: The source MOS based on RTCP statistics.
$acct.dest-leg-mos: The destination MOS based on RTCP statistics.
Available CDR variables are:
$cdr.session-id: The unique internal session-ID.
$cdr.recorded: An indicator as to whether the call was recorded or not.
$cdr.call-id: The unique call ID from the user agent.
$cdr.to: The To: URI.
$cdr.from: The From: URI.
$cdr.method: The SIP method that initiated the session.
$cdr.incoming-request-uri: The request URI for the incoming leg.
$cdr.previous-hop-ip: The IP address of the previous hop.
$cdr.previous-hop-via: The Via: header for the previous hop.
$cdr.outgoing-request-uri: The request URI for the outgoing leg.
$cdr.next-hop-ip: The IP address of the next hop.
$cdr.next-hop-dn: The domain name of the next hop.
$cdr.header: An arbitrary header from the call.
$cdr.origin: The origin header from the call.
$cdr.setup-time: The time at which the call was set up.
$cdr.connect-time: The time at which the call was connected.
$cdr.disconnect-time: The time at which the call was disconnected.
$cdr.disconnect-cause: The reason for the disconnection.
$cdr.duration: Duration of the call in seconds.
$cdr.scp-name: The VSP that handled the call.
$cdr.call-id-2: The secondary call ID for the outgoing call.
$cdr.originating-gateway: The origin Gateway.
$cdr.terminating-gateway: The terminating Gateway.
$cdr.packets-received-on-src-leg: The number of packets received on the source leg.
$cdr.packets-lost-on-src-leg: The number of packets lost on the source leg.
$cdr.packets-discarded-on-src-leg: The number of packets discarded on the source leg.
$cdr.pdv-on-src-leg: The average jitter on the source leg.
$cdr.max-jitter-on-src-leg: The maximum jitter on the source leg.
$cdr.codec-on-src-leg: The codec on the source leg.
$cdr.mimetype-on-src-leg: The mimetype on the source leg.
$cdr.latency-on-src-leg: Average latency on the source leg.
$cdr.max-latency-on-src-leg: Maximum latency on the source leg.
$cdr.packets-received-on-dest-leg: The number of packets received on the destination leg.
$cdr.packets-lost-on-dest-leg: The number of packets lost on the destination leg.
$cdr.packets-discarded-on-dest-leg: The number of packets discarded on the destination leg.
$cdr.pdv-on-dest-leg: The average jitter on the destination leg.
$cdr.max-jitter-on-dest-leg: The maximum jitter on the destination leg.
$cdr.codec-on-dest-leg: The codec on the destination leg.
$cdr.mimetype-on-dest-leg: The mimetype on the destination leg.
$cdr.latency-on-dest-leg: Average latency on the destination leg.
$cdr.max-latency-on-dest-leg: Maximum latency on the destination leg.
$cdr.rfactor-on-dest-leg-times-1000: The Rfactor on the destination leg.
$cdr.rfactor-on-src-leg-times-1000: The Rfactor on the source leg.
$cdr.mos-fmt-on-dest-leg: The MOS formatted on the destination leg.
$cdr.mos-fmt-on-src-leg: The MOS formatted on the source leg.
$cdr.mos-on-dest-leg: The MOS on the destination leg.
$cdr.mos-on-src-leg: The MOS on the source leg.
$cdr.call-type: The call type.
$cdr.disconnect-error-type: The disconnect error type.
$cdr.ani: The ANI.
$cdr.call-source-regid: The source registration ID.
$cdr.call-dest-regid: The destination registration ID.
$cdr.new-ani: The new ANI.
$cdr.cdr-type: The CDR type.
$cdr.hunting-attempts: The number of hunting attempts.
$cdr.call-pdd: The call PDD.
$cdr.call-source-realm-name: The source realm name.
$cdr.call-dest-realm-name: The destination realm name.
$cdr.call-dest-cr-name: The destination CR name.
$cdr.inleg-peer-dest: The in-leg peer destination.
$cdr.inleg-anchor-source: The in-leg anchor source.
$cdr.inleg-anchor-dest: The in-leg anchor destination.
$cdr.inleg-peer-sourcet: The in-leg peer source.
$cdr.outleg-peer-dest: The out-leg peer destination.
$cdr.outleg-anchor-source: The out-leg anchor source.
$cdr.outleg-anchor-dest: The out-leg anchor destination.
$cdr.outleg-peer-source: The out-leg peer source.
$cdr.called-party-after-src-calling-plan: The called party after source calling plan.
$cdr.last-status-message: The last status message.
$cdr.last-pkt-timestamp-on-dest-leg: The time of the last media packet on the destination leg.
$cdr.last-pkt-timestamp-on-src-leg: The time of the last media packet on the source leg.
$cdr.setup-time-integer: The setup-time as an integer.
$cdr.incoming-uri-stripped: The stripped down version of the incoming request URI.
$cdr.dnis: The DNIS.
$cdr.new-dnis: The new DNIS.
$cdr.custom-data: The custom data.
$cdr.creation-timestamp: The time the accounting record was written to the target.
Available session variables are:
$session.session-id: The session-ID for this session.
$session.request-id: The request ID for this session.
$session.caller-id: The caller ID for this session.
$session.diversion-header: The diversion-header for this session.
$session.pcharging-vector: The p-charging-vector for this session.
$session.digest-realm: The digest realm for this session.
$session.source-lnp: The source LNP for this session.
$session.destination-lnp: The destination LNP for this session.
Available media steering variables are:
$inleg.source.ip: The IP address to use for allocating media resources on the in-leg.
$inleg.source.port: The port to use for allocating media resources on the in-leg.
$outleg.source.ip: The IP address to use for allocating media resources on the out-leg.
$outleg.source.port: The port to use for allocating media resources on the out-leg.
For more information on configuring named variables, see Configuring Session Configuration Objects.
Using the named variable table, the ME is able to write out any information in the customData field of CDRs.
Leverage the accounting-data configuration object to write out any information you want in the CDR customData field. Use the entry > value property to reference the named variables table collected earlier via the session-config or reg-exp code. Or use it to reference a reserved keyword (reserved keywords are described later in this section).
Via the Radius Access message, VSA can also be stored and referenced in the named variable table. In the accounting-data > entry property, reference this information in the CDR customData field.
The ME has a list of reserved keywords you can use in CDRs or reg-exp code to access information you want. This avoids any confusion with named variables.
Reserved keywords must be referenced using the \!<reserved-keyword>! syntax.
The following table shows a list of keywords that extract information from either a SIP message or a session.
Table 1-10 Keywords to Extract SIP Message or Session Information
| Current Abbreviation | New Custom Keyword | Information Source |
|---|---|---|
|
\r |
$MSG_REMOTE_IP |
SIP Message - Remote IP |
|
\R |
$MSG_REMOTE_PORT |
SIP Message - Remote Port |
|
\p |
$MSG_PRIVATE_REMOTE_IP |
SIP Message - Private Remote IP |
|
\P |
$MSG_PRIVATE_REMOTE_PORT |
SIP Message - Private Remote Port |
|
\l |
$MSG_LOCAL_IP |
SIP Message - Local IP |
|
\L |
$MSG_LOCAL_PORT |
SIP Message - Local Port |
|
\n |
$SESS_LOCAL_IN_IP |
SIP Session - IP Address of the Interface For the In-Leg |
|
\N |
$SESS_LOCAL_IN_PORT |
SIP Session - IP Port of the Interface For the In-Leg |
|
\a |
$SESS_LOCAL_OUT_IP |
SIP Session - IP Address of the Interface for the Out-Leg |
|
\A |
$SESS_LOCAL_OUT_PORT |
SIP Session - IP Port of the Interface For the Out-Leg |
|
\g |
$SESS_REMOTE_IN_IP |
SIP Session - IP Address of the Remote End of the In-Leg |
|
\G |
$SESS_REMOTE_IN_PORT |
SIP Session - IP Port of the Remote End of the In-Leg |
|
\d |
$SESS_DEST_OUT_IP |
SIP Session - Out-Leg Destination IP Address |
|
\D |
$SESS_DEST_OUT_PORT |
SIP Session - Out-Leg Destination Port |
|
\e |
$SESS_PEER_IP |
SIP Session - ME Peer IP Address |
|
\E |
$SESS_PEER_PORT |
SIP Session - ME Peer Port |
|
\z |
$SESS_LOCAL_PEER_IP |
SIP Session - ME Local Peer IP Address |
|
\Z |
$SESS_LOCAL_PEER_PORT |
SIP Session - ME Local Peer Port |
|
\t |
$SESS_IN_CONTACT_HDR |
SIP Session - ME's In-Leg Contact HDR |
|
\o |
$SESS_OUT_CONTACT_HDR |
SIP Session - ME's Out-Leg Contact HDR |
|
\h |
$SESS_ORIG_IN_REQUEST_URI |
SIP Session - Origin In Request URI |
|
\i |
$SESS_ORIG_IN_TO_URI |
SIP Session - Origin In To URI |
|
\j |
$SESS_ORIG_IN_FROM_URI |
SIP Session - Origin In From URI |
The following table shows a list of keywords used in CDRs.
Table 1-11 Keywords Used In CDRs
| Current Abbreviation | New Custom Keyword | Information Source |
|---|---|---|
|
\b |
$BOX_ID |
Box Identifier |
|
\d |
$CDR_DIGEST_REALM |
SIP Session - Digest Realm |
|
\s |
$CDR_SRC_LNP |
SIP Session - Source LNP |
|
\e |
$CDR_DEST_LNP |
SIP Session - Destination LNP |
|
\v |
$CDR_DIV_HDR |
SIP Session - Diversion Header |
|
\c |
$CLUSTER_NAME |
SIP Meta - Cluster Name |
|
\r |
$CDR_RADIUS_CALLER_ID |
SIP Session - RADIUS Caller ID |
|
\o |
$CDR_REQUEST_ID |
SIP Session - Request ID |
|
\z |
$CDR_CONNECTED |
Call Data - Connected Bool |
|
\y |
$CDR_SCAN_TIME |
Call Data - Scan Time |
|
\x |
$CDR_FILE_TIME |
Call Data - File Time |
|
\w |
$CDR_PLAY_TIME |
Call Data - Play Time |
|
\u |
$CDR_DISCONNECT_REASON |
Call Data - Disconnect Reason |
|
\t |
$CDR_FINAL_REASON_CODE |
SIP Session - Last Response Code |
|
\q |
$CDR_POST_DIAL_DIGITS |
Call Data - Post Dial Digits |
|
\j |
$CDR_SRCLEG_CURR_JITTER |
Normalized Source Leg Current Jitter |
|
\m |
$CDR_SRCLEG_MAX_JITTER |
Normalized Source Leg Max Jitter |
|
\i |
$CDR_DESTLEG_CURR_JITTER |
Normalized Destination Leg Current Jitter |
|
\k |
$CDR_DESTLEG_MAX_JITTER |
Normalize Destination Leg Max Jitter |
You can add custom fields into ME-generated events. By using the named variables table, you can extract information from any SIP message header and reference it in the events to add the custom information. There are three events which allow you to include this information: callCreatedEventCustom, callConnectedEventCustom, and callTerminatedEventCustom.
Add a custom data field to the callCreated, callConnected, and callTerminated events via the third-party-call-control > custom-event-fields object.. Within this object, define the content of that field via the named-variable-entry object.
There are two advanced properties under the custom-event-fields object, custom-events-grouping-string and custom-event-delimiterwhich change the characters used to associate an event's variable with its value (default is =) as well as the character used to separate a group's custom event entries (default is ;). For more information on configuring custom event fields, see Configuring Session Configuration Objects.
Several configuration objects and actions require that you set a time or time interval. The time specifies a date and time, for example, a start date. The interval reflects a number of days, hours, minutes, and seconds, for example, a refresh timer. The CLI accepts multiple entry formats for setting these intervals and displays them in the following formats:
master-services
file-mirror
external-backup
admin enabled
url
refresh 0 days 00:30:00
You can enter a number of seconds; anything greater than 60 will be converted to hh:mm:ss. For example:
config external-backup> set refresh 120 config external-backup> show master-services file-mirror external-backup admin enabled url refresh 0 days 00:02:00
You can enter minutes or hours explicitly. For example:
config external-backup> set refresh 10:30:00 config external-backup> show master-services file-mirror external-backup admin enabled url refresh 0 days 10:30:00
To enter a number of days, enclose the string in quotation marks. You must enter the complete string for valid entry. For example:
config external-backup> set refresh ”2 days” Illegal value config external-backup> set refresh ”2 days 00:00:00” config external-backup> show master-services file-mirror external-backup admin enabled url refresh 2 days 00:00:00
In addition, the CLI accepts lexical representation for duration from the ISO 8601 extended format.
Several properties within this object can be configured to allow ME to determine the appropriate value (a setting of automatic). The default value for these properties is automatically determined by ME-based on the system hardware (processor, platform, memory, etc.). Although you can do so manually, do not change the value of these properties unless instructed to do so by Technical Support. Use the show automatic-values command to see the actual setting on your system.
For increased security, ME uses a two-part password mechanism for passwords shared with other devices (also known as shared secrets). You must configure both a password and a tag. An enterprise or RADIUS server, for example, probably has a configured password that ME must use to access the server. This shared secret is the password. The tag is not the password itself, but rather a user-configurable name used to access the real password. By managing shared secrets, you can maintain the secrecy of the other passwords on other devices. An administrator can set up the tags and passwords; end users can work with the configuration files and use the password tag, without having access to the password itself.
For example, if the secret for your RADIUS server is RadPswd, you can create a secret-tag of myTag. When administrators configure ME to communicate with the RADIUS server, they supply the tag, myTag. The real password for server authentication, RadPswd, remains hidden to the user. The tag can be reused when creating other configurations that use the same real password. Or, if the password is compromised, it can be changed without changing the configuration on ME.
ME uses a password store to maintain the actual password known to the other device. Using a password store allows the shared passwords to be stored outside of, and not displayed in, the configuration file. Password tags are stored in the ME configuration.
Note:
You can create a blank password by creating a tag without a corresponding password. This may cause problems when the external system, however, when it tries to authenticate the ME.This password mechanism applies only to cases of ME using a shared secret. It does not apply to passwords created for users under the access object. (These are stored as hashed data, never as plaintext.)
There are several tag properties throughout the ME configuration. These include the various external databases, enterprise servers and directories, and phone configurations, among others. The minimum password length for users is set within the password-policy object. When setting the Linux root password, with the secret action, the default minimum-length of four characters is applied. No password length minimum is enforced for other secrets that live on other machines (RADIUS servers, etc.).
There are two ways to set up a password and tag correspondence: from within the object configuration and by executing an action.
In the example below, ME creates a password tag, blue, for an LCS server:
NNOS-E> config vsp accounting database group Boston server 1 config server 1> set password-tag blue password: *********** confirm: *********** config server 1>
Because the tag did not already exist, the system prompted for the real password. If the tag had previously been created, the system would have simply accepted the password tag as part of the configuration.
config server 1> set password-tag blue
config server 1>
You can also create a password and tag correspondence outside of the object configuration, using the secret action.
NNOS-E> secret set red password: ***** confirm: ***** Success!
If you re-execute the secret set action, and supply a different password, ME overwrites the password that was associated with the tag with the new password.
Use the show secrets command to display configured password tags:
NNOS-E> show secrets
tag
---
blue
red
Note:
Passwords are maintained in a separate store; simply copying the configuration file between devices does not copy the password store. You can manually enter your passwords on each ME device. Or, you can use the secret synchronize action on the master device to copy your passwords on to other devices in the cluster.To support two or more users editing the same copy of the configuration, ME implements a configuration conflict feature. This applies to all changes to the configuration, regardless of the tool used to make the changes (ME Management System, CLI, etc.). ME warns any user who attempts to update and save a configuration if the configuration has been saved elsewhere since it was loaded or last saved (indicating that the user does not have the most current version).
Note:
When using web services to update the configuration, the ME does not check for revision numbers, and therefore does not implement configuration conflict detection. When the ME receives a SetConfig message, it overwrites the running configuration regardless of whether unsaved changes have been made by other users or tools.Revision management is the mechanism ME uses for avoiding these conflicts. Each top-level configuration object has an associated revision number. The top-level objects are: access, box, cluster, external-services, features, master-services, preferences, services, and vsp. ME increments the object revision number each time there is a saved change to that object (including one of its ”children”). You can use the show config-details command to display the current revision number for each top-level object. Each time the box is restarted, the revision numbers revert to 1.
The example below shows sample output for a box that was newly updated, with changes made to the access and source-route objects. Because the vsp object is the top-level parent of the source-route object, ME increments the vsp count. A change that increments the revision can be an addition, modification, or deletion: anything that is then saved.
NNOS-E> config access config access> delete permissions allowAll config access> return config> config vsp dial-plan config dial-plan> config source-route src1 config source-route src1> set priority 500 config source-route src1> exit Do you want to commit your changes before you exit (y or n)? y Do you want to update the startup configuration (y or n)? y NNOS-E> show config-details object revision size changed ------ -------- ---- ------- access 2 572 08:31:08 Mon 2008-08-28 box 1 6376 08:11:36 Mon 2008-08-28 cluster 1 9572 08:11:36 Mon 2008-08-28 external-services 1 151 08:11:36 Mon 2008-08-28 features 1 208 08:11:36 Mon 2008-08-28 master-services 1 558 08:11:36 Mon 2008-08-28 preferences 1 120 08:11:36 Mon 2008-08-28 services 1 925 08:11:36 Mon 2008-08-28 vsp 2 40906 08:17:49 Mon 2008-08-28
If another user had made changes to any part of the configuration before the sample user had saved changes, the CLI presents the following message:
Do you want to commit your changes before you exit (y or n)? y Your box changes will overwrite changes made by somebody else. Are you sure that you want to commit your changes (y or n)? n
All configuration changes are recorded in the event log. Use the show event-log command to display the contents:
08:16:16 Mon 2008-08-28[notice] 1:manager[system] 'vsp' configuration changed by userA via console
You can use CLI commands to control the display of output to your screen and set your prompt.
You can configure the CLI to either output text a page at a time or scroll text continuously. You do this from CLI config mode (see the cli command description for more information). To scroll text:
NNOS-E> config config> config box config> config cli config cli> set display scrolled
To pause the display with the --More-- prompt, enter the following command, specifying the number of lines in your display:
config cli> set display paged 24
To temporarily change the display output without changing your configuration, you can execute the following command from the top level, using the display action:
NNOS-E> display paged 24
When you specify paged output, the --More-- prompt accepts the following keystrokes:
By default, the system uses the prompt NNOS-E> as the top level prompt. If you'd like to change the prompt, use the following command:
NNOS-E> config box cli config cli> set prompt ”Think Big>” config cli> exit Do you want to commit your changes before you exit (y or n)? y Do you want to update the startup configuration (y or n)? y Think Big>
The prompt that you enter can be up to 64 alphanumeric characters. If you want the prompt to contain spaces, be certain to enclose it in quotation marks.
The CLI supports several mechanisms for exiting hierarchy levels and the CLI itself. As you exit certain situations, you are prompted by the system as to whether you wish to commit changes. The following table describes the prompts and their implications:
Table 1-13 CLI Prompts and Implications
| Prompt... | Occurs When... | Responses Result In.... |
|---|---|---|
|
Do you want to commit your changes before you exit (y or n)? |
You have made changes to the working config and you are leaving config mode. |
If you answer yes to the prompt, your changes are written to the running config (but not the saved config). They are used for your current session and until you next boot the system. If you answer no, your changes are discarded. |
|
Do you want to update the startup configuration (y or n)? |
You have committed changes from the working to running config, but have not yet saved them to the startup config for use when the system next boots. |
If you answer yes, the changes are written to the startup config. If you enter no, the changes are not written, but are still in the running config. If you later answer yes to this question, without having rebooted the system, ME writes those changes (if they still exist in the running config) to the startup config. |
The following table describes the commands used for exiting configuration mode levels and/or the CLI.
Table 1-14 Exit Configuration Commands
| Command | Function |
|---|---|
|
NNOS-E> exit |
From the top-level prompt, exit exits the CLI. |
|
NNOS-E> quit |
From the top-level prompt, quit exits the CLI. |
|
config> exit |
From the config prompt, exit exits configuration mode and returns to the top level CLI prompt. If you made changes to the configuration, the CLI issues a prompt asking you if you want to commit your changes. |
|
config object> cancel |
From within object configuration mode, cancel discards any changes to that object during the current running configuration session and moves you up one level in the configuration hierarchy. |
|
config object> exit |
From within object configuration mode, exit exits configuration mode and returns to the top level CLI prompt. If you made changes to the configuration, the CLI issues a prompt asking you if you want to commit your changes. |