Appendix D: Customizing the SMSbkup.ctl Backup Control File

Published : September 1, 2004

The backup control file, SMSbkup.ctl, is an ASCII text file located on the site server at SMS\inboxes\Smsbkup.box\. The file contains site-specific information that the Backup SMS Site Server task requires. This file contains the names of the files, registry keys, and databases that need to be backed up. It also contains commands that run during the backup operation to gather configuration information. The SMSbkup.ctl file contains tokens that it uses during run time, such as the SITE_BACKUP_DESTINATION token.

When the backup task runs, it reads this file and performs the commands in the order that they appear in the file. The SMSbkup.ctl file drives the Backup SMS Site Server task and determines what data is backed up from the site and where it is stored at the backup snapshot destination.

On This Page

Using the Default SMSbkup.ctl Backup Control File
Preventing Backup of inboxes
Customizing SMSbkup.ctl
General Editing Guidelines
File Name Conventions

Using the Default SMSbkup.ctl Backup Control File

The default SMSbkup.ctl file works well for common backup scenarios. When the backup task runs and uses the default SMSbkup.ctl file, it backs up all data necessary for recovery. However, if your site has specific backup requirements, you can customize the file. To ensure a successful recovery, you must at least back up all the data that SMSbkup.ctl backs up by default. You can add custom backup tasks specific to your site, but do not discard any backup tasks included in the default SMSbkup.ctl. The only exception to this is if, for performance reasons, you choose to prevent the backup of one or more inboxes.

  Caution

The SMS backup task is designed to back up specific data in an SMS site. Although you can use this backup task to back up other data, such backups can cause complications that are not associated with backing up the intended data from an SMS site.

Preventing Backup of inboxes

Using the default backup file, SMS backs up all subfolders under the \SMS\inboxes folder, some of which can contain a very large number of files. To increase the performance of the backup task, you might prefer not to back up a few specific inboxes, despite the expected data loss if the site fails. When you reduce the number of inboxes that are backed up, the backup task runs faster, reducing the site server’s downtime. Also, the resulting backup snapshot is smaller, saving disk space.

Most inboxes must be backed up. Carefully evaluate the importance of data in each inbox, because data for some inboxes cannot be recreated on the recovered site, or recreating that data might be difficult or time consuming.

There are only a few inboxes that the site can be successfully recovered without. You can choose to prevent backing up the following inboxes:

• Colfile.box — Hardware inventory data files waiting to be processed by the Inventory Data Loader. This data is regenerated at the first hardware inventory resynchronization cycle after recovering the site.

• Dataldr.box — Inventory MIF files waiting to be loaded into the site database by the Inventory Data Loader. This data is regenerated at the first hardware inventory resynchronization cycle after recovering the site.

• Ddm.box — Data discovery records waiting to be loaded into the site database by the Discovery Data Manager. No need to save it; Site System DDR would be regenerated seven days after recovering the site.

• Inventry.box — Hardware inventory data files received from the CAP, and from lower level sites. Those files are waiting to be processed into MIF files by the Inventory Processor. This data is regenerated at the first hardware inventory resynchronization cycle after recovering the site.

• Invproc.box — Hardware inventory data files that require history to be processed by Inventory Processor. This data is regenerated at the first hardware inventory resynchronization cycle after recovering the site.

• OfferSum.Box — Replication files from child site, and status message files waiting to be processed. On secondary sites, this folder also contains advertisement summarization files. After site recovery, most of the status messages are lost. The replication files from the child site will be sent again and should be recovered.

• Sinv.box — Software inventory data files received from lower level sites, waiting to be processed into the site database by the Software Inventory Processor. This data is regenerated during an inventory resynchronization cycle after recovering the site.

• Statmgr.box — Status message files received from lower level sites and waiting to be processed into the system’s event viewer by Status Manager. Some of those status messages are regenerated by the appropriate components, but most are not.

You can prevent SMS from backing up inboxes by modifying the backup control file. Replace the file command that backs up the inbox folder with individual file commands for each inbox subfolder that you want to back up. Leave out the inbox subfolders that should not be backed up.

Customizing SMSbkup.ctl

Before making any changes to the original SMSbkup.ctl file, save a copy of the file in case you need it later.

The information in the backup control file is organized into four sections:

• [Tokens] — A list of tokens and their values that the backup task uses as variables when it runs.

• [Stop] — A list of processes that the backup task stops before it starts to back up data.

• [Tasks] — A list of backup commands targeted at different types of data at the site.

• [Start] — A list of processes that the backup task starts after the backup task has been completed.

To ensure that the backup task produces a valid backup snapshot, carefully follow the modifications guidelines for each section, do not modify the order of the sections, and edit only the designated areas in the file.

[Tokens]

Several required tokens are predefined, and you cannot modify them. The default backup control file contains a list of all predefined tokens. The default structure of the backup snapshot destination folder allows multiple sites to share the same backup location.

You can customize this section by appending new tokens to it and assigning values to them as follows:

<MyToken>=<token value>

To reference a token, enclose it with the % character, as in % MyToken %. You can use environment variables as tokens.

[Stop]

By default, the following basic services are stopped:

• %SITE_SERVER%\SMS_SITE_COMPONENT_MANAGER

• %SITE_SERVER%\SMS_EXECUTIVE

• %SITE_DB_SERVER%\SMS_SQL_MONITOR

You cannot modify this default behavior.

You can customize this section by appending the following commands:

• To stop a Windows service that is installed on the backed up site server, use

  service <service name>

  Where <service name> is a full service name without the path to the executable file. All running instances of <service name> are stopped.

  To stop a service on a remote computer, type the service name as follows:

  \\<machine name>\<service name>

  This command stops all instances of the <service name>. When you add a service to this section, consider the effect of this service being stopped during the backup operation.

  The backup task attempts to stop a service only if that service is installed and it is running on the backed-up site server at the time that the backup task starts. The backup task restarts these services after the backup operation has been completed.

• To stop a Windows executable file that is running on the backed up site server, use

  exec <executable name>

  Where <executable name> is the file name of the executable file that you want stopped.

  You cannot stop an executable file that is running on a remote computer.

  You might not be able to stop an executable file properly. In some cases, when you stop an executable file, the operating system resources used by that executable file are not released. Therefore, use the exec command to stop an executable file only if it absolutely cannot be running during the backup operation and only if you cannot stop it using the service command.

• To pause the backup operation for a specified number of seconds, use

  sleep <seconds>

  Where <seconds> is a numeric value that specifies the number of seconds that the backup operation pauses. The maximum value for <seconds> is 900 (15 minutes).

[Tasks]

The default control file contains commands that back up all of the site data required for recovery. This includes SMS files, registry keys, configuration data, and the SMS site database.

All backup tasks in this section implicitly create the specified destination folder, if it does not already exist.

You can customize this section by appending the following commands.

• To back up a file object, use:

  file <source> <destination>

  Where <source> is a file or a folder to be backed up, and <destination> is the destination folder that the backup task copies the <source> object to. (If <source>is a folder, that folder is recursively backed up.)

  You can use the * and the ? wildcards when you specify <source>, as follows:

  • * replaces a variable length string.

  • ? replaces a one character string.

  Add file commands to back up custom SMS-related files, such as MOF files and custom SMS Administrator console files that are not stored in one of the directories that the backup task automatically backs up.

  Any of the following conditions cause this command to fail:

  • The <source> folder does not exist.

  • The backup task cannot read the <source> folder.

  • The backup task cannot write to the <destination> folder.

  • The <source> and <destination> directories are identical.

  • The <destination> folder is a child folder of the <source> folder.

• To back up a registry object, use:

  reg <source> <destination>

  Where <source> is a registry key string, and <destination> is the destination file that the backup task copies the registry key to. To back up a registry key on a remote computer, prefix the registry key with a computer name in a Universal Naming Convention (UNC) format.

  Any of the following conditions can cause this command to fail:

  • The backup task cannot access a remote registry key.

  • <source> does not exist.

  • The backup task cannot write to <destination>.

• To back up the SMS site database, use

  sitedbdump <source> <destination>

  Where <source> is a database name and <destination> is the destination file that the backup task copies the database to.

• To back up server configuration information, use

  machinfo <source> <destination>

  Where <source> is the machine from which configuration data is backed up and <destination> is the destination file in which machinfo stores the collected configuration data in.

  The machinfo command uses Srvinfo.exe, Net.exe and IPConfig.exe to gather information SMS runs Srvinfo.exe from the SMS\Bin\i386 folder (this is where SMS Setup installs this executable file), and Net.exe and IPConfig.exe from the Windows system folder, so always ensure that the respective paths contains the latest version of these executable files.

   Important
  If the site server is configured with the Advanced Security mode and SQL Server is running on an operating system in the Windows Server 2003 family, then you need to manually gather configuration information from SQL Server. For more information about this issue, see article number 316360 in the Microsoft Knowledge Base Web site.

• To back up the site SQL Server configuration info, use

  smssqlinfo <destination>

  Where <destination> is the destination file name (without suffix) to which the backup task copies the SQL Server configuration data.* *

  The smssqlinfo command requires that the Isql.exe tool be in the path. SMS Setup installs this tool to SMS\Bin\i386. However, several versions of Isql.exe can exist on the source computer. Ensure that the path accesses the latest version of this executable file.

  Smssqlinfo generates the following three files:

  • <destination>Data.txt

  • <destination>Dboption.txt

  • <destination>Helpdb.txt

  Caution
Do not modify or delete the default commands in this section. If you do, you risk the completeness of the backup snapshot generated with this control file, and you might not be able to recover the site using it.

[Start]

Lists processes that you want restarted when the backup operation has been completed.

By default, SMS restarts all the services that were stopped. This includes the services that were stopped by default and all the services that you added in the [Stop] section using the service <service name> command.

The backup task does not attempt to start any services that are not installed, services that are already running, or processes that were stopped using the exec <executable name> command.

In this section, you can append the same commands as in the [Stop] section, with one difference: when starting executable files, you must enter the full path of the executable file, even if the executable file is in the current path.

The sleep command is useful when you need to start two processes, but one process cannot start until the second process is fully initialized. However, it takes some time for the first process to initialize. In this case, start the first process, and use the sleep command to pause the backup task until the first process is fully initialized. Then start the second process.

In case of failure of the backup task, it restarts only the three basic services:

• %SITE_SERVER%\SMS_SITE_COMPONENT_MANAGER

• %SITE_SERVER%\SMS_EXECUTIVE

• %SITE_DB_SERVER%\SMS_SQL_MONITOR

General Editing Guidelines

• If <source>, <destination>, or <process name> contains spaces or tabs, then they must be back quoted, as in: `process name with spaces`.

• To include a literal back quote, percent sign, tilde (~), or any other special character, you must precede it with a tilde. For example, to reference a token named “100% completed” type:

  % 100~% completed %

• Use the following to include comments in the file:

  • To add a single comment line, include the # character at the beginning of a line. For example:

This is a single comment line.

  - To add multiple comment lines (a comment block) use the “\#stop” and “\#start” strings to delimit the beginning and the end of the comment block. For example:
    
    <pre IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml">

#stop
This is the beginning of my comment block and this is the end of my comment block #start

    Comment blocks can be nested, but ensure that the section headers, such as \[Tokens\] or  
    \[Stop\], are never commented out.

• You can specify <source> and <destination> paths with a UNC or drive letter format.

• Do not modify the section headings ([Tokens], [Stop], [Tasks], and [Start]), and do not modify their order.

• The backup control file, SMSbkup.ctl is not case sensitive.

• The backup task backs up each <source> only once. If a <source> token in a subsequent backup command resolves to a <source> that was already backed up by a previous backup command, then the subsequent backup command is ignored.

• If there are commands that operate on remote computers, you must ensure that the appropriate permissions to run these commands are in place. For example, to start a service on a remote machine, the SMSService account must have rights to start and shut down services on the remote machine.

• To enter a command line which contains spaces, for example to enter command-line switches, use the “`” character as follows:

exec c:\winnt\system32\svchost.exe -k netsvcs

File Name Conventions

The default SMSbkup.ctl file follows these naming conventions for the backup snapshot files:

• The prefix “SMSbk” is included in all file names to indicate that the files are part of an SMS backup snapshot.

• The type of server from which the data is being backed up is included in all file names.

  • Site = site server

  • Prov = site provider server

  • SQL = SMS site database server

• Each file name includes the data type.

  • Reg = registry keys

  • DB = database dump

  • ConfigNT = Windows NT® configuration data

  • ConfigSQL = SQL Server configuration data

• Each file name includes the actual data source. For example, “NAL” = NAL registry key.

• Extensions are based on the data type of each file:

  • .dat = registry keys and database dumps (i.e. raw data)

  • .txt = readable data

For example, the file with the backup of the NAL registry key from the site server is named
SMSbkSiteRegNAL.dat

It is recommended that you follow the default naming conventions when you add backup commands to the default backup control file. Following these conventions allows you to easily identify the content of each file in the backup snapshot.

  Important
If you modify SMSbkup.ctl file, closely monitor the next backup cycle. You might have introduced syntax errors in the file, in which case the task fails shortly after it starts. Fix these errors and rerun the task.