Editing Enterprise Device Configuration

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

The user device is configured using the following components:
* User configuration file: Enterprise User Configuration File (EUF)
* Configuration package: Enterprise Package (EP)

== Enterprise User Configuration File ==

The EUF is a result of the provisioning phase of the installation (recall [[Enterprise_-_Tried_and_tested_provisioning_strategies|the tried and tested]] or [[Enterprise_Provisioning_-_Strategy_Variations|the alternate]] provisioning strategies depending on your environment setup).
It may contain, e.g., user specific information. It is a simple XML file. We use 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>

This file is used by configuration scripts and programs to automatically fill-in e-mail addresses, passwords, etc. in the configuration files of the supported
applications. This way, after the installation of the Enterprise Package, the user will need to do only the minimal (if any) amount of manual setup.

In our examples, this configuration file is assumed to be in <code>/home/user/MyDocs/.documents/EnterpriseConfig.xml</code> after the provisioning.

== Enterprise Package ==

The EP is an installable application package that contains the following main parts:
* List of included applications
* Configuration scripts and configuration data: Used to configure the supported settings and applications on the device.

In this section, we create a simple EP that you can soon download from carage. This example can be used as a template to create your own customized package.

=== Adding applications ===

The EP may contain references to applications that are automatically installed when EP is installed.

To add an application you need to do the following steps:
# Make sure that a debian package is available of the application.
# Make sure that the repository where the debian package is found is accessible via the Application Manager during the installation of the EP.
# Edit the debian/control file of EP. For example, to add an application called "vpngui" you will have a control file similar to this:

Source: ep-example
 Section: user/office
 Priority: optional
 Maintainer: Joe Buck <joe.buck@net.org>
 Build-Depends: debhelper (>= 4.0.0), maemo-optify
 Standards-Version: 3.6.0
 
 Package: ep-example
 Architecture: all
 Section: user/office
 Depends: ${shlibs:Depends}, rdesktop-maemo (>= 1.6.0-2maemo1), rdesktop-m5ui (>= 1.0), enterprise-configurator (>= 1.0), vpngui (>= 5.5.0), vpnc (>= 0.5.9-1m6)
 Description: Enterprise application package for Joe Buck and his company.
 XB-Maemo-Display-Name: Joe Buck's Enterprise Package

[http://www.debian.org/doc/debian-policy/ch-controlfields.html Debian Policy Manual: Chapter 5 - Control files and their fields] has more information about creating Debian control files.

=== Configuring applications ===

When you look in the data directory of the example, you will see several different files.

The configurator uses a utility called enterprise-configurator. Here we demonstrate its usage by some practical examples.

This package contains command line utilities that simplify some common tasks.
One major component is the epconf program. It is called from the debian/postinst, preinst and prerm scripts (see [http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html Debian Policy Manual: Chapter 6 - Package maintainer scripts and installation procedure] for more information about debian maintainer scripts).

The files from the data directory are installed under <code>/usr/share/epconf-sets/ep-example</code> (see data/Makefile.am). The epconf utility processes them, for
example, after installation based on debian/postinst:

#!/bin/sh
 epconf macro /home/user/MyDocs/.documents/EnterpriseConfig.xml install ep-example
 exit 0

The epconf utility then processes the following files in <code>/usr/share/epconf-sets/ep-example</code>:

* <code>clean-user-data.sh</code>: This script is called when the users requests to clear the user data. It should remove user specific configuration files and sensitive data related to the applications that EP is responsible for.
* <code>process-list</code>: A list of processes that have to be stopped when EP is being configured. For example, if EP configures an IM client, probably the IM client should be stopped before the configuration starts. Every line in this file contains a process name as seen with the "ps" command.
* <code>process-list.stop</code>: This script is called if any of the processes listed in process-list is found running during configuration. It is responsible to stop those processes.

The device configuration is done with the following files:
 
* <code>*.epin</code>: These are in-files for the epconftool utility used by epconf.
* <code>*.crt</code>: These must be certificates in DER format. They are registered in the device for WLAN authentication.
* <code>*.vcard</code>: Every VCard file is inserted into the Contacts list.
* <code>thumbnail_*</code>: These image files are copied to the device and can be used in, e.g., Web bookmarks for thumbnail images (see [[Enterprise_Device_Configuration#Browser_Bookmarks|Browser Bookmarks]] for more information).

Epconf has two main arguments, <code>"install"</code> and <code>"uninstall"</code>, that do the configuration and de-configuration respectively. Epconf processes these above files during both installation and uninstallation.

Epconf in-files (<code>*.epin</code>) are special. In these, you can refer to text node values in the EUF. For example, based on our sample EUF above, if <code>"%CONF_SIP_NAME%"</code> appears anywhere in an in-file, it is replaced by epconf with the text <code>"ext-joe.4.buck"</code> (both without the double quotes). This is how the values in the EUF can be used to configure the device.

=== Configuration examples ===

The configurations below are included in our example.

==== Contacts ====

Contacts can be added to the contact list by providing the corresponding VCards in the data directory of EP.
An FN field must exist in each VCard that serves as an identifier. During installation, this FN field is used to detect duplicate contacts. During uninstallation, it is used to find the contact to be deleted.

For example:
 BEGIN:VCARD
 VERSION:3.0
 N:Helpline;Company
 FN:Company Emergency Helpline
 ORG:Company Co.
 TEL;TYPE=WORK:+456789098765
 END:VCARD

During uninstallation, all the contacts that have the "Company Emergency Helpline" FN field are deleted.

==== Desktop shortcuts ====

Desktop shortcuts are small icons on the desktop screen of the device. These are created by modifying the gconf database.
The configuration file that is responsible for this in our example is <code>data/shortcuts.do-as-user.epin</code>:
 [CONTROL]
 type:gconf
 
 [DATA]
 dir:/apps/osso/hildon-home/bookmarks/company
 replace:string:icon:%INFILE_DIR%/company_160x96.png
 replace:string:label:Company
 replace:string:url:http://www.company.com
 
 dir:/apps/osso/hildon-home/bookmarks/company-support
 replace:string:icon:%INFILE_DIR%/company_160x96.png
 replace:string:label:Support
 replace:string:url:http://www.company.com/support
 
 dir:/apps/osso/hildon-home
 merge:string-list:bookmark-shortcuts:[company,company-support]

This is a gconf in-file that is processed by epconf. The <code>CONTROL</code> section tells that it contains gconf related settings. The DATA section describes the gconf directories and their nodes that are modified during installation/uninstallation.

This example creates two shortcuts to two web pages. The <code>%INFILE_DIR%</code> macro is replaced by the <code>/usr/share/epconf-sets/ep-example</code> string. So, the icons are taken from <code>/usr/share/epconf-sets/ep-example/company_160x96.png</code>. Those icons are provided in the data directory of the EP package and are installed to /usr/share/epconf-sets/ep-example when the EP is installed.

==== WLAN ====

WLAN access points are also configured by using gconf in-files. The data/wlan.do-as-user.epin configures our example WLAN AP. The new AP will be available in the list of Access Points by the name <code>"COMPANY_RESTAURANT"</code>:

[CONTROL]
 type:gconf
 
 [DATA]
 dir:/system/osso/connectivity/IAP/COMPANY_RESTAURANT
 replace:int:EAP_default_type:25
 replace:int:proxy_https_port:0
 replace:int:proxy_http_port:0
 replace:string:type:WLAN_INFRA
 replace:string:ipv4_address:0.0.0.0
 replace:string:EAP_manual_username:anonymous@anon1
 replace:bool:ipv4_autodns:true
 replace:int:EAP_GSMSIM_max_reauth_count:100
 replace:string:ipv4_gateway:0.0.0.0
 replace:string:proxytype:NONE
 replace:int:wlan_powersave:4
 replace:string:autoconf_url:
 replace:string:proxy_https:
 replace:string:EAP_MSCHAPV2_username:%CONF_WLAN_RESTAURANT_LOGIN%
 replace:bool:TLS_server_authenticates_client_policy_in_client:false
 replace:string:wlan_security:WPA_EAP
 replace:string:proxy_rtsp:
 replace:bool:EAP_use_manual_username:true
 replace:int:proxy_ftp_port:0
 replace:int:proxy_rtsp_port:0
 replace:int-list:wlan_ssid:[87,73,86,79]
 replace:bool:EAP_wpa2_only_mode:false
 replace:int:wlan_adhoc_channel:0
 replace:string:ipv4_dns1:0.0.0.0
 replace:string:ipv4_dns2:0.0.0.0
 replace:string:proxy_http:
 replace:string:ipv4_netmask:0.0.0.0
 replace:int:PEAP_tunneled_eap_type:26
 replace:int-list:omit_proxy:[]
 replace:string:ipv4_type:AUTO
 replace:bool:wlan_hidden:false
 replace:string:EAP_MSCHAPV2_password:%CONF_WLAN_RESTAURANT_PASS%
 replace:int:EAP_MSCHAPV2_password_prompt:0
 replace:string:proxy_ftp:

Here the <code>%CONF_WLAN_RESTAURANT_USER%</code> macro will be automatically replaced by epconf with the value of the <code>/CONF/WLAN/RESTAURANT/USER</code> node from the <code>/home/user/MyDocs/.documents/EnterpriseConfig.xml</code> file. The <code>%CONF_WLAN_RESTAURANT_PASS%</code> is processed similarly.

Our WLAN needs also a root certificate used for authentication. It is in <code>data/wlan.crt</code> and it is automatically installed to the right place by epconf so, no special in-file is necessary.

==== Mail for Exchange ====

The Mail for Exchange (MfE) account is not fully configured due to the unavailability of the user's password. Nevertheless, the <code>data/activesync.do-as-user.epin</code> fills in most of the fields of the MfE setup wizard so, the user needs to provide only her password:

[CONTROL]
 type:gconf
 
 [DATA]
 dir:/apps/activesync/preconfigure
 replace:string:credentials/username:%CONF_REMOTE_ACCESS_LOGIN%
 replace:string:email/email_addr:%CONF_EMAIL_ADDRESS%
 replace:string:connection/exchange_server:mail.company.org
 replace:string:credentials/domain:COMPANY
 replace:int:connection/port:443
 replace:int:contacts/first_sync:1
 replace:bool:connection/secure_connection:true
 replace:bool:connection/sync/mail:true
 replace:bool:connection/sync/contacts:true
 replace:bool:connection/sync/calendar:true

Here the <code>%CONF_REMOTE_ACCESS_LOGIN%</code> macro will be automatically replaced by epconf with the value of the <code>/CONF/REMOTE_ACCESS/LOGIN</code> node from the <code>/home/user/MyDocs/.documents/EnterpriseConfig.xml</code> file. The <code>%CONF_EMAIL_ADDRESS%</code> is processed similarly.

==== SIP Account ====

A SIP VoIP account is created by <code>data/im-sip.do-as-user.epin</code>. It is an in-file that contains two shell scripts in its <code>DATA</code> section. One for installation and
one for uninstallation. The scripts after the <code>"install:</code>" mark is executed when epconf is invoked with the <code>"install"</code> argument. Similarly, the script after the <code>"uninstall:</code>" mark is executed during uninstallation (i.e. de-configuration).

==== Browser Bookmarks ====

Browser bookmarks are stored in an XML file. Modifying XML files is a complicated task so, epconf provides a way to do it relatively easily with in-files.
In our examples, web browser bookmarks are configured by <code>data/bookmarks.do-as-user.epin</code>:

[CONTROL]
 type:xml
 target:/home/user/.bookmarks/MyBookmarks.xml
 node_path:/xbel/bookmark
 node_id_path:./title
 if_exists:replace
 
 [DATA]
 <?xml version="1.0"?>
 <DOCTYPE xbel PUBLIC "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML" "http://www.python.org/topics/xml/
 dtds/xbel-1.0.dtd">
 <xbel version="1.0">
 <info>
 <metadata>
 <default_folder>yes</default_folder>
 </metadata>
 </info>
 <title>My bookmarks</title>
 <info>
 <metadata>
 <time_visited>%TIME_EPOCH%</time_visited>
 <time_added>%TIME_EPOCH%</time_added>
 <operator_bookmark>1</operator_bookmark>
 <deleted>0</deleted>
 </metadata>
 </info>
 <bookmark href="https://mail.company.com" favicon="" thumbnail="thumbnail_company.png">
 <title>Company Email</title>
 <desc>%MARKER%</desc>
 </bookmark>
 <bookmark href="company.com/" favicon="" thumbnail="thumbnail_company.png">
 <title>Company Home Page</title>
 <desc>%MARKER%</desc>
 </bookmark>
 </xbel>

The <code>"target"</code> tag in the <code>CONTROL</code> section tells the location of the bookmark file on the device. The <code>"node_path"</code> identifies (by an XPath expression) the nodes that are to be inserted. The <code>node_id_path</code> (also an XPath expression) tells what part of the nodes (identified by <code>node_id_path</code>) should be used for detection duplicate entries (nodes).

The <code>DATA</code> section contains the XML that we want to merge with the contents of the <code>"target"</code>. It must be a complete XML file because if the target does not exist it will be created with the full contents of the <code>DATA</code> section.

So, in our example, we want to add two bookmarks to <code>/home/user/.bookmarks/MyBookmarks.xml</code>. The bookmark nodes are taken from the <code>/xbel/bookmark</code> tags (subtrees). We use the <code>"title"</code> tag inside the <code>"bookmark"</code> tags for detecting if a bookmark already exists in the target. If a duplicate is detected, "if_exists" tells that we
want our bookmarks to overwrite the existing ones.

==== VPNGUI ====

The VPN client software has a UI called VPNGUI. The <code>data/vpngui-gateways.epin</code> configures two VPN gateways for our Joe Buck user. It is done by modifying the gconf database. Every VPN gateway has its own gconf directory under <code>/apps/osso/vpngui/ap/</code>. The gateway directory name must be a positive integer. For example, we
create gateway 0 (Company-Berlin) and 1 (Company-Vancouver):

[CONTROL]
 type:gconf
 
 [DATA]
 dir:/apps/osso/vpngui/ap/0
 replace:string:name:Company-Berlin
 replace:string:secret:aruba1
 replace:bool:secret_obf:false
 replace:string:group:company
 replace:string:gateway:192.122.220.123
 # Possible values: none, manual or auto
 replace:string:proxytype:manual
 replace:string:proxy_server:proxy.europe.company.com
 replace:int:proxy_port:8080
 replace:string:proxy_autoconfig_url:http://proxyconf.company.com/proxy.pac
 replace:string-list:proxy_ignore_hosts:[*.company.com]
 
 dir:/apps/osso/vpngui/ap/1
 replace:string:name:Company-Vancouver
 replace:string:secret:SDFGHJK1234567SDFGH34567XSDCFG34567XDCG
 replace:bool:secret_obf:true
 replace:string:group:linux-vpn
 replace:string:gateway:123.123.123.123
 # Possible values: none, manual or auto
 replace:string:proxytype:manual
 replace:string:proxy_server:proxy.americas.company.com
 replace:int:proxy_port:8080
 replace:string:proxy_autoconfig_url:http://proxyconf.company.com/proxy.pac
 replace:string-list:proxy_ignore_hosts:[*.company.com]

Whenever Joe Buck connects to a VPN gateway, we may need to run some actions. The VPNGUI supports post-connect and post-disconnect scripts that are run after
connection and after disconnection respectively. These scripts are put in place by <code>data/vpngui-scripts.epin</code>:

[CONTROL]
 type:shell
 
 [DATA]
 install:
 #!/bin/sh
 for PHASE in post-connect post-disconnect; do
         mkdir -p /etc/vpngui/$PHASE
         for i in `ls %INFILE_DIR%/*.$PHASE.vpns 2> /dev/null`; do
                 NAME=`basename $i | cut -f1 -d.`
                 chmod +x $i
                 ln -sf $i /etc/vpngui/$PHASE/$NAME
         done
 done
 
 uninstall:
 #!/bin/sh
 for PHASE in post-connect post-disconnect; do
         for i in `ls %INFILE_DIR%/*.$PHASE.vpns 2> /dev/null`; do
                 NAME=`basename $i | cut -f1 -d.`
                 rm -f /etc/vpngui/$PHASE/$NAME
         done
         rmdir -p /etc/vpngui/$PHASE > /dev/null || true
 done

It basically copies (links) the <code>data/*.vpns</code> files to the proper place where VPNGUI can find them during run-time.
In our example, these scripts (<code>data/50_company*.vpns</code>) force the SIP account to use the VPN connection (this is necessary due to a problem in the N900 software as of 2010.04.28).

==== RDesktop ====

In our example, we use a remote desktop client, rdesktop-maemo, which supports the configuration of a custom help file. We install a company specific help file with <code>data/rdesktop.epin</code>:

[CONTROL]
 type:shell
 
 [DATA]
 install:
 #!/bin/sh -ue
 mkdir -p /usr/share/rdesktop-m5ui
 ln -sf %INFILE_DIR%/rdesktop__help.pdf /usr/share/rdesktop-m5ui/
 
 uninstall:
 #!/bin/sh
 rm -f /usr/share/rdesktop-m5ui/rdesktop__help.pdf
 rmdir -p /usr/share/rdesktop-m5ui 2>/dev/null || true

= Summary =

In this page, we looked at how to create a custom Enterprise User Configuration File and a corresponding Enterprise Package. The provided examples can be used as a basis for your own deployment purposes. If you wish to learn more about epconf, feel free to read about [[Enterprise_Configurator|Enterprise Configurator]].

[[Category:Power users]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Enterprise_Device_Configuration"

Personal tools

Navigation

Views

Editing Enterprise Device Configuration

@@ Line 8: / Line 8: @@
 It may contain, e.g., user specific information. It is a simple XML file. We use the following as an example:
-<source lang="xml">
+ <?xml version="1.0" encoding="UTF-8" ?>
-<?xml version="1.0" encoding="UTF-8" ?>
+ <CONF>
-<CONF>
+   <NAME>Joe Buck</NAME>
-  <NAME>Joe Buck</NAME>
+   <REMOTE_ACCESS>
-  <REMOTE_ACCESS>
+     <LOGIN>joebuck</LOGIN>
-    <LOGIN>joebuck</LOGIN>
+   </REMOTE_ACCESS>
-  </REMOTE_ACCESS>
+   <SIP>
-  <SIP>
+     <NAME>ext-joe.4.buck</NAME>
-    <NAME>ext-joe.4.buck</NAME>
+     <PASS>98765876</PASS>
-    <PASS>98765876</PASS>
+   </SIP>
-  </SIP>
+   <WLAN>
-  <WLAN>
+     <RESTAURANT>
-    <RESTAURANT>
+       <LOGIN>joejoe</LOGIN>
-      <LOGIN>joejoe</LOGIN>
+       <PASS>buckybuck</PASS>
-      <PASS>buckybuck</PASS>
+     </RESTAURANT>
-    </RESTAURANT>
+   </WLAN>
-  </WLAN>
+   <EMAIL>
-  <EMAIL>
+     <ADDRESS>ext-joe.4.buck@company.org</ADDRESS>
-    <ADDRESS>ext-joe.4.buck@company.org</ADDRESS>
+   </EMAIL>
-  </EMAIL>
+ </CONF>
-</CONF>
-</source>
 This file is used by configuration scripts and programs to automatically fill-in e-mail addresses, passwords, etc. in the configuration files of the supported
@@ Line 49: / Line 47: @@
 To add an application you need to do the following steps:
-# Make sure that a Debian package is available of the application.
+# Make sure that a debian package is available of the application.
 # Make sure that the repository where the debian package is found is accessible via the Application Manager during the installation of the <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP</span>.
 # Edit the debian/control file of <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP</span>. For example, to add an application called "vpngui" you will have a control file similar to this:
-<pre>
+ Source: ep-example
-Source: ep-example
+ Section: user/office
-Section: user/office
+ Priority: optional
-Priority: optional
+ Maintainer: Joe Buck <joe.buck@net.org>
-Maintainer: Joe Buck <joe.buck@net.org>
+ Build-Depends: debhelper (>= 4.0.0), maemo-optify
-Build-Depends: debhelper (>= 4.0.0), maemo-optify
+ Standards-Version: 3.6.0
-Standards-Version: 3.6.0
+ Package: ep-example
-Package: ep-example
+ Architecture: all
-Architecture: all
+ Section: user/office
-Section: user/office
+ Depends: ${shlibs:Depends}, rdesktop-maemo (>= 1.6.0-2maemo1), rdesktop-m5ui (>= 1.0), enterprise-configurator (>= 1.0), vpngui (>= 5.5.0), vpnc (>= 0.5.9-1m6)
-Depends: ${shlibs:Depends}, rdesktop-maemo (>= 1.6.0-2maemo1), rdesktop-m5ui (>= 1.0), enterprise-configurator (>= 1.0), vpngui (>= 5.5.0), vpnc (>= 0.5.9-1m6)
+ Description: Enterprise application package for Joe Buck and his company.
-Description: Enterprise application package for Joe Buck and his company.
+ XB-Maemo-Display-Name: Joe Buck's Enterprise Package
-XB-Maemo-Display-Name: Joe Buck's Enterprise Package
-</pre>
 [http://www.debian.org/doc/debian-policy/ch-controlfields.html Debian Policy Manual: Chapter 5 - Control files and their fields] has more information about creating Debian control files.
@@ Line 78: / Line 74: @@
 This package contains command line utilities that simplify some common tasks.
-One major component is the epconf program. It is called from the debian/postinst, preinst and prerm scripts (see [http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html Debian Policy Manual: Chapter 6 - Package maintainer scripts and installation procedure] for more information about Debian maintainer scripts).
+One major component is the epconf program. It is called from the debian/postinst, preinst and prerm scripts (see [http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html Debian Policy Manual: Chapter 6 - Package maintainer scripts and installation procedure] for more information about debian maintainer scripts).
-The files from the data directory are installed under <code>/usr/share/epconf-sets/ep-example</code> (see <code>data/Makefile.am</code>). The <code>epconf</code> utility processes them, for example, after installation based on debian/postinst:
+The files from the data directory are installed under <code>/usr/share/epconf-sets/ep-example</code> (see data/Makefile.am). The epconf utility processes them, for
+example, after installation based on debian/postinst:
-<source lang="bash">
+ #!/bin/sh
-#!/bin/sh
+ epconf macro /home/user/MyDocs/.documents/EnterpriseConfig.xml install ep-example
-epconf macro /home/user/MyDocs/.documents/EnterpriseConfig.xml install ep-example
+ exit 0
-exit 0
-</source>
 The epconf utility then processes the following files in <code>/usr/share/epconf-sets/ep-example</code>:
@@ Line 115: / Line 110: @@
 For example:
-<pre>
+ BEGIN:VCARD
-BEGIN:VCARD
+ VERSION:3.0
-VERSION:3.0
+ N:Helpline;Company
-N:Helpline;Company
+ FN:Company Emergency Helpline
-FN:Company Emergency Helpline
+ ORG:Company Co.
-ORG:Company Co.
+ TEL;TYPE=WORK:+456789098765
-TEL;TYPE=WORK:+456789098765
+ END:VCARD
-END:VCARD
-</pre>
 During uninstallation, all the contacts that have the "Company Emergency Helpline" FN field are deleted.
@@ Line 129: / Line 122: @@
 ==== Desktop shortcuts ====
-Desktop shortcuts are small icons on the desktop screen of the device. These are created by modifying the GConf database. The configuration file that is responsible for this in our example is <code>data/shortcuts.do-as-user.epin</code>:
+Desktop shortcuts are small icons on the desktop screen of the device. These are created by modifying the gconf database.
+The configuration file that is responsible for this in our example is <code>data/shortcuts.do-as-user.epin</code>:
+ [CONTROL]
+ type:gconf
+ [DATA]
+ dir:/apps/osso/hildon-home/bookmarks/company
+ replace:string:icon:%INFILE_DIR%/company_160x96.png
+ replace:string:label:Company
+ replace:string:url:http://www.company.com
+ dir:/apps/osso/hildon-home/bookmarks/company-support
+ replace:string:icon:%INFILE_DIR%/company_160x96.png
+ replace:string:label:Support
+ replace:string:url:http://www.company.com/support
+ dir:/apps/osso/hildon-home
+ merge:string-list:bookmark-shortcuts:[company,company-support]
-<pre>
+This is a gconf in-file that is processed by epconf. The <code>CONTROL</code> section tells that it contains gconf related settings. The DATA section describes the gconf directories and their nodes that are modified during installation/uninstallation.
-[CONTROL]
-type:gconf
-[DATA]
-dir:/apps/osso/hildon-home/bookmarks/company
-replace:string:icon:%INFILE_DIR%/company_160x96.png
-replace:string:label:Company
-replace:string:url:http://www.company.com
-dir:/apps/osso/hildon-home/bookmarks/company-support
-replace:string:icon:%INFILE_DIR%/company_160x96.png
-replace:string:label:Support
-replace:string:url:http://www.company.com/support
-dir:/apps/osso/hildon-home
-merge:string-list:bookmark-shortcuts:[company,company-support]
-</pre>
-This is a GConf in-file that is processed by <code>epconf</code>. The <code>CONTROL</code> section tells that it contains GConf-related settings. The <code>DATA</code> section describes the GConf directories and their nodes that are modified during installation/uninstallation.
 This example creates two shortcuts to two web pages. The <code>%INFILE_DIR%</code> macro is replaced by the <code>/usr/share/epconf-sets/ep-example</code> string. So, the icons are taken from <code>/usr/share/epconf-sets/ep-example/company_160x96.png</code>. Those icons are provided in the data directory of the <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP</span> package and are installed to /usr/share/epconf-sets/ep-example when the <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP</span> is installed.
@@ Line 158: / Line 149: @@
 WLAN access points are also configured by using gconf in-files. The data/wlan.do-as-user.epin configures our example WLAN AP. The new AP will be available in the list of Access Points by the name <code>"COMPANY_RESTAURANT"</code>:
-<pre>
+ [CONTROL]
-[CONTROL]
+ type:gconf
-type:gconf
+ [DATA]
-[DATA]
+ dir:/system/osso/connectivity/IAP/COMPANY_RESTAURANT
-dir:/system/osso/connectivity/IAP/COMPANY_RESTAURANT
+ replace:int:EAP_default_type:25
-replace:int:EAP_default_type:25
+ replace:int:proxy_https_port:0
-replace:int:proxy_https_port:0
+ replace:int:proxy_http_port:0
-replace:int:proxy_http_port:0
+ replace:string:type:WLAN_INFRA
-replace:string:type:WLAN_INFRA
+ replace:string:ipv4_address:0.0.0.0
-replace:string:ipv4_address:0.0.0.0
+ replace:string:EAP_manual_username:anonymous@anon1
-replace:string:EAP_manual_username:anonymous@anon1
+ replace:bool:ipv4_autodns:true
-replace:bool:ipv4_autodns:true
+ replace:int:EAP_GSMSIM_max_reauth_count:100
-replace:int:EAP_GSMSIM_max_reauth_count:100
+ replace:string:ipv4_gateway:0.0.0.0
-replace:string:ipv4_gateway:0.0.0.0
+ replace:string:proxytype:NONE
-replace:string:proxytype:NONE
+ replace:int:wlan_powersave:4
-replace:int:wlan_powersave:4
+ replace:string:autoconf_url:
-replace:string:autoconf_url:
+ replace:string:proxy_https:
-replace:string:proxy_https:
+ replace:string:EAP_MSCHAPV2_username:%CONF_WLAN_RESTAURANT_LOGIN%
-replace:string:EAP_MSCHAPV2_username:%CONF_WLAN_RESTAURANT_LOGIN%
+ replace:bool:TLS_server_authenticates_client_policy_in_client:false
-replace:bool:TLS_server_authenticates_client_policy_in_client:false
+ replace:string:wlan_security:WPA_EAP
-replace:string:wlan_security:WPA_EAP
+ replace:string:proxy_rtsp:
-replace:string:proxy_rtsp:
+ replace:bool:EAP_use_manual_username:true
-replace:bool:EAP_use_manual_username:true
+ replace:int:proxy_ftp_port:0
-replace:int:proxy_ftp_port:0
+ replace:int:proxy_rtsp_port:0
-replace:int:proxy_rtsp_port:0
+ replace:int-list:wlan_ssid:[87,73,86,79]
-replace:int-list:wlan_ssid:[87,73,86,79]
+ replace:bool:EAP_wpa2_only_mode:false
-replace:bool:EAP_wpa2_only_mode:false
+ replace:int:wlan_adhoc_channel:0
-replace:int:wlan_adhoc_channel:0
+ replace:string:ipv4_dns1:0.0.0.0
-replace:string:ipv4_dns1:0.0.0.0
+ replace:string:ipv4_dns2:0.0.0.0
-replace:string:ipv4_dns2:0.0.0.0
+ replace:string:proxy_http:
-replace:string:proxy_http:
+ replace:string:ipv4_netmask:0.0.0.0
-replace:string:ipv4_netmask:0.0.0.0
+ replace:int:PEAP_tunneled_eap_type:26
-replace:int:PEAP_tunneled_eap_type:26
+ replace:int-list:omit_proxy:[]
-replace:int-list:omit_proxy:[]
+ replace:string:ipv4_type:AUTO
-replace:string:ipv4_type:AUTO
+ replace:bool:wlan_hidden:false
-replace:bool:wlan_hidden:false
+ replace:string:EAP_MSCHAPV2_password:%CONF_WLAN_RESTAURANT_PASS%
-replace:string:EAP_MSCHAPV2_password:%CONF_WLAN_RESTAURANT_PASS%
+ replace:int:EAP_MSCHAPV2_password_prompt:0
-replace:int:EAP_MSCHAPV2_password_prompt:0
+ replace:string:proxy_ftp:
-replace:string:proxy_ftp:
-</pre>
 Here the <code>%CONF_WLAN_RESTAURANT_USER%</code> macro will be automatically replaced by epconf with the value of the <code>/CONF/WLAN/RESTAURANT/USER</code> node from the <code>/home/user/MyDocs/.documents/EnterpriseConfig.xml</code> file. The <code>%CONF_WLAN_RESTAURANT_PASS%</code> is processed similarly.
@@ Line 208: / Line 197: @@
 The Mail for Exchange (MfE) account is not fully configured due to the unavailability of the user's password. Nevertheless, the <code>data/activesync.do-as-user.epin</code> fills in most of the fields of the MfE setup wizard so, the user needs to provide only her password:
-<pre>
+ [CONTROL]
-[CONTROL]
+ type:gconf
-type:gconf
+ [DATA]
-[DATA]
+ dir:/apps/activesync/preconfigure
-dir:/apps/activesync/preconfigure
+ replace:string:credentials/username:%CONF_REMOTE_ACCESS_LOGIN%
-replace:string:credentials/username:%CONF_REMOTE_ACCESS_LOGIN%
+ replace:string:email/email_addr:%CONF_EMAIL_ADDRESS%
-replace:string:email/email_addr:%CONF_EMAIL_ADDRESS%
+ replace:string:connection/exchange_server:mail.company.org
-replace:string:connection/exchange_server:mail.company.org
+ replace:string:credentials/domain:COMPANY
-replace:string:credentials/domain:COMPANY
+ replace:int:connection/port:443
-replace:int:connection/port:443
+ replace:int:contacts/first_sync:1
-replace:int:contacts/first_sync:1
+ replace:bool:connection/secure_connection:true
-replace:bool:connection/secure_connection:true
+ replace:bool:connection/sync/mail:true
-replace:bool:connection/sync/mail:true
+ replace:bool:connection/sync/contacts:true
-replace:bool:connection/sync/contacts:true
+ replace:bool:connection/sync/calendar:true
-replace:bool:connection/sync/calendar:true
-</pre>
 Here the <code>%CONF_REMOTE_ACCESS_LOGIN%</code> macro will be automatically replaced by epconf with the value of the <code>/CONF/REMOTE_ACCESS/LOGIN</code> node from the <code>/home/user/MyDocs/.documents/EnterpriseConfig.xml</code> file. The <code>%CONF_EMAIL_ADDRESS%</code> is processed similarly.
@@ Line 235: / Line 222: @@
 ==== Browser Bookmarks ====
-Browser bookmarks are stored in an XML file. Modifying XML files is a complicated task so, <code>epconf</code> provides a way to do it relatively easily with in-files. In our examples, web browser bookmarks are configured by <code>data/bookmarks.do-as-user.epin</code>:
+Browser bookmarks are stored in an XML file. Modifying XML files is a complicated task so, epconf provides a way to do it relatively easily with in-files.
+In our examples, web browser bookmarks are configured by <code>data/bookmarks.do-as-user.epin</code>:
-<pre>
+ [CONTROL]
-[CONTROL]
+ type:xml
-type:xml
+ target:/home/user/.bookmarks/MyBookmarks.xml
-target:/home/user/.bookmarks/MyBookmarks.xml
+ node_path:/xbel/bookmark
-node_path:/xbel/bookmark
+ node_id_path:./title
-node_id_path:./title
+ if_exists:replace
-if_exists:replace
+ [DATA]
-[DATA]
+ <?xml version="1.0"?>
-<?xml version="1.0"?>
+ <DOCTYPE xbel PUBLIC "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML" "http://www.python.org/topics/xml/
-<DOCTYPE xbel PUBLIC "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML" "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd">
+ dtds/xbel-1.0.dtd">
-<xbel version="1.0">
+ <xbel version="1.0">
-  <info>
+   <info>
-    <metadata>
+     <metadata>
-      <default_folder>yes</default_folder>
+       <default_folder>yes</default_folder>
-    </metadata>
+     </metadata>
-  </info>
+   </info>
-  <title>My bookmarks</title>
+   <title>My bookmarks</title>
-  <info>
+   <info>
-    <metadata>
+     <metadata>
-      <time_visited>%TIME_EPOCH%</time_visited>
+       <time_visited>%TIME_EPOCH%</time_visited>
-      <time_added>%TIME_EPOCH%</time_added>
+       <time_added>%TIME_EPOCH%</time_added>
-      <operator_bookmark>1</operator_bookmark>
+       <operator_bookmark>1</operator_bookmark>
-      <deleted>0</deleted>
+       <deleted>0</deleted>
-    </metadata>
+     </metadata>
-  </info>
+   </info>
-  <bookmark href="https://mail.company.com" favicon="" thumbnail="thumbnail_company.png">
+   <bookmark href="https://mail.company.com" favicon="" thumbnail="thumbnail_company.png">
-    <title>Company Email</title>
+     <title>Company Email</title>
-    <desc>%MARKER%</desc>
+     <desc>%MARKER%</desc>
-  </bookmark>
+   </bookmark>
-  <bookmark href="company.com/" favicon="" thumbnail="thumbnail_company.png">
+   <bookmark href="company.com/" favicon="" thumbnail="thumbnail_company.png">
-    <title>Company Home Page</title>
+     <title>Company Home Page</title>
-    <desc>%MARKER%</desc>
+     <desc>%MARKER%</desc>
-  </bookmark>
+   </bookmark>
-</xbel>
+ </xbel>
-</pre>
 The <code>"target"</code> tag in the <code>CONTROL</code> section tells the location of the bookmark file on the device. The <code>"node_path"</code> identifies (by an XPath expression) the nodes that are to be inserted. The <code>node_id_path</code> (also an XPath expression) tells what part of the nodes (identified by <code>node_id_path</code>) should be used for detection duplicate entries (nodes).
@@ Line 278: / Line 265: @@
 The <code>DATA</code> section contains the XML that we want to merge with the contents of the <code>"target"</code>. It must be a complete XML file because if the target does not exist it will be created with the full contents of the <code>DATA</code> section.
-So, in our example, we want to add two bookmarks to <code>/home/user/.bookmarks/MyBookmarks.xml</code>. The bookmark nodes are taken from the <code>/xbel/bookmark</code> tags (subtrees). We use the <code>"title"</code> tag inside the <code>"bookmark"</code> tags for detecting if a bookmark already exists in the target. If a duplicate is detected, "if_exists" tells that we want our bookmarks to overwrite the existing ones.
+So, in our example, we want to add two bookmarks to <code>/home/user/.bookmarks/MyBookmarks.xml</code>. The bookmark nodes are taken from the <code>/xbel/bookmark</code> tags (subtrees). We use the <code>"title"</code> tag inside the <code>"bookmark"</code> tags for detecting if a bookmark already exists in the target. If a duplicate is detected, "if_exists" tells that we
+want our bookmarks to overwrite the existing ones.
 ==== VPNGUI ====
-The VPN client software has a UI called VPNGUI. The <code>data/vpngui-gateways.epin</code> configures two VPN gateways for our Joe Buck user. It is done by modifying the gconf database. Every VPN gateway has its own gconf directory under <code>/apps/osso/vpngui/ap/</code>. The gateway directory name must be a positive integer. For example, we create gateway 0 (Company-Berlin) and 1 (Company-Vancouver):
+The VPN client software has a UI called VPNGUI. The <code>data/vpngui-gateways.epin</code> configures two VPN gateways for our Joe Buck user. It is done by modifying the gconf database. Every VPN gateway has its own gconf directory under <code>/apps/osso/vpngui/ap/</code>. The gateway directory name must be a positive integer. For example, we
+create gateway 0 (Company-Berlin) and 1 (Company-Vancouver):
-<pre>
+ [CONTROL]
-[CONTROL]
+ type:gconf
-type:gconf
+ [DATA]
+ dir:/apps/osso/vpngui/ap/0
+ replace:string:name:Company-Berlin
+ replace:string:secret:aruba1
+ replace:bool:secret_obf:false
+ replace:string:group:company
+ replace:string:gateway:192.122.220.123
+ # Possible values: none, manual or auto
+ replace:string:proxytype:manual
+ replace:string:proxy_server:proxy.europe.company.com
+ replace:int:proxy_port:8080
+ replace:string:proxy_autoconfig_url:http://proxyconf.company.com/proxy.pac
+ replace:string-list:proxy_ignore_hosts:[*.company.com]
+ dir:/apps/osso/vpngui/ap/1
+ replace:string:name:Company-Vancouver
+ replace:string:secret:SDFGHJK1234567SDFGH34567XSDCFG34567XDCG
+ replace:bool:secret_obf:true
+ replace:string:group:linux-vpn
+ replace:string:gateway:123.123.123.123
+ # Possible values: none, manual or auto
+ replace:string:proxytype:manual
+ replace:string:proxy_server:proxy.americas.company.com
+ replace:int:proxy_port:8080
+ replace:string:proxy_autoconfig_url:http://proxyconf.company.com/proxy.pac
+ replace:string-list:proxy_ignore_hosts:[*.company.com]
-[DATA]
+Whenever Joe Buck connects to a VPN gateway, we may need to run some actions. The VPNGUI supports post-connect and post-disconnect scripts that are run after
-dir:/apps/osso/vpngui/ap/0
+connection and after disconnection respectively. These scripts are put in place by <code>data/vpngui-scripts.epin</code>:
-replace:string:name:Company-Berlin
-replace:string:secret:aruba1
-replace:bool:secret_obf:false
-replace:string:group:company
-replace:string:gateway:192.122.220.123
-# Possible values: none, manual or auto
-replace:string:proxytype:manual
-replace:string:proxy_server:proxy.europe.company.com
-replace:int:proxy_port:8080
-replace:string:proxy_autoconfig_url:http://proxyconf.company.com/proxy.pac
-replace:string-list:proxy_ignore_hosts:[*.company.com]
-dir:/apps/osso/vpngui/ap/1
+ [CONTROL]
-replace:string:name:Company-Vancouver
+ type:shell
-replace:string:secret:SDFGHJK1234567SDFGH34567XSDCFG34567XDCG
-replace:bool:secret_obf:true
+ [DATA]
-replace:string:group:linux-vpn
+ install:
-replace:string:gateway:123.123.123.123
+ #!/bin/sh
-# Possible values: none, manual or auto
+ for PHASE in post-connect post-disconnect; do
-replace:string:proxytype:manual
+         mkdir -p /etc/vpngui/$PHASE
-replace:string:proxy_server:proxy.americas.company.com
+         for i in `ls %INFILE_DIR%/*.$PHASE.vpns 2> /dev/null`; do
-replace:int:proxy_port:8080
+                 NAME=`basename $i | cut -f1 -d.`
-replace:string:proxy_autoconfig_url:http://proxyconf.company.com/proxy.pac
+                 chmod +x $i
-replace:string-list:proxy_ignore_hosts:[*.company.com]
+                 ln -sf $i /etc/vpngui/$PHASE/$NAME
-</pre>
+         done
+ done
+ uninstall:
+ #!/bin/sh
+ for PHASE in post-connect post-disconnect; do
+         for i in `ls %INFILE_DIR%/*.$PHASE.vpns 2> /dev/null`; do
+                 NAME=`basename $i | cut -f1 -d.`
+                 rm -f /etc/vpngui/$PHASE/$NAME
+         done
+         rmdir -p /etc/vpngui/$PHASE > /dev/null || true
+ done
-Whenever Joe Buck connects to a VPN gateway, we may need to run some actions. The VPNGUI supports post-connect and post-disconnect scripts that are run after connection and after disconnection respectively. These scripts are put in place by <code>data/vpngui-scripts.epin</code>:
+It basically copies (links) the <code>data/*.vpns</code> files to the proper place where VPNGUI can find them during run-time.
+In our example, these scripts (<code>data/50_company*.vpns</code>) force the SIP account to use the VPN connection (this is necessary due to a problem in the N900 software as of 2010.04.28).
-<pre>
-[CONTROL]
-type:shell
-[DATA]
-install:
-#!/bin/sh
-for PHASE in post-connect post-disconnect; do
-        mkdir -p /etc/vpngui/$PHASE
-        for i in `ls %INFILE_DIR%/*.$PHASE.vpns 2> /dev/null`; do
-                NAME=`basename $i | cut -f1 -d.`
-                chmod +x $i
-                ln -sf $i /etc/vpngui/$PHASE/$NAME
-        done
-done
-uninstall:
-#!/bin/sh
-for PHASE in post-connect post-disconnect; do
-        for i in `ls %INFILE_DIR%/*.$PHASE.vpns 2> /dev/null`; do
-                NAME=`basename $i | cut -f1 -d.`
-                rm -f /etc/vpngui/$PHASE/$NAME
-        done
-        rmdir -p /etc/vpngui/$PHASE > /dev/null || true
-done
-</pre>
-It basically copies (links) the <code>data/*.vpns</code> files to the proper place where VPNGUI can find them during run-time. In our example, these scripts (<code>data/50_company*.vpns</code>) force the SIP account to use the VPN connection (this is necessary due to a problem in the N900 software as of 2010.04.28).
 ==== RDesktop ====
@@ Line 351: / Line 338: @@
 In our example, we use a remote desktop client, rdesktop-maemo, which supports the configuration of a custom help file. We install a company specific help file with <code>data/rdesktop.epin</code>:
-<pre>
+ [CONTROL]
-[CONTROL]
+ type:shell
-type:shell
+ [DATA]
-[DATA]
+ install:
-install:
+ #!/bin/sh -ue
-#!/bin/sh -ue
+ mkdir -p /usr/share/rdesktop-m5ui
-mkdir -p /usr/share/rdesktop-m5ui
+ ln -sf %INFILE_DIR%/rdesktop__help.pdf /usr/share/rdesktop-m5ui/
-ln -sf %INFILE_DIR%/rdesktop__help.pdf /usr/share/rdesktop-m5ui/
+ uninstall:
-uninstall:
+ #!/bin/sh
-#!/bin/sh
+ rm -f /usr/share/rdesktop-m5ui/rdesktop__help.pdf
-rm -f /usr/share/rdesktop-m5ui/rdesktop__help.pdf
+ rmdir -p /usr/share/rdesktop-m5ui 2>/dev/null || true
-rmdir -p /usr/share/rdesktop-m5ui 2>/dev/null || true
-</pre>
-== Summary ==
+= Summary =
 In this page, we looked at how to create a custom Enterprise User Configuration File and a corresponding Enterprise Package. The provided examples can be used as a basis for your own deployment purposes. If you wish to learn more about epconf, feel free to read about [[Enterprise_Configurator|Enterprise Configurator]].
-[[Category:Enterprise]]
+[[Category:Power users]]