http://www.microsoft.com/TechNet/boes/bo/sms/technote/sm303.htm (PC Press Internet CD, 03/1996)
| Updated: March 14,1996 |  Go To TechNet Home Page |
Presented by: Oscar
H. Newkerk
Oscar Newkerk is a Program Manager in the Systems Management
Server group at Microsoft.
Installation Using Systems Management Server
Installation Programs
Package Directory
Package Definition File
Installing Packages Using Systems Management Server Jobs
Using the Systems Management Server C APIs for Software Deployment
Appendix
Using the Microsoft® Systems Management Server centralized management for distributed systems to distribute software to the enterprise requires an understanding of the distribution model that Systems Management Server uses and the mechanisms that it provides to implement that model. The first part of this paper will discuss the model and the components of Systems Management Server that are involved in the distribution and installation of software. The second portion of the paper will discuss in detail the requirements for the producers of software to meet in order to have their software be easily installed and maintained by Systems Management Server.
During the installation of Systems Management Server, the user builds a hierarchical model of the enterprises using Systems Management Server sites and domains. A Systems Management Server site is a geographic or organizational unit that is controlled by a system running the Systems Management Server software.
A Systems Management Server domain represents a system that acts as a logon server or domain controller, for some collection of machines. The logon server can be a system running the Microsoft Windows NT™ operating system, a NetWare server, or a server running Microsoft LAN Manager local area network software. In all cases there are some number of PCs that use the domain controller as their logon server on a regular basis.
The installation of software using Systems Management Server starts with the collection of inventory information from machines. This hardware and software inventory information is stored in the Systems Management Server database and is used to plan and control the installation process.
Systems Management Server distributes software in the form of packages. Systems Management Server packages define the components to be installed, the supported platforms, and various configuration options for the software. Systems Management Server installs software by using the concept of jobs that target specific sets of machines for packages and that define the mechanics of the distribution of the package through the Systems Management Server hierarchy. The job defines a set of machines called distribution servers that act as staging points in the hierarchy for packages. Once the package is present on the distribution servers, then the job is sent as a control file to the target machines where it is executed by a components of the Systems Management Server client code called the Package Command Manager or PCM.
Distribution servers are machines in the Systems Management Server hierarchy that are used as staging points for the distribution of software packages. When a Systems Management Server job is created to distribute software, one of the attributes of the job is the list of distribution servers that will make the package available to the target systems. The package is copied to each distribution server and is exported as a share point from those machines.
The selection of distribution servers is important to the installation process since each machine that will install the package must be able to get the components of the package from a distribution server. If the target machines for the package includes a NetWare client, then a NetWare server reachable from the NetWare clients must be included in the list of distribution servers for the job. If the target machines for a package include Macintosh machines, then a Windows NT-based machine with the Services for Macintosh that is reachable form the target systems must be included in the list of distribution servers. Note that the distribution servers do not have to include all the logon servers in a domain.
Once the package has been delivered to the distribution servers that were specified in the job, then a control file is delivered to the target clients and is processed by the Package Command Manager (PCM) on the client. PCM is the Systems Management Server client component that is responsible for receiving the package on the client, controlling the installation, and reporting the status of the installation back to Systems Management Server.
When PCM receives a control file for the installation of the package, it reads the file to determine the attributes of the job. If the job requires that a package directory be available for the job to execute, then PCM connects to the appropriate share point on the specified distribution server and starts to process the job.
Processing of the job begins with PCM changing the active directory to the package share point and executing the command line specified in the job. When this command is finished, PCM reports status back to Systems Management Server and dismounts the package share.
The command line that is specified in the installation job is the setup or installation program for the application contained in the package. This command line can be anything that is appropriate to the actions required to install the software and the platform where the installation is to take place. The installation program should take any actions that are required to install the application and should also take account of the fact that it is running in the Systems Management Server environment by supporting the requirements of the installation process in Systems Management Server.
A software setup or installation program that is used in the Systems Management Server environment should support that environment in the following ways-
That is, it should not require input from the user during the installation, de-installation, or maintenance of the application. Any information or options that are required by the setup program should be supplied by command-line switches to the program or should be provided in a configuration file that is read by the program at run time.
Since multiple packages could be installed by Systems Management Server and the installation may be forced on the user for mandatory packages, no individual package installation should force a reboot of the machine as part of its installation program. Instead, PCM has the capability of intercepting these restart requests, queuing them up until all packages have been installed, and offering the user the chance to clean up any work in progress before the restart.
To copy system files that may be in use, setup programs restart the Microsoft Windows® operating system and run a program for the MS-DOS® operating system using ExitWindowsExec. In order to set up multiple programs before a restart, PCM prevents a reboot, and then it itself performs an ExitWindowsExec when a user elects to do so. Setup programs generally construct a batch file that contains the operations that must be performed during a restart. To coordinate multiple unattended setups, the following procedure must be followed. Concatenate the setup's batch file to the file _MSSETUP.BAT, or, if _MSSETUP.BAT doesn't yet exist, rename the setup's batch file. If it doesn't already exist, create an _MSRSTRT.EXE program to be executed by PCM when it calls ExitWindowsExec. This MS-DOS-based program must execute the batch file _MSSETUP.BAT and then delete the batch file and itself. If PCM detects, in the Windows directory, both of the files _MSSETUP.BAT and _MSRSTRT.EXE, then it decides that a restart must be performed and it displays a restart dialog box. This dialog box does not interfere with subsequent installations.
To report either success or failure of a PCM application installation, a MIF file must be created in the Windows directory. The MIF file should be named appname.MIF Where appname is the name of the application. In fact PCM will pick up any file in the Windows directory that has an extension of .MIF and that was created after PCM began the installation and send this back to Systems Management Server. The contents of the status MIF must match the format of the example in the Appendix.
The package directory is simply a directory structure that contains all of the files required to support the installation or de-installation options that are in the Package Definition File. When a job is created that uses a package, the contents of the package directory, including any subdirectory structure, is compressed and sent to all of the site servers of the target clients of the job. Once 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 should be included in the package directory. This includes any dynamic-link libraries (DLLs) or configuration files that might be required to support the operation of the setup program.
A Package Definition File (PDF) is an ASCII text file that contains predefined 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 name enclosed within square brackets). Key names can be separated by spaces. Each key contains one or more entries, where each entry has the form: name = value.
A PDF has specific keys and entries that are used by the system to set the properties of a package.
The [PDF] section identifies the file as a Package Definition File. This section contains a single entry:
The version of the PDF format used by the file.
Example
Version = 1.0
The [Package Definition] section defines the overall properties of the package.
The name of the product.
Example
Product = Excel
The version of the product.
Example
Version = 4.0a
The comment used for the package's Comment setting. When the PDF is imported into a new package, this string is used as the Comment in the Package Properties.
Example
Comment = Microsoft 4.0a for Windows
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
The access permissions to the packages created with this PDF once they are distributed. 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 (one with a .COM, .EXE, or .BAT extension), a 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 using the following entries: UserRead sets Read permission for the Users group, UserWrite sets Write permission for the Users group, GuestWrite sets Write 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,
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 Systems Management Server, the setup variations specify the package commands that will be defined for the package's Workstations property.
The name used for this package command. When the PDF is imported into a new package, this string is used as the Command Name for this package command.
Example
CommandName = Automated Minimum Installation
The command line used for this package command. When the PDF is imported into a new package, this string is used as the Command Line for this package command.
Example
CommandLine = setup.exe
The value for this entry specifies whether this package command requires interaction with the user to complete the command. When the PDF is imported into a new package, this entry is used as the Command Line for this package command. You can specify TRUE or FALSE.
Example
UserInputRequired = TRUE
On Windows-based clients, by default, once Systems Management Server starts executing a job, it intervenes if it receives a request to exit the Windows environment. Systems Management Server does this by returning 0 if it receives a WM_QUERY_END_SESSION. Systems Management Server then presents a dialog to the user asking the user to confirm when it is OK to reboot the computer. For programs simply attempting to reboot the system, this does not cause a problem. However, it is a problem for jobs attempting to run MS-DOS-based programs using ExitWindowsExec(). Setting SynchronousSystemExitRequired to TRUE disables the default Systems Management Server behavior so that the job can run an MS-DOS-based program.
On MS-DOS-based clients, setting SynchronousSystemExitRequired to TRUE indicates to Systems Management Server that the job will cause the client to reboot. This tells Systems Management Server to use overlay mode when executing the job. This frees up the memory used by Systems Management Server so it can be made available to the program being executed. By default, Systems Management Server executes programs synchronously and remains in memory when a job command line is executed.
Note that setting this value to TRUE isn't 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=TRUE
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
The [Setup Package for Sharing] section defines the Sharing properties of the package. Sharing properties are used for installing the package on servers and sharing it from those servers (Share Package On Server jobs).
The share name that you want to assign to the shared package when it is installed on a server.
Example
ShareName = exc40ash
The access permissions to the package's share when the shared package is installed on a server. You can assign permissions to two user groups: Users and Guests. There are two permissions that you can assign:
To run a program file (one with a .COM, .EXE, or .BAT extension), a user must have Read permission.
You assign permissions to these groups using the following entries: UserRead sets Read permission for the Users group, UserWrite sets Write permission for the Users group, GuestWrite sets Write permission for the Guests group, and GuestWrite sets Write permission for the Guests group.
Example
ShareAccess = UserRead, UserWrite, GuestRead, GuestWrite
Each [Program Item Properties Index] key specifies the program item properties for network applications contained in the package. Each program item will be defined in the package's Sharing property. The Program Item Properties key heading should have the following form: [Program Item Properties Index] where Index is a unique integer that identifies the program item within the PDF. The Index should start at 1 and increase by 1 for each additional program item.
The text used at workstations for the network application's program item description. When the PDF is imported into a new package, this entry is used as the Description for the program item.
Example
Description = Microsoft Excel
The command used to start the network application.
Example
CommandLine = EXCEL.EXE
The configuration script file used to configure the network application at workstations. If an explicit path is not specified, the package source directory is the default path to the configuration script.
Example
ConfigurationScript = exc40a0n.PCD
The name of the key where the network application's configuration information is stored in the Windows registry.
Example
RegistryName = EXCEL4
The file that the network application uses as a default initialization file.
Example
DefaultINIFile = EXCEL4.ini
This entry specifies whether the network application should be minimized to an icon each time the user starts it using the program item. You can specify TRUE or FALSE.
Example
RunMinimized = TRUE
Specifies whether the Systems Management Server APPSTART program should search local directories on the workstation's path for the file specified by Command Line. If APPSTART finds this file, it starts the local version; otherwise, it starts the network version. You can specify TRUE or FALSE.
Example
RunLocalCopyIfPresent = TRUE
This entry specifies how the Systems Management Server APPSTART program should connect to the server and shared directory where the network application is located. You can specify one of three values:
UNC
APPSTART executes the network application using a UNC name. No drive letter is connected to the application's shared directory.
ANYDRIVELETTER
APPSTART must connect to the application's shared directory using a drive letter-but APPSTART can use any available drive letter on the workstation.
SPECIFICDRIVELETTER DRIVE
APPSTART must connect to the application's shared directory using a specific drive letter. DRIVE specifies the drive letter that APPSTART must use. The drive letter must be followed by a colon (:).
Example
DriveMode = SPECIFICDRIVELETTER W:
This entry specifies the operating systems where the program item is made available. Separate the operating system names with commas. When the PDF is imported into a new package, this entry is used as the Supported Platforms for the program item.
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
This entry specifies whether an application icon is placed in a program group. This entry should be false for utility applications, such as MSAPPS, that are to be distributed along with other shared applications.
Example
DisplayIconInProgGroup = FALSE
This entry specifies the file that contains the icon that you want to use for the network application.
Example
SetupIcon = exc40a01.ico
The [Setup Package for Inventory] section defines the Inventory properties of the package. The Inventory properties are used by the Systems Management Server system to maintain inventory on the package.
The Systems Management Server 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 Systems Management Server Inventory Agent program detects the 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 Systems Management Server to collect specified files from workstations and store them at the site server.
This entry specifies whether the package should be included in the Systems Management Server inventory. You can specify TRUE or FALSE.
Example
InventoryThisPackage = TRUE
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 all files in the rule, 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 should 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 together using the following rules:
w Files are combined using AND and OR operators. AND has precedence over OR.
w Files can be grouped and ungrouped using parentheses. Files within a group are treated as a single entity. For example, the rule File1 AND (File2 OR File3) specifies that Systems Management Server 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 = )
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 should 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 Filename is required. All other attributes are optional.
The name of the file.
Example
Filename = EXCEL.EXE
This entry specifies whether the Systems Management Server system should collect a copy of this file and store it on the site server. You can specify TRUE or FALSE.
Example
Collect = FALSE
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
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 these 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
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.
Systems Management Server uses the CCITT-CRC standard to evaluate the CRC value. You must specify a CRC value computed with the CCITT-CRC algorithm.
By default, the entries are decimal. To specify a hexadecimal number, start the hexadecimal number with 0x.
Example
CRC = 5000, 300, 38707
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
The size of the file (in bytes).
Example
Size = 2766592
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
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
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
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"
Microsoft Systems Management Server uses jobs to distribute packages to target machines. There are three primary types of jobs for this purpose.
There are various job options that you can specify depending on the type of job that you are creating. The main options that affect the distribution of software are the specification of the target machines, the distribution servers where the package will be made available, and the options for the run phase of the job.
The most useful mechanism for specifying the set of machines that are the target of a job is to use a query against the Systems Management Server database. You can create a query that allows you to target only those machines that meet the criteria for the particular package that you are going to install. Once you have defined the query, the set of machines that are the result of the query can be specified as the target of the job.
Run Command on Workstation Jobs are the most common type of jobs used in Systems Management Server. This type of job is actually run on the target clients in the context of the package share that is associated with the job. This type of job is used to install, de-install and maintain software on client systems.
The Share Package on Server Job is used to install a shared application on a set of servers. Unlike the Run Command on Workstation job, the Share Package jobs does not actually execute a setup program on the target servers. It simply copies the files and directory structure in the package directory to the specified servers and makes it available as a share. The access permissions for the package are set in the PDF for the package.
Remove Package Jobs do not remove packages from client machines. This is done using de-install options for the Run Command on Workstation job. The Remove Package job is used to remove packages from Systems Management Server site servers, distribution servers, and servers that have had a package installed using the Share Package on server jobs.
The Systems Management Server Software Development Kit (SDK) includes a set of C APIs that can be used to interact with Systems Management Server and the information in the Systems Management Server database. These APIs allow you to build custom solutions with Systems Management Server to support creation of software packages, planning the deployment of applications, and the tracking of the use of software in your enterprise.
One use of the C APIs is to read information from the Systems Management Server database on sites, domains, and machines. In addition, you can list the queries, packages, and jobs that are in the database including the status of jobs.
The C APIs also allow you to create queries, packages, and jobs in the database. One example of the use of these APIs would be to tie a software repository system to the distribution capabilities of Systems Management Server.
The information in the repository could be used to create packages including detailed inventory rules for the various components and base levels of an application. Then the APIs could be used to create the appropriate jobs to deploy the application components to the servers and clients.
This is a sample status MIF that is returned by an application installation program to Systems Management Server. Sections in bold should be replaced by the application program with the appropriate information.
START COMPONENT NAME = "WORKSTATION" START GROUP NAME = "ComponentID"ID = 1CLASS = "DMTF|ComponentID|1.0" START ATTRIBUTE NAME = "Manufacturer"ID = 1 ACCESS = READ-ONLY STORAGE = SPECIFIC TYPE = STRING(64) VALUE = "manufacturer" END ATTRIBUTE START ATTRIBUTE NAME = "Product"ID = 2 ACCESS = READ-ONLY STORAGE = SPECIFIC TYPE = STRING(64) VALUE = "Product" END ATTRIBUTE START ATTRIBUTE NAME = "Version"ID = 3 ACCESS = READ-ONLY TORAGE = SPECIFIC TYPE = STRING(64) VALUE = "version" END ATTRIBUTE START ATTRIBUTE NAME = "Serial Number"ID = 4 ACCESS = READ-ONLY STORAGE = SPECIFIC TYPE = STRING(64) VALUE = "Serial Number" END ATTRIBUTE START ATTRIBUTE NAME = "Installation" ID = 5 ACCESS = READ-ONLY STORAGE = SPECIFIC TYPE = STRING(64) VALUE = "datetime" END ATTRIBUTE END GROUP START GROUP NAME = "InstallStatus" ID = 2 CLASS = "MICROSOFT|JOBSTATUS|1.0" START ATTRIBUTE NAME = "Status" ID = 1 ACCESS = READ-ONLY STORAGE = SPECIFIC TYPE = STRING(32) VALUE = "Success or Failed" END ATTRIBUTE START ATTRIBUTE NAME = "Description" ID = 2 ACCESS = READ-ONLY STORAGE = SPECIFIC TYPE = STRING(64) VALUE = "Error Message" END ATTRIBUTE END GROUP END COMPONENT
© 1995 Microsoft Corporation. .
THESE MATERIALS ARE PROVIDED "AS-IS," FOR INFORMATIONAL
PURPOSES ONLY.
NEITHER MICROSOFT NOR ITS SUPPLIERS MAKE ANY WARRANTY, EXPRESS
OR IMPLIED, WITH RESPECT TO THE CONTENT OF THESE MATERIALS OR
THE ACCURACY OF ANY INFORMATION CONTAINED HEREIN, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. BECAUSE SOME STATES/JURISDICTIONS DO
NOT ALLOW EXCLUSIONS OF IMPLIED WARRANTIES, THE ABOVE LIMITATION
MAY NOT APPLY TO YOU.
NEITHER MICROSOFT NOR ITS SUPPLIERS SHALL HAVE ANY LIABILITY FOR
ANY DAMAGES WHATSOEVER, INCLUDING CONSEQUENTIAL, INCIDENTAL, DIRECT,
INDIRECT, SPECIAL, AND LOSS OF PROFITS. BECAUSE SOME STATES/JURISDICTIONS
DO NOT ALLOW THE EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES,
THE ABOVE LIMITATION MAY NOT APPLY TO YOU. IN ANY EVENT, MICROSOFT'S
AND ITS SUPPLIERS' ENTIRE LIABILITY IN ANY MANNER ARISING OUT
OF THESE MATERIALS, WHETHER BY TORT, CONTRACT, OR OTHERWISE, SHALL
NOT EXCEED THE SUGGESTED RETAIL PRICE OF THESE MATERIALS.
 |
Click Here to Search TechNet Web Contents | TechNet CD Overview | |
Microsoft TechNet Credit Card Order Form At this time we can only support electronic orders in the US and Canada. International ordering information. |
| Go To TechNet Home Page |
©1996 Microsoft Corporation |  Go To Microsoft Home Page |