Using setup.exe and a custom config.xml to setup SharePoint is easy and worth it if you need to automate or standardize your SharePoint Server 2010 installations. Microsoft's guides on setup.exe and config.xml are great resources and do a good job of explaining all the available options. (I can wait while you read them over.)
Like MOSS 2007, SharePoint 2010 can be installed from the command line using setup.exe and a customized config.xml. Not much has changed between versions, so if you're already familiar with the process (MOSS 2007 setup.exe and MOSS 2007 config.xml) you're more or less ready. You will want to setup SharePoint from the command line when:
- automating the installation
- planning the configuration before the actual installation, such as when different groups are responsible for configuration (architects) and installation (implementors)
- standardizing an installation configuration for more than one server, usually in the same farm (all servers in the farm need the same installation configuration), but also for single-server farms that may need to be identical (development environments)
- you need to use installation options that are not available through the setup.exe GUI
As well as installation, setup.exe can be run from the command line to modify, repair, or uninstall an existing installation, though I'll skip over these in this guide.
When installing SharePoint, the only setup.exe switch that concerns us is /config. /config points setup to the config.xml file:
setup.exe /config path\to\config.xml
The path to config.xml can be a relative (.\configurations\myfarm.xml), an absolute (C:\xml\config-intranet.xml), or a UNC (\\IT\SharePoint\configurations\development-config.xml) path to an xml file with the configuration. The file doesn't have to be called config.xml so you can give it a name that holds more meaning. The config.xml documentation also says you can put config.xml in the same directory as setup.exe and it will use this ("Setup looks for a copy of Config.xml in the same folder as Setup.exe."). When I tried, setup.exe never used my config.xml unless I used the /config switch. Maybe this is a bug with setup.exe or the documentation.
Setup.exe is straightforward. Config.xml is where all the action happens.
Config.xml is where you can specify options for how SharePoint will install and how the installer will behave. There are some example config.xml files included with the SharePoint media in the Files folder. These are pretty simple, and you'll see this is the case with most config.xml files.
Some key points about the format of the XML:
- Elements are case-sensitive. This is important, because if you don't match the case of the element, bad things happen. Really bad things: XML errors.
- Attributes are case-sensitive. Setup.exe will generate errors if you misspell attributes.
- Attribute values must be in double quotes and are not case sensitive.
The config.xml file is made up of XML elements! Elements such as: Configuration, Package, INSTALLLOCATION, DATADIR, Display, Logging, PIDKEY, ARP, and Command.
This element is the top-level element, is required, and contains all the other elements. The Configuration element has no attributes. All other elements will nest inside the Configuration element. There is one Configuration element per config.xml.
<Configuration> ... Other elements ... </Configuration>
A Package element defines a product setup.exe will install. Config.xml can contain multiple Package elements so you can install multiple products. In SharePoint's case, setup.exe considers SharePoint Foundation and SharePoint Server two different products, so there are two package Ids:
- "sts" - SharePoint Foundation 2010
- "spswfe" - SharePoint Server 2010
<Package Id="sts"> ... SharePoint Foundation package settings ... </Package> <Package Id="spswfe"> ... SharePoint Server package settings ... </Package>
The INSTALLLOCATION (note the three Ls) element tells SharePoint where to install itself. The Value attribute specifies the path. Default path is "%PROGRAMFILES%\Microsoft Office Servers\14.0\". In the GUI installer's File Location tab INSTALLLOCATION is the first path.
EXTRA SUPER IMPORTANT INFORMATION
Even if you use the INSALLLOCATION element, SharePoint Foundation will still install the 14 hive to "%COMMONPROGRAMFILES%\Common Files\Microsoft Shared\Web Server Extensions\14". This doesn't appear to be customizable, and can be confusing, especially in organizations that install applications to drives other than C:. In these scenarios, if %COMMONPROGRAMFILES% points to "C:\Program Files\Common Files" (as it does by default), the 14 hive will install to the C: drive no matter what you do. This install is only a couple hundred MB, it's not very big at all. If you really want this somewhere else, you will need to change the location of %COMMONPROGRAMFILES% before installing SharePoint. I would test this before trying it in a production environment, as there's a possibility it won't work. If you're feeling clever, before running setup create a volume mount point for the 14 folder. This will add complexity that may not be obvious at first as the volume mount point is invisible to everything except the Disk Management snap-in. I've never tried this before, so be warned this isn't a recommendation.
<INSTALLLOCATION Value="D:\Program Files\Microsoft Office Servers\14.0" />
DATADIRThe DATADIR element lets you specify a folder for the data files. This is where SharePoint stores the index files and usually most farms will want to place this somewhere that has sufficient disk space. In the GUI installer, this is the second file location. By default, it installs to %PROGRAMFILES%\Microsoft Office Servers\14.0\Data. This folder has to be the same on all servers in the farm Value attribute specifies the folder where data files will reside.
<DATADIR Value="D:\Program Files\Microsoft Office Servers\Data" />
If you're configuring config.xml, it's likely you want some sort of unattended abilities. The Display element provides this by allowing you to disable certain prompts and confirmations, accept the EULA, and set the type of GUI the user will see. There are five attributes: Level, CompletionNotice, SuppressModal, NoCancel, and AcceptEula. The latter four are explained well in the documentation, and I have nothing more to add. Level has some nuances that I'll describe.
The Level attribute has three settings: None, Basic, and Full
|None||A full unattended installation. There is no UI, and the only evidence that anything is happening is setup.exe appears as a running process in Task Manager. Use this option if you don't need any user input and you don't want to run the SharePoint Configuration Wizard once installed (since you scripted this part as well...). [Updated below with PowerShell details on waiting for setup.exe to finish]|
|Basic||The Basic Level allows you to provide a limited UI to the user, generally if you have specified some settings already (like INSTALLLOCATION or PIDKEY) and you don't need the user to supply these. If you specify everything the Basic UI is simply a progress bar. This is handy as it lets administrators know the status of the installation at a glance. An issue I have observed is with running the SharePoint Configuration Wizard at the end. Normally there is a window at the end of the installation (the CompletionNotice) which allows you to start SPCW when you click finish, unless you uncheck "Run the SharePoint Products Configuration Wizard now". If you chose Basic and set CompletionNotice to "Yes", you'll see this window — not very unattended. If you set CompletionNotice to "No", then SPCW will automatically start — which is even worse. I recommend you don't use Basic if you want an unattended installation.|
|Full||Displays the UI, and if you provide the server type (Setting Id="SERVERROLE"), file locations (INSTALLLOCATION, DATADIR), product key (PIDKEY), or accept the EULA in the config.xml, setup.exe will populate (or accept) these fields in the UI automatically. In this respect, the only difference between Basic and Full is that Basic won't prompt for these values if specified, where as Full allows the user to make changes.|
<Display Level="Basic" CompletionNotice="No" SuppressModal="Yes" NoCancel="No" AcceptEula="Yes" />
The logging element is self-explanatory. By default SharePoint install will create its log in %temp%. Use this if you want more verbose logging or want to save the logs somewhere other than the default. If you're doing an unattended install, I recommend the verbose logging. Actually, I recommend the verbose logging in general as the log is only a two MB and it makes for some good nighttime reading.
<Logging Type="Verbose" Path="D:\Logs\SharePoint Install Logs" Template="Setup-Custom-ConfigXML-*.txt" />
Used for specifying the Windows Installer properties, the Setting element is the most confusingly documented of all the elements as some options can be specified within a Package element or globally within the Configuration element, and some parts don't really explain what the setting does so you'll probably walk away with more questions than when you started (I've tried answering the questions I had here). The Setting element has two attributes: Id and Value (again, note these are case sensitive). For each option, you need a separate Setting element.
There are only two package settings, LAUNCHEDFROMSETUPSTS, and SETUPCALLED.
|Setting Id||Setting Value|
|LAUNCHEDFROMSETUPSTS||The full description on TechNet is, "Use as part of the Package Id attribute. The default is Yes." When I read that I was reminded of every introductory programming language where the instructor presents the topic of comments and shows examples of bad comments. That is a bad comment. What does this do? Well, honestly, I have no idea. What I do know, is that it is required in the Package element for SharePoint Foundation 2010 (sts). If you specify it (and you must), then you need to set it to "Yes".|
|SETUPCALLED||Another wonderfully documented attribute: "Use as part of the Package Id attribute." This attribute is requred in the SharePoint Server Package element (spswfe), and needs to be set to "1".|
|OFFICESERVERPREMIUM||When I said two, I meant two plus an undocumented setting which may or may not actually do anything. OFFICESERVERPREMIUM was part of the MOSS 2007 config.xml, but it no longer appears in the SharePoint 2010 documentation. When set to "1", it would install Enterprise, and when set to "0" install Standard. Since the product key is keyed to the edition, this isn't needed. I only mention it because you'll find it referenced online a lot and it's used in AutoSPInstaller. Whether it works or is ignored doesn't really matter; if you include it nothing bad will happen since the product key is all that matters.|
The package settings for installing SharePoint Server will look exactly like this:
<Package Id="sts"> <Setting Id="LAUNCHEDFROMSETUPSTS" Value="Yes" /> </Package> <Package Id="spswfe"> <Setting Id="SETUPCALLED" Value="1" /> </Package>
Most of the available settings are global and apply to the entire install, regardless of what we're installing.
|Setting Id||Setting Value|
|SETUPTYPE||It's most likely you'll be using a CLEAN_INSTALL. Only use V2V_INPLACE_UPGRADE if you're upgrading from MOSS 2007, and SKU2SKU_UPGRADE if upgrading from SharePoint Foundation 2010 to SharePoint Server 2010. These options exist because there are a lot of you out there who want to do this. In 2007 there was also the V2V_GRADUAL_UPGRADE setup type, which no longer is a thing, so please do not use.|
|SERVERROLE||Hmm... SINGLESERVER or APPLICATION? Well, this server will be a WFE ... so APPLICATION doesn't make sense... hmm. Let's try SINGLESERVER. WRONG. It's bad enough you're prompted twice in the GUI to fall into this trap, but even in the config.xml Microsoft is trying to trick you into a standalone install. While it's theoretical you may want to install SQL Express with your copy of SharePoint Server 2010 Enterprise, I will argue that you probably do not want to use SINGLESERVER. Select APPLICATION (The 2007 role, WFE, was removed in 2010. Don't use WFE or you will hurt setup.exe's feelings).|
|USINGINSTALLMODE||Set this to 0 if you are doing a silent install (Display Level="None"), and set to 1 if you are doing Level="Basic" or "Full". Actually, in my tests it doesn't look like it makes a difference, setup will use whatever is specified in the Display element.|
|SETUP_REBOOT||SETUP_REBOOT lets you control how the server will restart following setup. Your options are Never, AutoAlways, Always, AutoIfNeeded, and IfNeeded. It's your call if you want the server to restart. Usually in a fresh install there is no restart required, but it's likely in an upgrade scenario. If you want your unattended installation to proceed with other steps once SharePoint is installed, you may not want to restart at this point. Here's what each option does (not documented, but it just so happens to be mentioned in the Setup properties in Office 2010 page on TechNet):
|REBOOT||Just in case you really don't want the server to restart, set REBOOT to "ReallySuppress". In combination with SETUP_REBOOT set to "Never", the setup will not restart the server.|
|AllowWindowsClientInstall||Is this another undocumented setting? When set to "True" AllowWindowsClientInstall will allow you to install SharePoint on Windows Vista or Windows 7. You'll probably never use this but it's requisite knowledge if you want to compete in your local SharePoint trivia night at the bar.|
<Setting Id="SETUPTYPE" Value="CLEAN_INSTALL" /> <Setting Id="SERVERROLE" Value="APPLICATION" /> <Setting Id="USINGINSTALLMODE" Value="1" /> <Setting Id="SETUP_REBOOT" Value="Always" /> <Setting Id="REBOOT" Value="ReallySuppress" /> <Setting Id="AllowWindowsClientInstall" Value="True" />
This element lets you specify the SharePoint product key. This is required if performing an automated install (Display Level="None" or "Basic"). The product key is 25 characters (ignoring the hyphens) and can be written with the hyphens if you wish. Remember, if you use the PIDKEY element, you are saving your product key in a text file on one or more servers. To be safe, make sure you properly secure this file with NTFS ACLs or delete the file after use. There is no way to encrypt this key, so don't store it in a world-readable fileshare unless you're cool with this. In my examples, I use the Enterprise Trial key that is available from the Microsoft SharePoint Server 2010 Trial download.
<PIDKEY Value="VK7BD-VBKWR-6FHD9-Q3HM9-6PKMX" />
The ARP element lets you play around with how SharePoint is displayed in Add or Remove Programs in Control Panel. The documentation is self-explanatory so I won't go into details, so configure if you wish. I will point out one warning: generally you do not want to prevent the display of the remove or change buttons in Add or Remove Programs unless you are 110% sure you will never need these. If you do remove them, you can run setup.exe to remove or change the installation.
With the Command element, you can run another command once setup is done. Don't use this element. The examples given are to move log files or launch a welcome page at the end of the install, but since it's likely you're automating the installation already, do this in your automation script so you can control for errors and other fun things. Use this element only if you know what you're doing. I won't even show an example because I personally don't have a use for it.
Let's try it outNow that all that is out of the way, here is an example config.xml that I made for my demo farm for my blog posts.
<!-- BlogFarm-config.xml Author: Jason Warren Last modified: October 7, 2011 This is the SharePoint Server 2010 config.xml file used for the "blog farm" I created for demonstrating how to use config.xml and for future how-to articles for the Habanero blog (http://www.habaneros.com/blog) References: Config.xml reference (SharePoint Server 2010) http://technet.microsoft.com/en-us/library/cc261668.aspx --> <Configuration> <!-- SharePoint Foundation 2010 Configuration --> <Package Id="sts"> <Setting Id="LAUNCHEDFROMSETUPSTS" Value="Yes" /> </Package> <!-- SharePoint Server 2010 Configuration --> <Package Id="spswfe"> <Setting Id="SETUPCALLED" Value="1" /> </Package> <!-- Display: Level: None (completely unattended) CompletionNotice: No (I want to continue on once complete) SuppressModal: Yes (I don't want error messages to stop install) NoCancel: Yes (Does nothing since window is not visible) AcceptEula: Yes (doesn't matter because I have the product ID) --> <Display Level="None" CompletionNotice="No" SuppressModal="Yes" NoCancel="No" AcceptEula="Yes" /> <!-- (Windows Installer) Settings: Setup Type: Clean Install (not an upgrade) Server Role: Application (server is in a farm, not standalone) Using Install Mode: 1 (Basic UI) Setup Reboot: Automatically reboot if needed --> <Setting Id="SETUPTYPE" Value="CLEAN_INSTALL" /> <Setting Id="SERVERROLE" Value="APPLICATION" /> <Setting Id="USINGINSTALLMODE" Value="1" /> <Setting Id="SETUP_REBOOT" Value="AutoIfNeeded" /> <!-- SharePoint Server 2010 Enterprise Product Key (Trial) --> <PIDKEY Value="VK7BD-VBKWR-6FHD9-Q3HM9-6PKMX" /> <!-- Installation Folders. Everything (except the 14 hive) on D: --> <INSTALLLOCATION Value="D:\Program Files\Microsoft Office Servers\14.0" /> <DATADIR Value="D:\Program Files\Microsoft Office Servers\Data" /> <!-- Logging: Type: Verbose (I want it all, because I am not halting on errors) Path: Put it on D: as well Template: Setup-Custom-ConfigXML-YYYYMMDDHHMMSSxxx.txt --> <Logging Type="Verbose" Path="D:\Logs\SharePoint Install Logs" Template="Setup-Custom-ConfigXML-*.txt" /> </Configuration>
- Setup command-line reference (SharePoint Server 2010)
- Config.xml reference (SharePoint Server 2010)
- Setup.exe command-line reference (Office SharePoint Server)
- Config.xml reference (Office SharePoint Server)
- Setup properties in Office 2010
- Microsoft Download Center: Microsoft SharePoint Server 2010 Trial
I originally had planned to write a post about using PowerShell to monitor the setup.exe process and hold off proceeding until it completed. This would be useful when scripting an unattended setup and only starting the farm creation once setup completes.
When I started looking at the PowerShell process cmdlets, I quickly realised that the Start-Process cmdlet has a -Wait parameter, which stops futher execution of the script until the process exits.
So for quick example, if you run setup.exe with a custom config.xml file from a PowerShell script, it could look something like this:
Start-Process .\setup.exe -ArgumentList "/config config.xml" -Wait
Once setup.exe finishes you can proceed with loading the Microsoft.SharePoint.PowerShell snapin and configuring the farm.