**MSI Deployment via Active Directory**

Active Directory contains a very useful feature which allows for
Administrators to automatically deploy software to machines or users
automatically when the machine is booted or a user logs on. This
document assumes you will be deploying software to a set of machines in
which the user does not have local admin rights, so it will focus on the
process to deploy to the computers via the Computer Configuration GPO
setting.

Before proceeding, there are a few items you should be aware of:

-   Software to be automatically installed must be in the form of an
    .MSI package, configured with minimal or no user interaction.
    Products such as WISE, Veritas Install Lite and InstallShield are
    common applications, and you may have some luck with the IExpress
    application bundled with Windows 2000 and Windows XP.

-   Installation runs as the local computer domain account (NT
    Authority\\System). Authentication to the share location containing
    the .MSI package uses the local machines Kerberos cache.

-   Package Deployment configured under the Computer Configuration Group
    Policies are only pushed to Computers within the assigned
    Organizational Unit (OU) tree

-   Package Deployment configured under the User Configuration Group
    Policies are only pushed to Users within the assigned Organizational
    Unit (OU) tree

-   The share containing the .MSI package must allow Domain Computers at
    least READ access. Authenticated Users group is also sufficient.

-   The Group Policy Object must allow for Read and Apply Group Policy
    rights for Domain Computers. Authenticated Users group is also
    sufficient.

-   To allow for multiple administrators to change or redeploy a
    package, the Group Policy must contain these additional
    administrator groups with the appropriate read/write/modify rights.

-   Packages are only deployed upon the initial boot of a computer, or
    during the logon of a user, depending on how the Package Object is
    defined. Packages will NOT be deployed during the normal Security
    Settings refresh interval.

-   Once a Package is successfully deployed, it will NOT be redeployed
    unless it is manually redeployed or versioning is enabled.

For those of you familiar with creating Group Policies and the Software
Settings Wizard, you may skip to the end of this document for a
quick-check list of items that need to be set. Microsoft also has a few
articles on how to publish software for deployment within Active
Directory at <http://support.microsoft.com/?kbid=314934>

Also, a short Troubleshooting section in Appendix C has been included to
cover some of the more common problems encountered when deploying
software via Active Directory.

**Verify the MSI Works First**

Before you defined the GPO and Package Objects, ensure that the MSI
installer files works as you planned. Keep in mind that if it attempts
to set HKEY_Current_User registry keys, that process will fail since
there is no user logged onto the machine during the software deployment,
so no HKEY_Current_User registry section is available. If you require
HKEY_Current_User registry keys to be set, split your MSI installer file
into two parts, and define the software installation in the Computer
Configuration GPO section, and the HKEY_Current_User registry updates in
the User Configuration GPO section. Also, you may want to test the MSI
file as the local computer account first. See the Troubleshooting
section on how to obtain a command prompt as the NT Authority\\System
account.

**Defining the GPO and Package Object**

Create a share on a server, and allow Domain Computers at least READ
access to the share. Copy the MSI installation file to the share and
ensure it also allows for Domain Computers READ access.

Create the Group Policy Object in the Active Directory Users and
Computers application:

1)  Right click on the OU you wish to define the GPO and select
    Properties

2)  Click the Group Policy tab and click New.

3)  Type a descriptive name for this new GPO. Be sure to prefix the name
    with your Section/Division to provide ambiguity.

![](media/image1.png){width="3.1215277777777777in"
height="2.6416666666666666in"}

4)  Click the Properties button, then select the Security tab. Add the
    Domain Computers group (or edit the existing Authenticated Users
    group) and assign the READ and APPLY GROUP POLICY rights.

5)  Click on the Edit button to edit this new Group Policy. Expand the
    Computer Configuration\\Software Settings tree on the left side of
    the screen. Right-click Software Installation tree option and select
    the menu item New\\Package

6)  An Open File dialog box should appear. Type in the UNC path to the
    server share where the MSI installer file is located. Select the
    appropriate MSI installer file and click Open. If you receive a
    'Cannot open file' error, check the share permissions to ensure the
    account you are using the Active Directory Users and Computers
    application with has READ/WRITE access to the share.

> ![](media/image2.png){width="2.863888888888889in" height="2.21875in"}

7)  Select the Assign radio button and click OK. The other Published and
    Advanced radio buttons are alternate ways to publish the MSI
    package. Published will not automatically install the MSI installer
    file, but instead place an entry in the local Add/Remove Programs
    utility for manual installation later. Advanced will give you the
    ability to change certain properties such as the Package Name.

> ![](media/image3.png){width="1.9125in" height="1.31875in"}

8)  You have now created and assigned the Package Object.

> ![](media/image4.png){width="3.6222222222222222in"
> height="1.3416666666666666in"}

9)  Right click on the Package Object and select Properties.

10) Click on the Security tab and add Domain Computers (or Authenticated
    Users if that is your scheme) to the security permissions. Ensure
    Domain Computers has the READ right.

![](media/image5.png){width="1.9493055555555556in"
height="2.183333333333333in"}

11) Click the Advanced tab and select Domain Computers (or Authenticated
    Users if that is your scheme) and click Edit. Assign the List
    Contents, Read All Properties and Read Permissions checkboxes are
    selected.

> ![](media/image6.png){width="1.7673611111111112in"
> height="2.2909722222222224in"}

12) Close the Group Policy window.

13) Close the GPO window.

14) The MSI package has now been defined and is ready for deployment.

15) Wait about 10-15 minutes for your changes to be replicated to the
    other Domain Controllers, then reboot a machine contained within the
    OU you defined the GPO for.

**Verifying Installation**

After rebooting a workstation contained within the OU you defined the
GPO Software Deployment policy for, an information box should appear on
the screen after the Applying Security Settings messages stating it is
installing the MSI package along with the name you defined in the
Package Object advanced properties, or defaulting to the deployment name
within the MSI installation file. After the workstation boots, log in
and open the Event Viewer. Navigate to the Applications Event Viewer. A
successful installation will have three informational entries indicating
a successful MSI deployment. If there are any Errors, check the Event
Viewer message to see what the failure reason was and consult the
troubleshooting section below.

**Redeploying the Package Object**

As time goes on, you may wish to update the MSI installer file and
redeploy the application to the targets. Keep in mind that once the
computer successfully deploys the software package, it will not redeploy
the application unless told to do so. To redeploy the Package Object:

1)  Open the Properties for the GPO you created defining the Package
    Object. Edit the Policy by clicking on the Edit button.

2)  Right-click on the Package Object and Redeploy Application.

> ![](media/image7.png){width="3.115972222222222in"
> height="1.6888888888888889in"}

3)  The package will now be marked for deployment at the next reboot of
    the target workstations.

**Appendix A: Changing the Location of the MSI Installation File**

At times, it may be necessary to change the UNC path of the MSI
installation file. The Active Directory Users and Computers application
does not give an interface to do so, so you basically have two options.
Either create a new Package object for software deployment or edit the
existing Package Object with the ADSI editor. The ADSI editor is part of
the Windows 2000 Resource Kit, and can be added to the MMC utility
through the Add/Remove Snap-In selection.

To edit the existing package, you first need the CLSID of the existing
Package Object:

1)  Open the GPO the Package Object it is defined in and right click the
    Package Object and select Properties.

2)  Click the Deployment tab, then click the Advanced button. Note the
    Script Name location. You will need the long alphanumeric number
    directly after the \\Policies notation.

> ![](media/image8.png){width="2.0069444444444446in"
> height="2.0236111111111112in"}

3)  Open the ADSI editor, connect it to your domain and navigate to the
    System\\Policies tree on the left side of the window. Locate the
    CLSID you noted above.

> ![](media/image9.png){width="3.7493055555555554in"
> height="1.5118055555555556in"}

4)  Expand this CLSID tree and then expand the following trees to get to
    the actual defined Package Object: CN=Machine \\ CN=Class Store \\
    CN=Packages.

![](media/image10.png){width="3.74375in" height="1.90625in"}

5)  Right click on the Package Object and select Properties. Navigate to
    the Optional property 'msiFileList'. This property contains the UNC
    path of the location of the MSI Installer file. Edit this value to
    represent the new UNC path. Note the leading zero. It is possible to
    have multiple UNC paths defined for a Package Object, starting with
    0:, then 1: and so on. If you are changing the UNC path, type in the
    new UNC path, prefixed with 0: and click the Add button. Select the
    old UNC path and click the Remove button.

> ![](media/image11.png){width="2.0215277777777776in"
> height="2.247916666666667in"}

6)  The UNC path for the Package Object has now been updated to reflect
    the new UNC path. If you wish to redeploy the MSI Installer file
    again to all computers within the OU, go back into the Active
    Directory Users and Computers, locate the Package Object in the
    assigned GPO, right click the Package Object and select 'Redeploy
    Application'

**Appendix B: Creating Kerberos Service Principals**

Since the local machine uses its local computer account Kerberos
credential cache to authenticate to the server share containing the MSI
Installation file, it must first request a HOST principal for the server
hosting the share. Depending on the permissions set on the server
computer object within Active Directory, this may be created
automatically, or you may need to create it manually. If the permissions
on the object allow for Full Control or Read/Write/Modify of SELF on the
server computer object, after the next Active Directory registration of
the server (usually after a reboot), the HOST service principal may be
automatically created. One cautionary note on this: if the server is
allowed to automatically update the properties on its own object, it
will remove anything you had defined manually. For example, if you
create the Package Object UNC path using the FQDN
([\\\\server.domain.com\\share\\Install.msi](../../../../../../../../share/Install.msi)),
and server.domain.com is not the actual computer name of the server, the
server will update Active Directory with the computer name instead
(HOST/server instead of HOST/server/domain.com). In this case, there
will be no HOST service principal for server.domain.com and the package
installation will fail. It is probably better to not let the server
auto-updates its own Active Directory object properties and instead
define both the HOST/server and HOST/server.domain.com HOST service
principals manually.

To create the HOST service principals manually, you need to use the ADSI
editor. Open the ADSI editor and navigate to your server computer
object. Navigate to the Optional servicePrincipalName attribute and add
both the HOST/server and HOST/server.domain.com values. Set this value
on all server computer objects that will be hosting shares for software
deployment. Client workstations that are received the software
deployment do not need to be modified.

![](media/image12.png){width="3.870833333333333in"
height="2.5083333333333333in"}

**Appendix C: Troubleshooting**

Various points during the GPO push of the MSI package may fail. At most
times, the failures are due to incorrect permissions for the computer
account to access the GPO, defined package, physical package, or
authentication problems. Also, an improperly configured MSI setup file
may cause installation failures. Microsoft has an excellent guide on
troubleshooting GPO's at
<http://www.microsoft.com/windows2000/techinfo/howitworks/management/gptshoot.asp>

**Problem:** You do not see the message box at startup stating the MSI
package is being installed.

**Resolution:** There are a few possibilities that can contribute to
this. Check to ensure the target machine is located within the OU (or
downstream OU) where the GPO containing the software deployment is
applied. Also, check the permissions on the OU and GPO to ensure Domain
Computers (or Authenticated Users) have both READ and APPLY GROUP POLICY
rights. Also ensure the defined package object within the GPO has the
appropriate rights for Domain Computers. Also, your GPO definition may
not have fully replicated through the Active Directory domain. Either
wait a while for replication to occur, or if you have Domain Admin
rights, manually force Replication.

**Problem:** The Application Event Viewer indicates errors that the MSI
package installation failed with an error 'Package source not located'.

**Resolution:** This indicates that the local computer read and tried to
apply the GPO and MSI Package object, but could not access the physical
.MSI file. Check the permissions on the share containing the MSI file to
ensure Domain Computers (or Authenticated Users) has at least READ
access rights. Also, check to ensure the Kerberos service principal
(servicePrincipalName) is set and correct for the computer containing
the share via the ADSI editor. It is also possible that the Package
Object was created using the physically path (C:\\Apps\\Installer.MSI)
instead of the UNC path
([\\\\server\\share\\Installer.MSI](../../../../../../../../share/Installer.MSI)).
Also, the Package Object may reference the FQDN of the share path
([\\\\server.domain.com\\share\\Installer.msi](../../../../../../../../share/Installer.msi)),
but a HOST/server.domain.com Kerberos Service Principal does not exist.

You can manually verify the computer account has access to the share and
MSI installer file by attempting to connect to the share as the local
computer account (NT Authority\\System) by performing the following:

1)  On the target computer, log in as an administrator.

2)  Schedule an AT job for 1 minute ahead of the current time to launch
    a command prompt as NT Authority\\System:

    a.  C:\\\> at 1:00pm /interactive cmd.exe

3)  After the command prompt window to appear, you will have NT
    Authority\\System access.

4)  Attempt to list the contents of the share using the UNC path:

    a.  C:\\\> dir [\\\\server\\share](../../../../../../../../share) -
        You should receive a directory listing of the files on the share

**Problem:** Package seems to install correctly by the Application Event
Viewer messages, but the application does not seem to work.

**Resolution:** If your MSI installers file attempts to write to
HKEY_CURRENT_USER in the registry, the installation may not be complete.
Since the application is installed using the local computer account, no
user is currently logged on, hence no available Current User profile
exists. Instead, split the MSI installation into two parts and push the
actual files and common registry keys via a Computer Configuration GPO,
and define the CURRENT_USER registry keys in a separate User
Configuration GPO. Also, ensure that the MSI installer file is able to
silently install with little or no user intervention. Test the
installation of your MSI installer file as the local computer account by
following the technique listed above on how to obtain a command prompt
as the NT Authority\\System account.

**Problem:** Cannot create GPO object.

**Resolution:** Ensure that the account you are using to run the Active
Directory Users and Computers application has sufficient rights to
create Group Policies. Usually, you must be a member of the Group Policy
Creator Owners group explicitly or implicitly by nested groups. See your
local OU administrator to verify your group membership and to delegate
the ability to create Group Policies.

**Problem**: The Deployment Counter on the Package Object is not
increasing even though my clients were successful in installing the
deployed package.

**Resolution:** If Domain Computers does not have WRITE privileges to
the Package Object, this counter will always be Zero. This is entirely
up to you is you want to allow Domain Computers to be able to write to
the properties of the defined Package Object, since this is only a
counter, and does not indicate which machines actually have the MSI
installed.

**Problem:** You updated the MSI installer file, but machines do not get
updated automatically.

**Resolution:** You must redeploy the Package Object within the GPO.
Right-click on the Package Object and select All Tasks\\Redeploy
Application --OR- use the built-in versioning techniques of Package
Objects (see Microsoft Knowledge Base for more info on using versioning
of Software Package Objects).

**Problem:** Other administrators cannot redeploy the software or edit
the GPO. Only the original creator or Domain Administrators can.

**Resolution:** Check the security permissions on both the Package
Object and the GPO to ensure intended administrators can
Read/Write/Modify the objects accordingly.

**Creating GPO's for MSI Deployment Quick-Check List**

Setup the Share and ensure Host Principals exists

-   Setup a Windows Share on a server and allow either Domain Computers
    or Authenticated Users at least READ access (I have had mixed
    experiences with Authenticated Users, so Domain Computers is
    recommended).

-   Ensure a 'HOST/\<shorthostname\>' and a 'HOST/\<host FQDN\>'
    principals exist for the servers object containing the share via the
    ADSI editor (servicePrincipalName attribute. E.g. HOST/server and
    HOST/server.domain.com).

> Create the GPO

-   Create a new GPO Computer Configuration\\Software Settings for the
    software you wish to deploy. Ensure the package deployment path is
    the UNC path (e.g.
    [\\\\myserver\\MSI\$\\mypackage.MSI](../../../../../../../../MSI$/mypackage.MSI))

> Create the Package object and apply permissions

-   Ensure Domain Computers (or Authenticated Users) has READ
    permissions to the newly created Package. Also, ensure List
    Contents, Read All Properties and Read Permissions are selected in
    the Advanced security settings for the Package.

-   If other Administrators will have the ability to edit the Package
    settings (not the physical MSI file, but the Package object defined
    in the GPO), add their accounts or their Administrators group to the
    Package Security settings.

> Assign permissions to the GPO itself

-   Ensure Domain Computers (or Authenticated Users) has READ and APPLY
    GROUP POLCY to the GPO itself.

-   If other Administrators will have the ability to change the GPO, add
    their user accounts or their Administrators group to the GPO
    Security settings.

> Assign the GPO to the OUs

-   Assign the new GPO to the OUs you wish to have the software deployed
    onto

> Replicate and Test

-   Wait 5-10 minutes for Replication to occur

-   Reboot target workstation and check event logs for installation
    failure messages