Enterprise Provisioning - Appendix

(wikify slightly)
 
Line 1: Line 1:
-
= Appendix 1: Content Type headers =
+
== Appendix 1: Content Type headers ==
Content Type headers direct the web browser behaviour. Headers must be the first output of the web application.  
Content Type headers direct the web browser behaviour. Headers must be the first output of the web application.  
Line 38: Line 38:
  <span style="color:green"><file content here></span>
  <span style="color:green"><file content here></span>
-
= Appendix 2: Creating a package on-the-fly =
+
== 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:
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:
Line 97: Line 97:
This command will create a package called <code>user-info-1.2345.deb</code>.
This command will create a package called <code>user-info-1.2345.deb</code>.
-
= Appendix 3: Creating a repository on-the-fly =
+
== Appendix 3: Creating a repository on-the-fly ==
The following section gives an example of how to create a temporary repository.
The following section gives an example of how to create a temporary repository.
Line 139: Line 139:
  components = sample1 sample2
  components = sample1 sample2
-
= Appendix 4a:  Creating an offline repository on-the-fly =
+
== 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 following section gives an example how to create an "offline repository" (i.e., a local repository on the device).
Line 181: Line 181:
* Tap the "Maemolocal"-install file to start the repository configuration and installation.
* Tap the "Maemolocal"-install file to start the repository configuration and installation.
-
= Appendix 4b - Selfcontained Offline repository =
+
=== 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)
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)
Line 207: Line 207:
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.
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 =
+
== 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.
The Application Manager repository configuration may need to be changed manually as a prerequisite for the Enterprise Package installation.
Line 222: Line 222:
First, create an XML file containing the desired repository configuration. In this example, we define two repositories, the second one being disabled.
First, create an XML file containing the desired repository configuration. In this example, we define two repositories, the second one being disabled.
-
<config>
+
<source lang="xml">
-
    <catalogue>
+
<config>
-
      <name>Enterprise Repository</name>
+
  <catalogue>
-
      <uri>https://server.example.com/repository/enterprise/</uri>
+
      <name>Enterprise Repository</name>
-
      <components>base extras</components>
+
      <uri>https://server.example.com/repository/enterprise/</uri>
-
    </catalogue>
+
      <components>base extras</components>
-
    <catalogue>
+
  </catalogue>
-
      <name>Test Repository</name>
+
  <catalogue>
-
      <uri>https://server.example.com/repository/test/</uri>
+
      <name>Test Repository</name>
-
      <components>base extras</components>
+
      <uri>https://server.example.com/repository/test/</uri>
-
      <disabled/>
+
      <components>base extras</components>
-
    </catalogue>
+
      <disabled/>
-
</config>
+
  </catalogue>
 +
</config>
 +
</source>
Second, run the following command (assuming the XML file is at <code>/etc/repoconf.xml</code>)
Second, run the following command (assuming the XML file is at <code>/etc/repoconf.xml</code>)

Latest revision as of 12:51, 4 October 2010

Contents

[edit] 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
<empty line>
<html content here>
  • "Save as" file: Directs the web browser to open a "Save As..." dialog
Content-Type: application/x-unknown
Content-Disposition: attachment; filename="EnterpriseConfig.xml"
<empty line>
<file content here>
  • Install file: Directs web browser to open Application Manager.
Content-Type: application/x-install-instructions
Content-Disposition: inline; filename="temp.install"
<empty line>
<install file content here>
  • 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
<empty line>
--xAAAAAx
Content-Type: text/html
<empty line>
<html content here>
--xAAAAAx
Content-Type: application/x-unknown
Content-Disposition: attachment; filename="EnterpriseConfig.xml"
<empty line>
<file content here>

[edit] 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 /etc/EnterpriseConfig.xml 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 dpkg or dpkg-dev, 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 /etc/EnterpriseConfig.xml.

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 if clause, "#DEBHELPER#" 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 user-info-1.2345.deb.

[edit] 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 tmprepo123 which contains the user-info package created earlier. Inside the repository, "distribution" is fremantle and "component" is userinfo.

The dpkg-scanpackages command is needed. It is usually available in the dpkg or dpkg-dev 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 user-info package. This example contains also an Enterprise repository, which contains the packages that user-info 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

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

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

  1. Create a repository directory and copy some packages there:
$ mkdir MaemoOffline
$ cp somewhere/*.deb MaemoOffline/
$ (cd MaemoOffline && apt-ftparchive packages . >Packages)
  1. 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 .auto.install, 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.

[edit] 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 user-info 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 /etc/repoconf.xml)

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