HDA OS Migration Guide

The purpose of this tutorial is to provide a method for migrating Amahi HDA settings from one Amahi supported OS to another (i.e. Fedora 14 or Ubuntu 12.04.x to Fedora 19).

Currently there IS NOT an automated upgrade path. It is a manual process. However, we have provided a script provided to capture most of the settings you will need for the new Amahi HDA. We hope this will make it a more manageable task than in the past.

DISCLAIMER: Please understand this is a guide to assist you in the migration. There is no guarantee this guidance will work for everyone. While every effort has been taken to accurately document the migration steps, use at your own risk.

IMPORTANT: You will need to document any manual configuration changes or apps installed from sources other than the Amahi App Store.

Backup Settings

As with any other migration process, you will need to back up your HDA settings. In order to make the new system look and feel like your current one, there are certain components we need to capture.

To make this as painless as possible, a script is being provided. Once you run the script, it will record all the important information such as users, shares, apps installed, network, and Greyhole settings (if installed) in a text file. You can then copy that file to a safe location for use once the new system is ready to be configured.

As root user, do the following:

• Navigate to the root directory:

cd /root

• Download hda_migration.sh script (sha1sum: 14281005c1263105862f5fe0bb1825963f330a53):

wget https://dl.dropboxusercontent.com/u/1380867/hda_migration.sh 

• Make it executable:

chmod 755 hda_migration.sh

• Run the script:

./hda_migration.sh

If all goes well, you will see a message similar to the one below:

HDA Settings Backup Complete!
Filename : hda_production_migration.txt
Directory: /root

Copy hda_production_migration.txt (hereon referred to as migration text) to another machine and view the contents. Ensure all your settings were accurately captured before proceeding to the next section.

You can also print the file to make it easy to follow along as you go through the migrations steps. See Additional Tips below for optional steps you may want to complete.

Greyhole Cleanup

If you are not currently using Greyhole, you can SKIP this section.

Otherwise, As root user, begin with emptying the trash:

greyhole -a

Also recommend you run a fsck to ensure all files are in place:

greyhole -f

Monitor activity via the log file:

tail -f /var/log/greyhole.log

Once it's complete, you can prepare to shutdown your system

Shutdown Preparation

Before powering OFF the HDA, you need to:

1. Turn OFF DHCP server on the HDA
2. Turn ON your router DHCP/DNS server
3. Power OFF any clients that aren't needed
4. Renew DHCP lease for clients to remain ON
5. Verify all clients have connectivity via the router
6. Download new Amahi install image

Once you have the media ready for install, it's time to power OFF your HDA.

As root user, execute:

shutdown now -P

or

you can select the Shutdown icon (the RED one) from the HDA Dashboard Settings tab.

Once the HDA is OFF, disconnect all hard drives except the one for the OS. You don't need to remove them, just disconnect the power and drive cables.

New Installation

To begin:

• Power ON your HDA
• Insert installation media (reboot if needed)
• Follow the appropriate Amahi installation instructions
• Once complete, DO NOT disable the router DHCP/DNS server yet.

Validate Success

Once the install is complete, you need to validate the install was successful. Ensure everything is working correctly before proceeding to the next section.

What you should check:

• Does the HDA boot successfully and without errors
• Can you connect to the Amahi Dashboard (http://hda or by IP Address)
• Does the HDA have internet connectivity (try yum list hda-platform)

If you have problems, refer to the Network Troubleshooting guide in the wiki.

Once everything appears to be working, you can now disable your router DHCP/DNS server. The Amahi HDA will become your DHCP/DNS server for the network.

NOTE: You will need to renew the DHCP lease on any client systems currently connected to the network.

Configure Drives

If you do not have any additional drives to connect to your HDA, you can SKIP this section.

Otherwise, you will need to:

• Power OFF the HDA
• Reconnect the power and drive cables
• Power ON the HDA

As root user, edit /etc/fstab:

vi /etc/fstab

• Append entries the end of the file as noted in the fstab section of the migration text. For example:

UUID=b7017251-cb54-438b-92a3-781537c565e6 /var/hda/files/drives/sdb ext4 defaults 1 2 noatime,data=writeback,nofail

• Ensure you DO NOT add any drive lines that contain /, /boot, or swap. For example:

UUID=1ebbf241-528c-465e-889f-acc15400dd8c /                       ext4    defaults        1 1

• Create directories that correspond the the path in the drive lines. For example:

mkdir -p /var/hda/files/drives/sdb

indicates a drive listed in /etc/fstab will be mounted at this location.

Once you have all the drives added to /etc/fstab and the directories created, you can then mount the drives.

mount -a

If there are any errors, compare with the fstab section of the migration text. DO NOT proceed to the next section until all drives are correctly mounted.

Install Applications

WARNING: Some applications may not be LIVE for the new Amahi supported OS. Also the application version could be newer than you had installed on your previous system. As a result, the databases(s) and/or configuration files(s) may not be compatible.

Refer to the INSTALLED APPS TAB section of the migration text to determine applications to install. Any previously purchased applications from the Amahi App Store will be available for install.

• As you proceed to install applications, compare the version you install with the version listed in the migration text. That will give you an indication if a database or configuration file restore will be successful.

• If you have any database(s) and configuration file(s) saved for applications, you can restore them in most cases. Database(s) can be restored via command line or using a MySQL application such as, Adminer or phpMyAdmin.

• Obviously you don't have to install all the applications you had on the previous system and you can choose to install new ones as well.

NOTE: You can now manually install any apps from sources other than the Amahi App Store if needed.

Migrate Settings

We are now ready to being updating the new HDA with our previous HDA settings. Start by selecting Setup from the Amahi Dashboard main page (http://hda).

• Users Tab

Create New users. Refer to USERS TAB section in the migration text.

• Shares Tab

Choose the appropriate section and complete as noted.

• Details section: Create Shares. Refer to SHARES TAB section in the migration text.
• Settings section. Update Work Group Name if needed. Refer to SETTINGS under the SHARES TAB section in the migration text.

• Network Tab

Choose the appropriate section and complete as noted.

• Fixed IPs section: Create Fixed IPs. Refer to FIXED IP under the NETWORK TAB section in the migration text.
• DNS Aliases section: Create DNS Aliases. Refer to DNS ALIASES under the NETWORK TAB section in the migration text.
• Settings section:

• Disable DHCP Server and/or DNS Server if needed. Refer to DHCP/DNS SERVER under the NETWORK TAB section in the migration text.
• Update Lease Time if needed. Refer to DHCP Lease Time under the NETWORK TAB section in the migration text.
• Change DNS Provider if needed. Refer to DNS PROVIDER under the NETWORK TAB section in the migration text.
• Update Gateway if needed. Refer to GATEWAY under the NETWORK TAB section in the migration text.

• Settings Tab

Enable Advanced Settings and/or Guest Dashboard. Refer to SETTINGS TAB section in the migration text.

You should now have the majority of your settings restored. Double check to ensure you did not overlook anything before moving to the next section.

NOTE: You can now make any manual configuration changes that are needed.

Setup Greyhole

If you do not want to use Greyhole, you can SKIP this section.

Otherwise install the Greyhole UI application. In the Amahi Dashboard, navigate to the Drive Pooling tab, choose:

• Partitions section and select the appropriate Locations for the Pool. Refer to greyhole.conf section (storage_pool_directory line) in the migration text to verify the correct partitions are chosen.

NOTE: If Greyhole UI application was installed on your previous HDA, you should refer to DRIVE POOLING TAB section in the migration text rather than greyhole.conf section.

• Shares section
  • Choose Storage Pool for the applicable Shares. Refer to greyhole.conf (num_copies line) section in the migration text to verify the correct Shares are chosen.
  • Select the appropriate Number Copies for Shares. Refer to greyhole.conf section (num_copies line) in the migration text to verify the correct Number Copies are chosen.

NOTE: If Greyhole UI application was installed on your previous HDA, you should refer to SHARES TAB (Disk Pool Copies column) section in the migration text to determine the appropriate setting.

Greyhole Advanced Options are configured in greyhole.yml file (/var/hda/platform/html/config). Compare the contents with the greyhole.yml section in the migration text for any differences. Make changes as needed.

Before proceeding to the next section, verify Greyhole is working properly. This can be done by monitoring the log:

tail -f /var/log/grehole.log

If there is a problem, refer to Greyhole Troubleshooting. Don't forget to install Mount Shares Locally service if needed.

Final Verification

All the settings and configuration changes from your previous HDA should now be complete. Recommend you verify that everything is working as desired. Its best to check things over thoroughly now to prevent an unexpected surprise later.

If something is not working as expected, double check migration text to ensure you didn't make any errors. Depending on the issue, you may need to refer to the Amahi Troubleshooting guidance.

Providing there are no problems, you should now have a fully functional up-to-date Amahi HDA.

Additional Tips

Each HDA is unique as will be the migration to a different Amahi supported OS. There are additional steps you can accomplish to make the transition a bit smoother.

Recommend backing up:

• App database(s) and configuration file(s)
• .bashrc and .vimrc files for each user
• User added terminal scripts
• Screen capture of dashboard tabs