This article provides guidelines and alternate references for the use of Change Farm command (CHFARM) within a Citrix environment.

CHFARM Usage

The CHFARM utility is used to change the farm membership of a Citrix Server.

Background

You can use the command line CHFARM when you want to modify the farm membership of a Citrix Server; you can move the server to another already existing server farm, or create a new server farm. The CHFARM utility is built into the Citrix Server software and is available on Presentation Server 4.5 (2003) and XenApp 5.0 (2008). The command line utility is no longer available on newer versions of XenApp 6.0 or 6.5 (Windows Server 2008/R2). Refer to CTX125142 - FAQ: Usage of the chfarm Command in XenApp 6 for more information.

When you run CHFARM command, it stops the IMA Service on the server. The data store configuration part of the Presentation Server Setup wizard appears. This is a GUI application requiring multiple inputs. To automate this configuration through a command line, refer to the Additional Resources section of this article. For information about data store set up and server farm configuration, see the Data Store Configuration section in the appropriate Administrator's Guide.

Overview of Command Line Parameters

CHFARM /joinfarm /ldsc:servername /user:[domain]\username /pwd:password [/zone:zonename] [/quiet] [/verbose]
CHFARM /joinfarm /ddsc:directdatastore /odbcuser:username /odbcpwd:password /dsnfile:pathplusname [/zone:zonename] [/quiet] [/verbose]

• /verbose - Sends extra debug information to a DOS window; an alternative to this is to redirect the output to a file (CHFARM parms >mylog.txt).

• /quiet - Suppresses "are you sure" messages.

• /noerror – Prevents any message prompts (benign or failures) from occurring and can facilitate the fully unattended CHFARM process execution (See Notes section for more information).

• /ldsc - The name of the server whose farm you want to join indirectly.

• /user - User name with optional domain [domain/] username.

• /pwd - Password for the [domain/] username.

• /zone - The zone name.

• /ddsc - Direct database store (for example, SQL Server).

• /odbcuser - User name for the ODBC database.

• /odbcpwd - Password for the ODBC user.

• /dsnfile - The path and name of the file you want to use as the .dsn file template; for example: /dsnfile:c:\mydir\MF20.dsn. The DSN file can be obtained from the first server to join the farm. By default, the template is located at C:\Program Files\Citrix\Independent Management Architecture\MF20.dsn. If the path to your dsn file contains spaces, use quotes ("). For example, /dsnfile:"C:\my setup files\Citrix\my stuff\mf21.dsn".

When you use the utility from the GUI and fill in all GUI prompts for Create or Join Farm, a batch file is created to automate the process of joining new servers to a farm. The batch file, JOINFARM.BAT, is located in the same folder as the utility. Modify the batch file according to the comments in the file that instructs you to fill in the password and in some cases, the /dsnfile location.

Notes

• There is no command line option for Create Farm; only Join Farm is supported.

• Use of the global farm settings for the License Server is assumed.

• Parameters with spaces in them must be enclosed using quotation marks (").

• Do not use the C:\Program Files\Citrix\Independent Management Architecture\mf20.dsn as the source location of the DSN file because it is also the destination.

• The password and DSN fields in the JOINFARM.BAT file are cleared after successfully running CHFARM command.

• If any errors are detected while running with command line parameters, a pop-up dialog box appears. You must clear the dialog box to continue with the GUI version. You can prevent benign or failure messages from occurring by using the /noerror command line parameter.

• If you use the /noerror command line parameter, you need to ensure that you use another mechanism to verify that the CHFARM execution worked successfully (For example, verify return code in redirected log file, and so on).

• Do not run CHFARM command on more than 10 servers simultaneously to avoid overloading the data store.

• Output from scripted CHFARM command can be directed to a file by using the DOS command >1.txt (to overwrite any existing file) or >>1.txt (to append to any existing file). For example: A:\newfarm >1.txt.

• Every time rename the JOINFARM.BAT file. If not, it is updated while the server is running, possibly confusing the batch file interpreter. In this example, it was renamed NEWFARM.BAT.

• If the IMA Service is slow in stopping (because of a very large farm, WAN, slow database, and so on) and times out, add a Dword entry StopServiceWait to the registry under the key HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\\IMA\RUNTIME and set it to the maximum number of seconds to wait for the service to stop. If no entry is present, the wait defaults to 900 seconds.

  Caution! Refer to the Disclaimer at the end of this article before using Registry Editor.

• CHFARM command can be useful to determine if an issue is related to the data store or server configuration.

• Do not remove a server that hosts a server farms data store from the server farm. If removed, it loses all configurations.

• To remove a server from a farm, you should either uninstall Citrix Presentation Server or run CHFARM command.

Sample Contents of JOINFARM.BAT

CHFARM /quiet /joinfarm /ddsc:"SQL Server" /zone:EMEA /odbcuser:sa /odbcpwd:password /dsnfile:"C:\Program Files\Citrix\my stuff\mf21.dsn". For more information, refer to CTX125130 – How to Remove a Server from the Farm in XenApp 6.x.

Additional Resources

CTX125142 –   FAQ: Usage of the chfarm Command in XenApp 6

Citrix TV - How To: Change Farms using CHFARM
Note: This video requires the Adobe Flash player plug-in for the web browser. You can also download the video from this link.