Installation via virtual machine image is deprecated as of Avalon 6.5. If you're looking for automated installation, please see our documentation on installing Avalon with Docker.
This documentation is for Release 3.0.0. For previous versions of Avalon look in the page history at version v.77.6.x.
|These instructions will walk you through the process of downloading, booting, and configuring a CentOS 7.x virtual machine image containing CentOS, Avalon 2.0Docker containers of Avalon, Fedora, Red5 and Opencast Matterhorn, along with preloaded additional instructions on loaded 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 5GB2GB. Due to the size, it may take some time to download.
3. Importing the Avalon VM Image
The OVA file currently contains release 6.4.2
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.
- Start the VirtualBox Manager
- Select the "File/Import Appliance..." menu item
- Press the "Open Appliance..." button and select the Avalon VM image you downloaded
- Press "Next >" or "Continue"
- Below the list of VM appliance settings, check the box next to "Reinitialize the MAC address of all network cards"
- Press "Import"
- The VM should now be visible in the list.
- Select the Avalon VM
Press the "Settings" icon
- Select the "Network" tab
- Make sure the "Attached to" field is set to "Bridged AdapterNAT"
- Press "OK"
- Press "Start" icon to boot the VM
- VirtualBox has networking quirks that require special configuration to make Avalon work in NAT mode. Please see VirtualBox Networking for details.
Users on Apple hardware may get the following error screen when starting the VM:
If you receive this dialog, click the Change Network Settings button followed by the OK in the following dialog to resolve the issue.
- Click on "Open a Virtual Machine"
- Select the .ova file you downloaded
- Press "Import"
- Press "Retry" to relax specification (if needed)
- Click on "Edit virtual machine settings"
- Click on "Network Adapter"
- Make sure it is set to BridgedNAT
- Press "Advanced..."
- Press "Generate" to create a new MAC address and press "Close"
- Press "Save"
- Click on "Network Adapter"
- Press "Play virtual machine"
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.
Unpack the OVA file. $DIST is where the VM files are going to be; $DOWNLOAD is where the OVA file was downloaded.
mkdir $DIST cd $DIST tar xvf $DOWNLOAD/avalon-vm.ova
The .vmdk file is the virtual disk image. The other files are settings for the VM (ovf) and checksum files (mf).
- Normally one would use virt-convert to convert .ovf to the right format, but there is a bug in it, so it has to be done by hand.
- By Hand Method
Convert disk image to qcow2
qemu-img convert -f vmdk -O qcow2 *.vmdk avalon-vm.qcow2
The VMDK file shipped is compressed so the new qcow2 file will be roughly twice as large. After the conversion the vmdk file is no longer needed and can be deleted.
Create a new VM
- Click on the "Create a new virtual machine" icon
- Enter the name for the virtual machine, select "Import existing disk image" and press "Forward"
- Select the disk image by pressing "Browse"
- Press "Browse Local"
- Navigate to $DIST
- Select the "avalon-vm.qcow2" file
- Select the OS type "Linux", Version "Red Hat Enterprise Linux 67" and press "Forward"
- Set the RAM to 3072 (3G) and press "Forward"
- Select "Customize configuration before install" and press "Finish"
- In the Configuration Window make these changes:
- In "NIC" set the source device to the macvtap enabled interface which represents the ethernet device of the host (usually eth0 or em1)
- Remove the DISK 1 Device and re-add it:
- Press "Add Hardware"
- Select the "Storage" tab
- Select "Select managed or other existing storage" and Browse
- Press "Browse Local"
- Navigate to $DIST and select the "avalon-vm.qcow2" file
- Set the device type to "Virtio disk"
- Set the cache mode to "default"
- Set the storage format to "qcow2"
- Press Finish
- Press "Begin Installation"
- By Hand Method
Generic VM Product
A generic VM product may be set up using these settings:
- Unpack the .ova file – it is just a tarball containing a .vmdk file and a configuration file
- Use these settings for the VM:
- 64-bit guest
- At least 2G of RAM (the shipped settings use 3G)
- At least 1 core
- Graphical Display
- System disk the the .vmdk from the .ova package
- The network interface must be bridged and have a unique MAC address
- Start the VM as appropriate for this VM software
Notes for ALL Virtualization Products
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.
If there is a firewall on the network, these ports must be accessible to the clients:
|tcp/22||SSH and SFTP Access|
|tcp/1935||Streaming Media Access for Red5 (RTMP)|
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.
The Avalon and CentOS End User License Agreements are displayed. Agree to the licensing terms and press Forward to continue.
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.
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 will send email in response to different events or at the request of the users:
|User Comments||This is the destination email address for comments sent in by users|
|Avalon Notifications||If there are issues with processing or other outstanding requests, they are sent to this address|
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.
There are two more pieces of information required for the Avalon set up to complete.
- Access Hostname - this is the host name the users will use to connect to avalon. The default is the name returned by DNS for the IP of the machine. If a DNS alias is used then the name should be set to the alias.
- Initial User - Avalon requires an initial user to be set up at install. This user has the ability to manage other users. The username should look like an email address and the password cannot be blank.
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.
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:
After you have connected to the VM via a web browser
- Login using username
- Open the built-in Chrome browser and point it to http://localhost.
- Click on Login
- Click on Register new identity
- Sign up using the default email@example.com email to get admin access
After you have signed in, Avalon VM can be used like any other Avalon installation. The Avalon Collections 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
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.
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.
To randomize the passwords used by Avalon, the command
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
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.
After the password is changed, log out and log in to the initial user using the password just created. You can create new collections and add items. Additional features can be configured using feature specific documentation.
5. Installing Sample Content (Optional)
The sample content can be ingested through a batch ingest process
- Create a new collection, for example, DEMO
tar zxvf DemoFixturesBatch.tar.gz
mv ExampleBatchIngest/* /home/avalon/avalon-docker/masterfiles/dropbox/DEMO/
As the samples are ingested, you will see new items being added to the collection. Be patient as the media transcoding may take a while.
6. Building your own OVA file
If you want to build your own OVA file follow the instructions on https://github.com/avalonmediasystem/avalon-packer
Troubleshooting the Avalon VM
Because the OVA uses Docker and Docker-Compose, you can find instructions on how to navigate the stack on the avalon-docker github page
Reconfiguring the Avalon VM
Resetting the root password
- When the VM starts there is a 3 second countdown before the boot begins. Press the spacebar during this countdown to get the boot menu.
- Edit the boot entry and boot
- Press the 'e' key to edit the first boot entry
- Use the down arrow to highlight the line beginning with 'kernel' and press 'e'.
- Add " init=/bin/bash" to the line, making sure there is leading space separating it from the the end of the existing command line.
- Press 'enter' to go back to the root/kernel/initd selection screen
- press 'b' to boot
- The system will boot to a root shell
Change the password.
mount -o remount,rw / passwd root mount -o remount,ro /
- A hard reboot of the VM is required to restart the system.
Known Issues - a list of bugs, workarounds, and cautions.
In addition, there are some issues for us to consider in future releases of this VM image:
- If VirtualBox doesn't have focus the screen may stop updating after a while for the build FFMPEG step. Giving VirtualBox focus updates the screen. This is probably related to the screensaver since it stops updating about 10 minutes in.
- Matterhorn has a service that is named after the original DHCP hostname from install time. It seems to be harmless but looks confusing.
- Sometimes when using the dropbox a duplicate processing job appears in matterhorn and the first one will fail during distribute-hls. The second one processes normally.
|information||oddity, potential todo item||todo item||issue w/o workaround||issue with workaround|