Systems Management Server Requirements for gaining the Microsoft BackOffice Logo

Overview

In order to gain Systems Management Server support, all applications must:

Support installation and de-installation in an unattended mode
Provide a Status Management Information File (Status MIF) with both required entries.
Provide a Package Definition File (PDF) with all required entries.

Installation Process Overview

The installation of software in the SMS environment starts with the collecting of inventory information from computers throughout the enterprise. This hardware and software inventory information is stored in the SMS database and is used to plan and control the installation process.

SMS distributes software throughout an enterprise in the form of packages. These packages define the components to be installed, the supported platforms, and various configuration options for the software.

SMS installs software by using jobs that target specific sets of computers and define the mechanics of the distribution through the SMS hierarchy. A job defines a set of computers called distribution servers, which act as staging points in the hierarchy for packages. Once a package is present on the distribution servers, the job is sent as a control file to the target clients, where it is executed by a component of the SMS client code called the Package Command Manager (PCM).

The processing of a job begins when the PCM mounts the package share point, changes the active directory to that point, and executes the command line specified in the job. The command line specified in the installation job is the Setup or installation program for the application contained in the package. This command line can be anything appropriate to the actions required to install the software, and to the platform where the installation is to take place. The installation program must perform the actions required to install the application, and must also take the SMS environment into account by supporting the requirements of the SMS installation process.

The following steps are required for installing software in an SMS environment:

Create an installation or Setup program according to the guidelines outlined in this paper.
Create a PDF using the format outlined in this paper
Create a package directory.
Import the software package into the SMS environment.
Use an SMS job to install the package.
Write a Status MIF in the Windows directory with a date and time stamp greater than the time that PCM launched the setup application. This is to indicate installation success or failure and to communicate additional information, such as why it did not succeed (i.e., No disk space)

The following steps are required for de-installing software in a SMS environment:

Create a program for de-install (may be a command line switch on your main setup program).
Write a Status MIF in the Windows directory to indicate the success or failure of the de-installation.

The same rules apply when maintaining packages.

1) Support Unattended Installation/De-installation

A software Setup or installation program used in the SMS environment must support that environment in the following ways:

Operate in Unattended Mode

It is mandatory that the program not require input from the user during the installation, removal, or maintenance of the application. Any information or options required by the Setup program should be supplied by command-line switches to the program, or be provided in a configuration file that is read by the program at run time or by some other means (the Windows Registry for example).

Your application must not show any dialogs or windows during installation/de-installation or maintenance. This is required for completely unattended install using the Package Command Manager.

Do Not Force Restart

Because multiple packages can be installed by SMS at one time, no individual package installation is allowed to force a restart as part of its installation program. Instead, the PCM has the capability of intercepting restart requests and queuing them up until all packages have been installed, offering the user the opportunity to save any work in progress before the restart.

Pass Restart Instructions to the PCM

To copy system files that may be in use, setup programs typically construct a batch file containing operations that must be performed during a restart, such as running a DOS program by using ExitWindowsExec, and then restarting Windows.

In order to set up multiple programs before a restart, the PCM prevents the restart, and then performs an ExitWindowsExec when the user elects to do so.

To coordinate multiple, unattended setups, concatenate the batch file of each Setup program to the file _MSSETUP.BAT. If _MSSETUP.BAT does not exist, then rename the batch file of the first Setup program to _MSSETUP.BAT and concatenate the batch files of additional Setup programs to that file. Next, create an _MSRSTRT.EXE program to be executed by the PCM when it calls ExitWindowsExec. This DOS program (_MSRSTRT.EXE) must execute the batch file _MSSETUP.BAT and then delete the batch file and itself.

After the installations are complete, if the PCM detects both _MSSETUP.BAT and _MSRSTRT.EXE in the Windows directory, it displays a dialog box prompting the user to exit Windows and restart. This dialog box does not interfere with subsequent installations.

1) Provide a Status MIF

To report the status of a PCM spawned application installation or de-installation, a Status MIF must be placed in the Windows directory. The MIF file should be named appname.MIF, where appname is the name of the application being installed or removed. This naming convention is designed to allow multiple installations in a single session to report their status and not have a conflict in the name of the status MIF files. In addition, the creation date and time stamp of the .mif file must be set to after the time that PCM started to run the job. In this way PCM knows that the status MIF file was placed there by your setup application and will update the SMS database with the values the file provides. These same rules all apply to the Status MIF for un-install.

It is important to note that PCM looks for status MIF(s) after the setup command that PCM launched completes. Thus, your installation must write the status MIF(s) before the original process launched by PSM exits. If your installation runs one command, that command spawning another command that actually writes the status MIF(s) after the first command has terminated, PCM will not recognize that the second command has written a status MIF and the status MIF will not be reported to SMS.

Minimum MIF File Entries

The contents of the status MIF must match the format of the following Status MIF Template. This is a template of a status MIF returned by an application installation program to SMS. Items in bold italics must be replaced by the application program with the appropriate information.

The Status attribute can be any of the following strings:

SUCCESS

FAILED

The Description string attribute is not case sensitive. Description can be any DMTF-compatible string. The maximum length is 254 characters.

Note that the Description attribute is only used if the Status is FAILED in which case the Description is reported in the SMS Job Status window in the SMS administrator application.

Start Component

Name = "Workstation"

Start Group

Name = "InstallStatus"

ID = 1

Class = "MICROSOFT|JOBSTATUS|1.0"

Start Attribute

Name = "Status"

ID = 1

Type = String(16)

Value = "FAILED"

End Attribute

Start Attribute

Name = "Description"

ID = 2

Type = String(128)

Value = "Audit job failed because of lack of disk space on target machine."

End Attribute

End Group

End Component

The Package Directory

The package directory is a directory structure that contains the files required to support the installation or removal options in the Package Definition File. When a job is created that uses a package, the contents of the package directory, including any subdirectory structure, are compressed and sent to the site servers of the target clients. When the compressed package is received at the site server, it is copied to the distribution servers specified in the job and decompressed. The package contents are then exported from the distribution server with the appropriate permissions set.

All of the files required to support the operation of the job must be included in the package directory, including any DLLs or configuration files required to support the operation of the Setup program.

It is highly recommended that you add an option on your setup application to setup up this directory on a network share with the appropriate un-installed files, complete with your SMS PDF file. This will advertise the fact that you are SMS capable and will make it much easier for administrators to use SMS with your product.

2) Provide a Package Definition File

A Package Definition File (PDF) is an ASCII text file that contains pre-defined Workstation, Sharing, and Inventory property settings for a package. When you create a new package, you can use the Import command from the Package Properties dialog box to define the properties for the package, using a PDF.

A PDF follows the standard initialization file format. It is an ASCII text file containing keys (the key names are enclosed within square brackets). Key names can be separated by spaces. Each key contains one or more entries, where each entry follows the format: name = value1, value2, ... Values are separated by a comma and at least one space.

A PDF has specific keys and entries that are used by the system to set the properties of a package. The following topics describe the specific keys and entries. All PDF files must at a minimum include the required entries as listed below.

[PDF] (required)

The [PDF] section identifies the file as a Package Definition File. This section contains a single entry:

Version (required)

The version of the PDF format used by the file.

Example

Version = 1.0

[Package Definition] (required)

The [Package Definition] section defines the overall properties of the package.

Product (required)

The name of the product.

Example

Product = Microsoft Excel

Version (required)

The version of the product.

Example

Version = 4.0a

Comment (required)

The comment used for the package's Comment setting. When the PDF is imported into SMS, this string is used as the Comment in the Package Properties.

Example

Comment = version 4.0a for Windows

SetupVariations (required)

A list of the setup variations supported by the package. Each setup variation name corresponds to a PDF key that defines a package command. The recommended name for these keys is [SetupVariation Setup].

Example

SetupVariations = Typical, Complete, Laptop, Automated

WorkstationAccess (recommended)

The access permissions to the packages created with this PDF. You can assign permissions to two user groups: Users and Guests. There are two permissions that you can assign:

Read

Permits users in the group to read and copy files, run programs, change directories within the shared directory, and read extended attributes of files.

To run a program file (that is, one with a .COM, .EXE, or .BAT extension), the user must have Read permission.

Write

Permits users in the group to write the contents and extended attributes of files.

You assign permissions to these groups by using the following entries: UserRead sets Read permission for the Users group, UserWrite sets Write permission for the Users group, GuestRead sets Read permission for the Guests group, and GuestWrite sets Write permission for the Guests group.

The default is for both Users and Guests to have both Read and Write permissions.

Example

WorkstationAccess = UserRead, UserWrite, GuestRead

[SetupVariation Setup]

For the setup variations specified in the SetupVariation entry in the [Package Definition] key, the PDF must have a key that defines each variation. For SMS, the setup variations specify the package commands that will be defined for the package's Workstations property.

CommandName (required)

The name used for this package command. When the PDF is imported into SMS, this string is used as the Command Name for this package command.

Example

CommandName = Automated Minimum Installation

CommandLine (required)

The command line used for this package command. When the PDF is imported into SMS, this string is used as the Command Line for this package command.

Example

CommandLine = setup.exe

UserInputRequired (required)

The value for this entry specifies whether this package command requires interaction with the user to complete the command. You must specify false .

Example

UserInputRequired = False

SynchronousSystemExitRequired (required)

On Windows clients, by default, once SMS starts executing a job, it intervenes if it receives a request to exit the Windows environment. SMS does this by returning 0 if it receives a WM_QUERY_END_SESSION. SMS then presents a dialog box asking the user to confirm when it is okay to restart the computer. For programs simply attempting to restart the system, this does not cause a problem. However, it does cause a problem for jobs attempting to run MS-DOS programs using ExitWindowsExec(). Setting SynchronousSystemExitRequired to TRUE disables the default SMS behavior so that the job can run an MS-DOS program.

On MS-DOS clients, setting SynchronousSystemExitRequired to TRUE indicates to SMS that the job will cause the client to restart. This tells SMS to use overlay mode when executing the job, freeing up the memory used by SMS so it can be made available to the program being executed. By default, SMS executes programs synchronously and remains in memory when a job command line is executed. Note that setting this value to TRUE is not necessary just to exit the environment at the end of the package Setup program. The possible values are TRUE and FALSE, and the default is FALSE.

Example

SynchronousSystemExitRequired = FALSE

SupportedPlatforms (required)

The value for this entry specifies the operating systems where the package can be installed and run. Each operating system name must be separated by a comma and a space.

Example

SupportedPlatforms = Windows 3.1, Windows NT 3.1 (Alpha), Windows NT 3.1 (MIPS), Windows NT 3.1 (x86), MS-DOS 5.0, MS-DOS 6.0, Macintosh

PDG platform string		UI display string
Windows NT (x86)	=	Windows NT (x86)
Windows NT (MIPS)	=	Windows NT (MIPS)
Windows NT (Alpha)	=	Windows NT (Alpha)
MS-DOS	=	MS-DOS
MS-DOS 5.0	=	MS-DOS
MS-DOS 6.0	=	MS-DOS
MS-DOS 6.2	=	MS-DOS
MS-DOS 6.21	=	MS-DOS
MS-DOS 6.22	=	MS-DOS
Macintosh	=	Macintosh
Windows 3.1	=	Windows 3.1
Windows95	=	Windows95

[Setup Package for Inventory] (required )

The [Setup Package for Inventory] section defines the Inventory properties of the package. The Inventory properties are used by the SMS system to maintain inventory on the package.

The SMS system identifies a package by searching for a set of files that you specify in the package's Inventory properties. For each file, you specify the attributes used to detect the file (such as file date, file size, CRC, and so on). If the SMS Inventory Agent program detects files that satisfy the conditions set by the package's Inventory properties, the Inventory Agent reports that the package has been detected on the workstation.

Within the Inventory properties, you can also set an option that enables SMS to collect specified files from workstations and store them at the site server.

InventoryThisPackage (required)

This entry specifies whether the package should be included in the SMS inventory. You can specify TRUE or FALSE.

Example

InventoryThisPackage = TRUE

Detection Rule (required)

This entry specifies the inventory rule used to identify the package. A package's inventory rule is the set of files used to identify the package. Using the AND and OR operators, you can specify the set of files required to detect the package.

For the files specified in the rule (except Boolean operators and grouping operators), the PDF must have a key that defines each file. Each file corresponds to a key that defines the attributes of the file. The file key heading must have the following form: [File index] where index is a unique integer that identifies the file within the PDF and the inventory rule. The index should start at 1 and increase by 1 for each additional file.

You combine the file specifications by using the following rules:

Files are combined using AND and OR operators. AND has precedence over OR.
Files can be grouped and ungrouped by using parentheses. Files within a group are treated as a single entity. For example, the rule File1 AND (File2 OR File3) specifies that SMS detects the package when File1 is found and either File2 or File3 is found—that is, File1 = TRUE and (File2 OR File3) = TRUE. Groups have precedence over AND and OR.

Example

Detection Rule Part 1 = File1

Detection Rule Part 2 = AND

Detection Rule Part 3 = File2

Detection Rule Part 4 = OR

Detection Rule Part 5 = (

Detection Rule Part 6 = File3

Detection Rule Part 7 = AND

Detection Rule Part 8 = File4

Detection Rule Part 9 = )

[FileIndex] (required)

For the files specified in the PackageDetectionRule entry in the [Setup Package for Inventory] key, the PDF must have a key that defines each file. Each file corresponds to a key that defines the attributes of the file. The file key heading must have the following form: [File index] where index is a unique integer that identifies the file within the PDF and the inventory rule. The index should start at 1 and increase by 1 for each additional file.

The File is required. All other attributes are recommended but not required.

File (required)

The name of the file.

Example

Filename = EXCEL.EXE

Collect

This entry specifies whether the SMS system should collect a copy of this file and store it on the site server. You can specify TRUE or FALSE.

Example

Collect = FALSE

BYTE

This entry specifies a value stored at a specific location in the file. This attribute requires two entries (separated by a comma and a space): Location is the data offset in bytes, and Value is the value stored at the offset. By default, the entries are decimal. To specify a hexadecimal number, start the hexadecimal number with 0x.

Example

BYTE = 20000, 216

Checksum

This entry detects the sum of all values stored at a specific set of bytes and compares the sum to a specified value. This attribute requires three entries (separated by a comma and a space): Start Location is the data offset where the summed values begin (in bytes), Length is the total number of bytes that are summed, and Checksum Value is the value checked against the summed values. By default, the entries are decimal. To specify a hexadecimal number, start the hexadecimal number with 0x.

Example

Checksum = 10000, 300, 32444

CRC

This entry detects the sum of all values stored at a specific set of bytes and compares the sum to a specified value. Unlike Checksum, CRC takes into account the sequence of the summed bytes. This makes it a more reliable identification of a file. In this attribute's settings, Start Location is the data offset where the summed values begin (in bytes), Length is the total number of bytes that are summed, and Checksum Value is the value checked against the summed values.

SMS uses the CCITT-CRC standard to evaluate the CRC value. You must specify a CRC value computed with the CCITT-CRC algorithm.

Example

CRC = 5000, 300, 38707

Date

The date of the file in decimal format: MM, DD, YY. The entries must be separated by a comma and a space.

Example

Date = 9, 2, 93

Size

The size of the file (in bytes).

Example

Size = 2766592

Time

The time of the file (using the 24-hour clock) in hours and minutes. The entries must be separated by a comma and a space.

Example

Time = 14, 18

LONG

An unsigned LONG value. This attribute requires two entries (separated by a comma and a space): Location is the data offset in bytes, and Value is the value stored at the offset.

Example

LONG = 30000, 1346373702

WORD

A WORD value. This attribute requires two entries (separated by a comma and a space): Location is the data offset in bytes, and Value is the value stored at the offset.

Example

WORD = 40001, 15488

Token # (1-4)

A string value. This attribute requires two entries (separated by a comma and a space): Location is the data offset in bytes, and Value is the string value stored at the offset. The string value must be enclosed by double quotation marks. You can define up to four separate StringValue entries.

Example

Token 1 = 710, "WIN"

Token 2 = 714, "EXCEL"

Example PDF for a "Simple Application"

[PDF]

Version=1.0

[Simple Server Install Setup]

CommandLine=instsrv.bat Install

CommandName=Automated installation of the Simple Service

UserInputRequired=FALSE

SynchronousSystemExitRequired=FALSE

SupportedPlatforms=Windows NT (Alpha), Windows NT (MIPS), Windows NT (x86)

[Simple Server Uninstall Setup]

CommandLine=instsrv.bat Remove

CommandName=Automated deinstallation of the Simple Service

UserInputRequired=FALSE

SynchronousSystemExitRequired=FALSE

SupportedPlatforms=Windows NT (Alpha), Windows NT (MIPS), Windows NT (x86)

[Package Definition]

Product=Simple Server

Version=1.0

Comment=Simple Server from the WIN32 samples of VC++ 2.0

SetupVariations=Simple Server Install, Simple Server Uninstall

[Setup Package for Inventory]

InventoryThisPackage=TRUE

Detection Rule Part 1=file 1

[file 1]

FILE=SIMPLE.EXE

COLLECT=FALSE

Checksum=

CRC=

DATE=

SIZE=

TIME=

BYTE=

WORD=

LONG=

TOKEN 1=

TOKEN 2=

TOKEN 3=

TOKEN 4=

Summary

Third party applications can gain Systems Management Server support by doing three simple things:

Support installation/de-installation of your application in an unattended mode
Provide Status Management Information Files (Status MIFs) with both required entries.
Provide a Package Definition File (PDF) with all required entries.