Setman Documentation

This page is part of setman.

This documentation is unfinished. Please read on but have patience with me.



System requirements

System requirements: Microsoft Windows XP or newer.

It is intended to add support for Windows 2000 and possibly older versions as well.

Conventions and Terms

The following terms and conventions are used throught this manual:

A user setting is a setting that only modifies the currently logged on user's profile.

A machine setting is something machine-wide. It may or may not affect users, depending on whether the setting takes precedence over user settings. If it does, it should be documented in the settings file.

The current vs. present terms relate to a current setting in a settings file vs. the present state of a setting on a machine.

importing refers to the action of importing a settings file on a machine, making all current settings present. Importing is done by reading the settings file setting-by-setting and importing them in that order.

exporting refers to reading a settings file, for each of the settings read the present value of the setting and writing this value as the current in the output file.

What is a 'setting'?

Not yet done.

User settings

Not yet done.

Machine settings

Not yet done.

Setman.js command line parameters

The file setman.js is the script that performs the various actions. It is a console type application with the following syntax:

	cscript setman.js <command> <file(s)> [options]

cscript refers the the Windows Scripting Host executable, cscript.exe, that resides in the %windir%\system32 folder on windows systems. This programs executes the setman.js script with the specified options. To simplify notation cscript will often be omitted in this manual, but you still have to type it every time you run setman. (More info on cscript.)

As setman.js /? will tell you, the various options are:

Setman, Settings Manager ver. 0.1.

See <> for more information and documentation.


  cscript setman.js <command> <infile> [<outfile>] [options]

Where <command> is:
  test       Display the result of importing <infile> but don't modify anything.
             Also displays current values
  import     Import the settings in <infile> to the local machine
  export     Export the settings in <infile> to <outfile> with the values
             currently present.
  validate   Validate <infile>.
  --help     Display this screen. Same as /? and -?.

Valid [options] are:

  -l <file>  Log information to <file>
  -s         Silent operation. Only displays output on error
  -d         For user settings, operate on Default User Profile instead of
             the current user's profile

The individual commands and options are explained below.

The import command


	setman.js import example-setttings.xml

The import command will import all current settings in the given file to the local machine. User settings can be applied to the Default User Profile using the -d option.

In the event of an error (access denied, system i/o, ...) the script will stop, but no attempt will be made to roll back any changes already made. An error message will be written to the standard error stream and, if logging is enabled, to the log file. Finally, the script will return the appropriate exit code. TODO: add an ignore-error flag to continue on error

The test command


	setman.js test example-setttings.xml

This command is useful in testing settings files. It displays all settings in the given file in high detail. It also displays the present settings on the system (adhering to any options you may have given). Running test on a reference machine and studying the result is a good way to ensure that the settings file will do what you expect. It is also helpful when creating or troubleshooting complex combined settings. Note that test does not validate the input file as thoroughly as the validate command.

The export command


	setman.js export example-setttings.xml temp-settings.xml

Exporting settings is the most complex thing setman.js does, and understanding a few details will help getting the desired results. Basically, export just opens the input file, processes it and updates the current values with the values present on the machine and saves it to the output file. The output file must not exist in advance. There are, however, a few things to consider:

  • Missing values. If a value is not present on the machine, which value, if any, should be written to the new file?
  • Undefined combined settings. If a series of present values in a combined setting do not match any defined combined value, what should be written?

These problems cannot be solved in an automated way that ensures consistency on a subsequent import. Therefore setman does this:

  • If a missing value is encountered, an empty current value is written and a message is displayed.
  • If a combined value cannot be resolved, an empty current value is written and a message is displayed. On a subsequent import, this empty value will cause the entire combined setting to be skipped.
The rule of thumb is that export is as conservative as necessary, skipping values if they cannot be resolved. This means it will sometimes be necessary to fill in values by hand, but it ensures that the exported file remains consistent - provided of course that the input file makes sence. For more information, see
the settings file format.

The validate command


	setman.js validate example-setttings.xml

Validation is not yet implemented.

Global options


	setman.js import example-setttings.xml -l %SystemRoot%\setman.log -d -s

-l <logfile>

Log information to <logfile>. This includes all information sent to the standard out and standard error streams.


Silent operation. Setman only displays output on error.


When processing user settings, use the Default User Profile instead of the current user's profile.


Prepare a newly installed workstation with default settings.
cscript z:\install\setman\setman.js import z:\install\setman\default-xpsp1-user.xml -d -s

Applying settings on each login from a login script.
cscript \\pdc\netlogon\setman\setman.js import \\pdc\netlogon\setman\enforced-settings.xml -s

Testing a set of settings.
cscript setman.js test xpsp1-workstation.xml

Exporting the settings defined in xpsp1-workstation.xml to a new file with the local machine's values.
cscript setman.js export xpsp1-workstation.xml my-workstation.xml

Exit codes

Not done yet.

A note on Cscript

Every time cscript.exe is invoked, it displays a startup banner displaying copyright notice and version number. This information can be annying and makes setman.js's output harder to read. Running

	cscript //NoLogo <script-file> <options>
will stop cscript showing the banner. This is useful for logon scripts. You can also run
	cscript //NoLogo //S
to disable the logo permanently for your user profile. You'll probably want this when you're messing around with Setman. Note that setman.js's -s option cannot disable cscript's banner.

The settings file format

This section describes the xml file format in complete detail (I hope). You may want to skip it and just have a look at the example files in the distribution. They are pretty self-explanatory. But in order to create and export files, it's a good idea to read the full details below.

Comments are highly welcome and can be posted to the mailing list or to me personally. In particular there's been some discussion about providing "default" settings. This would be an advantage, but may not be possible to keep up-to-date or even to implement properly.

File structure

The basic structure of the file is as follows:

  <settings os="">
        <setting ...> ... </setting>

The <comment>, <author> and <changelog> are provided for general information about the file.

<settings> contain the actual settings divided into <UserSettings> and <MachineSettings>. One of these may be missing or empty. The os attribute should be somthing like 'winxpsp1' to specify the intended operating system version.

The <UserSettings> and <MachineSettings> nodes may contain arbitrary groups, represented as nodes (like Explorer and Desktop above). The only restriction is that the nodes may not be named 'setting', which is reserved for actual settings as described in the following sections.

Basic settings

There are currently two basic settings, registry and services. They are explained in detail below, but share this common format:

<setting name="SettingName" longname="A longer, more descriptive name">
    A description the setting's purpose, prerequisites and consequences
  <method type="SettingType">
      [attributes related to this SettingType]
  <values type="SettingType" current="ValueName1">
    <val name="ValueName1" data="ValueData1"/>
    <val name="ValueName2" data="ValueData2"/>

The setting's name, SettingName, should be unique throughout the file. longname is optional, but recommended. All details about the setting and it's possible values are contained inside the setting's xml node. The actual ValueName however, is overridden if it is part of a combined setting.

The method node describes the SettingType as explained below. Inside the method node is a SettingType node that contains a number of attributes relevant for the SettingType.

The values node describes the possible values for the setting, as well as it's current value. All values (the val child nodes) are assigned a name attribute and a data attribute. The name is the one referenced by current. It should be chosen descriptively, like Enabled or Disabled for simple values. The data is the actual data to be written. The values node's current attribute contains the setting's assigned value - the name of the value data that is written when the settings file is imported by Setman.

The current attribute is mandatory, but may be left as current="". This specifies that the setting is undefined, meaning Setman will ignore it when processing the file. This also means that the setting will not be exported if the export command is given. See (not done yet) for more details on this.

reg - registry

A registry setting looks like this:

<setting name="HideFileExt" longname="Hide file extensions for known file types">
  <description>The default value 'Enabled' is confusing and have security issues. Should always be disabled</description>
  <method type="reg">
    <reg hive="HKCU" subkey="Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced" valuename="HideFileExt" valuetype="REG_DWORD"/>
  <values type="reg" current="Disabled">
    <val name="Disabled" data="0"/>
    <val name="Enabled" data="1"/>

The SettingType is "reg". The reg node contains all the information necessary to describe a registry setting. The valuetype can be any of the following:

Type Description Example data
REG_SZ String any random string
REG_EXPAND_SZ String containing environment variables %SystemRoot%\System32
REG_DWORD Integer (double) 58932712
REG_BINARY Binary data, comma-separated string of bytes af,e2,12,7a,ff,0e
REG_MULTI_SZ Multiple strings, separated by \0 String1\0String2\0String3

To specify a registry key's (Default) value, use the empty string as valuename.

srv - system services

This type of setting is not implemented yet.

Combined settings

Combined settings allow grouping and even nesting of settings. The purpose is to express that settings can depend on the values of other settings and that not all combinations of values make sence. Its format is similar to basic settings with a few modifications:

<setting name="SettingName" longname="...">
  <method type="combined"/>
  <values type="combined" current="CombinedValue2">
    <val name="CombinedValue1">
      <subval setting="BasicSetting1" value="Enabled"/>
      <subval setting="BasicSetting2" value="Enabled"/>
    <val name="CombinedValue2">
       <subval setting="BasicSetting1" value="Disabled"/>
       <subval setting="BasicSetting2" value="Disabled"/>
    <val name="CombinedValue3">
       <subval setting="BasicSetting1" value="Disabled"/>
       <subval setting="BasicSetting2" value="Enabled"/>
    <setting name="BasicSetting1">
    <setting name="BasicSetting2">

A combined setting's method node only has one attribute, type="combined" and no child nodes.

A new combinedsettings node contains all the settings that the combined setting is made of. The settings here can be any type of setting, basic or combined. The only thing to notice is that these settings's current values are ignored - they are overriden by the value of the combined setting they are part of.

The values node is the same as for basic settings, the current attribute describes which value is defined. The empty string again makes the value undefined and ignored by Setman.

The val nodes inside values node have only one attribute, name, which name the combined value. The current attribute of values should point to one of these names. The val nodes also have child nodes, subval, that describe which values the comprised settings should have. Each of the val nodes name a set of configurations of the comprised settings via their subval nodes. All val nodes must have a subval for each of the settings listed in the combinedsettings node.

The format allows nesting combined settings, but since it quickly gets complicated, it is not advised. See the file nested-combined-settings.xml in the distribution for an example.

Morten Odgaard Logo

Setman project page on Sourceforge
View mailing list