Using SharePoint 2010’s Catastrophic Restore Cmdlets

Restore-SPFarm

The Restore-SPFarm cmdlet is the yang to Backup-SPFarm’s yin, the white to its black, the 1 to its 0. You get the idea, right? Backup-SPFarm makes the backups, and Restore-SPFarm restores them. Neat, huh? Now, there is one other interesting thing about Restore-SPFarm worth noting: there is no Restore-SPConfigurationDatabase, so if you’ve made a configuration backup with Backup-SPConfigurationDatabase, you need to restore it with Restore-SPFarm just like you would a SharePoint 2010 backup that includes both content and configuration data. Whether you’re restoring content or configuration data, the options for Restore-SPFarm are the same; you’ll find that you can use its two parameter sets for either situation. Following is an example of Restore-SPFarm in action to perform a restore of the most recent backup file in the target directory:

Restore-SPFarm -Directory \\foo\backups\ -RestoreMethod New

The list that follows outlines the details of the first parameter set for Restore-SPFarm, which actually restores a backup file.

• Directory. When you’re performing a restore with Restore-SPFarm, this parameter is required (unless the –ShowTree parameter is provided; see the next list for further information). This parameter indicates the location of the backup to be restored. The target directory can be on the file system if SharePoint is installed on the same server as its back-end database; otherwise, it must be a UNC shared directory. This directory can store multiple backups for your farm. The most recent backup is used unless a BackupID parameter is also provided.

• RestoreMethod. When you’re performing a restore with Restore-SPFarm, this parameter is required (unless the –ShowTree parameter is provided). Acceptable input parameter values are New or Overwrite, and they determine whether you are restoring the backup to a different farm (the New option) or to the current farm (the Overwrite option). You should use the Overwrite option when you are restoring the backup to the same farm that the backup was created with; if you are restoring the backup to a different farm, use the New option.

• NewDatabaseServer. This input parameter is not required and can be used only with the RestoreMethod parameter. When used, it is set as the default database instance for the restored farm.

• AssignmentCollection. This is an optional parameter, intended to allow for the proper disposal of objects. Carefully consider using this parameter if your call of Restore-SPFarm also involves using SharePoint’s SPWeb, SPSite, or SPSiteAdministration objects; otherwise, it is not likely to be necessary.

• RestoreThreads. This parameter, which must be an integer from 1 to 10, is not required. It determines the number of threads SharePoint uses to complete the restore operation. If no RestoreThreads value is provided, SharePoint defaults to three threads.

• ConfigurationOnly. This is an optional parameter that does not actually require an input value to be provided for it. If you use this switch, the cmdlet only restores the configuration data for the item targeted, whether that is the full farm or an individual component of that farm. If you are restoring a backup created with the Backup-SPConfigurationDatabase cmdlet, you must use this switch to properly restore the configuration backup. Remember: restoring a farm’s configuration data does not include its service applications or Web applications. You must re-create these items or restore them via content backups after the configuration backup is complete to return them to your farm.

• Confirm. This is an optional parameter. If this parameter is used with an input value of True, the cmdlet prompts the user to confirm that he wants to proceed with the action. If a value of False is provided, the cmdlet proceeds without prompting for permission once executed. The default value for this parameter is False.

• Force. This is an optional parameter that does not actually require an input value to be provided for it. If this switch is not used, the cmdlet does not proceed with the restore operation if it is going to overwrite an existing SharePoint 2010 farm. If it is used, that check is overridden, and the restore is executed no matter what.

• Item. This parameter is not required. By default, if no item is specified, the entire farm is restored. If an Item input parameter is provided to specify the SharePoint component to be restored, it must be a valid item in the farm. If the item has spaces in its name, the entire item must be enclosed within quotation marks (“ ”). If the exact name or path for the desired component is unknown, you can use the ShowTree switch to list the components available within the farm.

  Tip

  If you are using the Item parameter to restore a farm’s Secure Store Service, you must refresh the store’s passphrase with the Update-SPSecureStoreApplicationServerKey cmdlet after you have successfully restored it.

  
  

• Percentage. This input parameter is not required. If a value is specified for the Percentage input parameter, it must be an integer between 1 and 100 and is used to determine the frequency with which Restore-SPFarm reports progress of the restore operation. For example, specifying a value of 20 displays the progress of the restore operation for every 20 percent of the operation that is completed. If no Percentage parameter is specified, STSADM.exe defaults to reporting progress every 5 percent of the operation. This input parameter has no affect on the outcome of the restore operation; it only affects the amount of information that the cmdlet reports about its activities during the operation. SharePoint is not able to calculate the completed percent of the restore operation with 100 percent accuracy. You may find that your actual progress updates do not appear with exactly the requested frequency.

  Tip

  For large SharePoint components, Microsoft recommends that a Percentage input of 1 be used to provide the best status data about your restore operation.

  
  

• BackupID. This input parameter is not required. If you use it, it must be a valid GUID for a backup package in the storage directory indicated by the DirectoryGet-SPBackupHistory cmdlet, discussed later in this parameter. If no BackupID parameter is used, the cmdlet selects the most recent backup in the target directory.

• FarmCredentials. This input parameter is not required. If you use it, this parameter indicates the credentials that the farm employs once it is restored, such as application pools for restored SharePoint Web applications. If a Web application’s application pool already exists, this data is ignored, and the farm uses the existing credentials.

• WhatIf. This is an optional parameter. If this parameter is used, PowerShell displays a message stating what the outcome of running the cmdlet will be, but the cmdlet itself is not executed. This can be helpful when testing scripts, allowing you to verify that you can provide the correct set of inputs and parameters to the cmdlet.

The second parameter set for Restore-SPFarm is best used to obtain valuable information about your farm for restoring it, rather than an actual restore operation. The key parameter in this set is the –ShowTree parameter; its presence indicates that the second parameter set is being used instead of the first.

• Directory. When you’re performing a restore with Restore-SPFarm, this parameter is required (unless the –ShowTree parameter is provided; see the next bullet for further information). This parameter indicates the location of the backup to be restored. The target directory can be on the file system if SharePoint is installed on the same server as its back-end database; otherwise, it must be a UNC shared directory. This directory can store multiple backups for your farm, the most recent backup is used unless a BackupID parameter is also provided.

• ShowTree. This is an optional parameter. If the ShowTree parameter is included with the call of Restore-SPFarm for a restore, the cmdlet does not complete a restore of any SharePoint components. Instead, it displays the components in the target backup package so that you can use their names to request a restore. If a value is specified via the Item parameter, any components that are not children of that input are excluded and marked with an asterisk (*). Any components that cannot be restored are enclosed within square brackets ([<item that can’t be restored>]).

• AssignmentCollection. This is an optional parameter. It is used with this parameter set in the same way that it is in the first parameter set.

• ConfigurationOnly. This is an optional parameter. It is used with this parameter set in the same way that it is in the first parameter set.

• Item. This is an optional parameter. It is used with this parameter set in the same way that it is in the first parameter set.

• WhatIf. This is an optional parameter. It is used with this parameter set in the same way that it is in the first parameter set.

Restore-SPSite

If you think of the Restore-SPFarm cmdlet as peanut butter is to the Backup-SPFarm cmdlet’s jelly, the Restore-SPSite cmdlet is the bacon to the Backup-SPSite cmdlet’s eggs—two great tastes that are great together. When you need to restore a site collection backup created with Backup-SPSite, you’re going to use Restore-SPSite. Makes sense, right? In fact, Restore-SPSite is the only way to restore a site collection backup created with SharePoint’s out-ofthe-box tools; you can’t restore that backup through the Central Administration site or with SQL Server’s management tools. Here’s a quick example of Restore-SPSite in action:

Restore-SPSite - Identity http://bar/sites/foo -Path \\foo\backups\bar.bak

The list that follows outlines each parameter available to be used with the Restore-SPFarm cmdlet and the possible options you can use for each parameter:

• Identity. When you’re restoring a site collection backup, this parameter is required and is the URL that you want users to enter when accessing your restored site collection. You can restore Backup-SPSite’s site collection backups to a new URL and attempt to update all the paths within the backup package to reflect the new URL for the site collection, as long as SharePoint is able to create a site collection at that path. Make sure to fully test the restored site collection’s resources that depend on this information, such as links, navigation controls, and search results, to confirm that all the collection’s data was correctly updated to the new path. You can also use a URL for an existing site collection, which completely overwrites the existing site collection, but you must use the Force parameter to enable this action.

• Path. When you’re restoring a site collection, this parameter is required and must be a valid UNC or Windows file path to a backup package created via Backup-SPFarm.

• AssignmentCollection. This is an optional parameter, intended to allow for the proper disposal of objects. Carefully consider using this parameter if your call of Restore-SPSite also involves using SharePoint’s SPWeb, SPSite, or SPSiteAdministration objects; otherwise, it is not likely to be necessary.

• HostHeaderWebApplicationURL. When you’re restoring a site collection backup, this parameter is not required. You use it if you want to restore your site collection to a Web application with a different URL than the value specified for the URL input parameter. This parameter is explained in more detail later.

• Confirm. This is an optional parameter. If it is used with an input value of True, the cmdlet prompts the user to confirm that he wants to proceed with the action. If a value of False is provided, the cmdlet proceeds without prompting for permission once executed. The default value for this parameter is False.

• ContentDatabase. This is an optional parameter. If this parameter is used, the site collection is provisioned within the content database matching the value provided. If the parameter is not used, the site collection is automatically placed in the content database with the least number of site collections in it and a status of Ready.

• Force. When you’re restoring a site collection backup, this switch is not required. Using it instructs Restore-SPSite to overwrite any existing site collection matching the value of the URL parameter.

• GradualDelete. This optional parameter alters the mechanics of the restore operation when you also employ the Force parameter. When you execute a site collection restore that overwrites an existing site collection, two sets of operations take place at the database level. The first set of operations entails the deletion of all existing items within the target content database that are tied to the site collection being overwritten. Once the existing site collection data is deleted, the second set of operations that take place involve the actual restoration of the site collection and the insertion of new rows into the content database. Without the use of the GradualDelete parameter, the delete and insert operations execute in serial fashion. Because the deletion of existing content throughout the content database can take a significant amount of time, poor performance on restore may result. When you employ the GradualDelete parameter, however, the deletion of existing site collection data from the content database is effectively deferred until after the restore operation has taken place. Deferred deletions are handled by a Gradual Site Delete timer job that is established and defaults to running daily for each Web application in the farm. Deferring deletion of site collection content can result in significant performance increases, particularly when a substantial amount of existing site collection content resides in the content database. Using this parameter when overwriting an existing site collection can reduce the performance impact of the operation on the SharePoint servers in your farm, as well as on SQL Server. Microsoft recommends using this parameter when restoring large site collections; we recommend that you test this parameter whenever possible to assess its impact and implications on the usability of a target site collection before using it in a production environment.

• WhatIf. This is an optional parameter. It is used with this parameter set in the same way as it is in the first parameter set.

You can use the HostHeaderWebApplicationURL parameter to restore a site collection to a URL different from the URL of its parent Web application. If you pass a value of http://bar for the HostHeaderWebApplicationURL parameter as an addition to the previous example, the restore operation creates a site collection for the foo address under the bar Web application even though they have different URLs. When it runs the restore operation, Restore-SPSite generates a host header for the target Web application in IIS so that requests submitted to the server for http://foo are mapped to the restored site collection even though it is within a Web application with a different URL (http://bar).

SharePoint site collections created using a host header in this fashion are called host-named site collections. Unlike normal site collections, host-named site collections use IIS host headers to direct traffic to the correct site collection instead of managed paths. This allows multiple site collections within a single Web application to have a unique URL that can be used to access its content independent of the other site collections in the Web application. Keep in mind that there are some drawbacks to host-named site collections; they are not compatible with alternate access mappings (AAMs) or the use of any zone other than the Default zone, so each site collection can only respond to traffic on a single URL. For more information on host-named site collections and their impact on the architecture and administration of your SharePoint farm, review this article from the Microsoft Knowledge Base: http://technet.microsoft.com/en-us/library/cc424952.aspx.

Restore-SPSite also has a second parameter set available for use, although it includes most of the same parameters and options as the first set. This second set allows for more control over what SharePoint content database the site collection is stored in when the cmdlet restores it. The only parameter from the first set not used by the second set is ContentDatabase. It is replaced by the two parameters listed next. (All the other parameters from the preceding list above can be used in conjunction with these two parameters as desired.)

• DatabaseName. This is an optional parameter. If you use this parameter, the site collection is provisioned within the content database matching the value provided, as long as it is a valid database name. If the parameter is not used, the site collection is automatically placed in the content database with the lowest number of site collections and a status of Ready.

• DatabaseServer. This is an optional parameter. It is used to specify the SQL Server instance that contains the database provided by the DatabaseName parameter. The value provided for this parameter must be a valid SQL Server instance that the farm can access. Furthermore, a valid value must be provided for the DatabaseName parameter for the cmdlet to successfully use this parameter.