Setman Documentation

The export command

Example:

	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 validate command

Example:

	setman.js validate example-setttings.xml

Validation is not yet implemented.

Global options

Example:

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

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.

Examples

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>

	cscript //NoLogo //S

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.

File structure

The basic structure of the file is as follows:

<setman>
  <comment/>
  <author/>
  <changelog/>
  <settings os="">
    <UserSettings>
      ...
      <Explorer>
        <setting ...> ... </setting>
        ...
      </Explorer>
      <Desktop>
      </Desktop>
      ...
    </UserSettings>
  
    <MachineSettings>
      ...
    </MachineSettings>
  </settings>
</setman>

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">
  <description>
    A description the setting's purpose, prerequisites and consequences
  </description>
  <method type="SettingType">
    <SettingType
      [attributes related to this SettingType]
    />
  </method>
  <values type="SettingType" current="ValueName1">
    <val name="ValueName1" data="ValueData1"/>
    <val name="ValueName2" data="ValueData2"/>
    ...
  </values>
</setting>

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"/>
  </method>
  <values type="reg" current="Disabled">
    <val name="Disabled" data="0"/>
    <val name="Enabled" data="1"/>
  </values>
</setting>

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:

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>
    <val name="CombinedValue2">
       <subval setting="BasicSetting1" value="Disabled"/>
       <subval setting="BasicSetting2" value="Disabled"/>
    </val>
    <val name="CombinedValue3">
       <subval setting="BasicSetting1" value="Disabled"/>
       <subval setting="BasicSetting2" value="Enabled"/>
    </val>
  </values>
  <combinedsettings>
    <setting name="BasicSetting1">
      ...
    </setting>
    <setting name="BasicSetting2">
      ...
    </setting>
  </combinedsettings>
</setting>

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.