C H A P T E R  6

Remote Command-Line Interface

This chapter describes the Remote Command-Line-Interface (CLI). Topics include:


Remote Command-Line Interface Introduction

The Remote Command-Line Interface (CLI) provides you remote access to commands for you to configure and gather the Sun Netra DPS runtime system information (for example, platform information). The CLI also provides you remote access to the Sun Netra DPS runtime interactive debugger and a core dump facility.


IPC Setup for Remote CLI

To access the CLI remotely, you must have the interprocess communication (IPC) mechanism set up on your system (see Chapter 5 for IPC information). In the same way that the IPC channel with ID 4 was set up to be used by the IP forward reference application, a channel with ID 1 must be set up for the remote CLI. SUNWndpsd must be installed on the Oracle Solaris system that will host the remote CLI.



Note - The remote CLI communicates over IPC channel number 1 (one), therefore, IPC channel number 1 should not be used for any other purpose.


The applications that use the remote command-line interface must have the following:



Note - The IP Forwarding (ipfwd) application has the Remote CLI functionality built in. You can use IP Forwarding as a reference on how an application enables Remote CLI functionality.



procedure icon  To Configure the Oracle Solaris Domain for Remote CLI

After the logical domains are configured and running, perform the following steps to configure the IPC channel in the Oracle Solaris domain:

1. On the primary domain, execute the following commands:


# ldm add-vdpcs ldg2-vdpcs-cli <ndps-domain>
# ldm add-vdpcc vdpcc-cli ldg2-vdpcs-cli <solaris-domain>

These commands set up an IPC data channel between ndps-domain and solaris-domain. The CLI server (ldg2-vdpcs-cli) runs on ndps-domain and the CLI client
(vdpcc-cli) runs on solaris-domain. Prior to execute these commands, ensure that the Global and Client Control Channels are already setup (see Chapter5 Interprocess Communication Software).

2. On the domain that has access to the Global Control Channel, execute:


# tnsmctl -S -C 3 -L <local_ldc> -R <remote_ldc> -F 3

local_ldc is the LDC number of the Client Control Channel at the server (ndps-domain) side.

remote_ldc is the LDC number of the Client Control Channel at the client (solaris-domain) side.

3. On the domain that has access to the Global Control Channel, execute:


# tnsmctl -S -C 1 -L <local_ldc> -R <remote_ldc> -F 3

local_ldc is the LDC number of the Data Channel at the server (ndps-domain) side.

remote_ldc is the LDC number of the Data Channel at the client (solaris-domain) side.

The channel ID assigned to this data channel is 1 (the dedicated channel number of the remote CLI communication over IPC in the Sun Netra DPS).


Accessing the Remote CLI

After IPC channel number 1 is set up between Sun Netra DPS Runtime and the remote CLI Solaris host system, enable remote CLI service in the Oracle Solaris host system. Enable remote CLI service with the command below:


# svcadm enable rcon

After enabling remote CLI service, you are ready to access the remote CLI.


procedure icon  To Access the CLI Console

1. Connect to the Oracle Solaris CLI host system.

Use telnet to the hosting Oracle Solaris system at the default port number 30001.


% telnet solaris-domain-host-name 30001
Trying 192.168.1.6...
Connected to solarisdomain.
Escape character is ’^]’.
ndps>

2. Enter help at the prompt, as shown in this example, to list options.


ndps> help
        connect                 : connect to NDPS
        disconnect              : disconnect from NDPS Channel
        send break dbg          : jump into debugger
        send break sys          : jump into system cli
        cont                    : quit from debugger
        c                       : quit from debugger
        coredump [-d <dump dir>] <corename>     : dumps lwrte core
                [-d <dump dir>] dump directory (default: "/tmp")
                <corename> core dump file name
        quit                    : quit from system cli
        exit                    : quit this program
        help                    : help for this
        console [-f file]       : connects to runtime console
                                  file is the optional log file
ndps>

3. To connect to the remote CLI, type connect at the prompt:

Type disconnect, as shown, to close the channel to the remote CLI.


ndps> connect
Opening channel 1
IPC channel #: 1
ndps> disconnect
Closing channel 1

4. To close the connection, type exit at the prompt.


ndps> exit
the IPC link is DOWN or CLOSED, please type connect to bring it up again!
Connection to sol closed by foreign host.
%


Debugging Remotely

After connected to the Sun Netra DPS runtime, you can access the Sun Netra DPS debugger.


procedure icon  To Access the Sun Netra DPS Debugger

single-step bullet  Type the send break dbg command:


ndps> connect
Opening channel 1
IPC channel #: 1
ndps> send break dbg
enter NDPS debugger...
dbg>

Type help or ? for help options.

Type c or cont to quit the debugger program:


dbg> c
exit NDPS debugger...
ndps>


Coredump Support

Coredump is supported under the Debugger program (see Debugging Remotely). From the dbg mode, use the coredump command to dump the Sun Netra DPS Runtime system core. The coredump command has the following format:


coredump [-d dump_dir] corename 

dump_dir is the directory where the core is saved on the CLI hosting Oracle Solaris system. By default, the core is saved in /tmp.

corename is the core file name. The next available numeric is appended to this core file name, followed by .gz.


dbg> coredump core
Using dump directory “/tmp”
Total dumped: 74024954 bytes, compressed to: 456741 bytes
finished coredump successfully!
dbg>

The preceding core file is created at /tmp/core-1.gz on the remote CLI host system (solarisdomain). Note that this can take up to several minutes due to the size of the core dump file.


System Configuration

The user can collect system information and, if desired, change the configuration from the system (sys) mode.


procedure icon  To Go to the sys Mode From the Remote CLI

1. Connect to the remote CLI.

See Accessing the Remote CLI.

2. To connect to sys mode, use the send break sys command.


ndps> connect
Opening channel 1
IPC channel #: 1
ndps> send break sys
enter NDPS system cli...
sys>

3. Enter help for options.


sys> help
        set             - set commands
        clr             - clear commands
        show            - show commands
        help            - help commands
        version         - version command
        quit            - quit sys cli command
sys>

4. To disconnect from sys mode, type quit.


sys> quit 
exit NDPS system cli... 
ndps> 


Compiling the Remote CLI Application

Build Script

TABLE 6-1 shows the remotecli application build script.


TABLE 6-1 Remote CLI Application Build Scripts

Build Script

Usage

./build (See Argument Descriptions)

Build remotecli application.


Usage

build cmt [profiler]

Build Script Arguments

[ ] - Optional arguments

Argument Descriptions

cmt

Specifies whether to build the remotecli application to run on the CMT1 (UltraSPARC T1) platform or CMT2 (UltraSPARC T2) platform.

cmt1 - Build for CMT1 (UltraSPARC T1) architecture
cmt2 - Build for CMT2 (UltraSPARC T2) architecture

This argument is required for scripts that expect <cmt>.

[profiler]

Generate codes with profiling enabled.

The above creates the bootable image at code/main/main.



Note - The remotecli application is a simple application to demonstrate remote CLI functions. The application does not perform any particular useful task. For details on how to integrate remote CLI functions into a large scale application, refer to the IP Forwarding application.