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)

Contents

[edit] Enterprise User Configuration File

The EUF is a result of the provisioning phase of the installation (recall the tried and tested or 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 /home/user/MyDocs/.documents/EnterpriseConfig.xml after the provisioning.

[edit] 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.

[edit] 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:

  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 EP.
  3. 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

Debian Policy Manual: Chapter 5 - Control files and their fields has more information about creating Debian control files.

[edit] 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 /usr/share/epconf-sets/ep-example (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 /usr/share/epconf-sets/ep-example:

  • clean-user-data.sh: 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.
  • process-list: 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.
  • process-list.stop: 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:

  • *.epin: These are in-files for the epconftool utility used by epconf.
  • *.crt: These must be certificates in DER format. They are registered in the device for WLAN authentication.
  • *.vcard: Every VCard file is inserted into the Contacts list.
  • thumbnail_*: 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, "install" and "uninstall", that do the configuration and de-configuration respectively. Epconf processes these above files during both installation and uninstallation.

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

[edit] Configuration examples

The configurations below are included in our example.

[edit] 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.

[edit] 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 data/shortcuts.do-as-user.epin: 

[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 CONTROL 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 %INFILE_DIR% macro is replaced by the /usr/share/epconf-sets/ep-example string. So, the icons are taken from /usr/share/epconf-sets/ep-example/company_160x96.png. 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.

[edit] 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 "COMPANY_RESTAURANT": 

[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 %CONF_WLAN_RESTAURANT_USER% macro will be automatically replaced by epconf with the value of the /CONF/WLAN/RESTAURANT/USER node from the /home/user/MyDocs/.documents/EnterpriseConfig.xml file. The %CONF_WLAN_RESTAURANT_PASS% is processed similarly.

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

[edit] Mail for Exchange

The Mail for Exchange (MfE) account is not fully configured due to the unavailability of the user's password. Nevertheless, the data/activesync.do-as-user.epin 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 %CONF_REMOTE_ACCESS_LOGIN% macro will be automatically replaced by epconf with the value of the /CONF/REMOTE_ACCESS/LOGIN node from the /home/user/MyDocs/.documents/EnterpriseConfig.xml file. The %CONF_EMAIL_ADDRESS% is processed similarly.

[edit] SIP Account

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

[edit] 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 data/bookmarks.do-as-user.epin: 

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

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

So, in our example, we want to add two bookmarks to /home/user/.bookmarks/MyBookmarks.xml. The bookmark nodes are taken from the /xbel/bookmark tags (subtrees). We use the "title" tag inside the "bookmark" 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.

[edit] VPNGUI

The VPN client software has a UI called VPNGUI. The data/vpngui-gateways.epin 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 /apps/osso/vpngui/ap/. 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 data/vpngui-scripts.epin: 

[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 data/*.vpns files to the proper place where VPNGUI can find them during run-time. In our example, these scripts (data/50_company*.vpns) 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).

[edit] 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 data/rdesktop.epin: 

[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

[edit] 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.

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