This page is part of setman.
This documentation is unfinished. Please read on but have patience with me.
System requirements: Microsoft Windows XP or newer.
It is intended to add support for Windows 2000 and possibly older versions as well.
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.
Not yet done.
Not yet done.
Not yet done.
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,
that resides in the
%windir%\system32 folder on windows systems. This programs
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
setman.js /? will tell you, the various options are:
----------------------------------------------------------------------------- Setman, Settings Manager ver. 0.1. See <http://setman.sourceforge.net> for more information and documentation. ----------------------------------------------------------------------------- Usage: 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.
setman.js import example-setttings.xml
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
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
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
test does not validate the input file as thoroughly as the
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
There are, however, a few things to consider:
These problems cannot be solved in an automated way that ensures consistency on a subsequent
import. Therefore setman does this:
import, this empty value will cause the entire combined setting to be skipped.
exportis 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.
setman.js validate example-setttings.xml
Validation is not yet implemented.
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.
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
cscript setman.js export xpsp1-workstation.xml my-workstation.xml
Not done yet.
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 //Sto disable the logo permanently for your user profile. You'll probably want this when you're messing around with Setman. Note that
-soption cannot disable cscript's banner.
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.
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>
<changelog> are provided for general information about the file.
<settings> contain the actual settings divided into
<MachineSettings>. One of these may be
missing or empty. The
os attribute should be somthing like 'winxpsp1' to specify
the intended operating system version.
<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.
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>
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
attribute and a
data attribute. The name is the one referenced by
current. It should be chosen descriptively, like Enabled or Disabled for simple
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.
currentattribute 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.
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:
|REG_SZ||String||any random string|
|REG_EXPAND_SZ||String containing environment variables||%SystemRoot%\System32|
|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
This type of setting is not implemented yet.
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,
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
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
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
Morten Odgaard email@example.com
Setman project page on Sourceforge
View mailing list