View source for Enterprise Provisioning - Appendix

= Appendix 1: Content Type headers =

Content Type headers direct the web browser behaviour. Headers must be the first output of the web application. 

* HTML content: Directs the web browser to display a web page.

 Content-Type: text/html
 <span style="color:green"><empty line></span>
 <span style="color:green"><html content here></span>

* "Save as" file: Directs the web browser to open a "Save As..." dialog

 Content-Type: application/x-unknown
 Content-Disposition: attachment; filename="EnterpriseConfig.xml"
 <span style="color:green"><empty line></span>
 <span style="color:green"><file content here></span>

* Install file: Directs web browser to open Application Manager.

 Content-Type: application/x-install-instructions
 Content-Disposition: inline; filename="temp.install"
 <span style="color:green"><empty line></span>
 <span style="color:green"><install file content here></span>

* Multipart: A web server reply may contain multiple content types. Following example directs the web browser to display a web page and open a "Save As" dialog simultaneously:

 MIME-version: 1.0
 Content-Type: multipart/mixed; boundary=xAAAAAx
 <span style="color:green"><empty line></span>
 --xAAAAAx
 Content-Type: text/html
 <span style="color:green"><empty line></span>
 <span style="color:green"><html content here></span>
 --xAAAAAx
 Content-Type: application/x-unknown
 Content-Disposition: attachment; filename="EnterpriseConfig.xml"
 <span style="color:green"><empty line></span>
 <span style="color:green"><file content here></span>

= Appendix 2: Creating a package on-the-fly =

The following section gives an example how to create an application package. In the example, a package containing the EUF is created. The file will be first created in <code>/etc/EnterpriseConfig.xml</code> and then copied to its final place by a post-install script. The reasons to do it this are:
* To demonstrate the creation of a post-install script
* Package managers might not always like to create files under the user's home directory.

This approach enables building packages also in a limited or "alien environment". (For example in RPM based distribution)

The "dpkg-deb" command is needed. Usually, it is available in package called <code>dpkg</code> or <code>dpkg-dev</code>, depending on the distribution (available also in RPM based distributions)

Setup the "buildroot":

 mkdir -p user-info-1.2345/DEBIAN

Create the package content: In this case, the file <code>/etc/EnterpriseConfig.xml</code>.

 mkdir -p user-info-1.2345/etc
 cp /path/to/EnterpriseConfig.xml user-info-1.2345/etc/EnterpriseConfig.xml

Create the post-install script:

 cat <<@EOF > user-info-1.2345/DEBIAN/postinst
 #!/bin/sh
 if [ "\$1" = "configure" -o "\$1" = "install" -o "\$1" = "triggered" ]; then
    mkdir -p /home/user/MyDocs/.documents
    su user -c "cp -f /etc/EnterpriseConfig.xml /home/user/MyDocs/.documents/EnterpriseConfig.xml"
 fi
 
 #DEBHELPER#
 exit 0
 @EOF
 chmod 755 user-info-1.2345/DEBIAN/postinst


Note, the <code>if</code> clause, <code>"#DEBHELPER#"</code> text and exit command must be present in the script as in the example.

Create metadata:

 cat <<@EOF > user-info-1.2345/DEBIAN/control
 Package: user-info
 Version: 1.2345
 Section: user/Enterprise
 Priority: extra
 Maintainer: John Smith <john.smith@example.com>
 Architecture: all
 Description: Package for Enterprise User Configuration File
  On-the-fly created package containing user personal data
 @EOF

Note about the version number: In a package like this, it might be a good idea to use an automatically increasing number such as a timestamp. That would cause subsequent provisionings behave as upgrades, which is in most cases the desired behaviour. As an example, in a Python script, a suitable timestamp (minutes since Epoch) can be created by 

 str(int(time.time()/60)

Build the package:

 dpkg-deb --build user-info-1.2345

This command will create a package called <code>user-info-1.2345.deb</code>.

= Appendix 3: Creating a repository on-the-fly =

The following section gives an example of how to create a temporary repository.
The sample procedure creates a temporary repository named <code>tmprepo123</code> which contains the <code>user-info</code> package created earlier. Inside the repository, "distribution" is <code>fremantle</code> and "component" is <code>userinfo</code>.

The <code>dpkg-scanpackages</code> command is needed. It is usually available in the <code>dpkg</code> or <code>dpkg-dev</code> packages, depending on the distribution (available also in RPM based distributions)

Create "bindir" environment variable:

 arch=`dpkg -I /path/to/user-info-1.2345.deb | grep Architecture: | awk '{print $NF}'`
 bindir="dists/fremantle/userinfo/binary-${arch}"

Create directory structure and go in the top level:

 mkdir -p tmprepo123/${bindir}/
 cd tmprepo123

Symlink (or copy) the package into repository:

 ln -sf /path/to/user-info-1.2345.deb  ${bindir}/

Create and compress the repository metadata:

 dpkg-scanpackages ${bindir} /dev/null > ${bindir}/Packages
 gzip -f -9 ${bindir}/Packages

Creating the install file: The following install file, when served with the correct Content-type header, would cause the device web browser to open the Application Manager and initiate the installation of the <code>user-info</code> package. This example contains also an <code>Enterprise</code> repository, which contains the packages that <code>user-info</code> depends on.

 [install]
 package =  user-info
 catalogues = Temporary; Enterprise
 
 [Temporary]
 name = Personal Info (temporary)
 uri = https://server.example.com/tmprepos/tmprepo123/
 components = userinfo
 
 [Enterprise]
 name = Enterprise Package Repository
 uri = https://server.example.com/repository/enterprise/
 components = sample1 sample2

= Appendix 4a:  Creating an offline repository on-the-fly =

The following section gives an example how to create an "offline repository" (i.e., a local repository on the device).
The offline repository presented here does need an Internet connection, but it does not need a connection to the Enterprise Intranet or VPN.

You can create the repository the same way as in Appendix 3 (or use some other repository).
You might consider merging the "enterprise repository" and "personal repository" into one for "offline usage".

Once you have the repository, continue with the installation file. You don't need the install-file shown in Appendix 3.
In this example, the repository is called "Maemolocal" and we expect it to have a "userinfo" component (same as in Appendix 3 example).

If you leave out the "package = user-info" it will just install the repository, but won't install any actual packages. You may replace the "user-info" with some other package you want to get installed when this repository is configured.

 cd ..
 cat << @EOF > Maemolocal.install
 [install]
 package =  user-info
 catalogues = Maemolocal
 
 [Maemolocal]
 name = Enterprise Repository - Local copy
 uri = file:/media/mmc1/Maemolocal
 components = userinfo
 
 @EOF

Notes
* If you really need a self contained offline (ie no network connection available) repository, then see the Appendix 4b.

Create the zip:

 rm -f maemolocal.zip
 zip -9 -r maemolocal.zip  *install Maemolocal/

Connect the device to the desktop computer with a usb-cable and unpack the contents of this zip file (with directories) to the top directory of the memorycard (MMC1).
Unplug the usb-cable when it is ready.

To install the repository on the device:
* Open the Filemanager,
* Go to the top directory of the memory card,
* Tap the "Maemolocal"-install file to start the repository configuration and installation.

= Appendix 4b - Selfcontained Offline repository =

If you need a repository which can be used completely offline, it needs to be self-contained (i.e., no dependencies for any other repositories)

# Create a repository directory and copy some packages there:
 $ mkdir MaemoOffline
 $ cp somewhere/*.deb MaemoOffline/
 $ (cd MaemoOffline && apt-ftparchive packages . >Packages)
# Create a matching MaemoOffline.install file:
 [card_install]
 card_catalogues = MaemoOffline
 packages = app-1; app-2
 
 [MaemoOffline]
 file_uri = MaemoOffline
 dist = ./

Create the zip file:

 rm -f maemooffline.zip
 zip -9 -r maemooffline.zip  MaemoOffline.install MaemoOffline/

Then you can continue as in Appendix 4a.

Automatic triggering of memory card installs (TO_BE_VERIFIED): Whenever a memory card is inserted that contains a file called <b>.auto.install</b>, that file is processed by the Application Manager. If you copy this MaemoOffline.install into .auto.install then the repository should get installed when user inserts the memory card.

= Appendix 5: Application Manager repository configuration commands =

The Application Manager repository configuration may need to be changed manually as a prerequisite for the Enterprise Package installation.

One good place to set repository configuration into sensible values is in the post-install script of the <code>user-info</code> package. 

Reset to factory defaults: Following commands reset the repository configuration to the factory defaults:

 hildon-application-manager-util restore-catalogues
 hildon-application-manager-util clear-user-catalogues

You might want to add the Enterprise Package repository or some other repository to the device repository configuration. This requires the following two steps:

First, create an XML file containing the desired repository configuration. In this example, we define two repositories, the second one being disabled.

 <config>
    <catalogue>
       <name>Enterprise Repository</name>
       <uri>https://server.example.com/repository/enterprise/</uri>
       <components>base extras</components>
    </catalogue>
    <catalogue>
       <name>Test Repository</name>
       <uri>https://server.example.com/repository/test/</uri>
       <components>base extras</components>
       <disabled/>
    </catalogue>
 </config>

Second, run the following command (assuming the XML file is at <code>/etc/repoconf.xml</code>)

 hildon-application-manager-config add /etc/repoconf.xml