This chapter explains how to capture and deploy Windows 2000 applications and files. The chapter includes the following information:
The value for the installPath variable is treated as a relative path to the default Remote Agent directory, unless you specify an absolute path, such as /opt or c:\mydir. For example, for a Windows Remote Agent, if you set the installPath variable to c/mydir, and deploy the file to an Agent with a default Remote Agent directory of c:\Program Files\N1 Service Provisioning System\agent, the file is deployed to c:\Program Files\N1 Service Provisioning System\agent\c\mydir.
The Windows common tasks page enables you to view and create components for the following Windows 2000 entities:
Windows applications, separated into three types:
COM+ applications
COM objects
Microsoft Windows installer files (.msi)
Internet Information Server (IIS) applications and support files, separated into five types:
IIS applications
IIS web sites or virtual directory settings
IIS global settings
ISAPI global filter settings
ISAPI web site filter settings
Other common Windows files, separated into five types:
Registry keys
Registry files
Data source names
Batch files
Scripting host scripts
Before you can deploy a file or application across systems, you have to make the file or application known to the Sun N1 Service Provisioning System software and wrap it into a component.
Although the general approach that you follow is the same for all component types, details differ depending on the actual types that you need to use.
Select the Windows icon under the Common Tasks section of the left control panel.
Click the Create New link next to the component type you need to create.
For example, to create a component that contains a batch file, follow these steps:
On the Components Details Edit page, fill in the appropriate information.
For example, for a batch file, fill in this information:
Click Check in Selected Item.
You can also create a component through the command line. For more information about commands, see cdb.rsrc: Managing Components in Sun N1 Service Provisioning System 5.2 Command-Line Interface Reference Manual.
For a simple file, such as a batch file, a command file, or a dynamic linked library file, use the following command:cr_cli -cmd cdb.rsrc.ci -src filename -dst component-name -u username -p password
where:
filename is the name of the file that you want to check in.
component-name is the name that you want to use for the component
For files that you have to browse, such as COM+ applications, registry keys, or data source names, the command is more complex. If you have exported the file, you can use an “Exported File Browser” to check in the file. In the command, you have to specify the sourcePath. The sourcePath is the path that you would see when you browse for a file of this component type in the browser interface.
The following example checks in a data source name from a file dsn.n1test.
%> cr_cli -cmd cdb.rsrc.ci -src exported/dsn.n1test -dst dsn.n1test -type 'com.sun.windows#data source name' -platform 'NM:system#Windows 2000 Server' -pickerName 'Exported File Browser' -extraOpts sourcePath='System DSNn\\1test\\' -u **** -p **** |
Capture the component as described above.
Go to the Components section of the Sun N1 Service Provisioning System application.
Choose the component to deploy.
Depending on the type of component that you choose to deploy, you might have to define variables or to perform other steps. At a minimum, you perform the rest of the steps listed here.
Click Run in the Actions column next to the Default:Install procedure.
A plan details page appears for running the installation procedure.
Choose a target host.
The target host should be a host for which the component that you are deploying applies. For example, deploying a Microsoft Windows IIS application to a non-Windows host would not be appropriate.
Click Run Plan.
To reflect the browser interface, the component types for this plug-in are grouped into three areas:
Windows applications component types
IIS component types
Additional Windows component types
Windows application component types consist of three types:
A component of this type represents a COM+ application. COM+ applications are treated as a unit. The settings and content are installed as a group.
When you browse for a COM+ application, the browser provides an alphabetical list of COM+ applications on the target system.
You can select a single COM+ application to be checked in. COM+ applications have no children and cannot be expanded.
COM+ applications are exported into a Microsoft Windows Installer (MSI) file using the COM+ Admin SDK.
The COM+ Application is re-exported on the target system as an MSI file and compared against the MSI file used to install the application. The software will only indicate that there were differences, but will not indicate the details of the differences.
If a COM+ application with the same name is already installed on the target system and running as a service, the existing application is stopped along with any running dependent services. The COM+ application will then be deleted from the COM+ catalog.
The new COM+ application is installed using the COM+ Admin SDK.
To start the COM+ application the user will have to use the startApp call step to manually start the COM+ application.
The COM+ application is uninstalled using the COM+ Admin SDK.
Action |
Condition |
Result |
---|---|---|
Install |
COM+ Application already exists with the same name and either cannot be stopped or dependent services cannot be stopped. |
Installation fails |
Uninstall |
MSI file used for installation is no longer available |
Uninstallion fails |
Install or Uninstall |
Remote Agent does not have administrator privileges |
Installation or Uninstallation fails |
Name |
Parameters |
Description |
---|---|---|
startApp |
appName – Full name of the COM+ application. |
Starts the COM+ application if it is run as a service |
stopApp |
appName – Fill name of the COM+ application to stop. |
Stops the COM+ application and all dependent services |
stopRouter |
N/A |
Stops the COM+ Routing services |
startRouter |
N/A |
Starts the COM+ Routing services |
installAsUser |
rsrcSrcPath – Name of the COM+ application rsrcInstallPath – Path to the *.msi file representing the application userID – User who is going to run the application password – Password of the user |
Enables installation of a COM+ application that runs as a particular user |
This component type represents a COM file.
To choose a file for this component type, select a *.ocx or *.dll file from the file browser.
The COM component is compared as a binary file against the file used during installation. The software indicates when there are differences, but does not provide details about the differences.
The Regsvr32 utility is called to register the COM components in the DLL using the following command line:
regsvr32.exe /s file path |
The Regsvr32 utility is called to unregister the COM components in the DLL using the following command line:
regsvr32.exe /s /u <file path> |
After the DLL is unregistered, it is removed from the target system.
Action |
Condition |
Result |
---|---|---|
Install |
The supplied .dll or .ocx file does not contain COM components |
Installation fails |
Uninstall |
The supplied .dll or .ocx file does not contain COM components |
Uninstallation fails |
A component of this component type includes a silent Microsoft Installer (MSI) file.
To choose a file for this component type, select a *.msi file from the file browser.
The Microsoft Windows installer service is called on the MSI file to import it into the target system with the following command:
misexec /qn /i file path |
The Microsoft Windows installer service uninstall is called on the MSI file used during installation to uninstall the package using the following command:
msiexec /qn /x file path |
After msiexec finishes, the MSI file is removed.
Action |
Condition |
Result |
---|---|---|
Install |
The supplied *.msi file is not a proper Microsoft Windows installer file. |
Installation fails. |
Install |
The agent does not have proper permissions to run installations |
Installation fails. |
Uninstall |
The package has already been uninstalled |
Uninstall fails |
IIS component types share some common information and consist of several component types:
The IIS component types share a common implementation. All IIS component types enable you to export, install, and delete data stored in the IIS metabase. To enable the common behaviors, these component types share a set of functions, formats, and errors.
When you browse for an IIS component, the browser provides a list of web sites and virtual directories on the target system. These items appear in the order that they occur in the metabase. This corresponds to the order in which the items appear in the IIS Control panel. This list is not alphabetical.
You can select a single web site or virtual directory. Selecting a web site is considered recursive. Double-clicking a web site displays a list of the virtual directories in the web site.
All IIS types use an XML format to store their section of the metabase. The present XML format does not support metabase properties of type NTACL (such as AdminACL). Any properties of this type that are encountered while reading from or writing to the metabase are ignored. Also, properties of type IPSec (such as IPSecurity) are written out as serialized objects. Those objects are not human-readable during either direct examination, or as difference results.
During a snapshot, the current state of the metabase is exported into an XML file. During an M-I difference, the metabase is re-exported and compared against the original XML file. The standard XML differentiator is used to generate differences between these files.
Action |
Condition |
Result |
---|---|---|
Install/Export |
IIS Does not exist or is the improper version |
Install/Export fails |
Install/Uninstall |
Remote Agent does not have administrator privileges |
Install/Uninstall fails |
Represents the settings for an IIS web site or virtual directory. Please note that this component type only contains the settings for a web site or virtual directory. The content on the web site must be checked in as a separate resource.
Installation occurs by reading the XML file and importing the file into the target system metabase. If a web site with the same name exists, the old web site is overwritten. If multiple web sites have the same name on the system, the first matching web site is removed and overwritten.
Special cases include untyped keys or nodes, and SSL certificates, which are not deployed. The relevant settings for SSL certificates in IIS (SSLCertHash and SSLStoreName) are preserved during a deployment if they exist on the target system. If relevant SSL settings do not exist, settings are not added.
To bring up a secure site after the site is deployed or redeployed, you must restart IIS.
The entire web site is removed on the target system. All virtual directories in the web site are removed regardless of whether they were installed by the provisioning software. If the settings are just for a virtual directory, only that directory is removed, not its containing site. The matching for uninstall is done by name, so the first web site with the same name found on the system will be uninstalled. Once this process is complete, the XML file used during installation is removed.
This component type is used to represent global IIS filter settings. This component type only contains the settings for an IIS Global Filter. You must install separately the actual DLL that implements the filter.
When you browse for an IIS global filter settings component, the browser provides a list of global filters on the target system. These filters appear in the order that they occur in the metabase. This corresponds to the order in which the items appear in the IIS Control panel. This list is not alphabetical.
You can select a single filter. Filters cannot be expanded.
Installation occurs by reading the XML file and importing the file into the target system metabase. If a filter setting with the same name exists on the target machine, the existing filter setting is overwritten.
The filter settings are removed on the target system. Once the settings are removed, the XML file used during installation is removed.
This component type contains the settings for a web site filter. You must install separately the actual DLL file that implements the filter.
When you browse for an IIS web site filter settings component, the browser provides a list of web site filters on the target system. These filters appear in the order that they occur in the metabase. This corresponds to the order in which the items appear in the IIS Control panel. This list is not alphabetical.
To see a list of filters for a web site, you must expand the web site. You can select all web site filters or an individual filter to be checked in.
Installation occurs by reading the XML file and importing the file into the target system metabase. If a filter setting with the same name exists on the target machine, the existing filter setting is overwritten.
The filter settings are removed on the target system. Once the settings are removed, the XML file used during installation is removed.
This component type is used to represent global IIS settings.
When you browse for an IIS global settings component, the browser provides a list of settings on the target system. These settings appear in the order that they occur in the metabase.
You can select a single setting to be checked in. Settings have no children and cannot be expanded.
Installation occurs by reading the XML file and importing the file into the target system metabase. The setting on the target system is overwritten if the setting exists.
Global settings cannot be uninstalled. Uninstalls will have no affect on the target system except to remove the XML file used during install.
The IIS Website (IIS Virtual Directory) component type is a composite component type that includes four components:
A component that contains IIS web site or virtual directory settings
A component that identifies an IIS virtual directory set
A component that defines an IIS web site filter set
A component that contains a directory
The IIS Website Filter component type is a composite type that includes two components:
A component that contains IIS web site filter settings
A component that contains a COM object
The Windows 2000 Plug-In also provides several additional component types:
This component type is used to represent registry keys and their associated values.
When you browse for a registry key component, the browser provides a list of registry keys from the main registry roots on the target system. The main registry roots include HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_USERS, and HKEY_CURRENT_CONFIG. These items appear in the order that they are presented in the registry.
You can select an individual key for check in. Selecting a key will check in that key and all of its children. Double clicking on a key will recursively check down the registry until a value is found. The name of the value is displayed but not its contents. Values can be individually exported.
Registry keys are exported into an XML file.
During a snapshot, the current state of registry key (and its children) is exported into an XML file. During a difference check, the registry key is re-exported and compared against the original XML file. The standard XML difference comparator is used to generate differences between these files.
The XML file that represents the registry is read and imported into the target system using an execJava step. Any keys for which values already exist in the target system are overwritten.
The execJava implementation takes the root of the exported key, and deletes all keys and values beneath it. If the root is a value, it will be deleted.
Action |
Condition |
Result |
---|---|---|
Install or Uninstall |
Remote agent does not have administrator privileges |
Installation or uninstallation fails |
A component of this component type contains a registry file (*.reg). Registry files are text files that specify the key and values to add or remove from the registry metabase.
The provisioning software does not compare versions of a registry file for differences. To be able to view differences between registry files, use the Registry Keys component type instead.
To choose a file for this component type, select a *.reg file from the file browser.
Regedit /s file path is called on the *.reg file to write its changes to the registry.
During uninstallation, only the *.reg file used during installation is removed. The registry keys inside the registry file are unaffected. Use the Registry Keys type to enable registry uninstallation.
Action |
Condition |
Result |
---|---|---|
Install |
The supplied *.reg file is not in the proper format for regedit. |
Installation fails |
Install |
The agent does not have proper permissions to write into the registry sections designated by the *.reg file. |
Installation fails |
A component of this component type represents ODBC settings for connecting to a database. You can modify these settings through the Data Source Administrator control panel on the system. The actual settings are stored in specific places in the registry. As a result, the Data Source Name (DSN) resource type is built on top of the Registry Keys resource type. The DSN installation, export, and uninstallation functions directly use the facilities provided by the Registry Key resource handler. The DSN browser mimics the Registry browser to provide an experience closer to the “Data Source Administrator” control panel.
When you browse for a DSN component, the browser provides a list of DSN files from the main registry roots on the target system. The DSN roots include User and System. DSN files are displayed in alphabetical order.
You can select an individual DSN file for check in. Double-click on the System and User roots to list the contained DSN entries.
On export, the browser exports the key that contains all the DSN settings, as well as the value of the same name in the “ODBC Data Sources” key at the same level in the registry hierarchy.
The DSN uninstallation is based on the registry uninstallation, with the caveat that the path being deleted is the key that contains the DSN settings but not the key that the DSN user interface uses to display the available DSN settings. Special logic exists to delete this key as well. The semantics of this process differ slightly from the registry uninstallation semantics, although both processes use the same executor.
The DSN system component directly calls the Install method of the registry system component. See Registry Keys Component Type for further information on implementation and possible errors.
A component of this component type contains a Windows batch *.bat or command *.cmd file.
When you create a component for this component type, you can request that the file browser show only that files that have *.bat or *.cmd extensions.
Action |
Condition |
Result |
---|---|---|
Install |
The supplied batch file is not a valid batch file or contains errors. |
Installation fails |
A component of this component type contains Microsoft Windows scripting host (WSH) scripts. These files are text files that are created by either vbscript (*.vbs) or jscript (*.js). These files may also be contained in an XML project file (*.wsf).
When you create a component for this component type, you can request that the file browser show only that files that have *.js, *.vbs, or *.wsf extensions.
When you uninstall a component of this component type, the script file is removed from the target host. However, any actions that the script performed are not undone.
Action |
Condition |
Result |
---|---|---|
Install |
The supplied file is not a valid *.wsf file or contains errors. |
Installation fails |
The Microsoft Windows System Component provides utilities for interacting with different windows systems, beyond those related to any specific component types. The plug-in includes five Windows-specific system services:
com.sun.windows#COM+ application services
com.sun.windows#data source name services
com.sun.windows#metabase services
com.sun.windows#registry key services
com.sun.windows#services
Extended control services are procedures that perform a software operation related to a resource or component. These services include services for starting and stop the Microsoft IIS Web Server and for starting and stopping specific Microsoft Windows services. The provisioning software includes two sets of extended control services that are not specific to individual resource types:
General purpose control services, which can be called by any component or plan
Resource-type-specific control services, which are related to a specific type of resource and that can be called only by components or plans that include resources with those resource types
General purpose control services include the ability to start or stop Microsoft Windows services. These control services can be called by any component or plan.
An example of a resource-type-specific control service is the startRouter procedure included with the COM+ Application resource type. This procedure starts COM+ routing services. It works only with resources that are of the COM+ Application resource type.
The following table lists the procedures for controlling IIS.
Table 4–10 Built-in Procedures for Controlling IIS
Name |
Parameters |
Description |
---|---|---|
stopIIS |
None |
Shuts down the IIS process |
startIIS |
None |
Restarts IIS if it is not running |
A component or plan may include steps to start or stop specific Microsoft Windows Services.
The following table describes procedures for controlling Microsoft Windows Services.
Table 4–11 Built-in Procedures for Controlling Microsoft Windows Services
Name |
Parameters |
Description |
---|---|---|
stopService |
serviceName – Name of the service to stop. |
Shuts down the service |
startService |
serviceName – Name of the service to start. |
Starts the Microsoft Windows service |