Tips for Configurator Interactive Sessions

Tips on using the configurator user interface.

When a user invokes cfgset in auto or interactive mode to create or update a config set, cfgset invokes the configurator to initiate an interactive session with the user. The configurator provides command help to aid users in navigating the tool and adding/updating configuration data. These tips supplement that help.

Know the difference between the two "interactive" modes

Interactive mode and auto mode can both result in a configurator interactive session, but their uses and behaviors are quite different.

auto mode

Helpful for verifying that all desired settings have been set.

Auto mode initiates an interactive session when there are one or more settings in the config set that meet state and level filtering criteria. Those settings are presented one at a time, and when all have been presented, the configurator exits the session.

interactive mode

Helpful for seeing the "big picture" and having more control over which services/settings are presented for configuration.

Interactive mode always initiates an interactive session. It provides two tiers of menus from which users can select one or more services/settings to drill down and configure just what is needed. The configurator presents the selected settings one at a time, as in auto mode, but when all selected settings have been presented, it returns the user to the menu from which the selection was made.

Service Configuration List Menu (or Service List Menu) lists the services in the config set
Service Configuration Menu (or service menu) lists the settings in a particular service

Filter wisely

Level and state filters determine what the configurator displays to users: what is included in the menu of services/settings for selection in interactive mode, and what setting fields are presented automatically for configuration in auto mode. The filters can be specified on the command line when invoking cfgset, and they can be changed in interactive mode. If not specified, they default to level basic and state unset (exception: for interactive mode, if a single service is specified, the default state is all).

In interactive mode, the configurator populates the Service List Menu with only those services that meet state and level filtering criteria; both filters can be switched to different values on this menu screen. In the case of a service menu, the configurator populates it with only those setting fields that meet level filtering criteria (shows all states); level can be switched on this menu screen, but state cannot. Just for fun, cycle through all levels/states, noting how level affects which services appear in the list, while state affects the status displayed for each service.

Tip: If the desired service/setting is not visible in an interactive-mode menu, simply switch level.

In auto mode, the configurator presents only those setting fields that meet state and level filtering criteria. There is no opportunity to switch filter values in auto mode, except by first switching to interactive mode.

Tip: A good way to confirm that all basic settings have been set is to run cfgset update p0 (where p0 is the config set name), which defaults to auto mode, level basic, and state unset. If the configurator does not present any settings, it means that no basic or required settings are unset.

How to switch states and levels (interactive mode only):

switch states: Enter s at the configurator prompt to switch from the current state to the next one: unset→set→all. To see all services/settings with the specified level, enter s until state=all displays in the menu header.
switch levels: Enter l (lowercase L) at the configurator prompt to switch from the current level to the next one: basic→advanced→required. To view all services/settings with the specified state, enter l until level=advanced displays in the menu header.

To see all possible services/settings, switch to state=all and level=advanced.

Get familiar with menus in interactive mode

The Service List Menu and all service menus have the same three-section layout: a list of services/settings, actions the user can take, and a prompt.

Figure: Sections of Interactive-Mode Menus

list

The menu name, config set name, and config set type are shown at the top of the list section. This section is helpful for seeing which services still have unconfigured settings (status column—see what changes when state is switched) and for selecting which service(s) to configure or reconfigure.

In a service menu, the list items are configuration settings for that particular service, filtered by level only (state is set to all and cannot be switched). This list is helpful for seeing the current state and value of the settings and for selecting which setting(s) to set or change.

actions

These three submenus show all commands currently available. Always use an action from the Select Options submenu before using any from the Actions on Selected submenu. Items in the Other Actions submenu can be used at any time (with the obvious exceptions of the exit commands Q and x, because when one of those is used, the configurator exits the interactive session).

Select Options: Actions that select one or more services/settings from the list. The selected services/settings are the only ones that can be acted upon. Once selected, an asterisk appears in the Selected column next to the item and its font color changes.
Actions on Selected: Actions that can be used on the selected service(s) or setting(s); a selection must be made first. Shows in parentheses how many items have been selected. A few of these actions, like toggle whether a service is enabled and toggle whether it inherits setting values from the global version of its template (applies to only a few services) move to the Other Actions submenu on service menu screens.
Other Actions: Actions that can be used on all services/settings or on the current configurator session. The most commonly used are the filter switches and help (?).

prompt

The prompt shows which menu is active and what the default action is. Before a selection is made, the default action is to save and exit (as shown in previous figure). When a selection is made, the default action is to configure the selected service(s) or setting(s), and the prompt changes to

MENU_NAME [default: configure – C] $

Note that accepting this default action (or entering C) displays the configuration setting screen for the first selected setting.

Get familiar with configuration setting screens

A configuration setting screen shows users information about the setting field to be configured (default/current values, data type, level, current state, etc.) and enables the user to navigate among setting fields, enter/change field values, and switch to interactive mode. The configuration setting screen is displayed when a user makes a selection and enters C in interactive mode, or when a setting matches state and level filters in auto mode. Configuration setting screens have a prompt that is packed with useful information. Consider this example of a prompt:

cray_auth.settings.access.data.policy
[<cr>=set 6 entries, +=add an entry, ?=help, @=less] $

The first line is the full name of the setting field being presented (this is the same as the corresponding entry in the configuration worksheet for this service). The part that precedes .settings. is the service name (cray_auth, the Cray Authentication service, in the example), and the part that follows is the setting field being presented. In the example, the setting is access and the field to be set (one of several for that setting) is policy.

The second line lists available commands. In the example, the default command (selected by pressing Enter or <cr>) sets the value to 6 entries, which is the default value provided in the configuration template for that service. If this setting field had already been configured with the value 6 entries, the default command would be <cr>=keep '6 entries', (set becomes keep). This list of available commands is not exhaustive: to see all possible options, enter ? after the prompt, which will insert a context-sensitive menu of commands between the information section and the prompt.

Switch to interactive mode, as needed

When in a configuration setting screen, whether the user has arrived there by invoking cfgset in auto mode or by making a selection and entering C in interactive mode, it is possible to switch to interactive mode and display either the service menu (lists settings for a single service) or the Service List Menu (lists services in the config set).

switch from setting screen to a service menu

To switch to interactive mode and display the service menu, enter ^ at the configurator prompt. Example:

cray_node_health.enabled
[<cr>=keep 'true', <new value>, ?=help, @=less] $ ^

switch from setting screen to Service List Menu

To switch to interactive mode and display the Service List Menu, enter ^^ at the configurator prompt. This action can be taken only if cfgset was invoked for all services (as this is the default, this is true unless the --service or -s option was used). Example:

cray_node_health.enabled
[<cr>=keep 'true', <new value>, ?=help, @=less] $ ^^

Switch between menus in interactive mode, as needed

switch from Service List Menu to service menu

When a service has been selected from the Service List Menu in interactive mode, enter v (view settings) to switch to the selected service's menu instead of taking the default action of Configure (C). The v action is available if only a single service is selected. If multiple services are selected, C is the only action available. Example:

Service List Menu [default: configure - C] $ v

switch from service menu to Service List Menu

To switch from a service menu to the Service List Menu, enter ^^ at the configurator prompt. This action can be taken only if cfgset was invoked for all services (as this is the default, this is true unless the --service or -s option was used). Example:

Node Health Service Menu [default: save & exit - Q] $ ^^

When in doubt, jump out

It is better to leave a setting field unconfigured than set it to an incorrect value or 'none.' If unsure what the value should be or whether that setting field is needed, jump out using one of these methods:

Switch to interactive mode.
Skip to the next setting field: enter > at the configurator prompt.

Get help early and often

Enter ? at the configurator prompt at any time to see a list of available commands. In interactive mode, this simply displays a verbose list of the same commands listed in the menu's three action submenus. However, in a configuration setting screen, entering ? displays a context-sensitive menu of available commands not displayed elsewhere. Here is an example of the commands available in the context of configuring a multival setting in a service (multival settings are configured by adding/changing entries). Use the ? command in configuration setting screens early and often to learn the available commands.

|--- Command Help
|  *    ++    - double view limit (currently 2)
|  *    --    - decrease view limit by half (currently 2)
|  *    *     - view all entries (no limit)
|  *    +     - add entries
|  *    <#>*  - change the <#> entry. Example: '2b*' selects sub-item b in entry 2 to change
|  *    <#>-  - delete the <#> entry. Example: '4-' deletes entry 4
|  *    d     - delete all entries in the list
|  *    <cr>  - accept the current value(s)
|  *    #     - set the value to its default
|  *    <     - go back to the previous setting
|  *    >     - skip and go to the next setting
|  *    ^     - Go to the 'cray_dvs' service menu (interactive mode)
|  *    ^^    - Go to the service list menu (interactive mode)
|  *    Q     - write out changes and exit the configurator
|  *    x     - revert all changes and exit the configurator
|  *    r     - refresh the screen
|  *    @     - toggle more/less info
|  *    ?     - show this help