Extending SMIT For Common Localized Tasks

Introduction

In large Unix environments it is popular to extend the operating system with various forms of "local-ware" that provide a means for administrators to accomplish a set of common tasks with speed and consistency. One of the target audiences for these scripts and binaries is typically someone who is either more junior / operational or more familiar with another Unix. In either case the operator may not be intimately familiar with all the available locally written tools and options for those tools.

The creators of AIX have provided the SMIT interface as a simplified method to interact with less frequently used commands. SMIT provides a way for administrators not familiar with a command to validate input, prevent missing an important flag, or simply find the command they are looking for.

It is possible to extend SMIT to provide the same benefits for local-ware. In the case of locally written applications it may be of even more value as the scripts written in house are not part of the common Unix lexicon. The SMIT interface not only provides a helper for all command line options, but also provides an index / menu for the commands themselves.

SMIT is designed to provide many of the features required for administrative tasks such as logging, the option to log only (and capture commands for later execution), and ACL controls for individual SMIT screens.1 Why not extend that functionality to the tools written in house?

Writing A SMIT Application

The scope of this paper is not the content of the local-ware portion, but in constructing the SMIT interface to an existing local-ware repository, creating smit screens for 3rd party products, or just re-organizing some typically unrelated functionality to a common SMIT menu.

In this example I will create an alternate SMIT menu system for the fictional ACME Enterprises IT organization that has the need to provide a SMIT interface for a mixture of OS and locally written commands to both junior administrators (operations) as well as administrators of other Unices.

While this project is not really an application, it does have many of the version control, distribution, packaging, and debugging issues found in application development. I will need to synchronize our SMIT screens with the local-ware repository that ACME keeps in /opt/aeadmin/bin. The distribution method will need to be upgradeable without breaking existing SMIT objects or corrupting the ODM. Finally I want to reduce the need to document local-ware and simplify the process of what we do document.

Creating SMIT screens

Each SMIT screen is defined by one or more ODM objects. There are four types of SMIT-specific ODM objects that, when combined, define three different SMIT screens. The relationship is as follows:

SMIT ODM objects used in this document are defined in the stanza / odmadd format and inserted into the ODM using the odmadd command. The examples I have provided are broken into individual "files" based upon their increasing complexity. There is no technical reason they could not be in a single file and added as a single group.

The odmadd stanza format begins with a header that consists with an ODM object type followed by a colon. The following lines consist of descriptor names and values assigned to those descriptors. In a database analogy, the table name is the ODM object type, the columns are the descriptors, and the rows are each ODM object inserted.

Extending the SMIT Top Menu

The first task for this application is to create a task / application specific menu of commands as well as several entry points. The menu should be self-explanatory but the concept of multiple entry points may not be so obvious. The goal is to have the new menu accessible via the SMIT top menu (the one you see by default when starting SMIT), and two fast paths (aeadmin and ae).

The sm_menu_opt object defined in the following file (ODM Object 1) will provide the first requirement by modifying the "top" menu in the SMIT menu tree.

The sm_menu_opt defined in ODM Object 1 will appear in the top menu because it shares an id with all other items in that menu. In this case the top menu items have an ID of "top_menu". The id_seq_num has been set to "210" to (sort) order its entry in the menu listing (near the bottom of the menu - because of the numbering scheme IBM has used for this menu).

The next_id descriptor is where this menu item will point to. It defines the SMIT screen (ODM object) to go to when this item is selected. I have specified that the next item is also a menu by setting a value of "m" in the next_type descriptor.

I set help_msg_loc to "aeadmin" so that I can later uniquely identify my SMIT ODM object from others. Technically this descriptor defines the string I pass to man to get help for this item but I am cheating by using this as a unique identifier to tell my items apart from IBM supplied items. (I will un-cheat later by creating and installing a common man page for this application.) The inclusion of this item will become more relevant later in this document when I discuss version control and deployment of the application.

The NLS (National Language Support)2 items text_msg_file, text_msg_set, and text_msg_id define where to get NLS items if I chose to internationalize this "application" I will not be using these items because the scope of this modification is only for the local IT group and does not require internationalization.

In the screenshot, labeled SMIT Screen 1, is the resulting SMIT menu from running smitty (or smit in a text environment3). As you can see, my new menu item showed up third from the bottom in the menu list.

The ACME Administration Menu

The next task is to define the menu items and additional fast paths to the proposed ACME Administration (aeadmin) menu. If I were to choose the ACME Admin menu now, having only created the menu pointer, SMIT would produce an error because the actual menu has not been created. In the next ODM definitions listed in ODM Object 2 I first define a single menu item for the menu to point to an existing SMIT fast path. Here the menu item is the same as before except I am defining the object with a id descriptor of the menu.

Additionally, the second object in the ODM Object 2 listing creates an additional alias that can be used as a fast path to the menu. Here I associate the ae string with the aeadmin menu.

I do not need to define the name of the menu screen as that information is derived from the pointer item in the previous menu as well as the text set in the alias object.4

The first sm_menu_opt object should look much like the one I defined in ODM Object 1 with a few exceptions. One key difference is that I am now in a new menu so the id matches all other object IDs that belong to that menu. The next key difference is that the next_id points to an object that is an already defined SMIT (menu) object for the Logical Volume Manager. Note that the lvm object exists at this point so this menu is a working submenu item.

The second sm_menu_opt object is an alias for a SMIT fast path. Here I am defining an additional fast path to get directly to this new menu. I set the id descriptor to the preferred alias (fast path) name. I set the next_id and text descriptors to point to the menu. Users can use the aeadmin fast path (same as the id descriptor) or now use just ae.

As with all our modifications, these objects do not use NLS support, and set help_msg_loc to my unique standard string "aeadmin" that will allow me to locate all my objects later.

The resulting screen, seen in the SMIT Screen 2 screen capture, is now available from the SMIT top menu link, the aeadmin and ae fast paths.

The choice of Logical Volume Manager as a menu item demonstrates that I could create a custom SMIT menu of only existing items using known fast paths. This is not as effective as creating my own content, so I will begin to insert local-ware screens in the next section.

Creating A Command / Dialog

In order to front a command I will need to utilize at least one sm_cmd_hdr / Dialog object, even if the user does not interact with it.5 In this example we will suspend belief for a moment and pretend that the local IT staff wrote the ls command, and that I need to write a SMIT dialog for it.

The basic steps for this task will be to first create a new menu item in the aeadmin menu, then create a dialog screen that will accept user input. The dialog screen needs to provide a relevant default value and validate the user input based upon requirements that we define.

To create this SMIT dialog I will need to define at least one of each of the following: sm_menu_opt, sm_cmd_hdr, and sm_cmd_opt. These objects are defined in the ODM Object 3 listing that follows.

In the sm_menu_opt object, defined in the ODM Object 3 listing, I define another menu item in our aeadmin menu. I set the id_seq_num as "020" to make it appear (sort) after the previously created item that I set to "010". I use a BASIC-like numbering scheme that will allow me to insert additional menu items later without the need to re-number the entire menu to accommodate a new item. The key difference with this menu item is that points to an entirely new object we call ae_ls that is next_type of "d". So I am telling SMIT that the object this points to is a dialog and not another menu. Otherwise, this sm_menu_opt should look much like menu items I created in the previous examples.

The sm_cmd_hdr object defines the dialog that I will be using. In itself, it only describes part of the dialog. The sm_cmd_opt defines each piece of data that the user will enter. The combined sm_cmd_opt's define the bulk of the user interactive components in the dialog. As well as providing the common binding framework, the sm_cmd_hdr provides the actual content of the command that will run as well as the (optional) default values. Together, these two objects define the entire SMIT dialog experience.

I will look at the sm_cmd_hdr object first6 as it is the framework that the sm_cmd_opt objects hang on. The id descriptor is set to the same name as the next_id in our previously created menu item. I define an option_id descriptor so that all the options can be placed, in order, into this dialog. SMIT will look for all sm_cmd_opt objects defined in the ODM with an id that matches this value. The name descriptor is set to the title I wish for the top of the dialog. This dialog does not have a pre-selector screen that would determine what group of options to present to the user so we do not set the has_name_select descriptor. (The selector screen and the sm_name_hdr object will be introduced in the next example.)

The command and the default values are also defined in the sm_cmd_hdr object through the cmd_to_exec and the cmd_to_discover descriptors. The cmd_to_exec example here is intentionally overly complex to demonstrate writing multiple line code in the ODM. Ideally, complex code is best maintained as a separate script (in a directory such as /opt/aeadmin/bin). This is further necessitated by the fact that this field has a limit of 1024 characters. The options I define in sm_cmd_opt objects will be passed as parameters to this command when it runs. The cmd_to_discover descriptor is used to define default values for the options. The first line of the output prints the disc_field_name of the sm_cmd_opt object, while the second line prints the desired default value. Multiple defaults can be specified as colon separated values. (In the next example I will show creating multiple defaults and what happens if some defaults are set, while others are not.)

Some relevant but less obvious sm_cmd_hdr descriptors I have set here as well. The value for ask will tell SMIT to warn the user before running the command and ask if they are sure the command should run. The default value for ask is "n", the alternative we chose is "y", so SMIT will treat the locally written version of ls as a potentially destructive command. The exec_mode descriptor defines how the output is handled in the result screen. By default, the output is piped to SMIT and scrolls as it runs. The value for ghost determines if the dialog (prompting for input) should be displayed. In this case I want the dialog to display because I expect user input, and do not rely upon default values. If I had a command / dialog that displayed status of a service, the current time, or something that does not require user input prior to running then I could set this to "y" instead of the default "n". Finally, I set my help_msg_loc value as it is available in all four SMIT objects.

Each user input is defined by an individual sm_cmd_opt object. In this example I only set one (for the directory to run ls against). If I had multiple inputs they would share the same id descriptor. The id descriptor of all the sm_cmd_opt objects associated with a dialog should match the option_id that is set in the sm_cmd_hdr object that defines the dialog. Here, I set them to "ae_ls_opts"7. Like menu items, the id_seq_num descriptor determines the order that the option will show up in the dialog. Also like menu objects is the name descriptor that defines what the prompt should be for the user input field. The programatic handle for the object is the name set in disc_field_name. This value is referred from the cmd_to_discover descriptor set earlier in the sm_cmd_hdr object should I choose to set a default value.

User inputted data is returned from each sm_cmd_opt object to the sm_cmd_hdr object's cmd_to_exec as ordered parameters to the command. The order will be the same as they appeared in the dialog. Any prefixes, such as a flag, is specified with the prefix descriptor. Even though they are ordered, best practices in command line utility development suggests that command line parameters should be acceptable in any order. Should the order of parameters be necessary, and the order of the dialog out of order then the items can be re-ordered using a wrapper function in the cmd_to_exec descriptor of the sm_cmd_hdr object (as in the sm_cmd_hdr example in ODM Object 3).

Many of the remaining sm_cmd_opt object descriptors define the nature and type of user input such as if they are required, they are a list, null values are allowed, and how to return the data. In this example I will only list the deviations from the defaults. More examples will be given later and complete documentation for the objects and descriptors is available from the AIX Information Center.

The op_type descriptor is set to the default so this is a simple (non-list) input. I have set the entry_type to "f" for a file (or directory). The size of the input is not (artificially) limited as entry_size is set to 0. The value for required is set to "+" that will require the user to input some data or the command cannot run. This descriptor also defines what is sent to the command if the user does not enter data.

The resulting dialog, shown in SMIT Screen 3, displays the single command option (the directory) with the default (the current working directory). The "*" character on the left notifies the user that this is a required value and the "/" on the far right notifies them that the input is a file / directory. When the enter key is pressed from this dialog the user will be prompted to insure that they want to run the command (as it may be dangerous / destructive) and then they will see the ls results of this directory.

Not shown here is the additional menu item that will be added to the aeadmin menu. This is menu item addition, along with the an item introduced in the next example, is visible later in the SMIT Screen 4 screenshot.

Creating A More Complex Command / Dialog

The final example creates a more complex dialog with a preceding selector screen. This is for a fictitious script that takes different parameters depending upon a "high" or "low" selection. Concepts like high or low might be appropriate, for example, for a command that can either read or write. When reading it might ask for query-specific or result limiting data and if it writes it would ask for content to write. The initial selector screen determines our intent with this command, and then directs us to the most appropriate input dialog for our proposed action.

Note that I have left some additional comments in the object definitions to help the reader to decode and differentiate the contents. The comments are anything following the "*" character. The section "division" lines were left in the sample code because of the large size of the information. odmadd will ignore this content.

I begin with a sm_menu_opt object that defines a menu item in the (aeadmin) application menu. The difference with this sm_menu_opt is that the next_type descriptor points to a selector / sm_name_hdr object, identified by "n", rather than another menu or dialog as in the previous examples. The selector object id is specified in the next_id descriptor as "ae_pco_sel".

The next object is a sm_name_hdr that defines the selector screen. This is a simple selector that does not cascade into another selector so I specify that the next_type is a dialog. The selector item is like a dialog in that I use sm_cmd_opt objects to define the options in the selector screen. They are linked, like the previous dialog object to the sm_cmd_opt object(s) via the option_id defined in the selector object and the id defined in the sm_cmd_opt(s). They both share the "ae_pco_opts" value for these descriptors.

The next_id in the sm_name_hdr is incomplete ("ae_pco_"). It will be appended with one of the items from the aix_values defined in, and returned from, the sm_cmd_opt objects. The concatenation of these two items point to what dialog will be displayed next.

The sm_cmd_opt for the selector screen defines a simple ring (multiple choice - pick one) option with the values of "High" and "Low". The aix_values list defines what will actually be sent back to the selector screen / object for each item in the disp_values ring. There should be a one-to-one ordered relationship between disp_values and aix_values. (Note that in the Option 1 - low dialog I break this rule by sending back a switch string for the "Yes" option and a null value for the "No" option.)

The next two items defined are the two (high and low) dialogs. As in the previous example, these are defined by sm_cmd_hdr objects. In comparison to the previous dialog example both of these dialogs are quite simple. The "High" dialog has a defined cmd_to_discover descriptor that will set defaults for two of the three options. In this example the first and third options are set to a default leaving the second option without. The resulting dialog screenshot, shown in SMIT Screen 6, shows the resulting values set and the second option as blank.

I have set the cmd_to_exec in both dialogs to run the echo command for the illustrative purpose of simply echoing the parameters as passed to the command.

Each of the options from the example in ODM Object 4 are broken out in the following table.

The menu in screenshot SMIT Screen 4 is the result of all the sm_menu_opt additions to the ACME Administration (aeadmin) menu. The last menu item created in the ODM Object 4 called "Process Config Options" appears second in the menu because of the value set in the id_seq_num descriptor in the sm_menu_opt object.

The SMIT Screen 5 screenshot is the selector screen that determines which dialog will be displayed next. The single question displayed is the "High or Low dialog" prompt defined in the sm_cmd_opt object along with the default "High" value selected from the choice ring defined in the same object. This is a required (*) value that can be picked from a list (+).

Options to the selector screen are "High" and "Low" as defined in the sm_cmd_opt object descriptor disp_values, but the value returned is either "high" or "low" as defined in the aix_values descriptor. The example here is only a matter of difference in case between the choices and the returned values, but the point is that an entirely different, but relative, value can be returned than what the user chooses.

The screenshot shown in SMIT Screen 6 shows the options for the "High" Dialog as well as the default values defined in the cmd_to_discover descriptor in the sm_cmd_hdr object for this dialog. Note that the middle value is not set to a default. When the defaults are set by name it is permissible to only set some and order is not required as the defaults are set by the disc_field_name of the sm_cmd_opt and not the order they appear in the dialog.

The "Low" dialog shown in the SMIT Screen 7 screenshot shows the options with two that are required (*), all three are selectable via the F4 key (+), one is a numeric entry (#), and one is a file or directory (/). Even though all three are selectable via the F4 key, each is a different type. The first item is a ring of values, the second is a list of numbers and the third is a list generated by the ls command.

Bits And Pieces

Inserting ODM Objects

In the actual ACME Enterprises deployment8, ODM objects were grouped into actions that were placed into files. Each file held all ODM objects for the menu item, dialog, and options. This was done to ease development by associating each addition of SMIT functionality with a single file. This was much easier than manipulating one giant file with all the objects. As a result syntax errors returned from the odmadd command were easier to locate in the object descriptions.

I then wrote a series of scripts to check and insert the objects. The check was primarily for the help_msg_loc descriptor to insure that it was set for every ODM object that was created. These (ODM object source) files were placed into a common directory where the check and add scripts can find them. These types of management utilities are not required but make for easier development and debugging of the objects you create.

When inserting objects into the ODM it is advisable to test the objects outside of the ODM prior to modifying the actual / production ODM database. This can be done by using an alternate copy of the SMIT specific ODM objects. The ODMDIR environmental variable for odmadd and the -o option for smit / smitty allow these alternate objects to be used rather than the actual ODM. This process is defined in the "Adding Tasks to the SMIT Database" Infocenter page.

Version Control

The method of version control used by ACME Enterprises was to create a menu item off the aeadmin screen that contained the version string as a text parameter. This allows someone to view the current version of the application from both within the ODM (via a call to odmget) as well as from the SMIT interface on the aeadmin menu. The version information is tied closely to the actual objects rather than kept in a separate version file where it could grow out of sync with the installed ODM objects.

One other complexity of version control is insuring that all local-ware scripts that the SMIT dialogs rely upon actually exist in the local script directory. A similar form of version control is recommended for these scripts so that they are kept in sync with the ODM objects. The loosely coupled nature of the command line API allows for some flexibility in this regard. ODM dialogs should not rely upon positional parameters in scripts - meaning: your script should accept parameters in any order, and should validate the parameters it receives. Any input errors should cause the script to exit with a non-zero value. SMIT will give ordered input to the commands, but this should not be assumed as the scripts may be called outside of SMIT.

Upgrades

The safest method I found to update the ODM objects was to remove all tagged objects and replace them with the new version of the tagged objects. This tag was mentioned earlier in the document as the help_msg_loc descriptor that is common to every SMIT ODM object. An odmdelete can be keyed on this descriptor that will delete only SMIT objects related to this key, and therefore the application.

Selectively deleting all application objects and then re-inserting the new / upgraded ones is much easier than maintaining some sort of ODM diff. This allows me to jump from one version to another without the need to modify ODM objects in place.

If the application is packaged as a installp package then the key method described here should not be necessary. Creating installp packages is beyond the scope of this document, but can make upgrades and version control much easier. The uninstall portion of the package can know what ODM objects to remove, solving the versioning of the ODM objects. The local-ware can be included as part (or dependency) of the package, solving issues with relationships and dependencies between the SMIT screens and the capabilities of the binaries / scripts that they call.

Footnotes

Author: William Favorite <wfavorite@tablespace.net>
Version: 0.9.0
Date: 12/30/8