SharePoint

Powerful Command Line Administration for SharePoint

Todd Klindt

At a Glance:

• Configuring SharePoint with STSADM
• Scripting daily administrative tasks
• Advanced STSADM Operations

Think about how people interact with Windows or Microsoft Office. Some users are avid mousers, using the pointer to navigate menus and toolbars to perform common tasks. Others are comfortable

with the keyboard, quickly executing familiar keystrokes and shortcuts. For any given task, there is almost always several ways to get it done.

The fact is, a graphical interface can be easy to use, but it can be equally cumbersome for tasks that require you to do the same thing repeatedly. Some things are easier to do with the keyboard. If you do any SharePoint® administration, you've probably experienced what it's like to be bogged down in a graphical interface. But SharePoint actually offers a more powerful way to get things done.

The primary interface for managing Windows® SharePoint Services (WSS) and Microsoft® Office SharePoint Server 2007 (MOSS) is the GUI-based SharePoint Central Administration. But SharePoint also includes a command-line tool for more powerful administration. This tool, STSADM.exe, provides all the functionality of SharePoint Central Administration, but with the command-line flexibility many administrators desire. In this article, I will give you a crash course in using STSADM to manage WSS and MOSS. I'll also give you some tips on how to configure your environment and discuss some common STSADM commands. I will even show you some advanced STSADM commands that can make you look like a hero-if the need to use them ever arises.

Getting Started

If you haven't stumbled upon STSADM, it could be because it is somewhat buried. In Windows SharePoint Services 2.0, it's in c:\program files\common files\microsoft shared\web server extensions\60\bin by default. The default location in version 3.0 is c:\program files\common files\microsoft shared\web server extensions\12\bin.

To simplify access to this tool, I use two different approaches. First, I simply add that directory to my PATH environment variable. This way I can use STSADM wherever I am in the file system. This, however, is not always an option. My second approach is to create a shortcut to CMD.EXE and set STSADM's location as the initial directory. Why not just point a shortcut directly to STSADM? This doesn't work since STSADM is not interactive. As a result, if you do point a shortcut directly to STSADM, you will be presented with a quick display of its usage and then it will be gone.

When you run STSADM, you need to be a member of the local Administrators group on the Web server, and you need to execute the app locally. This means you cannot use STSADM to remotely administer a SharePoint server.

To see what operations you can perform with STSADM, type stsadm.exe -help in a command prompt. Be sure to check this list after you apply updates and hotfixes to SharePoint since new operations may be added. There is also a handy guide to stsadm.exe operations available at go.microsoft.com/fwlink/?LinkId=77516.

STSADM Basics

Let's start by looking at some of the commands you might use to tweak your existing SharePoint installation. You can use STSADM to add functionality to SharePoint and to modify configuration settings.

STSADM uses the -o parameter followed by the operation you want to perform. Just typing STSADM -operationname will not work. If, for example, you want to add site templates to your installation, you can use the following command:

Stsadm -o addtemplate -filename <filename of the template> 
-title <title of template> -description <description of template>

Or, if you want to add a Web Part Package, you can use this command:

Stsadm -o addwppack -filename <filename of the Web Part Package>

For details on usage for any operation, simply pass the operation with no parameters and STSADM will tell you what it expects for input. STSADM -help operationname will also give you usage info.

When managing templates, you can use the enumtemplates operation to see which templates have been added and deletetemplate to remove any that are installed. Similarly, there are commands to work with Web Part packages. You can use the enumwppacks operation to list the Web Part packages installed on each virtual server or Web application, and deletewppack will let you remove any that have been added.

STSADM also has two operations that deal with SharePoint settings: setproperty and getproperty. Executing either with no parameters will give you a list of the properties you can view or manipulate. Like STSADM itself, this list changes with updates and hotfixes. Nevertheless, there are a few properties that are more useful than others. Figure 1 lists some of the properties you may want set after you get SharePoint installed, including the most common properties I hear SharePoint administrators ask about.

Figure 1 Setting Useful SharePoint Properties

Let's take a quick look at using one of these properties. The following command will have SharePoint send out immediate alerts every 10 minutes:

Stsadm -o setproperty -pn job-immediate-alerts -pv "Every 10 minutes"

Notice I used -pn and -pv instead of -propertyname and -propertyvalue. These are acceptable shortcuts for those times when you don't want to type the entire word. Also note that all the examples and commands I have discussed in this section will work for both versions 2.0 and 3.0 of Windows SharePoint Services.

Daily Administration

Day-to-day SharePoint administration is pretty easy. For most SharePoint administrators, the bulk of daily tasks consist of working with users and sites. STSADM has several operations to streamline these tasks.

I'll start with sites and webs. For purposes of consistency, I will use "site" to refer to site collections and "web" to refer to subsites (also known as subwebs). Some of the terminology is tricky, but if you stay consistent with what STSADM uses, it will be easier to find the command you need.

If you run a large SharePoint installation, you probably spend a lot of time creating new sites for users. I know I find myself repeatedly doing this. Creating new sites can be done quite easily in SharePoint Central Administration. But since I perform this task so often, I find it faster to use STSADM to get the job done.

I use the createsite operation. This is quite simple and takes the following parameters:

• url <url>
• ownerlogin <DOMAIN\name>
• owneremail <someone@example.com>
• ownername <display name>
• lcid <language>
• sitetemplate <site template>
• title <site title>
• description <site description>
• quota <quota template>

You can bring these up at the command prompt by typing stsadm -help createsite (see Figure 2). Of these nine parameters, the only mandatory fields are URL, ownerlogin, and owneremail.

Figure 2** Createsite Parameters **(Click the image for a larger view)

If you have sites that you create on a routine basis, you can go a step further in streamlining the process by writing a wrapper script around STSADM to automate the task. For instance, to automate the creation of personal sites, you can save the following to a text file named createpersonalsite.cmd:

stsadm -o createsite -url https://localhost/users/%1 -ownerlogin contoso\%1 
-owneremail %1@contoso.com -sitetemplate usersite.stp 
-title "Personal site for %1" -description "Personal site for %1" -quota "500 MB"

And then to create a site for the user jsmith, you could simply execute the following:

createpersonalsite.cmd jsmith

By scripting site creation, you save yourself a lot of typing and can make sure all your newly created sites are consistent. The operation createweb provides the same functionality at the web level.

In Windows SharePoint Services 2.0, the only easy way to get an exhaustive list of the site collections on a particular virtual server is to use STSADM. Enumsites lists in XML format all of the site collections on a specific virtual server or Web application. This can be coupled with a Data View Web Part to easily view a list of site collections. (See the sidebar "Working with a Data View Web Part" for more information.)

STSADM provides a deletesite operation for, as you can guess, removing sites. All you need to do is provide the URL. Optionally, you can pass it -deleteadaccounts to have the accounts deleted in Active Directory®. When working with webs you would use the deleteweb operation.

You can also add, delete, and enumerate the users of a site or web. The associated operations are adduser, deleteuser, and enumusers. These operations are handy if users need to be added to a site in bulk, or if you need to maintain a list of users who have access to a site for auditing purposes.

When working with webs you have access to an additional operation, renameweb, that lets you change the name and URL of a web. For example, to rename a web from "oldname" to "coolnewname," use the following:

Stsadm -o renameweb -url https://localhost/oldname -newname coolnewname

This can be a life saver when project names change or business units are realigned. In Windows SharePoint Services 2.0, this is a big issue, as the only way to migrate webs is with SMIGRATE.exe, which does not maintain any user-related settings like membership or alerts. With Windows SharePoint Services 3.0, this is less of an issue, as STSADM can back up and restore webs and sites.

Backing Up and Restoring

One of the best uses for STSADM is backing up and restoring sites and webs. For small to medium-sized installations, this functionality can be the cornerstone of a disaster recovery plan. The backup operation is self-explanatory and very easy to use. Simply tell STSADM which site to back up and where to write the backup file, like this:

Stsadm -o backup -url https://localhost -filename site.bak

This operation dumps the entire site collection to the file site.bak. It includes all site content, such as webs, document versions, lists, and users. It does not back up any site definitions or changes you've made at the file system level of your servers.

While the backup operation is important, it does have a few snags to keep an eye on. If the site is large enough, the Content Database may be locked during the backup process. This may prevent users from accessing any sites in that database until the backup operation is finished. This issue has been mitigated with service packs, but it is still something to keep an eye on as your sites grow. STSADM also uses the server's temp directory when doing backups and restores, so monitor your drive space.

Working with a Data View Web Part

You can couple the enumsites command with a Data View Web Part to create an easy way to view a list of site collections. Let's see how.

First, create a scheduled task that runs:

stsadm –o enumsites –url https://localhost
>c:\inetpub\wwwroot\excludedsite\sites.xml 

Make sure the XML file is being written out to a directory that is published with IIS, but not managed by SharePoint. Then use Microsoft FrontPage® (or the FrontPage successor, Microsoft Office SharePoint Designer 2007) to add a Data View Web Part to a Web Part page and point it at the URL of the XML file.

The Data View Web Part provides functionality like sorting, filtering, and grouping. You can also make the URL field a link to take you directly to the site. If you would like a list of webs instead, the operation enumsubwebs provides an XML output of the subwebs in a site collection or web.

Finally, keep in mind that while STSADM backups work well for small to medium sites, the functionality does not scale particularly well. For very large sites (several gigabytes or more), the backup and restore processes can slow down quite a bit.

Restoring a site is equally simple. STSADM -o restore takes a file created by STSADM -o backup and writes it to a site in SharePoint. You have a lot of flexibility with this command: you can restore a site back to its original location (if, for instance, the site was erroneously deleted), you can restore it as a different site on the same virtual server (perhaps if you want to test a process on a site without the risk of destroying data), or you can restore the site to a completely different server or virtual server.

Restoring to a different site or server makes it a bit easier to do individual document recovery. If you have a site backed up and a user needs a document restored, you do not need to restore the entire site. That would sacrifice all changes made to the site since the backup was stored. Instead, you can just restore the site to a different URL, grab the documents, and save them back to the original site.

In Windows SharePoint Services 2.0, STSADM has one fairly serious limitation. When backing up, it can only deal with sites, not with webs. Administrators made their discontent known and Microsoft responded. In Windows SharePoint Services 3.0, the backup and restore operations can now handle webs. It also adds two new commands: import and export.

To export a web, use the following simple command:

Stsadm -o export -url https://localhost/web -filename backup.dat

Export has handy options, including the -versions switch. This allows you to decide how large your backup files will be by restricting which file versions will be backed up.

To import a web back to the server, use the following command:

Stsadm -o import -url https://localhost/web2 -filename backup.dat

If your site is large enough, the backup file might be in multiple parts. In this case, point STSADM -o import to the first file and it will automatically grab the subsequent files.

Expert Operations

Now that you are comfortable with STSADM, I want to show you a couple of operations you can use to get out of a bind. The first is a newly added operation called migrateuser. Version 2.0 does not sync itself with Active Directory. If an account is renamed, it can no longer log in to SharePoint. In the past, there was also no way to migrate user access from one domain user to another. Before Windows SharePoint Services 2.0 Service Pack 2 (SP2), you had to remove the user from every web and manually add the new account.

SP2 introduced a new API and STSADM takes advantage of it. If the account jsmith is renamed to jjones, you can use the following command:

Stsadm -o migrateuser -oldlogin domain\jsmith -newlogin domain\jjones -ignoresidhistory

Since you're not actually migrating accounts, you can ignore Windows security ID (SID) history. Note that this command does not require a URL. It makes the change throughout the content databases, without regard to sites or webs.

Another operation that can get you out of a bind is unextendvs. If you do not want SharePoint to render a virtual server or Web application, you unextend it. Normally, you would do this from the SharePoint Configuration Analyzer. However, in a Web farm, SharePoint Configuration Analyzer requires that your servers are all at the same patch level. It is possible for a server to be out of sync with the rest of the farm and, therefore, it will not get the unextend option in SharePoint Configuration Analyzer. Using STSADM, though, the following command will unextend your virtual server:

Stsadm -o unextendvs -url https://localhost

Once the server is no longer in the Web farm, you can perform the maintenance you need.

On the subject of Web farms, for ease of administration, you may want all of your servers to have SharePoint Configuration Analyzer on the same port. The port is randomly generated when SharePoint is installed, but STSADM includes an operation to change the port to one you specify:

Stsadm -o setadminport -port 1026

This makes all the necessary database changes, it makes the IIS changes, and it adjusts the shortcut to SharePoint Configuration Analyzer in Administrative Tools.

Conclusion

Windows SharePoint Services is a powerful solution and it requires powerful administration. STSADM provides a way to accomplish SharePoint administration, including the automation of configuration and common day-to-day tasks. In fact, sometimes it is the only way to get the job done.

Todd Klindt is a Systems Analyst at UGS where he plays with SharePoint all day long—and gets paid to do so. He is also a Windows SharePoint Services MVP, and an Aquarius.

© 2008 Microsoft Corporation and CMP Media, LLC. All rights reserved; reproduction in part or in whole without permission is prohibited.