Enterprise Configurator

(add links)
 
(One intermediate revision not shown)
Line 1: Line 1:
-
Epconf helps to configure software components that are commonly used in
+
Epconf helps to configure software components that are commonly used in an enterprise environment (e.g. at companies).
-
an enterprise environment (e.g. at companies).
+
Supported devices:
Supported devices:
-
* N900 (Fremantle)
+
* [[Nokia N900|N900]] ([[Open development/Maemo roadmap/Fremantle|Fremantle]])
It supports the installation and modification of:
It supports the installation and modification of:
-
* Browser bookmark thumbnail images: thumbnail_* files.
+
* Browser bookmark thumbnail images: <code>thumbnail_*</code> files.
* Wifi root certificates: <code>*.crt</code> files are used when authenticating via WLAN.
* Wifi root certificates: <code>*.crt</code> files are used when authenticating via WLAN.
* GConf schemas: <code>*.schemas</code> files are registered with GConf.
* GConf schemas: <code>*.schemas</code> files are registered with GConf.
Line 12: Line 11:
* Custom actions: Custom configuration can be done with epconftool in-files (<code>*.epin</code>).
* Custom actions: Custom configuration can be done with epconftool in-files (<code>*.epin</code>).
-
The above mentioned input files are taken from the
+
The above mentioned input files are taken from the <code>/usr/share/epconf-sets/SET</code> directory.
-
<code>/usr/share/epconf-sets/SET</code> directory.
+
With epconf in-files you can configure:
With epconf in-files you can configure:
Line 22: Line 20:
If an epconf in-file file matches <code>*.do-as-user.epin</code> then the
If an epconf in-file file matches <code>*.do-as-user.epin</code> then the
operations described by it will be executed as the user <code>'user'</code>.
operations described by it will be executed as the user <code>'user'</code>.
-
For more information about in-files, please refer to epconftool.
+
For more information about in-files, please refer to epconftool. See [[#epconftool|the epconftool section]] for more details about epconftool in-files.
-
See [[Enterprise_Configurator#epconftool|here]] for more details about epconftool in-files.
+
== Command line syntax ==
== Command line syntax ==
-
usage: epconf [debug] macro file_name ACTION SET[:GROUP[:ELEMENT]]...
+
<pre>
-
    debug            Enables debug output.
+
usage: epconf [debug] macro file_name ACTION SET[:GROUP[:ELEMENT]]...
-
    macro            Uses the specified macro file instead of the default one.
+
    debug            Enables debug output.
-
    ACTION          May be either install or uninstall.
+
    macro            Uses the specified macro file instead of the default one.
-
    SET              Name of the configuration set to process.
+
    ACTION          May be either install or uninstall.
-
                      It may be "all" which means "Process all the available set".
+
    SET              Name of the configuration set to process.
-
                      "all" cannot be mixed with other sets!
+
                    It may be "all" which means "Process all the available set".
-
    GROUP            Can be one of
+
                    "all" cannot be mixed with other sets!
-
                          thumbnail: Process thumbnail_* thumbnails
+
    GROUP            Can be one of
-
                          crt: Process *.crt certificates
+
                        thumbnail: Process thumbnail_* thumbnails
-
                          vcard: Process *.vcard vCards.
+
                        crt: Process *.crt certificates
-
                          schemas: Process *.schemas GConf schemas
+
                        vcard: Process *.vcard vCards.
-
                          epin: Process *.epin epconftool in-files
+
                        schemas: Process *.schemas GConf schemas
-
                      If it is not given then all the groups are processed.
+
                        epin: Process *.epin epconftool in-files
-
    ELEMENT          This can be used only with epin group.
+
                    If it is not given then all the groups are processed.
-
                      Only the infile with the given name willbe processed.
+
    ELEMENT          This can be used only with epin group.
-
 
+
                    Only the infile with the given name willbe processed.
 +
</pre>
The following example pulls the input files from <code>/usr/share/enterprise_pilot/my_set</code>:
The following example pulls the input files from <code>/usr/share/enterprise_pilot/my_set</code>:
Line 56: Line 54:
  epconf install my_set:epin:best_in your_set:vcard their_set
  epconf install my_set:epin:best_in your_set:vcard their_set
-
= epconftool =
+
== epconftool ==
Epconftool processes in-files that can be used for the creation of sophisticated configuration
Epconftool processes in-files that can be used for the creation of sophisticated configuration
scripts.
scripts.
-
== Command line syntax ==
+
=== Command line syntax ===
 +
 
 +
<pre>
 +
usage: epconftool [-f] [-s] [-d] { -x | -l } macro-file { -i | -u } in-files...
-
usage: epconftool [-f] [-s] [-d] { -x | -l } macro-file { -i | -u } in-files...
+
  -i    Install using the given input files.
-
+
  -u    Uninstall using the given input files.
-
  -i    Install using the given input files.
+
  -x    Macro file in XML format
-
  -u    Uninstall using the given input files.
+
  -l    Macro file in plain key-value format
-
  -x    Macro file in XML format
+
  -f    Force. If the process fails at one input file it goes on to the next one.
-
  -l    Macro file in plain key-value format
+
        Without this option (default), a bad input file stops the entire process
-
  -f    Force. If the process fails at one input file it goes on to the next one.
+
        and the subsequent input files are not processed.
-
        Without this option (default), a bad input file stops the entire process
+
  -s    Do simple macro substitution (a macro in a macro is not processed).
-
        and the subsequent input files are not processed.
+
  -d    Print debug output to stderr.
-
  -s    Do simple macro substitution (a macro in a macro is not processed).
+
        Either -i or -u can be used. They cannot be mixed.
-
  -d    Print debug output to stderr.
+
</pre>
-
        Either -i or -u can be used. They cannot be mixed.
+
Built-in macros:
Built-in macros:
Line 81: Line 81:
* <code>MARKER</code>: This may be used e.g. in XML in-files. If a node_path node contains this as a text field anywhere in its subtree, then that node is removed during un-installation. Otherwise it is not removed!
* <code>MARKER</code>: This may be used e.g. in XML in-files. If a node_path node contains this as a text field anywhere in its subtree, then that node is removed during un-installation. Otherwise it is not removed!
-
== Macro file ==
+
=== Macro file ===
-
The MACRO file contains usernames, passwords, etc.
+
The MACRO file contains usernames, passwords, etc. Each value in this file has a key associated with it. E.g., the WLAN_username key may have the value Jack. The keys of the MACRO file can be used in in-files as <code>%key_name%</code>. E.g., <code>%WLAN_username%</code>.
-
Each value in this file has a key associated with it.
+
-
E.g., the WLAN_username key may have the value Jack.
+
-
The keys of the MACRO file can be used in in-files
+
-
as <code>%key_name%</code>. E.g., <code>%WLAN_username%</code>.
+
Two kinds of macro files are supported:
Two kinds of macro files are supported:
Line 93: Line 89:
* Key-value list
* Key-value list
-
=== XML ===
+
==== XML ====
Let's take the following as an example:
Let's take the following as an example:
-
<?xml version="1.0" encoding="UTF-8" ?>
+
<source lang="xml">
-
<CONF>
+
<?xml version="1.0" encoding="UTF-8" ?>
-
  <NAME>Joe Buck</NAME>
+
<CONF>
-
  <REMOTE_ACCESS>
+
  <NAME>Joe Buck</NAME>
-
    <LOGIN>joebuck</LOGIN>
+
  <REMOTE_ACCESS>
-
  </REMOTE_ACCESS>
+
    <LOGIN>joebuck</LOGIN>
-
  <SIP>
+
  </REMOTE_ACCESS>
-
    <NAME>ext-joe.4.buck</NAME>
+
  <SIP>
-
    <PASS>98765876</PASS>
+
    <NAME>ext-joe.4.buck</NAME>
-
  </SIP>
+
    <PASS>98765876</PASS>
-
  <WLAN>
+
  </SIP>
-
    <RESTAURANT>
+
  <WLAN>
-
      <LOGIN>joejoe</LOGIN>
+
    <RESTAURANT>
-
      <PASS>buckybuck</PASS>
+
      <LOGIN>joejoe</LOGIN>
-
    </RESTAURANT>
+
      <PASS>buckybuck</PASS>
-
  </WLAN>
+
    </RESTAURANT>
-
  <EMAIL>
+
  </WLAN>
-
    <ADDRESS>ext-joe.4.buck@company.org</ADDRESS>
+
  <EMAIL>
-
  </EMAIL>
+
    <ADDRESS>ext-joe.4.buck@company.org</ADDRESS>
-
</CONF>
+
  </EMAIL>
 +
</CONF>
 +
</source>
 +
When using the above example macro file, the macro values are the text nodes and the macro names are formed formed the tag names. For example, the <code>%CONF_REMOTE_ACCESS_LOGIN%</code> macro refers to the value <code>"joebuck"</code>.
-
When using the above example macro file, the macro values are the text nodes
+
==== Key-value list ====
-
and the macro names are formed formed the tag names. For example, the
+
-
<code>%CONF_REMOTE_ACCESS_LOGIN%</code> macro refers to the value <code>"joebuck"</code>.
+
-
 
+
-
=== Key-value list ===
+
Let's take the following as an example:
Let's take the following as an example:
-
"CONF_NAME" "Joe Buck"
+
<pre>
-
"CONF_REMOTE_ACCESS_LOGIN" "joebuck"
+
"CONF_NAME" "Joe Buck"
-
"CONF_SIP_NAME" "ext-joe.4.buck"
+
"CONF_REMOTE_ACCESS_LOGIN" "joebuck"
-
"CONF_SIP_PASS" "98765876"
+
"CONF_SIP_NAME" "ext-joe.4.buck"
-
"CONF_WLAN_RESTAURANT_LOGIN" "joejoe"
+
"CONF_SIP_PASS" "98765876"
-
"CONF_WLAN_RESTAURANT_PASS" "buckybuck"
+
"CONF_WLAN_RESTAURANT_LOGIN" "joejoe"
-
"CONF_EMAIL_ADDRESS" "ext-joe.4.buck@company.org"
+
"CONF_WLAN_RESTAURANT_PASS" "buckybuck"
 +
"CONF_EMAIL_ADDRESS" "ext-joe.4.buck@company.org"
 +
</pre>
-
When using the above example macro file, the
+
When using the above example macro file, the <code>%CONF_REMOTE_ACCESS_LOGIN%</code> macro refers to the value "joebuck".
-
<code>%CONF_REMOTE_ACCESS_LOGIN%</code> macro refers to the value "joebuck".
+
If the " (double quote) character appears in a key or a value, then it must be escaped. For example, "Norton said \"Howdy!\" and then he left.". Same for the \ (backslash) character. For example, "\\" represents a single backslash character.
If the " (double quote) character appears in a key or a value, then it must be escaped. For example, "Norton said \"Howdy!\" and then he left.". Same for the \ (backslash) character. For example, "\\" represents a single backslash character.
-
== Input Template file (in-file) ==
+
=== Input Template file (in-file) ===
In-files have the following general format:
In-files have the following general format:
-
[CONTROL]
+
<pre>
-
# Comment
+
[CONTROL]
-
type:gconf|xml|shell
+
# Comment
-
...
+
type:gconf|xml|shell
-
+
...
-
[DATA]
+
 
-
...
+
[DATA]
-
...%MACRO%...
+
...
-
...
+
...%MACRO%...
 +
...
 +
</pre>
The following lines are ignored:
The following lines are ignored:
Line 158: Line 156:
The tag (e.g., "type") and its value (e.g., "xml") in the <code>CONTROL</code> section are
The tag (e.g., "type") and its value (e.g., "xml") in the <code>CONTROL</code> section are
-
separated by a single colon character.
+
separated by a single colon character. The "type" tag is mandatory, and it must be the first non-ignored line in the <code>CONTROL</code> section.
-
The "type" tag is mandatory, and it must be the first non-ignored line in the
+
-
<code>CONTROL</code> section.
+
-
Every <code>%MACRO%</code> macro is replaced with the matching value from the <code>MACRO</code>
+
Every <code>%MACRO%</code> macro is replaced with the matching value from the <code>MACRO</code> file during the installation/un-installation process. Macro substitution
-
file during the installation/un-installation process. Macro substitution
+
is applied to the entire in-file (e.g. if the value of <code>MARKER</code> is "Hello Hippo" then <code>[CON%MARKER%TROL]</code> is replaced with <code>[CONHello HippoTROL]</code>).
-
is applied to the entire in-file (e.g. if the value of <code>MARKER</code> is "Hello Hippo" then <code>[CON%MARKER%TROL]</code> is replaced with
+
-
<code>[CONHello HippoTROL]</code>).
+
-
No recursive macro substitution is done. For example, if macro <code>%APPLE%</code> has
+
No recursive macro substitution is done. For example, if macro <code>%APPLE%</code> has the value <code>"Hello %WORLD%"</code> then the <code>%WORLD"</code> is not considered as a macro for substitution.
-
the value <code>"Hello %WORLD%"</code> then the <code>%WORLD"</code> is not considered as a macro
+
-
for substitution.
+
-
=== gconf ===
+
==== GConf ====
-
This in-file is used to add/remove gconf values.
+
This in-file is used to add/remove GConf values. See [2] for an example!
-
See [2] for an example!
+
Syntax:
Syntax:
-
[CONTROL]
+
<pre>
-
type:gconf
+
[CONTROL]
-
+
type:gconf
-
[DATA]
+
-
dir:/path/to/gconf/directory
+
-
behavior:type:key_name:value
+
-
behavior:type-list:key_name:[value,value,...]
+
-
...
+
-
The <code>"type"</code> tag tells that it's a gconf in-file.
+
[DATA]
-
The first line in the DATA section is the gconf directory that we want to configure.
+
dir:/path/to/gconf/directory
-
Subsequent lines describe key/value pairs for gconf keys, whitespaces are
+
behavior:type:key_name:value
-
not allowed.
+
behavior:type-list:key_name:[value,value,...]
-
Value lists are also supported. In this case, the type name is suffixed
+
...
-
with the <code>"-list"</code> word and the value is a comma separated list enclosed in brackets.
+
</pre>
-
The behavior can be one of the following:
+
The <code>"type"</code> tag tells that it's a gconf in-file. The first line in the DATA section is the gconf directory that we want to configure. Subsequent lines describe key/value pairs for GConf keys, whitespaces are not allowed. Value lists are also supported. In this case, the type name is suffixed with the <code>"-list"</code> word and the value is a comma separated list enclosed in brackets. The behavior can be one of the following:
* <code>replace</code>: If the key already exists, it is replaced.
* <code>replace</code>: If the key already exists, it is replaced.
* <code>merge</code>: Only for value lists. If the key already exists, it is merged with the specified one.
* <code>merge</code>: Only for value lists. If the key already exists, it is merged with the specified one.
Line 209: Line 195:
* If after removing the keys, the entire <code>/path/to/gconf/directory</code> directory is deleted from gconf if it has become empty.
* If after removing the keys, the entire <code>/path/to/gconf/directory</code> directory is deleted from gconf if it has become empty.
-
=== xml ===
+
==== XML ====
-
This in-file is used to add/remove xml nodes in xml files, such as bookmarks
+
This in-file is used to add/remove nodes in XML files, such as bookmarks and Pidgin accounts.
-
and Pidgin accounts.
+
Syntax:
Syntax:
 +
<pre>
 +
[CONTROL]
 +
type:xml
 +
target:/path/to/the/xml/file/that/we/want/to/modify/or/create.xml
 +
node_path:/xml/path/to/a/node
 +
node_id_path:/xml/path/to/the/id/node /xml/path/to/another/id/node
 +
remove_by:id|marker
 +
if_exists:replace|keepold
-
[CONTROL]
+
[DATA]
-
type:xml
+
A complete XML document...
-
target:/path/to/the/xml/file/that/we/want/to/modify/or/create.xml
+
</pre>
-
node_path:/xml/path/to/a/node
+
* <code>type</code>: Tells that it's an XML in-file.
-
node_id_path:/xml/path/to/the/id/node /xml/path/to/another/id/node
+
-
remove_by:id|marker
+
-
if_exists:replace|keepold
+
-
+
-
[DATA]
+
-
A complete XML document...
+
-
 
+
-
* <code>type</code>: Tells that it's an xml in-file.
+
* <code>target</code>: The file system path of the final output. If the file exists, it is also used as input.
* <code>target</code>: The file system path of the final output. If the file exists, it is also used as input.
* <code>node_path</code>: It is an XML-path that defines the nodes in the in-file <code>DATA</code> section that will be added to the target file.
* <code>node_path</code>: It is an XML-path that defines the nodes in the in-file <code>DATA</code> section that will be added to the target file.
Line 248: Line 233:
* If <code>remove_by</code> is <code>"id"</code>: Delete every node (based on <code>node_path</code>), from the target file that has the same id value (based on <code>node_id_path</code>) as the XML in the <code>DATA</code> section.
* If <code>remove_by</code> is <code>"id"</code>: Delete every node (based on <code>node_path</code>), from the target file that has the same id value (based on <code>node_id_path</code>) as the XML in the <code>DATA</code> section.
-
=== shell ===
+
==== shell ====
Shell in-files are a flexible way to create custom configurator scripts.
Shell in-files are a flexible way to create custom configurator scripts.
Syntax:
Syntax:
 +
<pre>
 +
[CONTROL]
 +
type:shell
-
[CONTROL]
+
[DATA]
-
type:shell
+
install:
-
+
commands
-
[DATA]
+
commands
-
install:
+
commands
-
commands
+
...
-
commands
+
-
commands
+
-
...
+
-
+
-
uninstall:
+
-
commands
+
-
commands
+
-
commands
+
-
...
+
 +
uninstall:
 +
commands
 +
commands
 +
commands
 +
...
 +
</pre>
-
The <code>DATA</code> section consists of and <code>"install"</code> and an <code>"uninstall"</code> subsection. The command
+
The <code>DATA</code> section consists of and <code>"install"</code> and an <code>"uninstall"</code> subsection. The command lines below the subsections constitute the content of the script. A script file is created with that content and is executed. So basically, you can write, e.g., shell scripts, perl and python scripts, etc.. Command lines cannot start with <code>"install:"</code> or <code>"uninstall:"</code>!
-
lines below the subsections constitute the content of the script. A script file
+
-
is created with that content and is executed. So basically, you can write, e.g., shell
+
-
scripts, perl and python scripts, etc..
+
-
Command lines cannot start with <code>"install:"</code> or <code>"uninstall:"</code>!
+
[[Category:Enterprise]]
[[Category:Enterprise]]

Latest revision as of 10:20, 2 February 2011

Epconf helps to configure software components that are commonly used in an enterprise environment (e.g. at companies).

Supported devices:

It supports the installation and modification of:

  • Browser bookmark thumbnail images: thumbnail_* files.
  • Wifi root certificates: *.crt files are used when authenticating via WLAN.
  • GConf schemas: *.schemas files are registered with GConf.
  • VCard files: *.vcard files are added to the contact list.
  • Custom actions: Custom configuration can be done with epconftool in-files (*.epin).

The above mentioned input files are taken from the /usr/share/epconf-sets/SET directory.

With epconf in-files you can configure:

  • Arbitrary XML files
  • GConf values
  • Anything with script files

If an epconf in-file file matches *.do-as-user.epin then the operations described by it will be executed as the user 'user'. For more information about in-files, please refer to epconftool. See the epconftool section for more details about epconftool in-files.

Contents

[hide]

[edit] Command line syntax

usage: epconf [debug] macro file_name ACTION SET[:GROUP[:ELEMENT]]...
    debug            Enables debug output.
    macro            Uses the specified macro file instead of the default one.
    ACTION           May be either install or uninstall.
    SET              Name of the configuration set to process.
                     It may be "all" which means "Process all the available set".
                     "all" cannot be mixed with other sets!
    GROUP            Can be one of
                         thumbnail: Process thumbnail_* thumbnails
                         crt: Process *.crt certificates
                         vcard: Process *.vcard vCards.
                         schemas: Process *.schemas GConf schemas
                         epin: Process *.epin epconftool in-files
                     If it is not given then all the groups are processed.
    ELEMENT          This can be used only with epin group.
                     Only the infile with the given name willbe processed.

The following example pulls the input files from /usr/share/enterprise_pilot/my_set:

epconf macro /home/user/macro.xml install my_set

The following example processes

  • best_in*.epin from /usr/share/enterprise_pilot/my_set then
  • *.vcard from /usr/share/enterprise_pilot/your_set and finally
  • all supported files from /usr/share/enterprise_pilot/their_set:
epconf install my_set:epin:best_in your_set:vcard their_set

[edit] epconftool

Epconftool processes in-files that can be used for the creation of sophisticated configuration scripts.

[edit] Command line syntax

usage: epconftool [-f] [-s] [-d] { -x | -l } macro-file { -i | -u } in-files...

  -i    Install using the given input files.
  -u    Uninstall using the given input files.
  -x    Macro file in XML format
  -l    Macro file in plain key-value format
  -f    Force. If the process fails at one input file it goes on to the next one.
        Without this option (default), a bad input file stops the entire process
        and the subsequent input files are not processed.
  -s    Do simple macro substitution (a macro in a macro is not processed).
  -d    Print debug output to stderr.
        Either -i or -u can be used. They cannot be mixed.

Built-in macros:

  • TIME_EPOCH: The seconds elapsed since 1970.01.01 (see 'man 2 time').
  • INFILE_DIR: Absolute path of the directory containing the in-file being processed.
  • MARKER: This may be used e.g. in XML in-files. If a node_path node contains this as a text field anywhere in its subtree, then that node is removed during un-installation. Otherwise it is not removed!

[edit] Macro file

The MACRO file contains usernames, passwords, etc. Each value in this file has a key associated with it. E.g., the WLAN_username key may have the value Jack. The keys of the MACRO file can be used in in-files as %key_name%. E.g., %WLAN_username%.

Two kinds of macro files are supported:

  • XML
  • Key-value list

[edit] XML

Let's take the following as an example:

<?xml version="1.0" encoding="UTF-8" ?>
<CONF>
  <NAME>Joe Buck</NAME>
  <REMOTE_ACCESS>
    <LOGIN>joebuck</LOGIN>
  </REMOTE_ACCESS>
  <SIP>
    <NAME>ext-joe.4.buck</NAME>
    <PASS>98765876</PASS>
  </SIP>
  <WLAN>
    <RESTAURANT>
      <LOGIN>joejoe</LOGIN>
      <PASS>buckybuck</PASS>
    </RESTAURANT>
  </WLAN>
  <EMAIL>
    <ADDRESS>ext-joe.4.buck@company.org</ADDRESS>
  </EMAIL>
</CONF>

When using the above example macro file, the macro values are the text nodes and the macro names are formed formed the tag names. For example, the %CONF_REMOTE_ACCESS_LOGIN% macro refers to the value "joebuck".

[edit] Key-value list

Let's take the following as an example:

"CONF_NAME" "Joe Buck"
"CONF_REMOTE_ACCESS_LOGIN" "joebuck"
"CONF_SIP_NAME" "ext-joe.4.buck"
"CONF_SIP_PASS" "98765876"
"CONF_WLAN_RESTAURANT_LOGIN" "joejoe"
"CONF_WLAN_RESTAURANT_PASS" "buckybuck"
"CONF_EMAIL_ADDRESS" "ext-joe.4.buck@company.org"

When using the above example macro file, the %CONF_REMOTE_ACCESS_LOGIN% macro refers to the value "joebuck".

If the " (double quote) character appears in a key or a value, then it must be escaped. For example, "Norton said \"Howdy!\" and then he left.". Same for the \ (backslash) character. For example, "\\" represents a single backslash character.

[edit] Input Template file (in-file)

In-files have the following general format:

[CONTROL]
# Comment
type:gconf|xml|shell
...

[DATA]
...
...%MACRO%...
...

The following lines are ignored:

  • empty lines: lines with only whitespace or newline
  • comments: lines whose first non-whitespace character is hash-mark ("#")

The tag (e.g., "type") and its value (e.g., "xml") in the CONTROL section are separated by a single colon character. The "type" tag is mandatory, and it must be the first non-ignored line in the CONTROL section.

Every %MACRO% macro is replaced with the matching value from the MACRO file during the installation/un-installation process. Macro substitution is applied to the entire in-file (e.g. if the value of MARKER is "Hello Hippo" then [CON%MARKER%TROL] is replaced with [CONHello HippoTROL]).

No recursive macro substitution is done. For example, if macro %APPLE% has the value "Hello %WORLD%" then the %WORLD" is not considered as a macro for substitution.

[edit] GConf

This in-file is used to add/remove GConf values. See [2] for an example!

Syntax:

[CONTROL]
type:gconf

[DATA]
dir:/path/to/gconf/directory
behavior:type:key_name:value
behavior:type-list:key_name:[value,value,...]
...

The "type" tag tells that it's a gconf in-file. The first line in the DATA section is the gconf directory that we want to configure. Subsequent lines describe key/value pairs for GConf keys, whitespaces are not allowed. Value lists are also supported. In this case, the type name is suffixed with the "-list" word and the value is a comma separated list enclosed in brackets. The behavior can be one of the following:

  • replace: If the key already exists, it is replaced.
  • merge: Only for value lists. If the key already exists, it is merged with the specified one.
  • keepold: If the key already exists, it is not changed.

Installation:

  • In the DATA section, all the %MACRO% tags are replaced with the proper values.
  • If the gconf directory /path/to/gconf/directory does not exist, it is created and populated with the provided key/value pairs.
  • If the gconf directory /path/to/gconf/directory exists:
    • If a provided key does not exist, it is created and its value is set.
    • If a provided key exists, the action taken depends on the specified behavior.

Uninstallation:

  • Simple values: The key is deleted.
  • List values: If behavior is "merge" only the values given in the in-file are removed from the list. For other behaviors, the entire key is deleted.
  • If after removing the keys, the entire /path/to/gconf/directory directory is deleted from gconf if it has become empty.

[edit] XML

This in-file is used to add/remove nodes in XML files, such as bookmarks and Pidgin accounts.

Syntax:

[CONTROL]
type:xml
target:/path/to/the/xml/file/that/we/want/to/modify/or/create.xml
node_path:/xml/path/to/a/node
node_id_path:/xml/path/to/the/id/node /xml/path/to/another/id/node
remove_by:id|marker
if_exists:replace|keepold

[DATA]
A complete XML document...
  • type: Tells that it's an XML in-file.
  • target: The file system path of the final output. If the file exists, it is also used as input.
  • node_path: It is an XML-path that defines the nodes in the in-file DATA section that will be added to the target file.
  • node_id_path: It is a spaces and/or tabs separated list of XML-paths. These paths are combined and used as the primary-key to identify duplicate/existing entries.
  • if_exists: Optional. Default is "keepold". Defines the behavior for installation. When set to "replace", existing nodes are replaced with the ones in the DATA section. When set to "keepold", existing nodes are left intact.
  • remove_by: Optional. Default is "marker". Defines the behavior for uninstallation. When set to "id", nodes that match the node_path/node_id_path are removed. When set to "marker", nodes that contain the %MARKER% value in any of their (or children) attributes or children nodes, are removed.

All XML-paths use the X-Path syntax, see http://www.w3schools.com/XPath/default.asp, http://www.w3.org/TR/xpath20/, http://xmlsoft.org/html/libxml-xpath.html.

The DATA section contains a complete XML document.

Installation:

  • In the DATA section, all the %MACRO% tags are replaced with the proper values.
  • If the target file does not exist, it is created with the output of the previous steps, which is the processed DATA section (the un-macroed DATA section).
  • If the target file exists:
    • Based on the node_id_path and node_path, nodes from the processed DATA section are added to the target file. If a node already exists (based on node_id_path), the node is not added.

Uninstallation:

  • If remove_by is "marker": Delete every node (based on node_path), from the target file that has a text element anywhere in it with the %MARKER% macro. Therefore, you MUST add the %MARKER% macro somewhere in the nodes that you want to be removed later.
  • If remove_by is "id": Delete every node (based on node_path), from the target file that has the same id value (based on node_id_path) as the XML in the DATA section.

[edit] shell

Shell in-files are a flexible way to create custom configurator scripts.

Syntax:

[CONTROL]
type:shell

[DATA]
install:
commands
commands
commands
...

uninstall:
commands
commands
commands
...

The DATA section consists of and "install" and an "uninstall" subsection. The command lines below the subsections constitute the content of the script. A script file is created with that content and is executed. So basically, you can write, e.g., shell scripts, perl and python scripts, etc.. Command lines cannot start with "install:" or "uninstall:"!