Enterprise Device Configuration

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 the provisioning strategies). It may contain, e.g., user specific information. It is a simple XML file. We use the following as an example:

  Joe Buck  joebuck   ext-joe.4.buck 98765876   <RESTAURANT> joejoe</LOGIN> 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  after the provisioning.

Enterprise Package
The <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">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 <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">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 <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP may contain references to applications that are automatically installed when <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP is installed.

To add an application you need to do the following steps:
 * 1) Make sure that a debian package is available of the application.
 * 2) 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.
 * 3) 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 . 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

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 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  (see data/Makefile.am). The epconf utility processes them, for example, after installation based on debian/postinst:

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

The epconf utility then processes the following files in :


 * : 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 <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP is responsible for.
 * : A list of processes that have to be stopped when <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">EP is being configured. For example, if <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">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.
 * : 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:
 * : These are in-files for the epconftool utility used by epconf.
 * : These must be certificates in DER format. They are registered in the device for WLAN authentication.
 * : Every VCard file is inserted into the Contacts list.
 * : These image files are copied to the device and can be used in, e.g., Web bookmarks for thumbnail images (see Browser Bookmarks for more information).

Epconf has two main arguments,  and , that do the configuration and de-configuration respectively. Epconf processes these above files during both installation and uninstallation.

Epconf in-files are special. In these, you can refer to text node values in the <span style="color:#0000ff" title="Enterprise User Configuration File: A container for user-specific and enterprise-specific configuration values collected from various sources.">EUF. For example, based on our sample <span style="color:#0000ff" title="Enterprise User Configuration File: A container for user-specific and enterprise-specific configuration values collected from various sources.">EUF above, if  appears anywhere in an in-file, it is replaced by epconf with the text   (both without the double quotes). This is how the values in the <span style="color:#0000ff" title="Enterprise User Configuration File: A container for user-specific and enterprise-specific configuration values collected from various sources.">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 <span style="color:#0000ff" title="Enterprise Package: Contains the Enterprise Configurator and also contains a reference to all other required packages.">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 : [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  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  macro is replaced by the   string. So, the icons are taken from. 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 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 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 :

[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  macro will be automatically replaced by epconf with the value of the   node from the   file. The  is processed similarly.

Our WLAN needs also a root certificate used for authentication. It is in  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  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  macro will be automatically replaced by epconf with the value of the   node from the   file. The  is processed similarly.

SIP Account
A SIP VoIP account is created by. It is an in-file that contains two shell scripts in its  section. One for installation and one for uninstallation. The scripts after the " mark is executed when epconf is invoked with the   argument. Similarly, the script after the  " 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 :

[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"> <default_folder>yes</default_folder> My bookmarks <time_visited>%TIME_EPOCH%</time_visited> <time_added>%TIME_EPOCH%</time_added> <operator_bookmark>1</operator_bookmark> 0   <bookmark href="https://mail.company.com" favicon="" thumbnail="thumbnail_company.png"> Company Email %MARKER% <bookmark href="company.com/" favicon="" thumbnail="thumbnail_company.png"> Company Home Page %MARKER%

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

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

So, in our example, we want to add two bookmarks to. The bookmark nodes are taken from the  tags (subtrees). We use the  tag inside the   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  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. 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 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 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]
 * 1) Possible values: none, manual or auto
 * 1) Possible values: none, manual or auto

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 :

[CONTROL] type:shell [DATA] install: 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: 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
 * 1) !/bin/sh
 * 1) !/bin/sh

It basically copies (links) the  files to the proper place where VPNGUI can find them during run-time. In our example, these scripts 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 :

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

= 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.