Sun Shared Shell User Guide

Table of Contents

Overview Illustration 1: Shared Shell Model Terminology System Prerequisites Information to Gather Before Using Shared Shell Overview of the Shared Shell Interface Illustration 2: Major Areas of the Shared Shell Window Initiating a Conference Without a Proxy Initiating a Conference With a Proxy Joining a Conference as a Participant Inviting Participants Interacting With the Shell Copying/Pasting Text Using the Terminal Mouse Tools Sending Text Messages by Using the Chat Pane Editing Preferences Setting Access Levels Terminating a Participant Transferring Files Leaving or Terminating a Conference Pinging the Target System Log Files "Communication Delayed" indicator

 
 

Overview

This guide is designed for Sun Services customers who use Sun Shared Shell (Shared Shell) to conduct secure conferences with Sun Services engineers. Shared Shell is a Java application designed to provide secure, shared, remote access to a command-line user interface, such as a shell. A shell is a text-based login session running on your system, under your control. You can invite your collegues or additional Sun engineers to participate in the conference as needed. You are always in control of who participates and who has access to the remote access session.

All communication between you and Sun is secured by industry-standard Secure Sockets Layer (SSL) encryption. Shared Shell also provides secure file transfer (which you control) and a chat interface for sending text messages between participants.

All activity from your system and the Sun Support Center is logged on both sides. Information logged includes all output from your shell, chat messages, file transfer information, and conference events, such as participants joining or leaving.

Illustration 1 provides a model that explains how Shared Shell works.

Terminology

You need to understand the following terms before using Shared Shell.

• Initiator: The person and Shared Shell client that initiates a session. This is the Shared Shell client that makes a local connection to the target server that is being diagnosed and invites and approves all other participants.
• Participant: A person and Shared Shell client that joins a session using an invitation key provided by you in your role as the initiator.
• Target system: The system being diagnosed, initially accessed by a local connection by you as the conference initiator. You must use either a Telnet or Secure Shell (SSH) connection. The target system can be a Sun server, a terminal server or console server, a Linux box, a storage array, or any other device that supports Telnet or SSH access.
• Initiator system: The system from which you initiate the Shared Shell session.
• Shell: The command line interface to the operating system on the target system .

System Prerequisites

The initiator system must meet the following requirements:

• Network connectivity from the initiator system to the Telnet or SSH port on the target system.
• A graphical user interface, such as Microsoft Windows or X Windows on a system that runs the Solaris Operating System or Linux. The graphical interface is required only on the initiator system, not on the target system.
• Java Runtime Environment (JRE) 1.4.2 or higher software installed with the Java Plug-In enabled. Links are provided on the Shared Shell launch page so you can check your JRE installation or download a new version.
• A web browser, such as Microsoft Internet Explorer 6.x or Mozilla Firefox 1.5.
• Internet access from the initiator system to the Shared Shell server, optionally through a proxy server, to ports 80 and 443.

The systems of the participants joining the conference must meet the following requirements:

• JRE 1.4.2 or higher software installed with the Java Plug-In enabled. Links are provided on the Shared Shell launch page so participants can check their JRE installation or download a new version.
• A web browser, such as Microsoft Internet Explorer 6.x or Mozilla Firefox 1.5.
• Internet access from the participant system to the Shared Shell server ports 80 and 443, optionally through a proxy server.>

The target system must have Telnet or SSH enabled.

Back To Top

---

Information to Gather Before Using Shared Shell

Name Description Login If you are a Sun employee, your official email address and LDAP password If you are not a Sun employee, a Sun OnlineSM Account login and password Note: If you do not have a Sun Online Account or if you have forgotten your user name or password, go to https://reg.sun.com/register. Shell/Server connection Protocol that you will use for this session (Telnet or SSH). Host name or IP Address of the target system. If you are launching Shared Shell from the target system, type localhost in the address field. Port for the Telnet or SSH connection, if it is set to something other than the default (23 and 22, respectively). Proxy Some networks are configured so that you must use a proxy server to reach the Internet. If your network requires a proxy, you must gather the following information: Proxy type (HTTPS or SOCK5) Proxy server address Proxy port Proxy user name (if proxy authentication is required) Proxy user name (if proxy authentication is required)

 
Table 1: Required Information

Back To Top

---

Overview of the Shared Shell Interface

The Shared Shell window is divided into three panes as shown in Illustration 2:
Major Areas of the Shared Shell Window.

Illustration 2: Major Areas of the Shared Shell Window

• Terminal pane - Provides the interface to the shell running on the target system. It emulates a subset of the ANSI terminal standard or VT100 terminal. It supports the use of tools to point to or draw over the terminal content. The scrolling function of this pane is synchronized among all participants in the conference. Participants with Full or No-Exec access rights can type into the Terminal pane, but only those with Full access can execute UNIX commands. See Access Levels.
• Chat pane - Enables participants to send and receive text messages to one another without interfering with the terminal shell. This pane is divided into two frames. The top frame displays all chat messages received and sent. The bottom frame is the input area for new messages to be sent. Each sender is assigned a color. Messages in the top frame are displayed with the sender's name next to the color-coded message. Chat is not controlled by access levels. For each chat messages received, there is a beep sound alert.
• Participants pane - Displays all active participants in the order in which they joined the conference with their access level and assigned color.

Colors Used in the Interface

Participant input is color-coded. Your input as the initiator is displayed in black. Other participants are assigned a color based on the order in which they joined the conference. The colors are used in the following order: black, blue, red, green, purple and brown.

There is no limit to the number of Sun support engineers that can be invited. If more than five participants join a conference, the colors are recycled.

Resizing Panes

You can resize the Shared Shell window to change the size of the Chat pane and Participants pane. The Terminal pane remains the same size to maintain display consistency among participants.

Back To Top

---

Initiating a Conference Without a Proxy

This procedure covers logging in for Sun Shared Shell clients who do not require a proxy to reach the Internet. In this procedure, you are the initiator of the session. A likely scenario is that you contacted Sun for technical support and a technical support engineer is on the phone. The technical support engineer asks you to launch a Shared Shell session.

Logging in
To log in, perform the following steps:

1. From a web browser, go to: http://sun.com/sharedshell
2. Click the orange Launch button.
   The Shared Shell Login screen appears (Illustration 3).
   
   
   
   
3. Do one of the following:
   • If you are not a Sun employee, type your Sun Online Account user name and password.
   • If you are a Sun employee, type your official Sun email address and your LDAP password.
4. Make sure the Use Proxy box is deselected.

Initiating the Session

1. Answer the question "How do you want to use Shared Shell today?" by selecting option 1: Initiate a session & connect to target system.
2. Choose Telnet or SSH in the Protocol field, depending on how you plan to connect to the target system.
3. If you are making an SSH connection, type into the User Name field the user name you plan to use to log in to the target system.
4. Do one of the following:
   • If you are initiating this session from the target system, type localhost in the Host Name or IP Address field.
   • If the initiator system and the target system are different, type the IP address or the host name of the target machine.
5. If your target system runs Telnet (port 23) or SSH (port 22) on a standard port, leave the Port field blank or accept the default. If it uses a nonstandard port (typical of terminal servers or serial console concentrators), type the appropriate port.
6. Click Start or press 'Enter' button.
7. If you are making a Telnet connection, the Terminal pane appears. Type your login and password as you would for any other Telnet connection.
8. If you are making an SSH connection, you might be prompted with the target server key fingerprint and you might be prompted for the password to use for SSH authentication in a dialog box. If so, type your password.

When you get a shell prompt, see Inviting Participants.

Back To Top

---

Initiating a Conference With a Proxy

This procedure covers logging in for Shared Shell clients who require a proxy to reach the Internet. In this procedure, you are the initiator of the session. A likely scenario is that you contacted Sun for technical support and a technical support engineer is on the phone. The support engineer asks you to launch a Shared Shell session.

Logging in
To log in, perform the following steps:

1. From a web browser, go to: http://sun.com/sharedshell
2. Click the orange Launch button.
   The Shared Shell Login screen appears (Illustration 3).
   
3. Do one of the following:
   • If you are not a Sun employee, type your Sun Online Account user name and password.
   • If you are a Sun employee, type your official Sun email address and your LDAP password.
4. Make sure Use Proxy is selected.
5. Click the Configure button to supply the proxy information.

The Proxy Configuration dialog opens (Illustration 4).

Illustration 4 Proxy Configuration Dialog Entering Proxy Information
Make sure that you have gathered the proxy information, as explained in Table 1: Required Information .

1. Choose HTTPS or SOCK5 in the Proxy Type field
2. Type the proxy server address into the Proxy Server Address field.
3. Type the port number into the Proxy Port field.
4. If your proxy requires authentication, select the Proxy Requires Authentication check box, and complete the following two steps:
   • Type the proxy user name in the Proxy User Name field.
   • Type the password in the Proxy Password field.
5. You can optionally choose to have the system remember the proxy user name and password for future sessions by selecting the Remember Password check box.
6. If you want to test your proxy entries before initiating the session, click Test or if you want to return to the login screen without testing your proxy entries, click OK.

Initiating the Session

1. Answer the question "How do you want to use Shared Shell today?" by selecting option 1: Initiate a session & connect to target system.
2. Choose Telnet or SSH in the Protocol field, depending on how you plan to connect to the target system.
3. If you are making an SSH connection, type into the User Name field the user name you plan to use to log in to the target system.
4. Do one of the following:
   • If you are initiating this session from the target system, type localhost in the Host Name or IP Address field.
   • If the initiator system and the target system are different, type the IP address or the host name of the target machine.
5. If your target system runs Telnet (port 23) or SSH (port 22) on a standard port, leave the Port field blank or accept the default. If it uses a nonstandard port (typical of terminal servers or serial console concentrators), type the appropriate port.
6. Click Start or press 'Enter' button.
7. If you are making a Telnet connection, the Terminal pane appears. Type your login and password as you would for any other Telnet connection.
8. If you are making an SSH connection, you might be prompted with the target server key fingerprint and you might be prompted for the password to use for SSH authentication in a dialog box. If so, type your password.

When you get a shell prompt, see Inviting Participants.

Back To Top

---

Joining a Conference as a Participant

This procedure covers joining a conference as a participant. Illustration 3: Shared Shell Login Screen shows the login screen.

1. Complete the procedure in Logging in, remembering to select the Proxy check box if you must use a proxy to reach the Internet.
2. If you are using a proxy, complete the procedure in Entering Proxy Information.
3. Answer the question "How do you want to use Shared Shell today?" by selecting 2, Join an existing session as a viewer.
4. Enter the invitation key provided by the conference initiator.
5. Click Start or press 'Enter' button.
   If your connection is successful, a grayed-out Terminal pane and a status message about waiting for approval appears.
6. When the initiator approves your joining, you will see the Initiator information dialog. You can verify that is the intended customer and decide to continue with the session or end it.
7. If you continue, your Terminal pane becomes active and you see the list of other conference participants in the Participants pane.

   If you enter an invalid invitation key or if the initiator does not approve your joining, the Login/Splash screen reappears, and you should try joining again.

Back To Top

---

Inviting Participants

To invite a Sun support engineer or a coworker from your company, to join the conference:

1. Select Conference -> Invite.
   The Invite Participant window appears.
2. Contact a Sun support engineer outside of Shared Shell, such as by telephone or email, and provide the key displayed in the Invitation Key field.
   
   The Sun support engineer types the invitation key into the Shared Shell application.
3. When the Sun support engineer's name appears in the Waiting to Join box, click Allow.
4. You can use the same invitation key to invite additional participants. When a participant requests to join the session, the Invite Participant window will appear and you can Allow or Deny the request.
5. Note that the invitation key will expire after 2 hours.

Interacting With the Shell

The Terminal pane emulates a subset of the ANSI terminal standard (or VT100), allowing screen-based text editors, such as vi, to be used, as well as other utilities that perform cursor control and basic screen-editing functions defined in this specification.

Note: Text color is used in Shared Shell to identify the participant who last entered input to the shell. Color is not supported for other functions.

Each participant's Terminal pane processes the output of the shell running on the target system. This pane includes a scrollback buffer that allows reviewing of previous shell output. This scrolling function is synchronized among all participants so that they always see the same Terminal pane contents.

To type input to the shell running on the target system:

1. Verify that you have Full or No-Exec access, as indicated in the Access menu or for your user name in the Participants pane. See Access Levels.
2. Position your mouse cursor in the Terminal Pane and click the left mouse button to ensure this pane is active.
3. Type your input.
   Each character typed is sent to the shell running on the target system, and you will see the shell output echoed back in your Terminal pane.

Copying/Pasting Text

You can copy text or command lines from the Terminal pane into the system clipboard. Text in the system clipboard (whether copied from the Terminal pane or another application) can be pasted into the Terminal pane. Text pasted into the Terminal pane is input to the shell one character at a time, just as if you typed it. The ability to paste into the Terminal pane is controlled by your access level. Everyone can copy text from the Terminal pane, regardless of their access level.

Note: If a participant has Full access rights, carriage returns embedded in pasted text execute the preceding text as a command. If a participant has No-Exec access, carriage returns are stripped from the pasted text.

To copy text from the Terminal pane into the system clipboard:

1. Select the Pointer Tool from the toolbar or Tools menu.
2. Highlight the text to be copied (you can only copy text in the Terminal pane).
3. Choose Edit -> Copy or click the Copy toolbar button

To paste text from the system clipboard to the shell:

1. Click in the Terminal pane to ensure it is active.
2. Choose Edit -> Paste or click the Paste toolbar button.

Using the Terminal Mouse Tools

When your mouse cursor is in the Terminal pane, it is also shown in all other participants' Terminal panes, and it is identified by your color and name. The cursor shape reflects the current tool you have selected (Pointer, Marker, or Eraser). If your cursor remains motionless in this pane, it appears grayed-out because this causes less distraction to other participants.

Note: To reduce network traffic and improve performance, move your mouse cursor out of the Terminal pane or leave it motionless when you are not actively using one of the tools.

Pointer Tool

The Pointer Tool displays your mouse cursor as a pointer in every participant's Terminal pane. This enables you to visually indicate shell output text that you want other participants to notice. You can also use the Pointer Tool to select text to be copied to the clipboard. Highlighted text is not visible to other participants.

To use the Pointer Tool:

1. Select the Pointer Tool from the toolbar or from the Tools menu.
2. Move your mouse cursor within the Terminal pane.
   The mouse cursor's position and movement are displayed to all participants.

Marker Tool

The Marker Tool displays your mouse cursor as a pen in every participant's Terminal pane. With this tool selected, you can highlight text in the Terminal pane or draw upon it. Your markups, identified with your assigned color, are displayed to all participants

To use the Marker Tool:

1. Select the Marker Tool from the toolbar or from the Tools menu.
2. Move your mouse cursor within the Terminal pane to where you want to start a markup.
3. Hold the left button down while moving the mouse to draw a line. You can draw over text to highlight it. For best results, draw slowly.
4. When you have completed a line, release the left mouse button.

Eraser Tool

The Eraser Tool displays your mouse cursor as an eraser in every participant's Terminal pane. With this tool selected, you can erase markups in the Terminal pane that were previously drawn by yourself or other participants. When you erase your markups, or the markups of another participant, they are removed in all participants' Terminal panes.

To use the Eraser Tool:

1. Select the Eraser Tool from the toolbar or from the Tools menu.
2. Move your mouse cursor within the Terminal pane to where you want to begin erasing previously drawn markup lines.
   
   Note: You cannot erase shell output text
3. Hold the left button down while moving the mouse to erase a line. For best results, erase slowly.
4. When you have completed erasing, release the left mouse button

Erase All Tool

The Erase All Tool erases all the markup in the Terminal pane that were previously drawn by yourself or other participants. When you erase the markup using Erase all, they are removed in all participants' terminal panes.

To use the Erase All Tool:

1. Select the Erase All Tool from the toolbar or from the Tools menu. The selection of Erase All tool erases all the markups in the terminal pane.
   
   Note: You cannot erase shell output text

Sending Text Messages by Using the Chat Pane

The Chat pane allows participants to send text messages to one another without interfering with the shell. Chat messages are sent to all the participants in the Participants pane.

To send a chat message:

1. Type your message into the bottom frame of the Chat pane and press Enter or click Send.
2. Your message, in your assigned color and preceded by your name, appears in the upper frame of your Chat pane and in the Chat panes of all the participants.

Copying Text messages from Chat Pane.

You can copy the text messages from the Chat Pane into the system clipboard.

To copy a text message:

1. In the Chat Pane, select the desired text messages needs to be copied by using the mouse pointer.
2. Choose Edit -> Copy or click the Copy toolbar button or pressing CTRL+C.

Editing Preferences

You can edit preferences by using the Preference Editor. In some cases, you can input text and in other cases you must select from a drop-down menu.

To edit a preference:

1. Select Edit -> Preferences
2. Select one of the preferences from the drop-down menu.
   The Preference Level and description are displayed beneath the selected preference. See the description to determine if the change is immediate or is implemented the next time Shared Shell is started.
3. Enter a new value for the preference by performing one of the following actions:
   • Resetting the preference to its default value by selecting the top value in the Value drop-down menu.
   • Typing in a new value and pressing Enter (if the field is editable).
     If you enter an invalid value, an error message is displayed above the Apply and Close buttons.
   • Selecting a value from the Value drop-down menu.
4. Click Apply to accept your changes.

Setting Access Levels

Each participant has an assigned access level that determines the participant's ability to type input to the shell in the Terminal pane. Participant access levels are conference-specific and can be changed during the conference.

As initiator of a conference, you always have Full access, while other participants join with View access. You control the access level of other participants and can drop a participant from the conference at any time. Each participant's access level is displayed next to the participant's name in the Participants pane. Table 2 shows the access levels that are available:

Table 2

Access Level Icon Description Full access Enables the participant to type anything into the target system's shell through the Terminal pane and to execute commands on the target system. The conference initiator always has Full access. No-Exec access Enables the participant to type anything except carriage returns (which would execute a command) into the target system's shell through the Terminal pane. This restriction enables a participant with Full access to review the input before pressing Enter and executing a command. View access Restricts the participant to a view-only mode. The participant is not allowed to type into the shell. All participants, other than the initiator, join with View access.

 

The initiator can change another participant's access level at any time using the pop-up menu in the Participants pane. Other participants can send you a request for a change in access level by using the Access menu.

To change a participant's access, you must be the initiator:

1. Select the participant to change in the Participants pane.
   Note: You can change the access level of more than one participant at a time.
2. Click the right mouse button in the Participants pane.
   The pop-up menu appears.
3. Click the access level you want to assign to the selected participant

As a participant, to request a change in your access level:

From the Access menu, choose the new access level. If you are requesting a lower level of access, it is assigned immediately. Otherwise, a message is displayed stating that the request has been sent to the initiator. If the initiator approves the request, the new level is displayed in the Participants pane. If the request is denied, participant notified about that. Access level changes for any participant will be communicated as a chat message to all the participants of the conference.

Terminating a Participant

As the initiator, to remove a participant from the conference:

1. In the Participants pane, select the participant's name.
2. Click the right mouse button in the Participants pane.
   The Participant menu appears.
3. Click Terminate Participant(s).
   The participant's name no longer appears in the Participants pane.

Transferring Files

Shared Shell enables participants to transfer files as long as the participants at both the source and destination agree. Multiple file transfers can occur at the same time. Once initiated, file transfers are performed in the background and do not interfere with other functionality.

Please note: There must be at least one participant in the conference before you can transfer a file. If there are no other participants, File Transfer option is grayed-out.

You have two types of file transfer options available:

1. Transfer a file to/from the Initiator's local system and a participant's system.
2. Transfer a file to/from the Initiator's target system and participant's system.
   (Note that this requires that the Initiator selected ssh to connect to the target system. File transfer to/from the target system is not support ed via telnet connections.)

Here's how to request a file transfer:

1. Open the Request File Transfer window
   Click the File Transfer toolbar button, or select Conference -> File Transfer from the menu. The Request File Transfer window appears:
   
   
2. Select the file transfer direction
   Click one of the arrows between the Remote System and Local System boxes.
   
   

Note:In the Remote System box, you may select either the Participant or the Target System - that is, the location of where you want to transfer a file to or from.

3. Select the file to be transferred
   • If you are transferring a file to/from the remote system, type the full path name of the file to download or upload in the Remote System box.
   • If you are transferring a file to/from your local system, you can transfer the file using either My Files (the local system box) or Target System in the Local System box. You can browse or type the full path of the file. The Browse button will be enabled only when you selected My Files option.
     Notes:
     
     • The Target System cannot be chosen simultaneously at both the 'remote' and 'local' boxes.
     • The My Files and Target System options will be available only to the Initiator file transfer window and not for participants.
       For more information about the target system refer to the Terminology section.


4. Transfer the file
• Verify that the information is correct, and click the Send Request button.
  • The file information and permissions are checked for both sides of the transfer. The remote participant is prompted to Allow or Deny the transfer.
  • If the remote participant approves the transfer, a dialog box appears that displays the file transfer progress for both participants. The dialog box also contains a Cancel button to cancel the file transfer at any time.
    
    
• When the transfer is complete, the progress window is replaced with a window that displays transfer statistics.
• For each new file transfer initiated, an automatic notification message sent through Chat to all the participants of that conference about this file transfer. It contains the file transfer information of source, destination, filename and size.

Note: The size of transmitted blocks (in bytes), and the interval between sending blocks, is controlled by system-level preferences. The FileXferXmitInterval value defines the time, in milliseconds, before a file block is transmitted. Changing the transfer speed can affect the performance of shell input and output and other functions.

Leaving or Terminating a Conference

Participants other than the initiator can leave a conference at any time by choosing Conference -> Leave.

Note: If the conference initiator leaves the conference by choosing Conference -> Leave or by closing the Shared Shell window, the conference is automatically terminated, and the shell receives a hang-up (HUP) signal, killing any processes that are running under it.

The preferred method of closing a conference is for the initiator to log out of the shell in the Terminal pane. Shared Shell detects that the shell connection is closed and terminates the conference, notifying active participants of the action before their window closes.

Pinging the Target System

To obtain information on network delays, select Tools -> Ping Target System.

A window appears displaying round-trip message times to the Shared Shell server and to the target system. On the target system, round-trip times to the target system are shorter because they are routed internally, instead of going through a server.

Back To Top

---

Log Files

Shared Shell generates logs on the target system and at Sun for shell output, chat messages, file transfer information, and general conference events (such as participants joining and leaving).

Three log files are created for each conference, where Date is the date the conference was created (in the form YYYYMMDD)and ConferenceID is the identifier assigned to this conference by the server:

• shsh_Date_ConferenceID_conf.log
  Contains general conference information in XML format, such as start time, end time, and records for each participant joining or leaving the conference.
• shsh_Date_ConferenceID_chat.log
  Contains chat messages in XML format.
• shsh_Date_ConferenceID_shell.log
  Contains raw shell output in text format.

On the target system, logs are stored in a location controlled by a user-level preference (LogDir), with a reasonable default location chosen based on the platform where Shared Shell was launched:

• If Shared Shell is launched on a Microsoft Windows system, the default location is something like C:\Documents and Settings\User Name\Sun Shared Shell\logs (the initial part of the path depends on system settings and locale, and it is based on the Windows HOMEDRIVE and HOMEDIR settings).
• If Shared Shell is launched on a Mac OS X system (not officially supported), the default location is something like $HOME/Library/Application Support/Sun Shared Shell/logs.
• On other systems, such as on Solaris platforms or Linux, the default location is $HOME/SunSharedShell/logs.

Changes to the LogDir preference take effect the next time Shared Shell is launched.

"Communication Delayed" indicator

If the Initiator is sending continuous terminal output, there could be some latency at participant side in seeing the output due to network traffic or server performance. When this occurs, a "Communication Delayed" indicator will be displayed on the Initiator:

1. A "Communication Delayed" button appears at the bottom of the Initiator window.





2. Click the button "Communication Delayed" to display the list of participants and their communication status.
   -The status will be "Normal" if there is no delay for that participant.
   -The status will be "Delayed" if there exists a delay for that participant.





3. The Initiator should inform the affected participant(s) about the communication delay.
   (Or, the Initiator may choose to stop sending continuous output.)
4. If Initiator continues the session with the delay, the Initiator terminal output will be stopped temporarily after some time, using the SSH flow control protocol. This is done to avoid more data being queued up at the server side for that participant and to avoid data loss.
5. Once the queue is cleared on the server, the initiator SSH terminal automatically resumes with the terminal execution.
Back To Top

---