-C H A P T E R

C H A P T E R 3

SMS DR User Interfaces

The dynamic reconfiguration (DR) feature supports a single point of control, the Sun Fire high-end server system controller (SC), which runs the system management services (SMS) software. However, DR also supports administration control from the domain. This chapter describes the DR interfaces on the SC. For information about using cfgadm(1M) to run DR on the domain, refer to the Sun Fire 15K/12K Dynamic Reconfiguration User Guide.

SMS DR Commands and Options

This section contains descriptions of the SMS DR commands and related options. For more information about each SMS DR command, refer to the System Management Services (SMS) 1.4 Reference Manual.

`addboard`(1M)

The addboard(1M) command attaches a specific board to a specific domain. Refer to the section Adding Boards, and to the addboard(1M) man page, for more information.

The following table describes the addboard(1M) command options and operands:

Options and Operands	Specifies
board_id	The board ID of the board to be added. The board ID corresponds to the board location (for example, SB2 is the board in slot 2). Multiple board identifiers are permitted.
`-c` function	The configuration state into which to move the board. You can add a board by steps. For example, you can assign the board, connect it, then configure it.
`-d` domain_id \| domain_tag	Identifies the target domain.
`-f`	Forces the specified action to occur. Typically, this is a hardware-specific override of a safety feature. Forcing a state change operation can allow use of the hardware resources of an occupant that is not in the `ok` or `unknown` conditions, at the discretion of any hardware-dependent safety checks.
`-h`	Help, which displays the usage description
`-n`	No to all prompts
`-q`	Quiet mode, which means messages are not written to standard output
`-r` retry_count	The number of retries that are performed if the operation fails
`-t` timeout	Wait time in seconds between retries
`-y`	Yes to all prompts

The following table contains the privileges needed to use the addboard(1M) command. The platform operator, platform service, and superuser groups cannot initiate the addboard(1M) command.

Platform Admin	Domain Admin	Domain Configurator
Can assign boards to a domain by using the `-c` option with the `assign` function.	Can connect or configure a board into the domain if the board has been assigned to the domain, or if it appears in the available component list for the domain and is not assigned to another domain.	Can connect or configure a board into the domain if the board has been assigned to the domain, or if it appears in the available component list for the domain and is not assigned to another domain.

The following example of the addboard(1M) command attaches system board 2 (SB2) to the domain specified by domain_id. Two retries are performed, if necessary, with a wait time of 10 minutes (600 seconds) between retries.

% addboard -d domain_id -r 2 -t 600 SB2

Note - If the addboard(1M) command fails during a DR operation, the board does not return to its original state. A dxs or dca error message is logged to the domain. If the error is recoverable, you can retry the command. If the error is unrecoverable, you will need to reboot the domain to use the board.

`deleteboard`(1M)

The deleteboard(1M) command attempts to detach a specified board from the domain in which it currently resides. Refer to the section Deleting Boards, and to the deleteboard(1M) man page, for more information.

The following table describes the deleteboard(1M) command options and operands:

Options and Operands	Specifies
board_id	The board ID of the board to be deleted. The board ID corresponds to the board location (for example, SB2 is the system board in slot 2). Multiple board identifiers are permitted.
`-c` function	The configuration state into which to move the board. You can delete a board by steps. For example, you can unconfigure the board, disconnect it, and then unassign it.
`-f`	Forces the specified action to occur. Typically, this is a hardware-specific override of a safety feature. Forcing a state change operation can allow use of the hardware resources of an occupant that is not in the `ok` or `unknown` conditions, at the discretion of any hardware-dependent safety checks.
`-h`	Help, which displays the usage description
`-n`	No to all prompts
`-q`	Quiet mode, which means messages are not written to standard output.
`-r` retry_count	Number of retries that are performed if the detach fails
`-t` timeout	Wait time in seconds before a retry
`-y`	Yes to all prompts

The following table contains the privileges needed to use the deleteboard(1M) command. The platform operator, platform service, and superuser groups cannot initiate the deleteboard(1M) command.

Platform Admin	Domain Admin	Domain Configurator
Can unassign boards that are not active in a domain by using the `-c` option with the `unassign` function. If the user also has domain privileges, `deleteboard` also unconfigures and disconnects the board before it unassigns it.	Can unconfigure, disconnect or unassign a board from the domain. The board can be unassigned from the domain only if it appears in the available component list.	Can unconfigure, disconnect or unassign a board from the domain. The board can be unassigned from the domain only if it appears in the available component list.

The following example of the deleteboard(1M) command detaches system board 2 (SB2) from its current domain. Two retries are performed, if necessary, with a wait time of 15 minutes (900 seconds) between retries.

% deleteboard -r 2 -t 900 SB2

Note - If the deleteboard(1M) command fails during a DR operation, the board does not return to its original state. A dxs or dca error message is logged to the domain. If the error is recoverable, you can retry the command. If the error is unrecoverable, you will need to reboot the domain to use the board.

`moveboard`(1M)

The moveboard(1M) command detaches a board from the domain in which it currently resides and attaches it to a specified domain. Refer to the section Moving Boards, and to the moveboard(1M) man page, for more information.

The following table describes the moveboard(1M) command options and operands:

Options and Operands	Specifies
board_id	The board ID of the board to be moved. The board ID corresponds to the board location (for example, SB2 is the system board in slot 2). Multiple board identifiers are permitted.
`-c` function	The configuration state into which to move the board. You can move a board by steps. For example, you can assign the board, connect it, and then configure it.
`-d` domain_id \| domain_tag	Identifies the target domain.
`-f`	Forces the specified action to occur. Typically, this is a hardware-specific override of a safety feature. Forcing a state change operation can allow use of the hardware resources of an occupant that is not in the `ok` or `unknown` conditions, at the discretion of any hardware-dependent safety checks.
`-h`	Help, which displays the usage description
`-n`	No to all prompts
`-q`	Quiet mode, which means messages are not written to standard output
`-r` retry_count	Number of retries that are performed if the operation fails
`-t` timeout	Wait time in seconds before a retry
`-y`	Yes to all prompts

The following table contains the privileges needed to use the moveboard(1M) command. The platform operator, platform service, and superuser groups cannot initiate the moveboard(1M) command.

Platform Admin	Domain Admin	Domain Configurator
Can re-assign boards from one domain to another domain by using the `-c` option with the `assign` function. The board cannot be active in the domain from which it is being re-assigned.	Can assign, connect, or configure a board that is in another domain. If the board is active in another domain, the `moveboard` command unconfigures and disconnects the board from that domain. The board must be in the available component list in order to unassign and re-assign it using `moveboard`. The `moveboard` command can connect and configure the board. The domain administrator must have domain privileges for both domains to use the `moveboard`(1M) command.	Can assign, connect, or configure a board that is in another domain. If the board is active in another domain, the `moveboard` command unconfigures and disconnects the board from that domain. The board must be in the available component list in order to unassign and re-assign it using `moveboard`. The `moveboard` command can connect and configure the board. The domain configurator must have domain privileges for both domains to use the `moveboard`(1M) command.

Platform Admin

Domain Admin

Domain Configurator

Can re-assign boards from one domain to another domain by using the -c option with the assign function. The board cannot be active in the domain from which it is being re-assigned.

Can assign, connect, or configure a board that is in another domain. If the board is active in another domain, the moveboard command unconfigures and disconnects the board from that domain. The board must be in the available component list in order to unassign and re-assign it using moveboard. The moveboard command can connect and configure the board.

The domain administrator must have domain privileges for both domains to use the moveboard(1M) command.

The domain configurator must have domain privileges for both domains to use the moveboard(1M) command.

The following example of the moveboard(1M) command moves system board 5 (SB5) from its current domain to the domain specified by domain_id. Two retries are performed, if necessary, with a wait time of 15 minutes (900 seconds) between retries.

% moveboard -d domain_id -r 2 -t 900 SB5

Note - If the moveboard(1M) command fails during a DR operation, the board does not return to its original state. A dxs or dca error message is logged to the domain. If the error is recoverable, you can retry the command. If the error is unrecoverable, you will need to reboot the domain to use the board.

`rcfgadm`(1M)

The rcfgadm(1M) command provides remote configuration administration operations on dynamically reconfigurable hardware resources. The rcfgadm(1M) command performs configuration administration on attachment points, which are device nodes in the device tree.

The following table describes the rcfgadm(1M) command options and operands.

Options and Operands	Specifies
`-a`	The `-a` option lists dynamic attachment points.
`-c` function	The configuration state into which to move the board. You can disconnect, connect, configure, or unconfigure a board.
`-d` domain_id \| domain_tag	Identifies the target domain.
`-f`	The specified action to be forced to occur
`-h` ap_id \| ap_type	Help message text to be printed. If ap_id or ap_type is given, the command displays the hardware specific help for the attachment point.
`-l` ap_id \| ap_type	State and condition of attachment points to be listed
`-n`	No to all prompts
`-o` hardware_options	Hardware specific options
`-r` retry_count	Number of times to retry the DR operation
`-s` listing_options	Options to list
`-T` timeout	Wait time in seconds between retries
`-t`	A test on one or more attachment points
`-v`	Specifies verbose mode.
`-x` hardware_function	Hardware specific functions
`-y`	Yes to all prompts

Refer to the rcfgadm(1M) man page for more information and examples of how to use this command.

The following table contains the privileges needed to use the rcfgadm(1M) command. The platform operator, platform service, and superuser groups cannot initiate the rcfgadm(1M) command.

Platform Admin	Domain Admin	Domain Configurator
Can assign boards to, or unassign boards them from, a domain by using the `-x` option with the `assign` or `unassign` function, respectively. To use the `unassign` function, the board must be assigned and cannot be active in a running domain.	Can disconnect, connect, configure, or unconfigure a board to or from the domain. Can assign or unassign a board if the board is in the domain's available component list.	Can disconnect, connect, configure, or unconfigure a board to or from the domain. Can assign or unassign a board if the board is in the domain's available component list.

Note - If the rcfgadm(1M) command fails during a DR operation, the board does not return to its original state. A dxs or dca error message is logged to the domain. If the error is recoverable, you can retry the command. If the error is unrecoverable, you will need to reboot the domain to use the board.

`scdrhelp`(1M)

The scdrhelp(1M) shell script starts the Sun Fire high-end server dynamic reconfiguration errors help system. The help system uses the JavaHelp trademark hsviewer script.

All of the user privileges groups can use this command, except for the domain administrator and the domain configurator.

Refer to the section Error Message Help System and to the scdrhelp(1M) man page for more information about this script.

`showboards`(1M)

The showboards(1M) command displays the assignment information and status of system boards in a domain; and indicates whether a board is a Capacity On Demand (COD) board. Refer to the section Showing Board Information, and to the showboards(1M) man page, for more information.

Although the showboards(1M) command is not DR-specific, it should be used in conjunction with the DR commands. The following table describes the showboards(1M) command options.

Option	Specifies
`-d` domain_id \| domain_tag	Identifies the target domain.
`-h`	Help, which displays the usage description
`-v`	Verbose mode. Displays all components, including domain configuration units (DCUs). DCUs include CPU, MCPU, hPCI, hsPCI+, and wPCI components. Displays the SC as well.

All of the user privileges groups can use this command; however, the domain administrator and the domain configurator can show boards only in the domains for which they have privileges.

`showdevices`(1M)

The showdevices(1M) command displays the configured physical devices on system boards and the resources that are made available by these devices. Although the showdevices(1M) command is not DR-specific, it should be used in conjunction with DR commands. Refer to the section Showing Device Information, and to the showdevices(1M) man page, for more information.

The usage information is provided by applications and subsystems that are actively managing system resources. The predicted impact of a system board DR operation can be displayed by performing an offline query of managed resources.

The following table describes the showdevices(1M) command options and operands.

Options and Operands	Specifies
board_id	The board ID of the board to be added. The board ID corresponds to the board location (for example, SB2 is the system board in slot 2). Multiple board identifiers are permitted.
`-d` domain_id \| domain_tag	Identifies the target domain.
`-h`	Help, which displays the usage description
`-p` reports	Offline query information
`-v`	All I/O devices

Only the domain administrator and the domain configurator can show device information in the domains for which they have privileges.

`showplatform`(1M)

The showplatform(1M) command shows the available component list, the domain state for each domain, and Capacity on Demand (COD) information. Although the showplatform(1M) command is not DR-specific, it should be used in conjunction with the DR commands. Refer to the section Showing Platform Information, and to the showplatform(1M) man page, for more information.

The following table describes the showplatform(1M) command options and operands.

Options and Operands	Specifies
`-d` domain_id \| domain_tag	The target domain name
`-h`	Help, which displays the usage description
-p domains \| available ethernet \| cod	Displays reports that are grouped by: domain state (`domains`); domain available component list (`availabl`e), domain ethernet addresses (`ethernet`); or Capacity On Demand (COD) information (`COD`).
`-v`	All available command information

All of the user privileges groups, except for the platform service and superuser groups, can use this command; however, the domain administrator and the domain configurator can show the platform information only in the domains for which they have privileges.

Error Message Help System

The SMS software contains an error message help system that you can use to find a description and recovery procedure for a specific error message.

To start the DR error message help system, enter the following command:

% /opt/SUNWSMS/jh/scdrhelp &

The standard JavaHelp system viewer, hsviewer, displays the DR error messages help system. The viewer consists of a toolbar and two panes: the content pane and the navigation pane, as shown in FIGURE 3-1.

FIGURE 3-1 hsviewer GUI Components

JavaHelp Table of Contents

The DR error messages are separated into logical groups according to the type of errors, as shown in FIGURE 3-1. These groups represent the major topics that appear as the top level headings in the table of contents. Error message numbers and/or abbreviated text appear under their respective group name.

JavaHelp Index

The DR error messages are indexed so that key topics are represented in the Index display (FIGURE 3-2). Some index topics are embedded when that embedding is deemed appropriate. For these topics, only the embedded topics are links to error messages.

FIGURE 3-2 JavaHelp Index Display

JavaHelp Search

The DR error messages help system provides a full-text search function. The search database is constructed by indexing the error message help files.

Before you search for a specific error message, first search on a specific string of text in the error message. Also avoid using numeric values because they are treated as replaceable text. The error JavaHelp system window is shown below:

FIGURE 3-3 JavaHelp Search Display

SMS DR Commands and Options

addboard(1M)

deleteboard(1M)

moveboard(1M)

rcfgadm(1M)

scdrhelp(1M)

showboards(1M)

showdevices(1M)

showplatform(1M)