These instructions will walk you through the process of downloading, booting, and configuring a virtual machine image containing CentOS, Avalon 1.0, Fedora, and Opencast Matterhorn, along with preloaded sample audio and video content. The image is configured to use 'bridged networking,' and thus it will have its own virtual network interface with its own MAC address and IP address (obtained via DHCP).

1. Getting a Virtualization Product

The Avalon VM is distributed as an Open Virtualization Appliance which should be compatible with these Virtual machine products:

Other virtualization products may be used but they will require manually converting the OVA file into something useful.

2. Getting the Avalon Virtual Machine Image

The Avalon VM file is located at http://www.avalonmediasystem.org/downloads/avalon-vm.ova and is roughly 5GB.  Due to the size, it may take some time to download.

3. Importing the Avalon VM Image

Each virtualization product has different methods for using a VM appliance.  The tested methods are below.  If you use a product which is not listed, please contact us with usage instructions and we will add them here.

VirtualBox

VMware Player

Libvirt's Virtual Machine Manager

Virtual Machine Manager is an open source GUI front end to QEMU, KVM and other Linux-based virtualization products.  It comes with Fedora Linux and other distributions.  It doesn't directly support OVA files so manual conversion is required.

Generic VM Product

A generic VM product may be set up using these settings:

Notes for ALL Virtualization Products

Disk Usage

The disk image in the OVA package is dynamically-allocated with a maximum size of 500G.  While the disk image may only use a few gigabytes when it is first used, it will grow as more data is placed into the VM.  Most VMs behave unpredictably when the host system doesn't have enough disk space to satisfy guest OS requests.  Monitor the disk usage closely.

Firewall

If there is a firewall on the network, these ports must be accessible to the clients:

PortPurpose
tcp/22SSH and SFTP Access
tcp/80Web Access
tcp/1935Streaming Media Access for Red5 (RTMP)
tcp/18080Matterhorn

4. First Boot of Avalon VM

The VM will take while to boot.  This is normal since some of the system services are slow to start.

When the VM is booted for the first time you will be taken through a series of steps to configure the virtual machine for use.  Many of the screens are the same as a standard CentOS or RedHat Enterprise Linux post-installation first boot.  For reference, the RedHat documentation for this process is at https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Installation_Guide/ch-firstboot.html.  Only pages which are specific to Avalon or differ from their RHEL counterparts are detailed below.

License Information

The Avalon and CentOS End User License Agreements are displayed.  Agree to the licensing terms and press Forward to continue.

Update Networking

The default networking configuration uses DHCP.  To change the networking configuration, press the Network Settings button to start the standard NetworkManager connection editor.  When the network configuration is correct, press Forward to continue. 

Build FFMPEG

FFMPEG is an open source tool used to convert multimedia formats into other formats.  While it is open source, there are some configurations that cannot be distributed as a binary package.  Avalon uses such a configuration, so to adhere to the licensing restrictions, the end-user (you) have to build FFMPEG.  To make the process easy, this screen offers a push button which will begin the process of building and installing a FFMPEG binary which will be used by avalon.  The installation will not continue until FFMPEG is built.

The build can take 15 minutes or more to finish.  Wait until the terminal screen shows a completion message before pressing Forward.

Once FFMPEG is built, the terminal window will display a message informing you to press the Forward button to continue the installation. 

If the build fails or otherwise has trouble, the installation will allow you to continue, but Avalon will not be fully functional.  Contact the developers for assistance.  The build log can be found in /root/ffmpeg-build.log.

Avalon Email

Avalon will send email in response to different events or at the request of the users:

User CommentsThis is the destination email address for comments sent in by users
Avalon NotificationsIf there are issues with processing or other outstanding requests, they are sent to this address
Support Requests

Support questions from the end users are sent to this address

In addition to the email addresses, the setup also requires an SMTP relay host to use to send email.  The port for the relay will usually be 587.

Avalon Configuration

There are two more pieces of information required for the Avalon set up to complete.

Reboot

Now that all of the changes have been made the Avalon is nearly ready to use.  The access URL is displayed on this screen. Take note of this URL; you will use this to access Avalon after reboot.  However, note that if you need to register your virtual machine's MAC network address with your institution's DHCP server after reboot, this URL will change.

Press Finish to reboot the machine and apply all of the changes.

5. Using the Avalon VM

Once the VM has rebooted and the login screen has appeared, the Avalon system is ready to use.  To use Avalon, open a web browser in your desktop operating system and point it to the access URL that was displayed prior to rebooting.

If the URL that was displayed on the reboot screen doesn't work, the IP of the VM may have changed during the reboot.  There are a couple of ways to determine the access URL:

  • If a hostname is displayed on the login screen, then CentOS was able to determine a name from the IP that was assigned to it and that name should be used. For example, if the login screen shows a hostname of foo.my.university.edu, then use the URL http://foo.my.university.edu/. If this hostname doesn't work, try the next method.
  • If the login window displays a generic CentOS version string, then it was unable to find a DNS entry for the address it was given.  Log in to the machine, open a terminal window, and run

    /etc/init.d/avalon_host_config hostname

    and the name displayed will be the access hostname.  This is the value that is inserted into the Avalon configuration files on boot, so it should work.

  • If your organization requires DHCP clients to register their MAC address, a web browser (Firefox) is available on the VM to use to register the machine.  After the machine has been registered according to your organization's policies, it will need to be rebooted to reconfigure Avalon with the new networking information.

After you have connected to the VM via a web browser, Avalon VM can be used like any other Avalon installation. The Collection Manager's Guide contains information for using Avalon.  The Avalon user created during the first boot process will be able to manage both collections and groups.

 


Troubleshooting the Avalon VM

Discovering Configuration

Besides the hostname (which is covered above), all of the settings and passwords that were set by the install process are stored in /root/avalon-setup.log.

SFTP dropbox password

The SFTP dropbox user is "avalondrop" and the random password generated user can be discovered by running this as root:

grep avalondrop /root/avalon-setup.log

Matterhorn admin password

Matterhorn runs on http://<access host>:18080 and has an administrative user called "admin".  The password can be determined by running this as root:

grep security.admin.pass /root/avalon-setup.log

Fedora admin password

The username for the fedora instance on http://localhost:8983/fedora is "fedoraAdmin".  The password can be determined by running this as root:

grep fedoraAdmin /root/avalon-setup.log

Reconfiguring the Avalon VM

All of the avalon configuration scripts below leave a log of changes in /root/avalon-setup.log.  Since this file may contain passwords, make sure the file permissions are set appropriately.

Email Addresses

The avalon email addresses can be reconfigured by running (as root):

/usr/share/avalon/avalon_config_email <comments_email> <notifications_email> <support_email> <smtp_server_address> <smtp_port>

To use the existing value for any of the above arguments, use '-'.  The Avalon application stack will need to be restarted for the changes to take effect.

Randomize Passwords

To randomize the passwords used by Avalon, the command

/usr/share/avalon/avalon_randomize_passwords

can be used.  The changes will appear in /root/avalon-setup.log and all Avalon-related services will need to be restarted to make sure the passwords work correctly.

Accessible Hostname Configuration

Reconfiguring the accessible network address is more complicated.  On each reboot the accessible name is reconfigured during startup when

/etc/init.d/avalon_host_config

is run.  If the file /etc/sysconfig/avalon_host_config contains a name, that is used for the accessible name, otherwise the DNS name for the host is used.  If this script is run during normal operations, the avalon services will need to be restarted to be updated with the new configuration.

Resetting the Initial User Password

If you have the root password, select "Other..." on the Login box, and use "root" for the username, and the root password.  When the desktop has started, go to the Applications menu and select "System Tools/Terminal" to start a terminal.

Within the terminal, run the password change command, replacing "username" with the username that was created during install.

passwd username

After the password is changed, log out and log in to the initial user using the password just created.

Resetting the root password

 


Known Issues

Known Issues - Release 1.0 - a list of bugs, workarounds, and cautions for using Release 1.0.

In addition, there are some issues for us to consider in future releases of this VM image:

(info) information(question) oddity, potential todo item(plus) todo item(minus) issue w/o workaround(warning) issue with workaround