C H A P T E R 4 - Further Management Information

C H A P T E R 4

Further Management Information

Configuring Scripting Capabilities

A system administrator can log in to the Service Processor (SP) using secure shell (SSH) and issue commands, or more commonly, write a shell script that remotely invokes these operations.

Note - You must create a valid initial manager account before using SSH. The SP includes a setup account that can be used to set up an initial manager account. This initial manager user can create additional users.

The SP includes a suite of commands that enables management and monitoring of the server; this suite of commands is referred to as server management commands. From the command line, for instance, you can write data driven scripts that automate configuration of multiple machines.

The Sun Fire V20z and Sun Fire V40z Servers Network Share Volume CD contains sample scripts for getting started, which you can access after you extract the files on the CD. See Network Share Volume (NSV) CD-ROM for more information about the script locations.

Using Shell Scripts

An administrator can make configuration changes for a single SP by using SSH to log in and run commands. For a multi-system environment in which configurations for all SPs must be synchronized, you can automate configuration changes.

As a Unix/Linux administrator, you can use SSH, trusted-host relationships or public-key authentication, and Unix/Linux shell scripting to automate tasks that need to be performed on multiple SPs.

1. Set up your system for scripting.

Sun Fire V20z and Sun Fire V40z remote scripting solutions depend on SSH for authentication and data encryption. If you do not already have SSH, you can obtain a free implementation, OpenSSH, available at www.openssh.org. The SP allows the use of SSH v2 only. Refer to Remote Scripting Using SSH.

2. Create a trusted-host relationship or add your public key for SSH authentication.

In order to use SSH in a scripted environment such that you are not prompted for a password upon the execution of each command, you can establish a trusted-host relationship between the machine from which the commands are sent and the SP on which the commands are executed. (This requires the prior creation of a manager-level user on the SP.) Refer to Creating Trusted-Host Relationships.

You can also add a public key for SSH authentication, allowing you to log in via SSH and execute remote commands without being prompted for a password. Refer to Adding Public Keys.

3. Configure your client for scripting.

You must configure the client machine on which you will be running scripts.

4. Create your scripts.

Remote Scripting Using SSH

Remote scripting to the SP is done by using a program called SSH. For example, as a user on the UNIX machine client.company.com with the SP name sp.company.com, you could execute a command on the SP from the UNIX client using the following format:

# ssh sp.company.com command

Because the SSH server must authenticate the remote user, the user must either enter a password, or a trusted-host relationship must exist, or the remote user's public key must be installed on the SP.

If using trusted-host relationships for passwordless access, the SP must have a local user of the same name as the remote user (or the remote user should be a member of a directory service group that is mapped to a local SP administrative group).

You can also add your public key file instead of creating a trusted-host relationship to be authenticated via SSH. Refer to Adding Public Keys.

When configured for passwordless access, the ssh daemon on the SP allows the remote user access to sp.company.com without a password, either for logging in, or for issuing remote ssh commands from the command line or from a script.

Configuring Multiple Systems for Scripting

There are two ways to configure multiple SPs for scripting:

Execute the procedure to configure the client machine on which you will be running scripts for each SP.

Set up the trust relationship or add your public key file on an initial machine and use the autoconfiguration feature to duplicate the configuration on each of the additional machines. Refer to Creating Trusted-Host Relationships and Adding Public Keys.

Generating Host Keys

To establish a trusted-host relationship, you must set up a host key which is used to authenticate one host to another. The host's SSH install should generate the host keys. If it does not, follow these steps to generate a host-key pair:

1. Enter the following command:

# ssh-keygen -q -t rsa -f rsa_key -C '' -N ''

2. Move rsa_key to /etc/ssh/ssh_host_rsa_key.

3. Move rsa_key.pub to /etc/ssh/ssh_host_rsa_key.pub.

4. Ensure that only the root user has read or write permissions to /etc/ssh/ssh_host_rsa_key.

The ssh_host_rsa_key.pub file is the file you will transfer to the SP.

Note - Only protocol version 2 key types and 1024-bit key sizes (the default generated by ssh-keygen) are supported.

5. Continue with Creating Trusted-Host Relationships for instructions on creating public keys that can be used for passwordless access.

Note - Use scp to copy the files to either /tmp or to your home directory. The sp commands will then install the file specified on the command line.

Creating Trusted-Host Relationships

Adding a trusted-host relationship is one way to allow for passwordless access and thus is a means for one-to-many scripting. Once a host-equivalence relationship has been created with a client, users on that client can remotely execute commands on the Service Processor without being prompted for a password, provided one of the following conditions is met:

The user's login name on the client is the same as that of a local user on the SP.

The user's login on the client belongs to a directory service group that is mapped to an SP administrative group. (In this case, the SSH command executes as a well-known auxiliary user on the SP: either rmonitor, radmin or rmanager.)

Note - Support is available for SSH protocol version 2 key types (RSA or DSA) only. If DNS is enabled on the SP, the client machine must be specified with its DNS name, not an IP address.

Manager-level users can create a trusted-host relationship for the specified host from the command line using the access add trust command:

# access add trust {-c | --client} HOST {-k | --keyfile} \PUBLIC KEY FILE

Adding Public Keys

Adding a user's public key is another way to allow for passwordless access and thus provide one-to-many scripting. Once a public key for a specific user has been installed on the SP, that user can remotely execute commands on the SP without being prompted for a password, if that user has installed the associated private key on the client.

Note - Support is available for SSH protocol version 2 key types (RSA or DSA) only.

Only local users can add public keys. Users who obtain authorization from directory services group mappings are not able to add public keys.

Local admin-level or manager-level users can add public keys using the access add public key command:

# access add public key -l PUBLIC_KEY_FILE [-u user]

The public-key file is your RSA or DSA key. Up to 10 users can install public keys; only one key per user is allowed.

Admin-level users can only add their own public key. Manager-level users can add a public key for any local user. If the user is not specified in the command, the current user is the default.

Note - The maximum supported key length is 4096 bits.

Generating a Host-Key Pair

To establish a trusted-host relationship, you must set up a host key, which is used to authenticate one host to another. Follow these steps to generate a host-key pair by copying the public key to the SP to which you want passwordless access:

1. Execute the following command:

# ssh-keygen -t rsa -N

2. Accept the default values, installing to the following directory:

$HOME/.ssh/id_rsa

The following files are created:

$HOME/.ssh/id_rsa $HOME/.ssh/id_rsa.pub

Enabling SSH Access Using Trusted-Hosts

Follow these steps to add users to the local /etc/password file to attempt trusted-host access to the Service Processor:

1. Set up your host keys by executing the following command:

# ssh-host-config

2. Enable access for clients by launching a Bash shell.

If you want all network accounts added, execute mkpasswd >> /etc/passwd.

If you want just local accounts added, execute mkpasswd -l >> /etc/passwd.

3. Issue the following commands as a manager-level user on the client to establish a trusted-host relationship (manager1 is used in the example in this step):

a. Copy the client key to /tmp on the SP.

# scp /etc/ssh_host_dsa_key.pub manager1@sp.test.com:/tmp

b. Authenticate yourself for the scp command by entering the password for your manager-level user.

c. Add the client key to the set of trusted hosts for this SP.

# ssh sp.test.com access add trust -c client.test.com -k \/tmp/ssh_host_dsa_key.pub

d. Authenticate yourself for the ssh command.

From this point, any user with the same login on both sp.test.com and client.test.com has access without requiring a password to the like-named account on sp.test.com.

4. Create or modify the file /etc/ssh_config to ensure it contains the following entry:

Host * HostbasedAuthentication yes

Enabling SSH Access Using Public Keys

Follow these steps to install public keys to enable SSH access.

1. Set up your host keys. Refer to Generating a Host-Key Pair.

2. Install your public key using the access add public key command.

3. Run the following command:

# ssh-keygen -t rsa -N

This command generates ~/.ssh/id_dsa and ~/.ssh/id_dsa.pub.

4. Run the following command:

# scp ~/.ssh/id_rsa.pub SP_IP:/tmp

Enter your password when prompted.

5. Run the following command:

# ssh SP_IP access add public key -k /tmp/id_rsa.pub

Enter your password when prompted.

6. Run the following command:

# ssh SP_IP rm -f /tmp/id_rsa.pub

From this point, you have access without requiring a password.

Guidelines for Writing Server Management Command Scripts

This section describes some basic guidelines for managing your systems by writing scripts for remote execution on one or more SPs.

Shell Scripts: You should be familiar with standard shell scripting. Refer to Using Shell Scripts.

SSH: You must currently use an SSH (Secure Shell) client to execute automated command scripts. Refer to Remote Scripting Using SSH.

Authentication: To avoid being prompted each time you run a script on an SP, upload a public key or trusted-host key to each SP. Refer to Creating Trusted-Host Relationships and Adding Public Keys.

Authorization Levels: Access changes (such as adding users or uploading keys) typically requires manager-level access while most other management tasks can be performed by an administrator level user.

Return Codes: Every subcommand returns a return code upon completion.

Nowait Argument: Most commands complete their execution fairly quickly and are therefore performed synchronously. For some longer operations (such as rebooting the platform), a --nowait option is provided so that a script can initiate the operation without waiting for it to return.

Quiet Argument: The delete and update operations (such as access delete user, sp delete event) accept multiple targets. To ensure a certain set of targets is deleted on a set of SPs, you can use the --quiet argument to suppress errors if one of the targets is not found, or to suppress interactive warning messages from the platform command.

Command Output

The following list defines common general output:

Commands that complete successfully return 0 with no success return string. Some exceptions are commands that also return vital information.

Table output, interactive warnings and any other non-error messages are directed to standard output.

Commands that return errors display the return codes and a descriptive error string.

Following are common characteristics of table output from a get command:

Heading columns are provided by default for output with more than one column.

Single column output does not include a heading.

To suppress headings, use the -H argument.

Data for each column is left-aligned with at least one space between columns. Numeric data might be right-aligned.

The -D argument allows you to specify a delimiter character when scripting. This is very useful in parsing fields with white space.

If all lines have the same number and type of data values, each row is printed to a separate line so variable data can be parsed easily. For example, executing access get users -g monitor returns a list of monitor users each on a separate line.

Commands that return multiple columns (such as inventory get hardware) may have a minimal default set of columns and a --verbose argument to display all columns. Some commands include arguments that allow you to select specific columns to output.

Other Tips For Best Results

Externalize the set of SP IP addresses into a file to be shared across all of your scripts.

Consider using a script to create the initial manager account and upload its public key on your SPs.

Test the output and return codes of each command manually by using SSH to log in to the SP and run the commands individually.

Test your scripts on a single staging machine before applying them to your remaining machines.

To configure all of your SPs identically, consider configuring a single SP and then using the sp load settings command to synchronize that configuration on the remaining machines.

Note - If running the script from the SP, there is a limited number of commands (not a full bash environment).

Console Redirection Over Serial

Redirecting the console interaction over the serial port allows the user another method to monitor the server.

The BIOS redirects console output to serial by default (9600, 8N1, no handshake).

This section describes how to configure these options for both Linux- and Solaris-based servers.

Linux-based Server

Caution - Redirecting the console over serial is a procedure intended for advanced users of Linux only.

You can seriously disrupt the proper functioning of the server or render the server unbootable if you introduce a problem in the configuration files.

The goal of these configurations is to configure the bootloader to redirect its output, pass the kernel the proper parameters and configure a login session on the serial port.

The BIOS redirects console output to serial by default (9600, 8N1, no handshake) until a bootloader program is run from the hard disk drive. The bootloader must be configured to support the serial console in addition to the keyboard, video and mouse (KVM) console.

Two common bootloaders are grub and Linux Loader (LILO).

Caution - Do not edit the working-image section of your configuration files directly.

Copy the working-image section and paste it within the configuration file. Make your editing changes to this copied section.

grub

If you use grub, there are three steps to enable console redirection over serial; these steps all involve editing the grub configuration file:

If you are using Red Hat Linux, the grub file is /etc/grub.conf.

If you are using SUSE Linux, the grub file is /boot/grub/menu.1st.

Note - On Red Hat Linux systems, the file /etc/grub.conf might be a symbolic link to the file /boot/grub/grub.conf.

1. Pass the proper console parameters to the kernel.

2. Configure the grub menu system to redirect to the proper console.

3. Remove any splash images that would prevent the proper serial-console display.

For more information on the parameters, refer to the file kernel-parameters.txt in your kernel documentation.

For more information on grub, run the command info grub.

Note - If the arrow keys do not work through your remote serial concentrator, you can use the keystroke combinations of <CTRL+P> and <CTRL+N> to highlight the Previous and Next entry, respectively. Pressing Enter then boots that entry.

The parameter console=ttyS0 tells the system to send the data to the serial port first. The parameter console=tty0 tells the system to send the data to the KVM second.

A working-image section in your grub configuration file should have an entry for the kernel image to boot. The stock kernel entry looks like:

kernel /vmlinuz-kernel_revision ro root=/dev/sda5

where kernel_revision is simply the kernel version that you are using.

1. Change the stock kernel entry of your image to include the console-kernel parameters, as follows:

kernel /vmlinuz-kernel_revision ro root=/dev/sda5 console=ttyS0,9600 console=tty0

Note - These options should all be on one line with no wrap to a second line.

2. Add the following two lines to the top of your grub configuration file:

serial --unit=0 --speed=9600

terminal serial console

Adding these two lines at the beginning of the file sets up your serial port or your KVM as your grub console so that you can remotely or locally select a boot image from the grub menu.

3. Comment out or remove the following line from your grub configuration file:

splashimage=(hd0,1)/boot/grub/splash.xpm.gz

Removing the splashimage line allows for greater compatibility during your serial connection; with this line removed, the splash image does not prevent the proper grub menu from displaying.

LILO

Note - When you enable the BIOS option "Console Redirection After POST", and LILO is used as a bootloader, the system may hang with an "L" printed on the screen.

This issue arises because there is not enough lower memory available to load the second-stage boot file that LILO uses. If you turn off the option "Console Redirection After POST" in the BIOS, the system will boot normally. See Enabling and Disabling BIOS Console Redirection.

If you require the option "Console Redirection after POST", use grub or upgrade to a newer version of LILO. The current version of LILO is 22.5.9; to access the the LILO pages, visit http://lilo.go.dyndns.org/ and click on the link.

Before you upgrade, we recommend that you verify with your OS vendor that they support the updated version of LILO.

Passing proper parameters to kernel

LILO uses the append feature in an image section in order to pass to the kernel the proper parameters for using the serial console.

1. In the file /etc/lilo.conf on your Sun Fire V20z or V40z server, enter the consoles in the append statement:

append="console=ttyS0,9600 console=tty0"

2. After modifying the file /etc/lilo.conf, run lilo from the command line to activate the change.

For more information on LILO, run the commands man lilo or man lilo.conf.

getty

You can run a service called getty to enable login on the serial interface.

To enable getty, append the following line to the list of gettys in the /etc/inittab file:

7:12345:respawn:/sbin/agetty 9600 ttyS0

Note - It does not matter where you append this line in the list.

Note - Make certain that the first number is unique within the inittab file.

The list of gettys currently looks like the following:

# Run gettys in standard runlevels

1:2345:respawn:/sbin/mingetty tty1

2:2345:respawn:/sbin/mingetty tty2

3:2345:respawn:/sbin/mingetty tty3

4:2345:respawn:/sbin/mingetty tty4

5:2345:respawn:/sbin/mingetty tty5

6:2345:respawn:/sbin/mingetty tty6

securetty

To add the serial-console device /dev/ttyS0 to the file /etc/securetty, run the following command:

# echo ttyS0 >> /etc/securetty

Solaris-based Server

Caution - Redirecting the console over serial is a procedure intended for advanced users of Solaris only.

You can seriously disrupt the proper functioning of the server or render the server unbootable if you introduce a problem in the bootenv.rcfile.

Note - The default setting for the output device is screen and for the input device is keyboard.

To change the settings

To enable Console Redirection over Serial on a Solaris-based server:

In a terminal window, run the eeprom command to change the settings for the output and input devices, as shown here.

eeprom output-device=ttya

eeprom input-device=ttya

To verify the settings

To verify that the changes were made:

1. In a terminal window, run the eeprom command with no arguments.

The contents of the bootenv.rc file display in the terminal window.

2. Locate the following lines and verify that they display the correct values.

output-device=ttya

input-device=ttya

To reset to the default settings

To reset the system to the default settings:

To reset the output and input devices to the default settings, run the eeprom command with the following arguments.

eeprom output-device=screen

eeprom input-device=keyboard

Enabling and Disabling BIOS Console Redirection

Note - Console redirection is enabled by default in the BIOS.

If the default settings have been changed in the BIOS, the following procedure explains how to change the console-redirection settings.

1. Boot or reboot the server.

2. When prompted, press <F2> to enter BIOS setup.

3. Select the Advanced menu from the category selections along the top.

4. Select Console Redirection.

Note - Make note of all settings in this menu, as they are required for configuring the remote-console access and the Serial-Over-LAN (SOL) feature.

To disable Console Redirection to Serial, select Disabled from the Com Port Address option.

To change the baud rate, select the desired bit rate from the Baud Rate option.

To disable Continue C.R. after POST, toggle the setting to OFF.

5. Save the changes to the BIOS settings.

6. Press <F10> to exit the BIOS setup.

For the new settings to take effect, you must reboot the server.

Network Share Volume (NSV) CD-ROM

A network share volume (NSV) structure is included with the server on the Sun Fire V20z and Sun Fire V40z Servers Network Share Volume CD.

Although the SP functions normally without access to an external file system, a file system is required to enable several features, including event log files, software updates, diagnostics and the troubleshooting dump utility. You can configure the NSV to be shared among multiple SPs. Admin- and manager-level users can configure the external file system; regular users can only view the current configuration.

The following software components are included with the server:

Platform BIOS

SP base software

SP value-add software

Update file for downloading Java Runtime Environment (JRE) packages

Network share volume software, which includes diagnostics

Platform software

Motherboard platform drivers

All of these software packages are packaged with the NSV and are installed on the file server when the external file system is installed and configured.

For instructions on extracting and installing the NSV software, refer to the Sun Fire V20z and Sun Fire V40z Servers Installation Guide.

Network Share Volume Structure

The following compressed packages are included with your server on the Sun Fire V20z and Sun Fire V40z Servers Network Share Volume CD:

TABLE 4-1 Network Share Volume Compressed Packages
File Name	File Contents
`nsv_V2.1.0.`x`.zip`	Service processor software
`nsv-redhat_V2.1.0.`x`.zip`	Drivers for Red Hat Linux OS
nsv-solaris9_V2.1.0.x.zip	Drivers for Solaris 9 OS
`nsv-suse_V2.1.0.`x`.zip`	Drivers for SUSE Linux OS

When extracted, the compressed packages in TABLE 4-1 populate the following files on the NSV:

/mnt/nsv/ diags logs scripts snmp spupdate sw_images (this folder appears after you extract one of the OS-specific Zip files)

TABLE 4-2 Extracted Files on the Network Share Volume
File Name	Description
`diags`	Offline location of the server diagnostics.
`logs`	Offline location of the log files for the SP.
scripts	Sample scripts that can be used for scripting commands.
`snmp`	SNMP MIBS. Refer to Chapter 3 for details.
`spupdate`	The server for updating the SP. Refer to Chapter 1 for details.
`sw_images`	Contains a directory hierarchy of platform and SP components, including subdirectories for each version.

Serial Over LAN

The Serial Over LAN (SOL) feature lets servers transparently redirect the serial character stream from the baseboard Universal Asynchronous Receiver/Transmitter (UART) to and from the remote-client system over LAN. Serial over LAN has the following benefits compared to a serial interface:

Eliminates the need for a serial concentrator.

Reduces the amount of cabling.

Allows remote management of servers without video, mouse or keyboard (headless servers).

Serial over LAN requires a properly configured LAN connection and a console from which an ssh session can be established.

In a Linux environment, you can use a shell such as csh or ksh as your console. This console works well in a scripting environment in which you might want to monitor many servers.

Enabling or Disabling the SOL Feature on the Server

Note - When the SOL feature is enabled, you cannot access the server through the external DB9 serial port (COM A).

Note - The variable spuser is the user account created when securing the SP. The variable spipaddr is the IP address assigned to the SP.

For more information, see Initial Setup of the Service Processor.

You can enable or disable the SOL feature through the SP.

Enabling the SOL feature

To enable the feature, run the following command:

# ssh -l spuser spipaddr platform set console -s sp -e -S 9600

Note - Ensure that the baud rate value passed to the -S argument matches the speed that was specified for the serial-redirection feature of the BIOS and the speed used for your boot loader and OS configuration.

The default baud rate in the BIOS settings is 9600.

Disabling the SOL feature

To disable the feature, run the following command:

# ssh -l spuser spipaddr platform set console -s platform

Launching an SOL Session

To launch an SOL session, run the following command:

# ssh spipaddr -l spuser platform console

Terminating an SOL Session

To terminate an SOL session:

1. Press Control-e.

2. Press the `c' key.

3. Press the period key (.).

You can also terminate an SOL session by terminating the ssh session:

1. Press Enter.

1. Press the tilde key (~).

2. Press the period key (.).

Escape Sequences for Remote Console Terminal

If you are accessing your server using a remote console terminal, you might need to use the escape sequences shown in TABLE 4-3. If a regular function key is not working properly, use the escape sequence listed next to it in the table.

You will most likely need to use the escape sequences if you are using a Linux or Solaris OS.

TABLE 4-3 Special Keys for Remote Console Terminal
Function Key	Escape Sequence
HOME	<ESC> h
END	<ESC> k
INSERT	<ESC> +
DELETE	<ESC> -
PAGE UP	<ESC> ?
PAGE DOWN	<ESC> /
ALT	<ESC>^A
CTRL	<ESC>^C
F1	<ESC> 1
F2	<ESC> 2
F3	<ESC> 3
F4	<ESC> 4
F5	<ESC> 5
F6	<ESC> 6
F7	<ESC> 7
F8	<ESC> 8
F9	<ESC> 9
F10	<ESC> 0
F11	<ESC> !
F12	<ESC> @