# Chapter 5

# Using the `rscadm` Utility

> The `rscadm` utility and its subcommands allow administration of Sun Remote System Control (RSC) from the host. You must log in to the server as root to use `rscadm`.

> Installation places the `rscadm` utility in the following directory:

> `/usr/platform/`platform-name`/rsc/`

> You can obtain the string to use for platform-name using the Solaris command
> `uname -i`. For example:

>     % uname -i
>     SUNW,Sun-Fire-280R

> Set your path to the `rscadm` utility so that you can use the command `rscadm`.

> Most `rscadm` subcommands are also available using the RSC command shell, but `rscadm` is convenient for:

- Reconfiguring RSC when account passwords are unknown
- Resetting RSC when it fails to respond
- Backing up configuration data
- Downloading RSC firmware
- Synchronizing RSC date and time to the server's date and time

> Note - You cannot use the `rscadm` utility, and you should not use RSC software, while SunVTS diagnostics are running.

> The `rscadm` utility uses the following subcommands.

> TABLE 5-1 `rscadm` Subcommands
> Subcommand | Description
> `help` | Displays a list of `rscadm` commands and brief descriptions for each
> `date` | Displays or sets the current time and date
> `set` | Sets a configuration variable
> `show` | Displays one or more configuration variables
> `shownetwork` | Shows current RSC card network configuration
> `loghistory` | Returns the most recent log entries
> `resetrsc` | Resets RSC immediately
> `download` | Downloads firmware to the RSC flash PROM
> `send_event` | Logs an event; can also send an alert message
> `modem_setup` | Changes configuration of the RSC modem
> `useradd` | Adds an RSC user account
> `userdel` | Deletes an RSC user account
> `usershow` | Shows characteristics of an RSC user account
> `userpassword` | Sets or changes a user's password
> `userperm` | Sets the authorization for a user
> `version` | Reports the RSC version on the host
> `status` | Same as the `version -v` command.

> Note - On Sun Enterprise 250 servers, the `rscadm` subcommands `shownetwork, loghistory`, and `version` are not available.

## `rscadm` Subcommands

### `help`

> This subcommand prints out a basic Help message including a list of `rscadm` subcommands and a short description of each.

### `date [-s]
date [[mmdd]HHMM|mmddHHMM[cc]yy][.SS]`

> Use the `date` subcommand to show the current date and time. Use the `-s` option to synchronize RSC time to the server time. Supply a date with the subcommand to set RSC time to a time other than the server time.

> See "date [[mmdd]HHMM|mmddHHMM[cc]yy][.SS]" for a description of date formats.

### `set` variable-value

> Use the `set` subcommand to set an RSC configuration variable. See "RSC Configuration Variables" for descriptions of these variables.

> You can use the null string ("") to set a variable to null. To set a variable to a string that includes spaces or UNIX shell special characters, enclose the string in double quotes. For example:

> `#` `rscadm set page_info2 ""`
> `#` `rscadm set page_init1 "&F &E0"`

### `show [`variable`]`

> Use the `show` subcommand to display the value of one or more RSC configuration variables. If you do not specify a variable, RSC displays all configuration variables. See "RSC Configuration Variables" for descriptions of these variables.

### `shownetwork`

> The `shownetwork` subcommand displays the current network configuration.
> For example:

>     # shownetwork
>     RSC network configuration is:
>     IP Address: 129.149.2.6
>     Gateway Address: 129.149.2.7, 129.149.2.8
>     Netmask: 255.255.255.0
>     #

> Note - The `rscadm` subcommand `shownetwork` is not available on Sun Enterprise 250 servers.

### `loghistory`

> Use the `loghistory` subcommand to display the history of all events logged in the RSC event buffer. These events include server reset events and all RSC commands that change the state of the system. This will return the log entries in reverse order, with the newest messages first.

> Note - The `rscadm` subcommand `loghistory` is not available on Sun Enterprise 250 servers.

### `resetrsc [-s]`

> This subcommand resets RSC immediately. To terminate all connections cleanly before the reset, use the `-s` option. If no argument is supplied, this subcommand performs a hard reset and drops all connections.

> Note - When you reset RSC on a Sun Enterprise 250 server without also resetting the server, RSC time defaults to 1/1/70. To synchronize RSC time with server time, reset the server, use the `rscadm` command `rscadm date -s`, or run the script `/usr/platform/`platform-name`/rsc/rsc-initscript`. You can obtain the string to use for platform-name using the Solaris command `uname -i`.

### `download [boot]` file

> This subcommand supports downloading new firmware residing in file into RSC. If you specify `boot`, the contents of file will be installed in the boot section of RSC non-volatile memory. If you do not specify `boot`, the contents of file will be installed in the main firmware section of RSC non-volatile memory.

> When the transfer completes, RSC resets itself. If the host keyswitch is in the Lock position, you cannot update RSC firmware, and an error message displays.

### `send_event [-c]` message

> Use this subcommand to enter an event into the RSC event log. Use the `-c` option to also send an alert message that RSC forwards according to the alert configuration. The message is an ASCII string of no more than 80 characters. To use a string that includes spaces or UNIX shell special characters, enclose the string in double quotes.

> See Appendix C for an example of a Perl script that uses this subcommand to send an alert.

### `modem_setup`

> Use this subcommand to change configuration of the RSC modem (or for Sun Enterprise 250 servers, the configuration of the modem connected to the RSC serial port). You can enter standard attention (AT) commands and see responses from the modem. At the beginning of a line, enter the escape character followed by a period to exit from this subcommand. By default, the escape character is tilde (~). For example:

> # rscadm modem_setup
> AT <enter>
> OK
> ~.
> #

> The escape character for `modem_setup` is the same as the escape character used for the RSC shell `console` command, which is set using the `escape_char` configuration variable. See escape_char.

> Note - For Sun Enterprise 250 servers, the escape sequence for `rscadm modem_setup` is always `~.` (a tilde followed by a period). The RSC console has a configurable exit character, but the escape character for `rscadm modem_setup` is fixed.

### `version`

> Reports the RSC version on the host (not available on Sun Enterprise 250 servers). An example of output returned by this command is:

>     # rscadm version
>     RSC version v2.0.0
>     RSC Bootmon v2.0.0
>     RSC Main v2.0.0
>     RSC POST status = 0XFFFF

> This command also has a `-v` switch. Using`-v` provides more information about RSC, as shown in the following example:

>     # rscadm -v version
>     RSC Version v2.2
>     RSC Bootmon Version: v2.0.0
>     RSC Bootmon checksum: 3688AD82

>     RSC Firmware Version: v2.2.0
>     RSC Build Release: 20

>     RSC firmware checksum: 00A000A0

>     RSC firmware built: Sep 14 2001, 14:40:38

>     RSC System Memory Size 8 MB

>     RSC NVRAM Version = 4

>     RSC hardware type: 3

### `status`

> Same as the `version -v` command; available on all supported servers.

### User Account Administration Subcommands

> To administer user accounts from the host using `rscadm`, log in to the host as root and use the `rscadm` utility with the following subcommands:

- `useradd` (see "useradd username" )
- `userdel` (see "userdel username")
- `usershow` (see "usershow [username]" )
- `userpassword` (see "userpassword username")
- `userperm` (see "userperm username [a][u][c][r]" )

## `rscadm` Error Messages

> This section offers further explanation of error messages received from the `rscadm` utility. The last 12 messages are usage error messages.

    Passwords didn't match, try again

During execution of the `userpassword` subcommand, you enter the password twice. If passwords do not match, you are prompted to enter them again.

    rscadm: all user slots are full

This error occurs if you try to add a user account when RSC already has the maximum number of accounts configured. RSC supports only 16 user accounts (4 on the Sun Enterprise 250 servers). You must delete an account before you can add another.

    rscadm: command line too long

Check for an extremely long command line.

    rscadm: command unknown

You used an invalid `rscadm` subcommand.

    rscadm: could not connect to modem

During execution of the `modem_setup` subcommand, RSC could not connect to the RSC modem. Perhaps the modem is not connected or is currently being used by the paging subsystem.

    rscadm: could not disconnect from modem

During execution of the `modem_setup` subcommand, RSC refused to disconnect from the modem.

    rscadm: could not read date from RSC

An undefined error in RSC firmware occurred when trying to get the RSC date.

    rscadm: could not send alert

During execution of the `send_event` subcommand, RSC firmware could not send an event.

    rscadm: could not set date on RSC

RSC detected an internal error while trying to set the date.

    rscadm: couldn't add user

RSC encountered an internal error when trying to add a user account. The RSC SEEPROM may be faulty.

    rscadm: couldn't change password

RSC encountered an internal error when trying to change a user password. The RSC SEEPROM may be faulty.

    rscadm: couldn't change permissions

RSC encountered an internal error when trying to change user permissions. The RSC SEEPROM may be faulty.

    rscadm: couldn't create thread

During execution of the `modem_setup` subcommand, a thread create call failed.

    rscadm: couldn't delete user

RSC encountered an internal error when trying to delete a user account. The RSC SEEPROM may be faulty.

    rscadm: couldn't get information on user

RSC encountered an internal error when trying to access user information during a `usershow` subcommand. The RSC SEEPROM may be faulty.

    rscadm: download failed, RSC reported erase error

During execution of the `download` subcommand, RSC reported a hardware problem when trying to program the RSC EEPROM.

    rscadm: download failed, RSC reported int_wp error

During execution of the `download` subcommand, RSC reported a hardware problem when trying to program the RSC EEPROM.

    rscadm: download failed, RSC reported range error

During execution of the `download` subcommand, RSC reported a hardware problem when trying to program the RSC EEPROM.

    rscadm: download failed, RSC reported verify error

During execution of the `download` subcommand, RSC reported a hardware problem when trying to program the RSC EEPROM.

    rscadm: download failed, RSC reported vpp error

During execution of the `download` subcommand, RSC reported a hardware problem when trying to program the RSC EEPROM.

    rscadm: download failed, RSC reported wp error

During execution of the `download` subcommand, RSC reported a hardware problem when trying to program the RSC EEPROM.

    rscadm: download rejected, keyswitch in secure mode?

You cannot execute the `download` subcommand when the server keyswitch is in the Lock position.

    rscadm: either the RSC hardware was not detected or a lock file
    was found. Only one instance of rscadm can run at a given time.

As stated.

    rscadm: Error downloading file

An internal error occurred during execution of the `download` subcommand.

    rscadm: ERROR, callback init failed

An internal error occurred during execution of the `download` subcommand.

    rscadm: ERROR, passwords didn't match

During execution of the `userpassword` subcommand, you enter the password twice. If passwords do not match, you are prompted to enter them again. If they do not match again, the subcommand fails.

    rscadm: ERROR, unable to set up message queue

An internal error occurred during execution of the `download` subcommand.

    rscadm: event message can't exceed 80 characters

The message for the `send_event` subcommand cannot exceed 80 characters.

    rscadm: file could not be opened

During execution of the `download` subcommand, the `rscadm` utility could not open the file specified on the command line.

    rscadm: file not a valid s-record

During execution of the `download` subcommand, the file to download is not a valid s-record file.

    rscadm: INTERNAL ERROR in set date

This is an internal `rscadm` software error.

    rscadm: INTERNAL ERROR, overflow in callback

An internal error occurred during execution of the `download` subcommand.

    rscadm: invalid variable

During execution of the `set` subcommand, you entered an invalid variable. See RSC Configuration Variables for correct values.

    rscadm: invalid variable or value

During execution of the `set` subcommand, you entered an invalid variable or value. See RSC Configuration Variables for correct values.

    rscadm: malformed password

You entered an invalid password. A valid password has between six and eight characters, at least two of which are alphabetic characters, and at least one of which is a numeric or special character.

    rscadm: malformed username

You entered invalid characters in a username.

    rscadm: maximum username length is - 16

The username you entered exceeded 16 characters; the maximum length for a username is 16 characters ( for Sun Enterprise 250 servers, maximum length is eight characters).

    rscadm: RSC did not respond during boot initialization

An internal error occurred during execution of the `download` subcommand.

    rscadm: RSC failed to respond during download

During execution of the `download` subcommand, RSC did not enter boot mode correctly.

    rscadm: RSC firmware not responding

RSC main firmware is not responding. Perhaps RSC is booting, main firmware is corrupt, or RSC has a hardware problem.

    rscadm: RSC not responding to requests

The response expected from RSC was not sent. Check that RSC is working.

    rscadm: RSC returned fatal error

During execution of the `download` subcommand, RSC returned an undocumented error.

    rscadm: RSC returned garbage

This error can occur in various situations; as stated.

    rscadm: RSC returned unknown error

During execution of the `download` subcommand, RSC returned undocumented status (neither success nor failure).

    rscadm: RSC returned wrong response

RSC returned an invalid response during a `user*` subcommand. This is considered an internal error in RSC or `rscadm`.

    rscadm: RSC unable to free up memory

This message can occur in various situations. The `rscadm` utility was unable to free the received message from the RSC firmware.

    rscadm: Unable to reset RSC hardware

During execution of the `resetrsc` subcommand, an attempt to hard reset RSC failed.

    rscadm: unable to send data to RSC

RSC did not acknowledge data sent to it. Check that RSC is working.

    rscadm: Unable to send modem data to RSC

RSC did not acknowledge data sent to it. Check that RSC is working.

    rscadm: user already exists

The user you are trying to add already has an RSC account on this server.

    rscadm: username did not start with letter or did not contain
    lowercase letter

You used an invalid username format when trying to add an RSC user account.

    rscadm: username does not exist

The username you specified is not associated with an RSC account on this server.

    This program MUST be run as root

As stated.

    USAGE: rscadm <command> [options]

For a list of subcommands, type `rscadm help`.

    USAGE: rscadm date [-s] | [[mmdd]HHMM | mmddHHMM[yyyy]][.SS]

Date parameters have the following ranges:

- 01 <= mm <= 12
- 01 <= dd <= 31
- 01 <= HH <= 23
- 00 <= MM <= 59
- 19 70 <= ccyy <= 2038

    USAGE: rscadm download [boot] <file>

    USAGE: rscadm loghistory

    USAGE: rscadm resetrsc [-s]

    USAGE: rscadm send_event [-c] "message"

    USAGE: rscadm set <variable> <value>

    USAGE: rscadm show [variable]

    USAGE: rscadm shownetwork

    USAGE: rscadm useradd <username>

    USAGE: rscadm userdel <username>

    USAGE: rscadm userpassword <username>

    USAGE: rscadm userperm <username> [cuar]

    USAGE: rscadm usershow [username]

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.