OpenChange

h1. OpenChange Appliance

h2. Introduction

The OpenChange appliance is a virtual environment configured to provide a development environment similar to the OpenChange's development one. It contains everything to run OpenChange server out of the box and to start developing or following latest evolution of the OpenChange project. 

Existing appliances have been created using "Virtualbox 3.2.6":http://www.virtualbox.org/wiki/Downloads but was exported using the OVF format (Open Virtualization Format) 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 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 through FTP or rsync

h3. FTP download method

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

<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

To fetch via rsync use this command:

<pre>

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

</pre>

h3. Check Integrity

The OpenChange appliance comes with different level of integrity:

* one SHA512 file to check tarball integrity

* one SHA512 within the archive to check appliance data integrity

<pre>

$ sha512sum -c ubuntu-appliance.sha512sum

ubuntu-appliance.tgz: OK

$ tar xzvf ubuntu-appliance.tgz

SHA512SUM

ubuntu-appliance.mf

ubuntu-appliance.ovf

ubuntu-appliance.vmdk

$ sha512sum -c SHA512SUM

ubuntu-appliance.mf: OK

ubuntu-appliance.ovf: OK

ubuntu-appliance.vmdk: OK

</pre>

h2. Importing appliance in VirtualBox

h3. Using command line tools

From your Linux console, replace /path/to with the path where you extracted the appliance.

It is advised to first run a dry-run using the following command:

<pre>

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

</pre>

If successful, it is safe to import the appliance using the command below:

<pre>

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

</pre>

h3. Using VirtualBox GUI

# Click _File_ in the menu bar, then select _Import Appliance_

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

!http://tracker.openchange.org/attachments/72/vbox_appliance_import.png!

After VirtualBox is finished import the appliance, you can boot it. 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. Run OpenChange appliance

h3. Account information

Once you have started the appliance, you will access the default console login screen. The default account enabled with sudo privileges to run command as root is:

* username: *openchange*

* password: *openchange*

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

h3. Networking

The appliance comes with 2 network interfaces configured:

* 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 you will need to either edit or delete the existing MAPI profile to reflect this change.

h3. Services

The appliance comes with samba4 and openchange server installed and configured.

Two accounts exist on the Samba4 and OpenChange 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 OpenChange server either by running the *_startme.sh_* script located in the openchange's account home directory or using:

<pre>

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

</pre>

It is recommended to keep the server running in single mode and dedicate a console to it.

h4. OpenChange client

The appliance comes with a default mapiprofile database and a default openchange profile 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 (_/home/openchange/openchange/_) and its associated samba4 git-master revision (_/home/openchange/openchange/samba4/_) which means you can follow latest openchange advances using *svn up* from openchange trunk directory and rebuil openchange sources on purposes.

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