Packaging Standards – Example Policy
The following document is what I would consider an example of standards that provides high quality packages and an automated output that is possible to seamlessly automate. Variations would exist on this theme depending on the technology used in different organisations.
General
- Packages will be created as .MSI files whenever possible
- All packages will conform to the Package naming conventions.
- A transform will be created for any vendor MSI. The transform will conform to packaging naming standards.
- All packages will use a standardised deployment directory structure that shall be called with “Install.vbs”.
- All packages will be removable and will have a functioning removal script created before being introduced into the environment.
Installation
- Software packages are responsible for assigning appropriate access rights to directories and registry keys when default permissions are not sufficient. Any security rights that differ from the standard must be registered as an exception.
- Installation to root drives is not desired. Applications that must install to the root of a drive require additional approval before being deployed.
- Packages are not to modify the access rights of any pre-existing, Windows directories.
- Packages must install silently in a background process (no GUI) without user interaction.
- Packages must be able to install regardless of whether a user is logged on to the workstation.
- Packages that modify the PATH environment variable are responsible for removing modification when the package is uninstalled.
- Packages must have automated uninstall and rollback routines.
- Uninstall packages must leave a machine clean and without evidence of the packages
Status Reporting
- MSIEXEC, verbose logs will be produced to C:\Windows\Logs. These are an important tool for remote support staff.
- The package installing VBS script will relay Return Codes back to SMS / SCCM at package installation completion.
- No package created should be dependent on mapped drives, drive letters, UNC paths, ODBC or other generic DB connection information for its operation unless that requirement is universal.
- ODBC information should be included within an application whenever possible
- UNC paths should be used as much as possible.
- Status MIF files will be produced with each installation
User data
Many applications let the user create and store data files. In short, user created files that the user expects to be able to locate later for viewing or editing. The location for storing these files is “USERPROFILE”\My Documents\. You should ensure that the applications File Open and Save dialogs defaults to this location to make it easier for the user.
It’s accepted that these locations are rarely controllable by the packaging process as default open and save locations are coded by developers into their respective applications.
For more detailed info about recommended practice for user data read Section 1 3.1 in the document "Designed for Microsoft Windows XP" Application Specification at http://www.microsoft.com/downloads/details.aspx?FamilyID=209e3d65-f0be-4eef-8602-73bb9bc29d54&displaylang=en. It is important for programmers of applications so they retrieve the \My Documents\ folder location in a correct manner (SHGetFolderPath).
Application data
Applications may have a requirement to store some configuration or other data connected to the user or machine in some files. These files should be stored at different locations depending on the scope needed of the configuration/files. It is never permissible to store these data under the “SystemRoot” directories or in the application’s program files folder. There are applications that do this, especially older ones.
When storing data at any of these locations the application in question should not store the data at the root of the ...\Application Data\... directory. A directory substructure should be created like this:
...\Application Data\<name of application>\
It is accepted that Application Packagers have little control over the temporary working directories of specific applications as these are determined by developers.
When applications generate their own specific Application Data that is business critical it should be stored on a network drive. No business related data should ever be stored on the hard drive of a workstation due to security concerns and threat of data loss.
When it is possible to configure application data directories for business critical data, this should be directed to the user’s home drive and should be saved within a directory representing the application name. It is recommended that this folder resides under a root directory folder called “APPDATA” so it doesn’t become entangled with user documents or the user profile.
For more detailed info about recommended practice for application data read the document "Designed for Microsoft Windows XP" Application Specification at
. This is especially important for programmers of applications so they retrieve the different application data folder locations in a correct manner.
Self-updating applications
In the last several years publishers have included a feature in their applications that make it capable of updating itself or data files from some dedicated server on the Internet. Usually this is done to make it easier to fix bugs in the application, add some small new features or update some local data files.
With proprietary solutions there is no way of knowing how secure or compatible the change is. Also, the organisation loses control of when the applications are updated. All changes to business Applications must be governed by Change Control and formal testing requirements. The risk of business applications failing through the release of untested updates is too great to allow self-updating within the environment.
Any application that requires self-updating must be seen as an exemption to required packaging standards and requires signoff before being introduced into the environment.
Scripting technology
In some cases more advanced logic may be needed to get an application installed. VBScript will be used primarily if scripting is required. All packages will be initiated with a standardised “Install.vbs” installation script. Any irregular or special scripting should take place either within this script or within a secondary, chained VBS script.
Batch Scripting is legacy Microsoft technology that is not required or accepted within the production environment.
Scripting within MSI’s
VBScript is preferred to be installed within the Binary table of the MSI.
Custom Actions in the “CustomAction” table should have an Action column value of the following format:
MYCOMPANY_<descriptive name>
When writing the VBScript code in the embedded file it should contain enough comments in the code to easily explain the purpose of the script and make it possible to understand its workings for easier troubleshooting.
Naming Conventions
Naming standards are important to the discipline of the packaging process. This section describes the rules for the naming of the respective files.
The reason for all these rules are to make sure we have distinct names that gives us the possibility to make future automated operations that has to take for granted the structure of the file names.
Package Naming Convention
The following naming convention will be used for all for applications or components delivered by packagers:
<Application>_<Operational Designator>_<Version>_<Architecture><Build>
Application Name, Version , Architecture and Internal Package “release” (or build number) are mandatory fields that must be used with all applications. An internal release number is important for keeping track of bug fixes or changes that are made to packages that have been introduced into production.
Application name
No abbreviations are to be used in determining Application Name. The application name will be the same as reported by the application vendor. All illegal characters used within the application name are to be removed.
Version
This is a numeric field that allows the use of the period. The version field will always have at least two components (i.e. 01.00)
Windows Installer does not accept non numeric forms of version. For the sake of consistency, the odd packages that use other friendly descriptors such as Microsoft’s “SR” or “RC” descriptors, this shall be removed from the version field.
Occasionally applications that use dates as part of their versioning will have dates converted to numeric format where the date will be represented in the version field as either “Version.Year.Month” or “Year.Month.Day”.
Exactly how dates are represented is dependent on the date versioning system used by the Vendor.
Examples:
Laws of New Zealand 12, Feb 2007 would translate to
LawsOfNewZealand12_20.07_86a
Or
NZ Case Law – March 2006 would translate to:
NZCaseLaw_2006.04_86a
Now that previous character limitations in regard to string size and directory depth are disappearing with Windows systems.
Optional Designator
An Optional designator may be used when naming a package. Packagers are encouraged to make packages as generic as possible so they may be used within the entire environment. When packages are specialised or tailored for a subsection of the environment, an optional designator or description may be used. This may represent a site, business group or language depending on the specifics of the configuration used.
Examples:
Winzip_08.01_86a – normal application
FinancialReporting-UK_09.02_86a – optional site designator
FinancialReporting-HR_09.02_86a – optional business group designator
Build
Every completed and tested package will remain unique within the environment.
Each package will be referenced with a “build” or release number. Once testing is completed on a package it will never be altered again. Any future alterations will take place in a new package with an incremented build number.
Note:
Vendor name is not included within the package name due to current limitations with Windows Explorer that still prevent a path depth of more than 260 characters. To prevent future problems, the package name is intentionally kept as short as possible.
Allowable Characters
The following rules are to be applied to characters used in the <...> fields:
- Never use the space characters in the naming in the field.
- Use the capital letter form (Case Stud) for all fields. Meaning you never should use only lowercase or uppercase characters. WinZip is correct, never winzip or WINZIP. Exception is when the name of the creator or application is written in real life as only lowercase or uppercase.
- Only valid characters to be used in the fields are: a-z, A-Z, 0-9,
- The _ (underscore) character should always be used as delimiter.
MSI Package Requirements
Shortcuts
The MSI and MST files should abide by following rules/guidelines if the application creates any shortcuts:
- Shortcuts should not be placed at locations other than on the Windows Start Menu except in special circumstances.
- The number of shortcuts inside the folder should be kept to a minimum. Do not create Readme shortcuts, uninstall shortcuts or help file shortcuts (if help is reached from inside the application). Shortcuts should only be recreated when they start the application or components not reachable from inside the application.
- Desktop Shortcuts will not be created.
- Applications with a single shortcut will not have separate subdirectories created off the Start menu. An application will only have a new directory created if it is expected that two or more shortcuts will belong within that application group.
- Wherever possible, advertised shortcuts should be created. Without Advertised shortcuts MSI technology cannot use self healing features. In the advent that non-application shortcuts are created (such as a required help file shortcut), these may be exempt from being advertised.
Permissions
All permissions will be set with the utility SubiNacl which will be embedded within the binary tables of the MSI.
- Permissions will only be increases where absolutely necessary. In situations where additional rights are given to users under a normally protected area of the file system, additional custom actions will be used to reinstate read only protection of executables, DLL and OCX files.
- Only a single instance of SubiNacl should exist within the Binary Table and should be labelled as “SubiNacl”.
- All permission changes will be recorded within the application’s “Release.txt” file.
Files and Subdirectories
Applications should always install to a subdirectory under “Program Files”. If an application installs files or subdirectories off the root of the drive it represents a standard exemption and must be approved before it can be released into the environment.
Internally Packaged Applications
General concept
An application will be installed with all possible features or options unless specifically stated otherwise. Application Packagers cannot be expected to know what add-ons or options are of benefit to the staff members who use the applications.
The organisation is best served by ensuring that all features of a product are included within a commissioned package.
All packages will be configured with English language and Metric measurement settings. In the advent that that local language configuration is not available, English (United Kingdom) will be used before resorting to English (United States).
Unless you are actually American!... Ed.
Everything with the MSI will be set to be installed locally.
What is contained within a package is ultimately a business decision which will be determined by the Business Owner and/or Technical Product Owner for the application.
Although Packagers should have been instructed on how to configure an application before packaging has begun, any confusion must be resolved by the customer with the assistance of the packaging team.
Licensing
Licensing and Registration should be made out to Trading name of the organisation wherever possible. Licences will not be created in the name of individuals or business groups.
Unattended install
Repackaged applications will not utilise GUI interface Dialogs. Completed MSI packages will be designed to run with the unattended switch /qn (Quiet with no dialog).
All applications must be tested to install and uninstall silently, without requiring a GUI shell.
Property requirements
All internal packages will have the following properties set:
ALLUSERS = 1
PACKAGENAME = Conforming to Published Standards
REBOOT=ReallySuppress
ARPNOREMOVE = 1
ARPNOMODIFY = 1
Removing the ability for applications to be manually “modified” or removed by staff with administrative rights is an important step to ensuring that standardisation remains. This is also extremely important to remain in control of licensing and auditing within the environment.
ICE validation
All ICE errors are to be corrected. If an error physically cannot be corrected the error and justification why it is not correctable must be documented.
All ICE warnings should be corrected whenever possible. The only exceptions outside the scope of this requirement are ICE33 errors.
COM correction
For MSI healing to work correctly, registry entries and their associated files must be grouped together within the correct components. A tendency of capturing tools such as Wise is to group orphaned COM entries under a “Registry” component. These entries must be corrected and shifted to the correct components. Orphaned entries that associate to files outside of the package must be deleted. Merge Modules should be used whenever possible.
Any COM registration captured under the HKCU section of the registry must be shifted to the HKLM registry section.
Legacy install files
Legacy Install files captured within the created MSI must be removed. This includes files like Setup.exe, setup.ins, Installshield files and all other created log files.
Single feature MSI
A large amount of experience is needed to be able to properly author and MSI into multiple features that will heal properly. It is extremely difficult to create a quality assured process that will adequately ensure that an MSI will heal correctly when multiple features are involved. For this reason, internally captured MSI installations are expected to consist of a single Feature.
Vendor Supplied MSI
Property requirements
All Transformed vendor packages will have the following properties set:
ALLUSERS = 1
PACKAGENAME = Conforms to Package Naming standards
REBOOT = ReallySuppress
ARPNOREMOVE = 1
ARPNOMODIFY = 1
Supporting the Production environment is dependent on standardisation. Removing the ability for applications to be manually “modified” or removed by staff with administrative rights is an important step to ensuring that standardisation remains.
ICE validation
ICE errors within Vendor supplied MSI installers will not be corrected. The correction of these errors could be seen as invalidating Vendor support due to the amount of reconstruction work that can be involved.
No additional ICE errors will be introduced by the creation of an MST.
Table/custom action replacement
Two MSI tables are not to be used within the corporate environment. These tables have shown themselves to be problematic and will be removed from Vendor supplied MSI packages.
LockPermission table
The LockPermission table replaces permissions on the File System or Registry of the target machine. The failing of this table is that it does not consider what permissions already existed and strips everything before placing its own permissions on the workstation. All permissions changes need to be replicated with a utility in the binary table such as SubiNacl.
Self registration table
Self-registration is a script based way to ensure that COM details are registered files that are installed. It does not support any form of healing and causes compatibility issues when used with other applications.
COM registration should be extracted through using a tool such as WiseComCapture.exe and imported into appropriate components within the MSI.
Self registration custom actions
Self Registration is also sometimes achieved through Custom Actions and the commands regsvr32 or msiexec /x or msiexec /y. These have the same effect as using the self registration table and also should be replaced.
Remember that all changes to a Vendor supplied MSI are to be enacted through the use of Transforms and not by directly editing the MSI!
Reboot suppression
Legacy Installshield installers that utilise their own rebooting through the Property RebootYesNo shall have that property set to No. Windows Installer is not to reboot target workstation as this will be controlled by the Software Deliver system.
Deployment Directory Requirements
- All applications deployed shall require two directories, one for application installation and a second for application removal.
- Containing directory structures shall adhere to application naming conventions.
- Directories for the removal of applications shall be appended with the designation “_uninstall”.
Installation directory
An Installation directory will contain:
- The MSI and associated Cab files.
- An MST (if required).
- A Release.txt.
- Install.vbs. (An installation file with appropriate syntax for a silent install) *******
- Any additional scripts required for the application install.
***** NOTE: This was written many years ago ago. Instead of using a standardised VBScript for installing (and removing packages), I would now recommend the ue of the XML Launcher found on this site. The next few paragraphs about Install.vbs and Remove.vbs would be adequite for medium sized orgganisations but we can do much better with modern technology.
There should only ever be one MSI contained within a package directory. An application which requires multiple MSI installers will be broken into multiple, corresponding packages. The only exception is when patches or updates are released for a specific application, in this scenario; the patches will be chained as part of the installation script.
In an attempt to ensure that no software updates or changes occur in an ad-hoc fashion, when application updates are made available, this will generally require the release of a new package into the environment. No changes are to take place to a production package without incrementing the package versioning and name.
Uninstall directory
An Uninstall directory will contain
- Uninstall.vbs.
- Any additional scripts or executables required for cleanly removing the application.
**** Note - this is a point for argument & is depenendent on how your SCCM environment is setup.
Release.txt
A text based file containing application specific information that may be required by support or deployment staff. Any reason as to why an application does not conform to standards must be documented within this file.
Release.txt must also contain instructions as to the needed state of the target workstation such as “user logged out” or if reboots are required before or after the installation of this package.
Any software dependencies must be identified in this text file by their properly formatted application name.
Release notes must contain:
- The Packaging Request number authorising the package to be created.
- The Application name used for the package
- The name of the Packager and person who conducted Peer Review for the package.
- The result of Peer Review testing
- Package dependencies for this package to function correctly
- Any special deployment instructions
- Required Drive mappings needed by the application.
- Software dependencies (identified by the formal package name).
- Any server names hard-coded into the package.
- Details of servers in ODBC entries within the package.
- Justification for any standard that could not be met.
- A requirement of a reboot after the application is installed.
- Requirements for users to be logged out while installation is taking place.
- Information on how we got around any significant, non-standard issues or errors.
Install.vbs
Install.vbs is a standardised installation script used for the deployment of packaged applications. Apart from controlling the installation of the product, the script also controls:
- Uninstall of existing product.
- TaskKill of potentially running executables (normally processes) that could prevent the removal of the product.
- MSI Logging – Verbose logging to C:\Windows\Logs\<Packagename>.log.
- The creation of a 1k signature file on the workstation bearing the application package name with a .sig extension. This provides redundancy to software auditing as many systems have difficulty in auditing software on the basis of specific registry keys.
This signature file also records the name of the user account that installed the application.
Packaging should not just be considered as producing an MSI package. There are some applications or updates that cannot be properly MSI packaged and will have their own special requirements for deployment. The goal of commissioning a package is to produce and “item” that conforms to all internal standards that can be deployed to production workstations independent of further configuration or environmental knowledge. For this reason, just producing an MSI is not considered a completed “package”.
By requiring a package to also have a containing folder that conforms to the naming convention along with a standard installation script that is always what needs to be invoked guarantees that standardisation of software delivery is achieved. There is no requirement for Software Delivery “loading” of packages to differ in anyway in handling completed packages (such as different installation switches and configuration).
Uninstall.vbs
Uninstall.vbs is a standardised installation script used for the deployment of packaged applications into the environment. Apart from controlling the installation of the product, the script (within a package’s corresponding “_uninstall” directory also controls:
- Uninstall of existing product.
- “Task Kill” of potentially running executables (normally processes) that could prevent the removal of the product.
- MSI Logging – Verbose logging to C:\Windows\Logs\<Packagename>.log.
- Creation of Active Setup entries that will clean the user profile of registry entries that could cause problems after the removal of this application. An example is with Excel Add-ins where keys must be removed for each user of that machine if an Add-in no longer exists.
- The removal of Signature Files.