OpenChange

h1. OpenChange Appliance

{{>toc}}

h2. Introduction

The OpenChange appliance is a virtual environment configured to provide a development environment similar to that used by other OpenChange developers. It contains everything needed to run OpenChange server "out of the box" and to start developing or following latest evolution of the OpenChange project. 

The appliance was created using "Virtualbox 3.2.6":http://www.virtualbox.org/wiki/Downloads but was exported using the "Open Virtualization Format":http://en.wikipedia.org/wiki/Open_Virtualization_Format (OVF) with 0.9 legacy enabled to maximize the number and versions of virtualization systems able to import this appliance. This guide primarily focuses on VirtualBox, but additional setup and configuration information for other virtualization systems is welcome.

h2. Available appliances

h3. Ubuntu 10.04 Lucid LTS OpenChange appliance

* *size: 1.7Gb*

* x86 architecture

* 5Gb of Hard Disk drive

* 256Mb of memory

* 2 network interfaces:

** eth0: NAT

** eth1: Bridged with a default IP set to 10.254.0.100

h2. Download OpenChange Virtual Appliance

You can either download the appliance using either FTP or rsync. You do not need to use both, although you can use the rsync method to update an existing appliance downloaded using either method.

h3. FTP download method

The appliance can be retrieved through FTP from the following address: ftp://openchange:openchange@labs.openchange.org

You can use any graphical or command line client that supports FTP. For example, you can use:

<pre>

$ wget ftp://openchange:openchange@labs.openchange.org/ubuntu-appliance.tgz

$ wget ftp://openchange:openchange@labs.openchange.org/ubuntu-appliance.sha512sum

</pre>

An unpacked version of the appliance is available within the unpacked/ubuntu-appliance directory under the root directory of the FTP account.

h3. rsync download method

The applicance can be retrieved (or updated) through rsync using this command:

<pre>

$ rsync -az labs.openchange.org::ubuntu-appliance ubuntu-appliance

</pre>

where the second "ubuntu-appliance" is the directory where your files will be downloaded to.

h3. Check Integrity

The OpenChange appliance comes with two different layers of integrity checking

* one SHA512 file to check tarball integrity (not applicable for rsync) named "ubuntu-appliance.sha512sum"

* one SHA512 named "SHA512SUM", within the tarball or rsync download to check appliance data integrity

To check the tarball, use the following command:

<pre>

$ sha512sum -c ubuntu-appliance.sha512sum

ubuntu-appliance.tgz: OK

</pre>

You can then extract the tarball (if applicable) using the following command:

<pre>

$ tar xzvf ubuntu-appliance.tgz

SHA512SUM

ubuntu-appliance.mf

ubuntu-appliance.ovf

ubuntu-appliance.vmdk

</pre>

You can then verify the download using the following command:

<pre>

$ sha512sum -c SHA512SUM

ubuntu-appliance.mf: OK

ubuntu-appliance.ovf: OK

ubuntu-appliance.vmdk: OK

</pre>

h2. Importing appliance in VirtualBox

Before you import the appliance, make sure that the download passes the integrity checks (see previous step).

There are two ways to import the appliance into VirtualBox - using the VBoxManage command line tool, or using the VirtualBox GUI client. You only need to use one.

h3. Using the VBoxManage command line tool

We suggest doing a "dry-run" of the import using the following command (where "/path/to/" is replaced by the location that you downloaded the appliance image to):

<pre>

$ VBoxManage import /path/to/ubuntu-appliance.ovf --dry-run

</pre>

If successful, it is safe to import the appliance using the command below (again, replacing "/path/to"):

<pre>

$ VBoxManage import /path/to/ubuntu-appliance.ovf

</pre>

h3. Using VirtualBox GUI

Click _File_ in the menu bar, then select _Import Appliance_

!vbox-filemenu.png!

This will bring up the import wizard, which looks like the following:

!importwizard.png!

Click the Choose button, navigate to the directory where you extracted the appliance and select the OVF file (ubuntu-appliance.ovf) 

!importfiledialog.png!

This will return you to the import wizard, where you should see the filename and path that you just selected. You can then click Finish, as shown below:

!importwizard2.png!

This will bring up the setting menu, as shown below

!importsettings.png!

Change any settings that may be required (in particular, you may wish to increase the RAM if your host machine has plenty of memory) and select the Finish button to finalize the import process. You should see progress indications as the virtual machine is imported. Note that the import may take some time.

After VirtualBox is finished importing the appliance, you can boot it (e.g. using the "Start" icon in the VirtualBox GUI). If you encounter issues when launching the virtual machine for the first time, please refer to the [[OpenChange_Appliance#Troubleshooting|troubleshooting section]] of this guide.

h2. Using the OpenChange appliance

h3. Account information

Once you have started the appliance, you will access the default console login screen. The default account is:

* username: *openchange*

* password: *openchange*

Note that this user is enabled with sudo privileges to run command as root.

*You are strongly encouraged to change the password as soon as possible.*

h3. Networking

The appliance is configured with 2 network interfaces:

* NAT on eth0

* Bridged on eth1 with an IP address set to *10.254.0.100* by default.

You can dynamically change the IP address using:

<pre>

sudo ifconfig eth1 XXX.XXX.XXX.XXX

</pre>

or make this change permanent by changing the eth1 address in */etc/network/interfaces*.

Note that the pre-configured client-side profile depends on this address, so if you change the address, you will need to either edit or delete that existing MAPI profile to reflect the change. Refer to the mapiprofile man page for how to do this.

h3. Services

The appliance comes with samba4 and openchange server installed and configured. Two accounts are set up on the server:

* *Administrator* with a password set to *#1OpenChange*. The password above is also the adminpass used during samba4 provisioning.

* *openchange* user with a password set to *openchange* 

You can run the OpenChange server either by running the *_startme.sh_* script located in the openchange account home directory or using:

<pre>

$ sudo /usr/local/samba/sbin -d5 -i -M single

</pre>

It is recommended that you keep the server running in single mode and dedicate a console to it. You can obtain a second console login using the <Alt-F2> key combination, which may be useful to perform testing. You can also work over ssh (which is enabled on the appliance).

h4. OpenChange client

The appliance comes with a default mapiprofile database and a default openchange profile that you can use to test OpenChange server:

<pre>

$ mapiprofile --list

We have 1 profiles in the database:

        Profile = openchange [default]

$ mapiprofile --dump

Profile: openchange

        username          == openchange

        password          == openchange

        mailbox           == /o=First Organization/ou=First Administrative Group/cn=Recipients/cn=openchange

        workstation       == ubuntu

        domain            == OPENCHANGE

        server            == 10.254.0.100

</pre>

After the server is started (see previous section), you can call openchangeclient to test/stress OpenChange server:

<pre>

$ openchangeclient --mailbox

$ openchangeclient --fetchmail

</pre>

h2. Update OpenChange appliance

The appliance comes with a subversion trunk repository of openchange (located in _/home/openchange/openchange/_) and its associated samba4 git-master revision (located in _/home/openchange/openchange/samba4/_) which means you can follow latest openchange advances using *svn up* from openchange trunk directory and rebuilding openchange sources whenever required.

h2. Troubleshooting

h3. Failed to open a session for the virtual machine

!http://tracker.openchange.org/attachments/73/vbox_e_fail_isession.png!

If you encounter the above message when running the appliance, run:

# Click on _Settings_, then select _Storage_ panel

# Click on the appliance vmdk in the Storage tree and remove it (right click and _Remove attachment_)

# Click on _Add attachment_ or _Add Hard drive_ and select the appliance vmdk again (vmdk may be added automatically)

# Power on the virtual machine