Data Management

TechRepublic Tutorial: Redirect a MetaFrame database with Citrix's DSMAINT tool

A tutorial showing how to use the DSMAINT tool in the command line


With the introduction of MetaFrame XP, Citrix took a giant leap by centralizing all the server farm information into a database for easy management, scalability, and centralization. MetaFrame's Independent Management Architecture (IMA) data store database supports one of the following database formats: it can either be a Microsoft Access database hosted on an existing Citrix MetaFrame XP Server, or it can be hosted on its own Microsoft SQL or Oracle Database servers. You should note that if you decide to use SQL Server or Oracle databases, they will have to be on a dedicated server and shouldn't be hosted on any of the existing MetaFrame XP servers.

Configuration of the IMA data store takes place during the installation of Citrix MetaFrame XP and is one of the steps required to successfully complete the installation and add the server to the farm. It is during this installation process that you select which database type you will use. The ODBC configuration information for SQL Server or Oracle databases is stored in the file MF20.DSN located in the %systemroot%\Program Files\Citrix\Independent Management Architecture\ directory. Microsoft Access stores this information in the same directory under an Access database file; so, if you are using Access, the file name would be MF20.MDB.

But what if after the installation of MetaFrame XP you decide to either upgrade or simply change the IMA data store location? How do you reconfigure the data store to point to the new location? Or what if you decide to migrate from a Microsoft Access data store to a Microsoft SQL Server data store (e.g. because your farm outgrew Access's ability to handle more servers)? If for any reason you need to change the IMA data store or reconfigure it, you'll need the help of the DSMAINT tool. DSMAINT is also useful if you ever want to recreate or even change the name of the DSN file that holds the database information.

Avoid confusion with Novell's DSMaint
DSMAINT (aka the Data Store Maintenance tool) is a Citrix Systems utility and should not be confused with the tool offered by Novell that bears the same name (usually spelled DSMaint).

Using DSMAINT
As I mentioned, DSMAINT is a command line tool, so to use it the first thing you need to do is open a command prompt on a Citrix MetaFrame XP server and run the command DSMAINT. You can also run DSMAINT remotely if you use RCMD.

DSMAINT has the following syntax:
DSMAINT [CONFIG | BACKUP | FAILOVER | COMPACTDB | COMPARE | MIGRATE | PUBLISHSQLDS | RECOVER | RECREATELHC]

This allows you to do numerous maintenance tasks to the IMA data store. For the purposes of this article, we are only going to discuss the CONFIG and the MIGRATE features. To migrate the IMA data store between different databases (e.g., from Microsoft Access to SQL Server), you must create the new DSN and make sure it points to the right server using the following command:
Dsmaint migrate /srcdsn:dsnfilename /srcuser:username /srcpwd:password
/dstdsn:dsnfilename /dstuser:username /dstpwd:password
dsmaint config /user:username /pwd:password /dsn:dsnfilename


In this command, srcdsn is the source DSN or the current DSN filename. The srcuser and the srcpwd are the existing user and password used to connect to the database. Dstdsn stands for the destination DSN; you should put the destination DSN filename together with the destination user and password that will be used to access the database. This is a database user and the required password (not a Windows user name and password), so the user would have to be created in the database software and assigned a password there.

Moving the IMA database to a different server
Sometimes you may need to simply change the database server. This is different from the above scenario in that the database software won't be changed, but you will have to reconfigure the DSN to point to a different physical server. Since the IMA database is fairly small in size, many companies just create a new database on an existing server. So, if you have SQL Server in your environment, you may add the IMA database to that SQL server since the IMA database isn't likely to grow much, if at all. In the event that the SQL Server that hosts the IMA database needs to be changed or upgraded for any reason, you'll need to reconfigure the MF20.DSN file to point to this new server. To do this, follow these steps:
  1. Reconfigure the MF20.DSN by going to Start | Settings | Control Panel | Administrative Tools | Data Sources ODBC.
  2. Click on the File DSN tab, and browse to the location where the MF20.DSN file is located. By default, it is located in %systemroot%\Program Files\Citrix\Independent Management Architecture\ directory.
  3. Edit MF20.DSN to point to your new server.
  4. From a command prompt, execute the following command: dsmaint config� [/user:<username>] [/pwd:<password>] [/dsn:<filename>] where the user and password here are the new database's set of credentials. For the /dsn parameter, make sure you put the full path to the location where this DSN is located on the server's hard drive.
  5. Stop and start the IMA service.

If you wanted to keep the existing DSN and just create a new one, or if you wanted to rename the DSN to something that makes more sense to you, you'll have to modify the following registry key to reflect these changes:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\DataSourceName

Change the value of the DataSourceName to reflect the location and the name of your DSN.

More DSMAINT
DSMAINT is a tool that any Citrix administrator will come in contact with at one point or another while working with Citrix MetaFrame XP. The tool has a broad range of features and can accomplish many administrative tasks. In addition to the two functions I discussed in this article, DSMAINT can also compact, back up, and compare databases, and much more. As a Citrix administrator, you should become familiar with this tool and its options.

Editor's Picks

Free Newsletters, In your Inbox