Software

SolutionBase: Get a handle on Exchange indexes with the Microsoft Exchange Server MSSearch Administration Tool

Full-text indexing on Microsoft Exchange isn't as easy as it could be. At least it isn't without a little bit of extra help. Here's how to get a handle on Exchange indexes with the MSSearch Administration Tool.

Have you ever noticed that the Exchange System Manager really doesn't have many options for working with Exchange full text indexing? I have always felt like I wanted to have more control over the indexing process, but was prevented from having that control by limitations in the graphical user interface.

Fortunately, Microsoft has realized that these limitations can sometimes be a problem and has created a utility called MSSearch Admin tool. This tool can be used to do things such as enabling and disabling an index, checking an index's status, fixing index configuration problems, and resetting a malfunctioning index. In this article, I will show you where to get this tool and how to use it.

Acquiring the MSSearch Admin tool

You can download the MSSearch Admin tool directly from Microsoft's Web site. The download consists of a 94 KB (yes, that's KB, not MB) self extracting executable file.

Installing the MSSearch Admin tool

The installation procedure for the MSSearch Admin tool is simple. Just double click on the file that you downloaded, and the file's contents will be extracted. Actually preparing the tool for use is a different story though. The MSSearch Admin tool is a Visual Basic script.

There are two reasons why this complicates things. First, the script is completely text based, which means that you will have to manage your server's full text index from the command line. The second reason why the tool being Visual Basic Script based complicates things is that Windows Server 2003 can't natively run this particular script from the command line.

Running the MSSearch Admin tool

After you extract the MSSearch Admin tool, it will create a folder containing several files. Most of these files are XSL style sheets, but there is also a script file called MSSearch_Admin.vbs. You must copy the VBS and the XSL files to the directory on your server's hard drive that contains the Exchange System Manager console (usually C:\Program Files\Exchsrvr\bin).

Earlier, I mentioned that Windows can't natively run the MSSearch Admin tool from the command prompt. In order to be able to run the script, it must get a little help from a file named ADS.DLL. ADS.DLL is a component in another Microsoft utility called Array Convert. You can download and install the Array Convert utility and then copy the ADS.DLL file from Array Convert to the Exchange System Manager folder. You can download this utility from the Microsoft Web site.

The command's syntax

As I have already explained, the MSSearch Admin tool is actually a Visual Basic script with no graphical user interface. As such, you will have to use the tool via the command line. Like most of Microsoft's command line based tools, there are several parameters that can be used in conjunction to the MSSearch_Admin.vbs command. The full syntax is listed below:

MSSearch_Admin.vbs /Action:<action> [/ExServer:<servername>] [/Application:<application>] [/Index:<index>] [/OutputFile:<filename>]

In the sections below I will discuss each of these parameters in detail.

The Action parameter

If you look at the syntax of the MSSearch Admin tool, you will notice that the /Action parameter is the first parameter that must be specified. The /Action parameter is used to control what the tool is actually going to do. For example you would use the Action parameter to tell the MSSearch Admin tool whether you want to check an index's status or disable the index. In many cases the /Action parameter can be used without the need for other parameters.

However, to get the most benefit from the /Action parameter, you need to at least be familiar with the other parameters that are available to you. That being the case, I am going to talk about the other MSSearch Admin parameters first, and then come back to the /Action parameter later on

The ExServer parameter

The ExServer parameter is used to specify the name of a target Exchange Server. The usage of this parameter is pretty simple, but there is one important thing to keep in mind. The server that you specify must exist within the same domain as the machine that you are running the MSSearch Admin tool from.

To specify a server name, simply use the following syntax:

/ExServer:servername

For example, if you wanted to run the MSSearch Admin tool against a server named MYSERVER, then you would use the /ExServer parameter as shown below:

/ExServer:myserver

The Application parameter

Normally, you will only have to use the Application parameter if you are running the MSSearch Admin tool against a clustered Exchange Server deployment. The reason for this is that each Exchange Server deployment (clustered or not) is assigned an application name that can be referenced through the MSSearch Admin tool.

In a non-clustered environment, the application name is always ExchangeServer_<servername> where <servername> is the name of your Exchange Server. The MSSearch Admin tool knows that the application name is always a direct reflection of the server name, so in non clustered environments it isn't necessary to specify the application name because the MSSearch Admin tool is smart enough to figure out the application name for itself.

Things work a little bit differently in a clustered Exchange Server deployment though. In a clustered environment, each node in the cluster has its own server name, but there is also a virtual server name that is shared by all of the servers in the cluster. If you want to run the MSSearch Admin tool against an Exchange Server cluster, then you would use the Application parameter to specify the cluster's virtual server name. For example, if you had two servers named Server1 and Server2 forming an Exchange cluster named CLUSTER, then you would specify the Application parameter like this:

/Application:CLUSTER

The Index parameter

The Index parameter is used when you want to perform the specified action against a specific index. You will almost always want to use the /Index parameter in conjunction with the /ExServer parameter. The reason for this is that there is always the chance that you could have multiple servers that use the same index name. To avoid confusion, it is best to tell the MSSearch Admin tool the name of the server that you want to work with and the name of the index on that server.

If you don't know the name of the index, it's no problem. You can derive the index name from the Exchange System Manager. To do so, open the Exchange System Manager and navigate through the console tree to Administrative Groups | your administrative group | Servers | your server | the storage group containing the indexed store | the store that you need to find the index for.

Now, expand the store's node and you will see a sub container named Full-Text Indexing. If you select this container, you will see some summary information related to the index appear in the console's details pane. One of the pieces of information that is given is the index name. This is the name that you will use with the /Index parameter.

The OutputFile parameter

The OutputFile parameter is always optional. If you use the OutputFile parameter, then the script's results will be written to the file that you specify in XML format. If you do not use the OutputFile parameter then the output will be displayed on the screen rather than being written to a file. The syntax for the OutputFile parameter is:

/OutputFile:filename.xml

The Action parameter

The Action parameter is the only parameter that the MSSearch_Admin script actually requires you to use. It is however also the parameter with the most options. In many cases, the /Action parameter can be used without having to specify any of the other parameters that I have already talked about. In other cases though, the Action parameter requires you to use some of the other parameters that I have discussed so that you can specify a particular Exchange Server or a specific index on an Exchange Server. The syntax of the Action parameter is as follows:

MSSearch_Admin.vbs /Action:<action>

In this syntax, the <action> portion of the command would be replaced by one of the following actions:

  • LIST
  • STATUS
  • FIXUP
  • ENABLE
  • DISABLE
  • FULL
  • INCREMENTAL
  • PAUSE
  • RESUME
  • STOP
  • RESET
  • LIST

    As you probably know, full text indexing is applied at the information store level. Using the Action command with the LIST option causes the MSSearch Admin tool to query all of the Exchange Servers within the current domain to see which of those servers have Full Text Indexing enabled. If indexes are found, then the MSSearch Admin tool will display a list of which stores have full text indexing enabled.

    It is also possible to run the LIST option on a per server basis by using it in conjunction with the /ExServer:servername parameter. If you specify the LIST action along with the name of an Exchange Server, the MSSearch Admin tool will display a list of the stores on the specified server that have full text indexing enabled.

    STATUS

    As the name implies, the STATUS action allows you to check the status of an index file. Along with the index's status, the STATUS action will return the index's location on the server. The STATUS action will also let you know if the specified index has any configuration problems.

    As you may have already figured out, the STATUS action can't be used by itself. You must also specify the server name and the index name. The full syntax of such a command would look something like this:

    MSSearch_Admin.vbs /Action:STATUS /ExServer:<server name> /Index:<index name>

    FIXUP

    The FIXUP action is a little less intuitive than some of the other actions that I have talked about. I mentioned that the STATUS action would tell you if there were any configuration problems associated with an index. If the STATUS action does report a configuration problem, then the FIXUP command is what you would use to fix the configuration problem.

    The million dollar question though is what are these configuration problems? After all, full text indexing is mostly self-configuring. If you simply enable full text indexing for a store and let the index do its thing, then you will never have a configuration problem. Configuration problems are the result of bugs in Exchange Server that are triggered during administrative actions. There are three types of actions that can result in configuration problems.

    One action that results in a configuration problem is moving an index. When you move an index, the Active Directory still points to the index's old location even after the move is complete.

    The second administrative action that causes configuration problems is renaming a domain. I'm not exactly sure of the nature of the configuration issue, but I've been told that it has to do with an Active Directory mismatch.

    The third circumstance that results in a configuration error is modifying the primary SMTP address for the default recipient policy. Again, doing so results in some sort of mismatch.

    Technically, you don't even have to worry about understanding the nature of the configuration errors though. The STATUS action will tell you if configuration errors are present, and the FIXUP action will correct those errors. As with the STATUS action, the FIXUP action requires you to specify the server and index name that you want to run the MSSearch Admin tool against. The syntax is as follows:

    MSSearch_Admin.vbs /Action:FIXUP /ExServer:<server name> /Index:<index name>

    Once last thing that you need to know about the FIXUP action is that after running FIXUP against an index, the index will be disabled for searching. To make the index usable after running a FIXUP, you must run a full population against the index and then enable the index. The FULL and the ENABLE actions that I will discuss in a moment can be used for these purposes.

    ENABLE

    As you have probably already figured out, the ENABLE action enables the specified index for searches. The syntax for the ENABLE action is as follows:

    MSSearch_Admin.vbs /Action:ENABLE /ExServer:<server name> /Index:<index name>

    DISABLE

    Just as the ENABLE action is used to enable searches against an index, the DISABLE action prevents an index from being searched. If you want to disable an index, you can do so by using the following command:

    MSSearch_Admin.vbs /Action:DISABLE /ExServer:<server name> /Index:<index name>

    FULL

    If you've done much work with full text indexing, then you know that after an index is created, it must be populated. If you want to perform a full index population, you can do so by using the FULL action. The only stipulation to using this action is that the indexes current status must be IDLE. You can perform a full population of an index by entering the following command:

    MSSearch_Admin.vbs /Action:FULL /ExServer:<server name> /Index:<index name>

    INCREMENTAL

    The INCREMENTAL action launches an incremental population of an index. An incremental population refers to a situation in which an index is already populated, but you want to update the index to reflect the most recent additions to the store. As with full population, the INCREMENTAL action can only be used against an index with a status of IDLE. The syntax for an incremental population is:

    MSSearch_Admin.vbs /Action:INCREMENTAL /ExServer:<server name> /Index:<index name>

    PAUSE

    The PAUSE action temporarily suspends the index population process. You can pause the population process any time that an index's status is either CRAWLING or CRAWLING INCREMETAL. The command for pausing an index population is:

    MSSearch_Admin.vbs /Action:PAUSE /ExServer:<server name> /Index:<index name>

    RESUME

    As you might have guessed, the RESUME action allows you to go back to populating an index after a pause. To resume the population process, use this command:

    MSSearch_Admin.vbs /Action:RESUME /ExServer:<server name> /Index:<index name>

    STOP

    The STOP action works exactly like the PAUSE action except that instead of temporarily suspending index population, the population process is aborted. In order to use the STOP action, the index must have a status of CRAWLING or of CRAWLING INCREMENTAL. The command for aborting index population is:

    MSSearch_Admin.vbs /Action:STOP /ExServer:<server name> /Index:<index name>

    RESET

    The RESET action is used to reset a malfunctioning index. This command should be used as a last resort only. The RESET command is basically the equivalent to deleting an index and recreating the index from scratch. Of course this means that the index will have to be completely repopulated after the reset occurs. If you decide that you need to reset an index, you can do so by using the following command:

    MSSearch_Admin.vbs /Action:RESET /ExServer:<server name> /Index:<index name>

    Getting control over indexes

    As you can see, the MSSearch Admin tool gives you more control over full text indexing than what the Exchange System Manager gives you. Although this utility takes a little getting used to, it is pretty much the most powerful tool available for managing indexing within an Exchange organization.

Editor's Picks

Free Newsletters, In your Inbox