Command-Line Utilities

Table Of Contents

Command-Line Utilities

Information About the Command-Line Utilities

Description of the CLU Commands

Command-Line Utilities

This module describes the Command-Line Utilities (CLU) that is distributed with the Subscriber Manager (SM) application.

Information About the Command-Line Utilities

The SM provides a set of Command-Line Utilities (CLU). The CLU is designed mainly for viewing SM operations and statistics, and subscriber management, therefore only subscriber-related CLU changes are persistent. The CLU is used for configuration only indirectly, in that it loads the edited configuration file to the SM.

This module describes in detail all the CLU commands, their operations and options. The shorter description of the CLU commands given in the "Configuration and Management" module is more oriented toward the performance of routine management and configuration tasks.

CLU commands are executable only when the user is logged in to the machine using the pcube account, which is always installed (see "Installation and Upgrading"). In general, the CLU runs as a separate process to the configured entity and communicates with it via a predefined communication port and interface. Therefore, the configured entity must keep a certain communication port open at all times, at least locally on the configured machine.

Description of the CLU Commands

This section describes in detail the Command-Line Utilities commands, their operations and options.

• Informative Output

• Parsing CLU Operations and Options

• Information About the p3batch Utility

• Information About the p3cable Utility

• Information About the p3clu Utility

• Information About the p3cluster Utility

• Information About the p3db Utility

• Information About the p3domains Utility

• Information About the p3ftp Utility

• Information About the p3http Utility

• Information About the p3inst Utility

• Information About the p3log Utility

• Information About the p3net Utility

• Information About the p3radius Utility

• Information About the p3rpc Utility

• Information About the p3sm Utility

• Information About the p3subs Utility

• Information About the p3subsdb Utility

Informative Output

All CLU commands support the following operations for informative output:

Operation

Description

--help

Prints the help for the specified CLU command, then exits.

--version

Prints the SM program version number, then exits.

Parsing CLU Operations and Options

Place in quotation marks a command operation or option containing any of the following characters:

•A space character

•A separation sign (comma ","; ampersand "&"; colon ":")

•An escape character (backslash "\")

•Parenthesis ("(" or ")")

•An exclamation mark ("!")

•The comparison operators ("<" or ">")

A command operation or option that contains any of the following characters must have that character preceded by an escape character:

•An equal sign (=)

•A quotation mark (" or ")

•An escape character (backslash "\")

•An exclamation mark ("!")

•The "$" character

The following table shows several examples of the above rules:

Operation/option contains the character

Example of how operation/option should be written

Space character

--property="file name"

Escape character (backslash "\")

--property="good\\bad"

Equal sign (=)

--property="x\=y"

Quotation marks (" or ")

--name="\"myQuotedName\""
(in the above example, inner quotation marks are escaped)

Separation characters

comma (,)

--names="x,y"

ampersand (&)

--names="x&y"

colon (:)

--names="myHost:myDomain"

One-letter abbreviations are available for some of the operations and options. For example, -d is an abbreviation for --domain. Note that only one hyphen (-), not two, precedes the letter for an abbreviation, and that if the operation or option takes a parameter, there is a space and not an equal sign before the parameter.

Example of using full name

--domain=subscribers

Example of using abbreviated name

-d subscribers

Information About the p3batch Utility

p3batch Utility

The p3batch utility enables you to run many operations on a single connection with the SM. You can use any text editor to create a batch file that contains a series of CLU commands, one command per line (terminated by a new-line sign). Use the p3batch utility to run this file and execute the commands, where empty lines are skipped.

All batch file command line operations use the same connection option. The p3batch utility ignores any connection options in the script file commands. While processing the operations in the batch file, a progress indicator is displayed. The command format is:

p3batch[FILE-OPTION] [ERROR-OPTION]
The following tables list the p3batch options.

Table B-1 p3batch File Option

File Operation

Abbreviation

Description

Notes

--file=FILE

-f

Runs a batch file, where FILE specifies the CLU script (batch) file to run.

A progress indicator is displayed.

Table B-2 p3batch Error Option

Error Option

Description

--skip-errors

Specifies that the batch operation should not halt if an error occurs.

If this flag is not used, the batch operation will halt if an error occurs.

Examples of using the p3batch Utility

•To run a batch file that will halt if an error occurs.

p3batch --file=mainBatchFile.txt
•To run a batch file that will not halt if an error occurs.

p3batch --file=mainBatchFile.txt --skip-errors
Information About the p3cable Utility

p3cable Utility

In a cable environment, the CPE is modeled as the subscriber, and inherits its policy and domain from the cable modem (CM) through which it connects to the network. Each cable modem is linked with one or more CPEs. For background information about special characteristics of the cable environment, see the "CPE as Subscriber in Cable Environment" section on page C-1.

You can use the p3cable utility commands to import cable modem information from a CSV file to the SM and to export the cable modem information from the SM to a CSV file. You can also use this utility to clear the repository of all cable modems, and to show whether to allow or deny the login of CPEs that belong to unfamiliar cable modems; i.e., cable modems that do not exist in the SM database. However, to specify whether to allow or deny such a login, use the "Configuration File Options" of the configuration file p3sm.cfg.

The command format is:

p3cable OPERATION[FILE-OPTIONS]
The following tables list the p3cable operations and options.

Table B-3 p3cable Operations

Operation

Description

--import-cm

Imports cable modems from a CSV file. The filename that is to be imported is specified using the format --file=import-filename.

The results go to a results file.

--export-cm

Exports cable modems to a CSV file. The filename that is to be exported is specified using the format --output=export-filename.

The results go to a results file.

--clear-all-cm

Clears the repository of all cable modems.

--show-dynamic-mode

Shows whether to allow or deny the login of CPEs that belong to unfamiliar cable modems; i.e., cable modems that do not exist in the SM database.

Table B-4 p3cable File Options

File Option

Abbreviation

Description

--file=FILE

-f FILE

Specifies the CSV FILE to import from.

--output=FILE

-o FILE

Specifies the subscriber CSV FILE to export to.

Examples of using the p3cable Utility

•To import cable modem information from the specified csv file:

p3cable --import-cm -f CMFile.csv
•To export cable modem information to the specified csv file:

p3cable --export-cm --outfile=myCMFile.csv
•To clear the repository of all cable modems:

p3cable --clear-all-cm
•To display whether the login of CPEs that belong to unfamiliar cable modems (cable modems that do not exist in SM database) is allowed or denied:

p3cable --show-dynamic-mode
Information About the p3clu Utility

p3clu Utility

The p3clu utility prints a list of all supported CLU utilities and options.

The command format is:

p3clu OPERATION
The following table lists the p3clu operations.

Table B-5 p3clu Operations

Operation

Description

--help

Prints the currently supported CLU commands.

Example of using the p3clu Utility

•To display a listing of all supported CLU utilities and operations:

p3clu --help
Information About the p3cluster Utility

p3cluster Utility

The p3cluster utility displays the redundancy state of a cluster of two SM nodes and its components. This utility also supports operations that alter the redundancy state of the SM. These operations are used by the SM Cluster Agent and for administrative tasks.

The command format is:

p3cluster OPERATION
The following table lists the p3cluster operations.

Table B-6 p3cluster Operations

Operation

Description

--show

Displays the redundancy status of the SM and its components.

--active

Make the SM become the active SM in the cluster.

--standby

Make the SM become the standby SM in the cluster.

Example of using the p3cluster Utility

•To display the redundancy status of the SM and its components:

p3cluster --show
Information About the p3db Utility

p3dbUtility

The p3db utility manages and monitors the TimesTen database. The CLU exposes capabilities of some of the TimesTen CLUs with respect to specific needs of the SM.

The command format is:

p3db OPERATION[OPTIONS]
The following tables list the p3dboperations and options.

Note Use caution when activating commands that can affect the database. If used incorrectly, these commands can possibly damage the database.

Table B-7 p3db Operations

Operation

Description

--rep-status

Displays status of the replication agent.

--rep-start

Starts the replication agent.

Note Use only for database recovery.

--rep-stop

Starts the replication agent. Note: Use only for database recovery. Stops the replication agent. Note: Use only for database recovery.

Note Use only for database recovery.

--status

Displays the database status.

--destroy-rep-db

Destroys the replicated data-store.

--destroy-local-db

Destroys the local data-store.

--duplicate

Copies the data-store from the remote machine to the local machine.

Note This option is applicable only for a cluster setup . For additional information, see the "Data Duplication Procedure" section on page 4-22.

--keep-in-mem[SECS]

Indicates to the database daemon how many seconds to keep the database in the memory, after the last connection to the database is down. Use this option with large databases to reduce the SM restart time.

Note To prevent limitations in performing a database destroy, do not use values above a few minutes (that is, above a few hundred seconds).

Table B-8 p3db Options

Option

Description

--local=LOCAL_HOSTNAME

Specifies the local machine.

--remote=REMOTE_HOSTNAME

Specifies the remote machine.

Examples of using the p3db Utility

•To display the status of the replication agent:

p3db --rep-status
Information About the p3domains Utility

p3domains Utility

The p3domains utility displays the subscriber domains. When a system has more than one SCE platform, you can configure the platforms into groups or domains. A subscriber domain is one or more SCE platforms that share a specified group of subscribers. You must add the SCE platform to the network and create the domain before you can add an SCE platform to a domain.

The command format is:

p3domains OPERATION[OPTIONS]
The following tables list the p3domains operations and options.

Table B-9 p3domains Operations

Operation

Description

--show-all

Displays all configured domains.

--show

Displays a domain and its associated network elements.

Table B-10 p3domains Domain/Network Element (NE) Options

Domain/NE Option

Abbreviation

Description

Notes

--domain=DOMAIN

-d DOMAIN

DOMAIN specifies logical name.

nonecannot be used, it is a reserved word.

Examples of using the p3domains Utility

•To display all configured domains:

p3domains --show-all
•To display the specified domain and its associated network elements:

p3domains --show --domain=myDomain
Information About the p3ftp Utility

p3ftp Utility

The p3ftp utility monitors the SM internal FTP server.

The command format is:

p3ftp OPERATION
The following table lists the p3ftp operations and options.

Table B-11 p3ftp Operations

Operation

Description

--show

Displays the port number the FTP server listens to, the passive FTP port range the server uses, the current number of open sessions, the maximum number of sessions supported, and the state (ONLINE/OFFLINE) of the FTP server.

Examples of using the p3ftp Utility

•To display the port number that the FTP server listens to, the passive FTP port range that the server uses, the current number of open sessions, the maximum number of sessions supported, and the state (ONLINE/OFFLINE) of the FTP server.

p3ftp --show
Information About the p3http Utility

p3http Utility

The p3http utility monitors the HTTP adapter server.

Note The HTTP adapter server is a technician interface and normally should not be used.

The command format is:

p3http OPERATION
The following table lists the p3httpoperations:

Table B-12 p3http Operations

Operation

Description

--show

Displays the port number that the server listens to, the state of the server, and the current number of open sessions.

Examples of using the p3http Utility

•To display the port number to which the server listens, the state of the server, and the current number of open sessions:

p3http --show
Information About the p3inst Utility

p3inst Utility

The p3inst utility installs or uninstalls an application (pqi file).

Note Before using p3inst to install an application pqi file, read the application installation instructions that came with the application you are using.

The command format is:

p3inst OPERATION[FILE-OPTION] [ARGUMENT-OPTION]
The following tables list the p3instoperations and options.

Table B-13 p3inst Operations

Operation

Abbreviation

Description

Notes

--install

-i

Installs the specified application pqi file to the SM.

It may be necessary to specify arguments for the installation procedure in the command line. Requires a file option.

Progress indicator

--uninstall

Uninstalls the specified application pqi file from the SM. Requires a file option.

Progress indicator

--upgrade

Upgrades an existing application using the specified application pqi file. It may be necessary to specify arguments for the upgrade procedure in the command line. Requires a file option.

Progress indicator

--rollback

Returns the specified application to the previous version. Rollback is the opposite of an upgrade operation: it reverses the upgrade.

Progress indicator

--describe

-d

Displays the contents of the specified application pqi file.

--show-last

Lists the details of the last installed application pqi file.

Table B-14 p3inst File Options

File Option

Abbreviation

Description

--file=FILE[;FILE...]

-f FILE[;FILE...]

Specifies one or more installation FILEs to use. If there is more than one FILE, semicolons should separate them.

Table B-15 p3inst Argument Options

Argument Option

Description

--arg=ARG1[,ARG2...]

Specifies one or more arguments for the install and upgrade procedures.

Examples of using the p3inst Utility

•To install the specified installation file:

p3inst --install --file=myInstallation.pqi
•To uninstall the specified installation file:

p3inst --uninstall -f oldInstallation.pqi
•To upgrade an existing application using the specified application pqi file:

p3inst --upgrade --file=newInstallation.pqi
•To upgrade an existing application using the specified application pqi file, using arguments in the command line:

p3inst --upgrade -f newInstallation.pqi
•To return the specified application to the previous version:

p3inst --rollback
•To display the contents of the specified application pqi file:

p3inst --describe --file=myInstallation.pqi
•To list the details of the last installed application pqi file:

p3inst --show-last
Information About the p3log Utility

p3log Utility

The p3logutility configures and manages the SM user log. The user log contains all user-related events and errors. Use the user log to view the history of the system events and errors.

The command format is:

p3log OPERATION[FILE-OPTION]
The following tables list the p3logoperations and options.

Table B-16 p3log Operations

Operation

Description

Notes

--extract

Retrieves the user log from the agent.

Progress indicator

--reset

Clears the user log.

Table B-17 p3log File Option

File Option

Abbreviation

Description

--output=FILE

-o FILE

Specifies to where the SM user log file should be extracted.

Examples of using the p3log Utility

•To extract the SM user log to the specified file:

p3log --extract -o aug20.log
•To clear the SM user log:

p3log --reset
Information About the p3net Utility

p3net Utility

The p3netutility shows the connection status of network elements and tries to reconnect disconnected elements.

The command format is:

p3net OPERATION[NETWORK-ELEMENT-OPTION]
The following tables list the p3netoperations and options.

Table B-18 p3net Operations

Operation

Description

--show-all

Shows all the configured network elements.

--show

Shows the element connection status/general information.

--connect

Tries to connect a disconnected element.

Table B-19 p3net Network Element Options

Network Element Option

Abbreviation

Description

--ne-name=NAME

-n NAME

Specifies the logical NAME for the network element.

--detail

(Optional) Used with the --show-all operation for displaying additional information as a table.

Examples of using the p3net Utility

•To connect a disconnected element to the network:

p3net --connect -n mainNE
•To display the names of all configured network elements:

p3net --show-all Network Element name list: ========================== sceRome sceLondon
sceRome is a cascade setup containing two SCEs. This is displayed as a single entry in the list.

•To display all configured network elements details (as a table):

p3net --show-all --detail ========================================================================== | Name | Host | Conn- | Subscriber | Domain | | | Status| Management | ========================================================================== | sceRome | 1.2.3.4* | up | active | subscribers | sceRome | 1.2.3.5 | up | active | subscribers | sceLondon | 1.2.3.6 | up | active | domain1
sceRome is a cascade setup containing two SCEs. This is displayed as two entries with the same name where '*' represents the currently active SCE.

Note The SM does not synchronize the standby SCE; therefore, the Subscriber Management field on the standby SCE might appear as not-active if the SCE was never active.

•To display the connection status of the specified network element:

p3net --show --ne-name=mainNE Network Element Information: ============================ Name: mainNE Host: 1.1.1.1 Ip: 1.1.1.1 Port: 14374 Status: Connection ready Type: SCE2000 Domain: subscribers Subscriber Management: Active Redundancy Status: Standalone Quarantine Status: ok
•To display the connection status of cascaded SCEs, use the SCE name that appears in the configuration file:

p3net --show -n test Network Element Information: ============================ Name: test Host: 1.1.1.1 Ip: 1.1.1.1 Port: 14374 Status: Connection ready Type: SCE2000 Domain: subscribers Subscriber Management: Active Redundancy Status: Active Quarantine Status: ok Network Element Information: ============================ Name: test Host: 2.2.2.2 Ip: 2.2.2.2 Port: 14374 Status: Connection ready Type: SCE2000 Domain: subscribers Subscriber Management: Not-Active Redundancy Status: Standby Quarantine Status: ok
Information About the p3radius Utility

The p3radius utility displays the statistics of the RADIUS Listener LEG. For information about this CLU, see the Cisco SCMS SM RADIUS Listener LEG Reference Guide .

Information About the p3rpc Utility

p3rpc Utility

The p3rpc utility displays the information of the proprietary Cisco RPC (Remote Procedure Call) server interface to the SM. It also authenticates users.

The command format is:

p3rpc OPERATION[OPTIONS]
The following tables list the p3rpc operations and options.

Table B-20 p3rpc Operations

Operation

Description

--show

Displays the port number to which the PRPC server listens, the maximum number of connections, the current number of active connections, and the host IP to which the server listens.

--show-client-names

Displays the names of the connected clients. Can be used for extracting the LEG_NAME key, see the "LEG-Domains Association Section".

--show-statistics

Displays the PRPC server statistics. They contain information about the number of current PRPC sessions and statistics for PRPC server actions such as invocations and errors.

--reset-statistics

Clears the PRPC server statistics.

--set-user

Adds or updates the username and password.

--validate-password

Validates the username and password.

--delete-user

Deletes a user configuration.

--show-users

Displays all configured users.

Table B-21 p3rpc User Options

User Option

Abbreviation

Description

--username=USER-NAME

-u

Specifies the name of the user. Used with --set-user, --validate-password, and --delete-user operations.

--password=USER-PASSWORD

-p

Specifies the password of the user. Used with --set-user, --validate-password, and --delete-user operations.

Table B-22 p3rpc Miscellaneous Options

Option

Abbreviation

Description

--remote=IP[:port]

-r

(Optional) Used with --set-user, --validate-password, and --delete-user for users operations on the remote SM in High Availability setups.

The port option should be used if the PRPC Server port on the remote SM machine differs from the default value (14374).

Examples of using the p3rpc Utility

•To display the port number to which the PRPC server listens, the maximum number of connections, the current number of active connections, the host IP to which the server listens, and the name of the configuration file used by the server:

p3rpc --show
•To display the statistics of the PRPC server:

p3rpc --show-statistics
•To clear the statistics of the PRPC server:

p3rpc --reset-statistics
•To show all the users configured at the PRPC server:

p3rpc --show-users
Information About the p3sm Utility

p3sm Utility

The p3sm utility performs general configuration and management of the SM.

The command format is:

p3sm OPERATION[OPTIONS]
The following tables list the p3sm operations and options.

Table B-23 p3sm Operations

Operation

Description

Notes

--show

Displays the current SM configuration and statistics.

--load-config

Reloads the SM configuration file.

If the -f option is not used, file p3sm.cfg is loaded.

--resync

Resynchronizes subscribers of specified SCE with the SM database.

The SCE is specified using the option --ne-name=SCE_NAME.

Progress indicator

--resync-all

Resynchronizes all subscribers of all SCEs with the SM database.

Progress indicator

--start [--wait]

Starts the server. The option --waitcauses the CLU to return only after the SM is up.

Default: started

--stop

Stops the server.

Note When using fail-over, a simple shut-down of the SM does not work, the Veritas Cluster Server identifies that the SM is down and attempts to restart it. The correct procedure is:

1. Perform the manual fail-over. See Subscriber Manager Fail-Over.

2. Use the Veritas Cluster Manager Application to stop the monitoring (probing) of the SM.

3. Use the SM CLU ( p3sm --stop) to stop the SM

--restart [--wait]

Stops the server operation and then restarts it. The option --wait causes the CLU to return only after the SM is up.

--sm-version

Displays the currently installed SM version.

--sm-status [--detail]

Displays the SM operational status: whether the SM is running or not, and whether it is Active or Standby. If errors have occurred, it also displays their summary. To receive a detailed description, use the option --detail.

--extract-support-file

Retrieves the support file from the agent.

This command extracts the SM support information to a defined file, which is defined using the option --output=FILE. SM support information should be extracted and sent to Cisco customer support with each support request.

--reset-sm-status

Clears errors and warnings that were displayed to the user.

--logging=[on/off]

Enables/disables the logging of user logon to the UserLog.

Note Enabling this flag may affect performance.

--show-stats

Displays statistics information regarding logon operations and inactive subscriber removal operations. The rate results are updated once every 10 seconds.

--reset-stats

Resets the statistics information.

Table B-24 p3sm SM Options

SM Option

Abbreviation

Description

--ne-name=NAME

-n NAME

Specifies logical NAME of the SCE platform to resynchronize.

Table B-25 p3sm File Options

File Option

Abbreviation

Description

--output=FILE

-o FILE

Where to extract the support information file, relative to the SM root directory

--file=FILE

-f FILE

File to load the configuration from, relative to the SM configuration directory.

Table B-26 p3sm Miscellaneous Options

File Option

Abbreviation

Description

--ignore-warnings

-i

Ignore configuration validation warnings while loading the configuration file.

--remote=IP[:port]

-r

Used with --load-configto load the local configuration file to both the local SM and the remote SM.

--detail

Displays a detailed view of the SM status.

--wait

Used with --startor --restartto signal the CLU to return only when the SM is up.

Examples of using the p3sm Utility

•To start the server:

p3sm --start
•To stop the server:

p3sm --stop

Note When using fail-over, a simple shut-down of the SM does not work, the Veritas Cluster Server identifies that the SM is down and attempts to restart it. The correct procedure is:

1. Perform the manual fail-over. See Subscriber Manager Fail-Over.

2. Use the Veritas Cluster Manager Application to stop the monitoring (probing) of the SM.

3. Use the SM CLU ( p3sm --stop) to stop the SM

•To display the SM configuration:

>p3sm --show Subscriber Management Module Information: ========================================= Persistency in SCE (static): false Auto-resync at SCE reconnect: true Save subscriber state on logout: false Pull mode is on: false LEG block mode is on: false Logon logging is on: false Statistics: Number of logins: 1872423 Number of logouts: 1824239 Number of auto-logouts: 0 Number of pull requests: 0 LEG-SM link failure: Clear all subscribers mappings: false Timeout: 60 Up time: 4 hours 16 minutes 44 seconds Inactive Subscribers Removal: Is Enabled: false Inactivity timeout: 1 hours Max removal rate: 10 subscribers per second Task interval: 10 minutes Last run time: Was never run Automatic Logout (lease-time support): Is Enabled: false Max logout rate: 50 IP addresses per second Task interval: disabled Grace period: 10 seconds Last run time: Was never run Command terminated successfully
•To resynchronize the subscribers of the specified SCE with the SM database:

p3sm --resync --ne-name=my_SCE_100
•To stop the server operation and then restart it:

p3sm --restart
•To reload the SM configuration file, p3sm.cfg:

p3sm --load-config
•To display the SM operational status (active or inactive):

>p3sm --sm-status SM is running. SM operational state is Active Command terminated successfully
•To extract the SM support information to the specified file:

p3sm --extract-support-file --output=support.zip
•To display statistics information regarding logon operations and inactive subscriber removal:

>p3sm --show-stats Subscriber Management Statistics Information: ============================================ Number of logins: 1872423 Login rate: 10.34 Number of logouts: 1824239 Logout rate: 10.67 Number of auto-logouts: 0 Auto-logout rate: 0 Number of pull requests: 0 Pull requests rate: 0 Inactive Subscriber Removal Information: ============================================ Number of inactive subscribers removed: 56732 Inactive subscribers removal rate: 9.98 Command terminated successfully
Information About the p3subs Utility

p3subs Utility

The p3subs utility manipulates individual subscriber information in the SM database. Regarding properties, the property names depend on the application running on your system. To find descriptions of the application property names and values, see the documentation provided with the application installed on your system.

The command format is:

p3subs OPERATION[SUBSCRIBER-OPTIONS]
The following tables list the p3subs operations and options.

Table B-27 p3subs Operations

Operation

Description

--add

Adds/updates a subscriber. The operation fails if the subscriber exists, unless the --overwriteoption is used.

--set

Adds/updates mappings and/or properties for the specified subscriber.

A new mapping overwrites all existing mappings, unless the --additive-mapping option is used.

A property is overwritten only when a new value is assigned to it, but not when a different property has a new value assigned to it.

--show

Displays information for the specified subscriber.

--remove

Removes the specified subscriber.

--show-all-mappings

Displays all the mappings for the specified subscriber.

--remove-mappings

Removes the specified mapping of the specified subscriber.

--remove-all-mappings

Removes all the mappings of the specified subscriber.

--show-property

Displays the value of the specified property of the specified subscriber.

--show-all-properties

Displays the values of all the properties of the specified subscriber.

--show-all-property-names

Displays all the property names and descriptions.

--reset-property

Resets the specified property of the specified subscriber to its default value.

--remove-properties

Removes all properties and custom properties from the subscriber record.

--clear-state

Clears applicative state of specified subscriber. This command clears only the backup copy at the SM; it does not clear the applicative state record in the SCE platform.

Table B-28 p3subs Subscriber Options

Subscriber Option

Abbreviation

Description

--overwrite

Used in add operations to replace the existing subscriber configuration, instead of failing.

--subscriber=NAME

-s NAME

Performs operation using specified subscriber NAME.

--additive-mappings

Adds the new mapping(s) to any existing ones. (Without this option, any existing mappings are overwritten.)

--ip=IP1[/RANGE][,...]

Performs operation using specified IP mapping(s). IP is in dotted notation.

"/RANGE" is used for specifying several consecutive mappings, by specifying the number of consecutive set bits in the mask. For example, 1.1.1.0/30 means 1.1.1.0 to 1.1.1.3 , or 1.1.1.0 with mask 255.255.255.252.

--vlan-id=VLAN1[,...]

Performs operation using specified VLAN mapping(s).

--mpls-vpn=VPN-ID@PE-IP[...]

Performs operation using specified MPLS/VPN specification. The notation of the MPLS/VPN mappings is VPN-ID@PE-IP. VPN-ID is the VPN identifier of the VPN site (can be RT or RD). The PE-IP is the loopback IP address of the PE router attached to the VPN. For more information on the MPLS/VPN mappings, see the Cisco SCMS SM MPLS/VPN BGP LEG Reference Guide .

--property=KEY1[=VAL1][;...]

-p KEY1[=VAL1][;...]

Performs operation using the specified KEY=VAL property/properties. These properties are defined by the application and influence the subscriber service in the SCE.

--custom-property=KEY1[=VAL1 ][;...]

Performs operation using the specified KEY=VAL custom property/properties. These properties are user defined and have no influence on the service the subscriber receives.

--domain=DOMAIN

-d DOMAIN

Performs operation on specified DOMAIN. If DOMAIN is none , the operation refers to subscribers who have no domain specified.

Note When working with VLAN mapping types, the SCE must be configured using the following CLI:

SCE2000#>configure SCE2000(config)#>in li 0 SCE2000(config if)#>VLAN symmetric classify
Examples of using the p3subs Utility

•To add a subscriber with the specified IP address:

p3subs --add --subscriber=jerry --ip=96.142.12.7
•To overwrite subscriber information (because the subscriber jerry already exists, this operation would fail, but the overwrite option allows the IP address to be overwritten):

p3subs --add --subscriber=jerry --ip=96.128.128.42 --overwrite
•To set a property value for the specified subscriber:

p3subs --set --subscriber=jerry --property=packageId=1
•To add new mappings for the specified subscriber; any existing ones are overwritten:

p3subs --set --subscriber=jerry --vlan-id=1
•To add new mappings to the existing ones for the specified subscriber:

p3subs --set --subscriber=jerry --vlan-id=4,2 --additive-mappings
•To display information for the specified subscriber:

p3subs --show --subscriber=jerry
•To remove the specified subscriber:

p3subs --remove --subscriber=jerry
•To display all the mappings for the specified subscriber:

p3subs --show-all-mappings --subscriber=jerry
•To remove the specified mappings for the specified subscriber:

p3subs --remove-mappings --subscriber=jerry --ip=96.142.12.7,96.128.128.42
•To remove a range of consecutive mappings for the specified subscriber:

p3subs --remove-mappings --subscriber=jerry --ip=1.1.1.0/30
•To remove all the mappings for the specified subscriber:

p3subs --remove-all-mappings --subscriber=jerry
•To display the value of the specified property for the specified subscriber:

p3subs --show-property --subscriber=jerry --property=reporting
•To display the values of all the properties for the specified subscriber:

p3subs --show-all-properties --subscriber=jerry
•To display all the property names and descriptions:

p3subs --show-all-property-names
•To reset specified property of specified subscriber to its default value:

p3subs --reset-property --subscriber=jerry --property=rdr.transaction.generate
•To clear the applicative state of the specified subscriber. This command clears only the backup copy at the SM, it does not clear the applicative state record in the SCE platform:

p3subs --clear-state --subscriber=jerry
Information About the p3subsdb Utility

p3subsdb Utility

The p3subsdb utility manages the subscriber database and performs operations on groups of subscribers.

The command format is:

p3subsdb OPERATION[OPTIONS] [FILE-OPTIONS]
The following tables list the p3subsdb operations and options.

Table B-29 p3subsdb Operations

Operation

Description

Notes

--clear-all

Removes all subscriber records from the SM database.

Progress indicator

--clear-domain

Removes all subscriber records from the specified domain.

Progress indicator

--show-num

Displays number of subscribers in database for the specified domain.

--show-all

Lists all the subscriber names.

--show-domain

Lists all the subscriber names in the specified domain.

--import

Imports subscribers to the database from a specified CSV file.

The filename that is to be imported is specified using the format "--file=import-filename".

The results go to a result file, import-results.txt , which is created in the same directory as the CSV file.

Progress indicator

--export

Exports subscribers from the database to a specified CSV file.

The filename that is to be exported is specified using the format "--output=export-filename".

The results go to a result file, export-results.txt, which is created in the same directory as the CSV file.

Progress indicator

--clear-all-states

Clears the state of all subscribers in the SM database.

--remove-property

Removes a specified property from all subscribers in the system.

Note After running this command you should re-synchronize all SCE devices.

--remove-all-ip

Removes all the IP addresses of all subscribers.

--remove-all-vlan

Removes all the VLAN tags of all subscribers.

--remove-all-mpls-vpn

Removes all the MPLS/VPN mappings of all subscribers.

Table B-30 p3subsdb Options

Option

Abbreviation

Description

--prefix=NAME

Used in the export operation for filtering the export.

--property=PROP

Used in removing of property PROP from all of the subscribers.

--domain=DOMAIN

-d DOMAIN

Performs the operation on the specified DOMAIN. If DOMAIN is none , the operation refers to the subscribers who have no domain specified.

Table B-31 p3subsdb File Options

File Option

Abbreviation

Description

--file=FILE

-f FILE

Specifies the subscriber CSV FILEs to import from.

--output=FILE

-o FILE

Specifies the subscriber CSV FILE to export to.

Examples of using the p3subsdb Utility

•To import subscribers from a specified CSV file:

p3subsdb --import --file=mySubscriberFile.csv
•To export subscribers to a specified CSV file:

p3subsdb --export -o mySubscriberFile.csv
•To export subscribers to a specified CSV file, using filtering options:

p3subsdb --export --prefix=a --output=mySubscriberFile.csv
•To export subscribers to a specified CSV file, using filtering options:

p3subsdb --export --prefix=a -o a.csv
•To remove all subscriber records from the SM database:

p3subsdb --clear-all
•To remove all subscriber records from the specified domain:

p3subsdb --clear-domain --domain=myDomain
•To list all the subscribers: p3subsdb --show-all To list all subscribers in a specified domain:

p3subsdb --show-domain --domain=myDomain
•To show the number of subscribers in a specified domain:

p3subsdb --show-num --domain=myDomain
•To list all subscribers who have no domain specified:

p3subsdb --show-domain --domain=none
•To clear the state of all subscribers in the SM database:

p3subsdb --clear-all-state
•To remove a property from all subscriber records:

p3subsdb --remove-property --property=monitor

Operation	Description
`--help`	Prints the help for the specified CLU command, then exits.
`--version`	Prints the SM program version number, then exits.

Operation/option contains the character	Example of how operation/option should be written
Space character	`--property="file name"`
Escape character (backslash "\")	`--property="good\\bad"`
Equal sign (=)	`--property="x\=y"`
Quotation marks (" or ")	`--name="\"myQuotedName\""` (in the above example, inner quotation marks are escaped)
Separation characters
comma (,)	`--names="x,y"`
ampersand (&)	`--names="x&y"`
colon (:)	`--names="myHost:myDomain"`

Example of using full name	`--domain=subscribers`
Example of using abbreviated name	`-d subscribers`

Operation	Description
`--import-cm`	Imports cable modems from a CSV file. The filename that is to be imported is specified using the format `--file=import-filename`. The results go to a results file.
`--export-cm`	Exports cable modems to a CSV file. The filename that is to be exported is specified using the format `--output=export-filename`. The results go to a results file.
`--clear-all-cm`	Clears the repository of all cable modems.
`--show-dynamic-mode`	Shows whether to allow or deny the login of CPEs that belong to unfamiliar cable modems; i.e., cable modems that do not exist in the SM database.

File Option	Abbreviation	Description
`--file=FILE`	`-f FILE`	Specifies the CSV FILE to import from.
`--output=FILE`	`-o FILE`	Specifies the subscriber CSV FILE to export to.

Operation	Description
`--show`	Displays the redundancy status of the SM and its components.
`--active`	Make the SM become the active SM in the cluster.
`--standby`	Make the SM become the standby SM in the cluster.

Operation	Description
`--rep-status`	Displays status of the replication agent.
`--rep-start`	Starts the replication agent. Note Use only for database recovery.
`--rep-stop`	Starts the replication agent. Note: Use only for database recovery. Stops the replication agent. Note: Use only for database recovery. Note Use only for database recovery.
`--status`	Displays the database status.
`--destroy-rep-db`	Destroys the replicated data-store.
`--destroy-local-db`	Destroys the local data-store.
`--duplicate`	Copies the data-store from the remote machine to the local machine. Note This option is applicable only for a cluster setup . For additional information, see the "Data Duplication Procedure" section on page 4-22.
`--keep-in-mem[SECS]`	Indicates to the database daemon how many seconds to keep the database in the memory, after the last connection to the database is down. Use this option with large databases to reduce the SM restart time. Note To prevent limitations in performing a database destroy, do not use values above a few minutes (that is, above a few hundred seconds).

Option	Description
`--local=LOCAL_HOSTNAME`	Specifies the local machine.
`--remote=REMOTE_HOSTNAME`	Specifies the remote machine.

Operation	Description
`--show-all`	Displays all configured domains.
`--show`	Displays a domain and its associated network elements.

Operation	Abbreviation	Description	Notes
--install	-i	Installs the specified application pqi file to the SM. It may be necessary to specify arguments for the installation procedure in the command line. Requires a file option.	Progress indicator
--uninstall		Uninstalls the specified application pqi file from the SM. Requires a file option.	Progress indicator
--upgrade		Upgrades an existing application using the specified application pqi file. It may be necessary to specify arguments for the upgrade procedure in the command line. Requires a file option.	Progress indicator
--rollback		Returns the specified application to the previous version. Rollback is the opposite of an upgrade operation: it reverses the upgrade.	Progress indicator
--describe	-d	Displays the contents of the specified application pqi file.
--show-last		Lists the details of the last installed application pqi file.

Operation	Description	Notes
`--extract`	Retrieves the user log from the agent.	Progress indicator
`--reset`	Clears the user log.

Operation	Description
`--show-all`	Shows all the configured network elements.
`--show`	Shows the element connection status/general information.
`--connect`	Tries to connect a disconnected element.

Network Element Option	Abbreviation	Description
`--ne-name=NAME`	`-n NAME`	Specifies the logical NAME for the network element.
`--detail`		(Optional) Used with the `--show-all` operation for displaying additional information as a table.

Operation	Description
`--show`	Displays the port number to which the PRPC server listens, the maximum number of connections, the current number of active connections, and the host IP to which the server listens.
`--show-client-names`	Displays the names of the connected clients. Can be used for extracting the LEG_NAME key, see the "LEG-Domains Association Section".
`--show-statistics`	Displays the PRPC server statistics. They contain information about the number of current PRPC sessions and statistics for PRPC server actions such as invocations and errors.
`--reset-statistics`	Clears the PRPC server statistics.
`--set-user`	Adds or updates the username and password.
`--validate-password`	Validates the username and password.
`--delete-user`	Deletes a user configuration.
`--show-users`	Displays all configured users.

User Option	Abbreviation	Description
`--username=USER-NAME`	`-u`	Specifies the name of the user. Used with --set-user, --validate-password, and --delete-user operations.
`--password=USER-PASSWORD`	`-p`	Specifies the password of the user. Used with --set-user, --validate-password, and --delete-user operations.

Operation	Description	Notes
`--show`	Displays the current SM configuration and statistics.
`--load-config`	Reloads the SM configuration file. If the -f option is not used, file p3sm.cfg is loaded.
`--resync`	Resynchronizes subscribers of specified SCE with the SM database. The SCE is specified using the option --ne-name=SCE_NAME.	Progress indicator
`--resync-all`	Resynchronizes all subscribers of all SCEs with the SM database.	Progress indicator
`--start [--wait]`	Starts the server. The option --waitcauses the CLU to return only after the SM is up.	Default: started
`--stop`	Stops the server. Note When using fail-over, a simple shut-down of the SM does not work, the Veritas Cluster Server identifies that the SM is down and attempts to restart it. The correct procedure is: 1. Perform the manual fail-over. See Subscriber Manager Fail-Over. 2. Use the Veritas Cluster Manager Application to stop the monitoring (probing) of the SM. 3. Use the SM CLU ( p3sm --stop) to stop the SM
`--restart [--wait]`	Stops the server operation and then restarts it. The option --wait causes the CLU to return only after the SM is up.
`--sm-version`	Displays the currently installed SM version.
`--sm-status [--detail]`	Displays the SM operational status: whether the SM is running or not, and whether it is Active or Standby. If errors have occurred, it also displays their summary. To receive a detailed description, use the option --detail.
`--extract-support-file`	Retrieves the support file from the agent. This command extracts the SM support information to a defined file, which is defined using the option --output=FILE. SM support information should be extracted and sent to Cisco customer support with each support request.
`--reset-sm-status`	Clears errors and warnings that were displayed to the user.
`--logging=[on/off]`	Enables/disables the logging of user logon to the UserLog. Note Enabling this flag may affect performance.
`--show-stats`	Displays statistics information regarding logon operations and inactive subscriber removal operations. The rate results are updated once every 10 seconds.
`--reset-stats`	Resets the statistics information.

File Option	Abbreviation	Description
`--output=FILE`	`-o FILE`	Where to extract the support information file, relative to the SM root directory
`--file=FILE`	`-f FILE`	File to load the configuration from, relative to the SM configuration directory.

File Option	Abbreviation	Description
`--ignore-warnings`	`-i`	Ignore configuration validation warnings while loading the configuration file.
`--remote=IP[:port]`	`-r`	Used with --load-configto load the local configuration file to both the local SM and the remote SM.
`--detail`		Displays a detailed view of the SM status.
`--wait`		Used with --startor --restartto signal the CLU to return only when the SM is up.

Operation	Description
`--add`	Adds/updates a subscriber. The operation fails if the subscriber exists, unless the --overwriteoption is used.
`--set`	Adds/updates mappings and/or properties for the specified subscriber. A new mapping overwrites all existing mappings, unless the --additive-mapping option is used. A property is overwritten only when a new value is assigned to it, but not when a different property has a new value assigned to it.
`--show`	Displays information for the specified subscriber.
`--remove`	Removes the specified subscriber.
`--show-all-mappings`	Displays all the mappings for the specified subscriber.
`--remove-mappings`	Removes the specified mapping of the specified subscriber.
`--remove-all-mappings`	Removes all the mappings of the specified subscriber.
`--show-property`	Displays the value of the specified property of the specified subscriber.
`--show-all-properties`	Displays the values of all the properties of the specified subscriber.
`--show-all-property-names`	Displays all the property names and descriptions.
`--reset-property`	Resets the specified property of the specified subscriber to its default value.
`--remove-properties`	Removes all properties and custom properties from the subscriber record.
`--clear-state`	Clears applicative state of specified subscriber. This command clears only the backup copy at the SM; it does not clear the applicative state record in the SCE platform.

Subscriber Option	Abbreviation	Description
`--overwrite`		Used in add operations to replace the existing subscriber configuration, instead of failing.
`--subscriber=NAME`	`-s NAME`	Performs operation using specified subscriber NAME.
`--additive-mappings`		Adds the new mapping(s) to any existing ones. (Without this option, any existing mappings are overwritten.)
`--ip=IP1[/RANGE][,...]`		Performs operation using specified IP mapping(s). IP is in dotted notation. "/RANGE" is used for specifying several consecutive mappings, by specifying the number of consecutive set bits in the mask. For example, 1.1.1.0/30 means 1.1.1.0 to 1.1.1.3 , or 1.1.1.0 with mask 255.255.255.252.
`--vlan-id=VLAN1[,...]`		Performs operation using specified VLAN mapping(s).
`--mpls-vpn=VPN-ID@PE-IP[...]`		Performs operation using specified MPLS/VPN specification. The notation of the MPLS/VPN mappings is VPN-ID@PE-IP. VPN-ID is the VPN identifier of the VPN site (can be RT or RD). The PE-IP is the loopback IP address of the PE router attached to the VPN. For more information on the MPLS/VPN mappings, see the Cisco SCMS SM MPLS/VPN BGP LEG Reference Guide .
`--property=KEY1[=VAL1][;...]`	`-p KEY1[=VAL1][;...]`	Performs operation using the specified KEY=VAL property/properties. These properties are defined by the application and influence the subscriber service in the SCE.
`--custom-property=KEY1[=VAL1 ][;...]`		Performs operation using the specified KEY=VAL custom property/properties. These properties are user defined and have no influence on the service the subscriber receives.
`--domain=DOMAIN`	`-d DOMAIN`	Performs operation on specified DOMAIN. If DOMAIN is none , the operation refers to subscribers who have no domain specified.

Operation	Description	Notes
`--clear-all`	Removes all subscriber records from the SM database.	Progress indicator
`--clear-domain`	Removes all subscriber records from the specified domain.	Progress indicator
`--show-num`	Displays number of subscribers in database for the specified domain.
`--show-all`	Lists all the subscriber names.
`--show-domain`	Lists all the subscriber names in the specified domain.
`--import`	Imports subscribers to the database from a specified CSV file. The filename that is to be imported is specified using the format "--file=import-filename". The results go to a result file, import-results.txt , which is created in the same directory as the CSV file.	Progress indicator
`--export`	Exports subscribers from the database to a specified CSV file. The filename that is to be exported is specified using the format "--output=export-filename". The results go to a result file, export-results.txt, which is created in the same directory as the CSV file.	Progress indicator
`--clear-all-states`	Clears the state of all subscribers in the SM database.
`--remove-property`	Removes a specified property from all subscribers in the system. Note After running this command you should re-synchronize all SCE devices.
`--remove-all-ip`	Removes all the IP addresses of all subscribers.
`--remove-all-vlan`	Removes all the VLAN tags of all subscribers.
`--remove-all-mpls-vpn`	Removes all the MPLS/VPN mappings of all subscribers.

Option	Abbreviation	Description
`--prefix=NAME`		Used in the export operation for filtering the export.
`--property=PROP`		Used in removing of property PROP from all of the subscribers.
`--domain=DOMAIN`	`-d DOMAIN`	Performs the operation on the specified DOMAIN. If DOMAIN is none , the operation refers to the subscribers who have no domain specified.

File Option	Abbreviation	Description
`--file=FILE`	`-f FILE`	Specifies the subscriber CSV FILEs to import from.
`--output=FILE`	`-o FILE`	Specifies the subscriber CSV FILE to export to.