top of page

(or from non-AWS FreePBX systems to AWS FreePBX)

Updated: 2018-03-28

INTRODUCTION:

We are pleased announced the release of AWS FreePBX® 12.7.4-1710-2 (AMI v3.0); based on RHEL 7.3 and featuring FreePBX® 14, with support for Asterisk® 14 and full Commercial Module support through Sangoma! 

​

AWS FreePBX® 12.7.4-1710-2 features a new core OS based on RHEL 7.3 to support the new modern software requirements of FreePBX® 14. This new OS provides all the stability of a RHEL 7 based distribution, with the flexibility of hand-picked and maintained modern packages. However, this presents a significant upgrade obstruction for those presently running production systems on our previous AWS FreePBX versions based on CentOS 6.x.

​

This Migration Guide will aid you in moving from v2.x to v3.x. Aside from the recommended step of updating your existing instance(s) to the latest v2.9, no major changes need to be made to your existing production systems in order to attempt a migration to v3.x. You will be launching a new instance based on AMI v3.x and then following these steps to convert and migrate a COPY of your environment to the new instance. This will ensure you can setup and test the new instance without risking serious interruption to your current production environment.

​

WARNING: DO NOT ATTEMPT TO RESTORE FREEPBX 13 (AMI v2.x) BACKUP FILES TO FREEPBX 14 (AMI v3.x) WITH THE BACKUP/RESTORE MODULE! THIS WILL PERMANENTLY CRASH THE WEB INTERFACE AND SCRAMBLE THE CONFIGURATION DATABASES OF THE FREEPBX 14 INSTANCE!

​

This Guide will follow the following structure:

  • Prerequisites and other important information regarding the migration process

  • Main Migration Guide that will be applicable to most customer environments

    • Phase One - Launch and Pre-Configure NEW v3.x Instance​

    • Phase Two - Migrate a Copy of the Existing Configuration from the Old v2.x Instance to the New v3.x Instance

    • Phase Three - Verify Migrated Data, Post-Configure New v3.x Instance, Test the New v3.x Instance

    • Phase Four - Swap the New v3.x Instance into Production

  • Reverting to your Old Instance in the event you run into major issues after the migration is complete

 

UPDATES TO THIS GUIDE:

  • 2018-03-28 - We have added information regarding an error message (du: cannot access `': No such file or directory) during migration and how to address the issue.

  • 2017-11-23 - We have added CDR/CEL database, Custom Sound file, and /etc/asterisk/*_custom.conf file migration. You will now be prompted at the beginning of the wizard with several questions regarding these migration options. You MUST answer the same way on both servers.

PREREQUISITES:

READ THIS ENTIRE GUIDE FROM START TO FINISH BEFORE ACTUALLY BEGINNING ANY MIGRATION STEPS! There are several things you must keep in mind and prepare for in your environment. This list may not be complete, depending on your unique environment. Please take the time to consider how your setup will need to be adjusted to complete the migration successfully. This will help ensure you are fully prepared for all the steps involved. 

​

  • Your existing instance(s) should be running the latest v2.9 AMI software. This is the only step of the guide you might take that could cause any interruption to your production environment. Therefore, we mention this as a prerequisite so you can plan to take this step during non-business hours. Run SmartUpgrade to perform a normal update to your instance(s) to ensure they are running v2.9 with all the latest updates. This will maximize success during the rest of this process. If you've never used SmartUpgrade before, check out this FAQ Article. You will need to be familiar with SmartUpgrade and SSH access to your instance throughout this guide. 
    >> http://forum.thewebmachine.net/forum/5118559/

​

  • You will need to Software Activate the new v3.x instance(s) via Admin > System Admin from the GUI as part of this process. You will need to register each as a NEW deployment. IF you have commercial licenses from Sangoma that you want to move to the new instance(s), you will wait to do this until you are ready to place the v3.x instance(s) into production. Once you are ready to complete that swap at the very end, you can then move your existing v2.x deployment activation(s) and license(s) to the new v3.x instance(s). IF you have no commercial module licenses that you paid for from Sangoma, you don't have to migrate deployment activations from v2.x at all.

​

  • From the time you begin migrating an instance until the time you finally swap the new v3.x instance into production, it is important that you do not make any changes to the configuration of the existing v2.x instance. Once you have completed Phase 2, any changes made to the configuration of the old v2.x instance must also be made to the new v3.x instance MANUALLY. 

​

  • THE FOLLOWING ITEMS CANNOT BE MIGRATED FROM THE OLD INSTANCE TO THE NEW INSTANCE WITH THIS PROCESS:​​

    • 3rd Party modules like phpmyadmin and webmin designed for much older versions of FreePBX

      • These modules are not compatible with FreePBX 14!

    • Queue Metrics

    • iSymphony

      • Refer to iSymphony support documentation for the proper procedure to migrate your data, BUT YOU MUST SKIP STEPS 2 & 7 ASKING YOU TO PERFORM FREEPBX BACKUP/RESTORE! THIS WILL BREAK YOUR v3.x INSTANCE ON RESTORE, you will need to copy these settings by hand from the old instance to the new instance via the FreePBX GUI

    • Network and Operating System level settings

      • If you made any customizations at the OS level or configured advanced network level services like VPN, you will have to replicate these settings yourself manually​

​

-MAIN MIGRATION GUIDE-

Phase One:

In Phase One, we will perform the following steps:

  1.  Launch a New Instance based on the latest v3.x AMI

  2. Activate that New Instance via System Admin

  3. OPTIONAL: If you are using IMAP VoiceMail Storage, you will perform additional necessary steps​

​

​

​

STEP 1:

From the AWS EC2 Console, launch a NEW AWS FreePBX v3.x instance in the SAME REGION and of the SAME INSTANCE TYPE as the old AWS FreePBX v2.x instance you are migrating from. You can use this button to quickly reach the launch page:

 

​

​

​

PRIVACY WARNING: Clicking the "Launch an Instance" button on this page will expose your personal information to Amazon Web Services (AWS) and their affiliates for the purposes of processing your subscription. Click here to view our Total Privacy Policy.

 

Do NOT assign an Elastic IP to the new instance at this time. 

​

​

STEP 2:

Once the new instance has had a few minutes to start up, connect your web browser to the Public IP address that was auto-assigned on launch. Use the standard launch credentials to log into the FreePBX GUI:

  • USERNAME: admin

  • PASSWORD: <i-instanceID>

​

Navigate to Admin > System Admin and then choose Activation. On the Activation page, choose the Activate button. As you complete the Activation Wizard, you will choose New Activation. If you plan to migrate your existing paid commercial licenses from the old instance, you should make it clear this is a test deployment ID so you can delete it later. If you have no need to migrate paid module licenses, you can name this something appropriate like "My PBX v3."

​

If you are NOT using IMAP VoiceMail Storage, you can proceed to Phase Two.

 

 

STEP 3 (OPTIONAL):

If you ARE using IMAP VoiceMail Storage, you must now complete the IMAP VoiceMail Guide found at the following page. Be sure to manually copy your existing IMAP VoiceMail General settings from the old v2.x instance to the new server. You do NOT have to perform any extension changes, as those will be handled during the migration process.

>> http://forum.thewebmachine.net/topic/10187012/

​

​

​

Phase Two:

In Phase Two, we will perform the following steps:

  1. Initiate the primary automated migration process via SmartUpgrade on both old and new instances

  2. Perform additional data exports/imports from the old instance to the new instance via their GUIs - We'll need these to fill in any gaps left by the automated migration process

​

​

STEP 1:

PRIVACY WARNING: Using the automated Instance Migration utility will result in your data passing through one or more Sangoma servers for the purposes of moving your migration data between instances. The data is encrypted locally on your old instance before being passed to the new instance and cannot be viewed by Sangoma or TheWebMachine Networks. Click here to view our Total Privacy Policy.

​

Once you have your new v3.x instance launched and activated, you'll use SmartUpgrade to perform the automated portion of the migration process. If you are unfamiliar with SmartUpgrade and connecting to your instance via SSH, please see this FAQ:
>> http://forum.thewebmachine.net/forum/5118559/

​

Connect to BOTH THE NEW AND OLD INSTANCES via SSH. Once connected to both, start with the NEW instance by running this command and follow the instructions presented to obtain the Conversion ID:

​

smartupgrade instance-migration

​

Initially, the wizard will ask you a few questions such as whether this is the new or old server and if you want to migrate CDR. Once you answer these questions, you will be presented with the following. Since this is the NEW instance, simply press ENTER to generate a new Conversion ID:

​

<<NEW v3 INSTANCE>>

screenshot 1

​

You will then be presented with the Conversion ID. Copy this ID (the highlighted part below):

​

<<NEW v3 INSTANCE>>

screenshot 2

​

​

Now that you have the Conversion ID, run the same SmartUpgrade instance-migration command on the OLD instance***. Once again, you will be asked the initial questions such as whether this is the old or new server and if you want CDR migration. This time, once you have answered and see the prompt below you will want to enter the ID you copied from the NEW instance a moment ago before pressing ENTER:

​

*** If you are migrating from a non-AWS FreePBX system, you can run these commands on the old server instead: 

wget http://files.thewebmachine.net/instance-migration.sh && chmod +x ./instance-migration.sh && ./instance-migration.sh

​

<<OLD v2 INSTANCE>>

screenshot 3

​

The automated migration process will now begin. You may be asked if you wish to move large folders like FreePBX Backups in /var/spool/asterisk/backup. Since v2.x backups would break v3.x, these files don't need to be migrated. Once you have answered these questions, if presented with them, the process will proceed and migrate all the data it possibly can. When it is complete on the old machine, it will look like this:

​

<<OLD v2 INSTANCE>>

screenshot 4

​

NOTE: If you see messages that say "du: cannot access `': No such file or directory," you will need to CTRL+C to cancel, run the wizard again, then choose N for questions like "Directory /var/spool/asterisk/voicemail? (2.50GB) [yN]." You can copy these directories over using WinSCP later. If you try to proceed after seeing "du: cannot access `': No such file or directory," the migration WILL fail!

​

Once the old instance has finished, the new instance will work on importing the migrated data. When it is complete on the new machine, it will look like this:

​

<<NEW v3 INSTANCE>>

screenshot 5

​

This completes this step. Please proceed with Step 2 below.

STEP 2:

Now we must perform some additional data exports and imports to fill in any gaps left behind by the automated migration tool. This fixes things like Extension Secrets, VoiceMail account information, User Accounts & Groups,

​

First, you'll navigate the OLD v2.x instance GUI to Admin > Bulk Handler. From that page, EXPORT Extensions, DIDs, User Manager Users, and User Manager Groups. If you use the Blacklist and Contacts modules, you can export these too. When you click the Export button on each tab, you will be prompted to download a CSV file for each type of export data. Once you have completed the exports to CSV, you will IMPORT those same CSV files on the NEW v3.x instance.

​

screenshot 6
screenshot 7
screenshot 8

​

If you encounter the error "Unable to parse file" while importing, this usually means there is no data to import from that file (it is empty). Simply move on to the next import file.

​

If you need more information on the FreePBX Bulk Handler module, visit this page:

>> https://wiki.freepbx.org/display/FPG/Bulk+Handler+User+Guide

​

Phase Three:

In Phase Three, we will perform the following steps:

  1. Verify various module settings and user data to ensure they migrated properly

  2. Complete final setup steps on the new v3.x instance

  3. Connect a test endpoint to the new instance in order to confirm server functionality

​

​

STEP 1:

At this time, you will want to perform a side-by-side comparison of each module in the old and new instances in order to confirm that all of your data was migrated successfully. The best place to start is the Dashboard, as this will show you any errors on the new instance. Here are a few things you will need to attend to manually:

  • The default 'admin' login password for the FreePBX GUI will not be changed on the new instance during the migration, It will remain the launch default password unless you change it yourself. You can leave this as it is or change it. You can change the admin login information via Admin > Administrators. Then select the right-side slide-out menu and choose the admin account to edit the password

​

  • The IP information in Asterisk SIP Settings will not be migrated to the new instance because this will be obviously different until you swap the server into production. We cover this in Step 2 below.

​

​

STEP 2:

In order to test an endpoint with the new instance, we need to tell the instance its current (TEMPORARY) IP address information, just like you did when you first setup the old instance. To refresh your memory, here are the steps:

  1. Navigate to Settings > Asterisk SIP Settings

  2. Use the Detect Network Settings button to auto detect the necessary information

  3. Click Submit in the lower right corner of the screen

  4. Click the Apply Config button in the upper right corner of the screen

​

​

In order to ensure that everything we have done takes proper effect, you need to REBOOT YOUR NEW INSTANCE AT THIS TIME.

​

​

STEP 3:

Now that the new instance has been configured, you should be able to test an existing endpoint (or several) by editing the endpoint's SIP Server host/IP address to reflect the new instance temporary IP. You should be able to leave all other settings on the endpoint as they were, since the new instance should now have identical SIP login credentials as the old instance. Once you have connected a test endpoint, place a few internal test calls to things like *43 (echo test), queues, IVRs, etc. 

​

NOTE: During migration, the trunks on the new instance are disabled to prevent conflicts with your current production environment, so outbound/inbound calling to the outside world won't work right away. If you have setup your Trunk provider with the temp IP of the new instance or your Trunk provider uses simple user/pass authentication without IP restrictions, you can enable your trunks and test external calling if you'd like.

​

Once you have tested the new instance to your satisfaction, you are ready to swap the new v3.x instance into production. Proceed to Phase Four below.

​

Phase Four:

In Phase Four, we will perform the actual swap of the new v3.x instance into production by completing the following final steps:

  1. Re-Associate your production Elastic IP from the old v2.x instance to the new v3.x instance

  2. Update Asterisk SIP Settings on the GUI to reflect the proper IP address, enable Trunks on the new instance, disable Trunks on the old instance

  3. OPTIONAL: Migrate existing Deployment Activation with paid module licenses from the old server instance to the new server instance

  4. OPTIONAL: If you were using S3Sync or Auto File Deletion services on your old instance, you will need to configure these manually on the new instance

​

​

​

STEP 1:

Since the new instance is a near clone of the old instance now, all we have to do to swap the new server into production is to move your current production Elastic IP from the old instance to the new instance and update Asterisk SIP Settings. First you will move the Elastic IP from the AWS EC2 Console:

  1. Select Instances on the EC2 Console, then click the Public IPv4 Address of your old v2.x instance. This will take you to the Elastic IPs section of the Console filtered to show only this 1 IP

  2. Choose Actions > Associate Address

  3. Select the Instance drop-down and choose your new v3.x instance

  4. Select the Private IP drop-down and choose the instance's private IP

  5. Check the Reassociation checkbox

  6. Click the blue Associate button to complete the process

​

screenshot 9

​

As soon as you click the Associate button, your Elastic IP will be moved to the new v3.x instance and a new temporary Public IP will be assigned to the old v2.x instance. YOU SHOULD POWER OFF THE OLD v2.x INSTANCE AT THIS TIME TO AVOID TRUNK CONFLICTS! Your endpoints should begin connecting to the new instance within a few minutes, but some devices or software may need rebooted or restarted in order to switch to the new server. We suggest giving your endpoints 5-10 minutes to settle while you move on to Step 2. 

​

​

STEP 2:

Now you need to update Asterisk SIP settings on the new v3.x instance to reflect your Elastic IP. Just perform the following steps from the new instance FreePBX GUI, which will now be accessible via the Elastic IP address:

  1. Navigate to Settings > Asterisk SIP Settings

  2. Highlight and Delete the External Address field

  3. Use the Detect Network Settings button to auto detect the necessary information

  4. Click Submit in the lower right corner of the screen

  5. Click the Apply Config button in the upper right corner of the screen

​

​

Finally, you may now enable your SIP Trunks in Connectivity > Trunks. Edit each Trunk and change the Disable Trunk setting to NO, Submit the change, and Apply Config.

​

​

STEP 3 (OPTIONAL):

If you have paid commercial module licenses from Sangoma and need to migrate your deployment ID to the new v3.x instance, follow these steps:

  1. Log into your Sangoma Portal account: >> https://portal.sangoma.com

  2. From the left-side menu, choose Products > PBX > List

  3. Locate your existing deployment containing the old v2.x module licenses you paid for and make note of the "Deployment Name" (it is the Deployment ID #) then choose to View the deployment information

  4. Select the Licenses tab, take a moment to review the listed licenses to be certain this is the deployment ID you want to relocate, then choose the Reset Hardware Lock button at the bottom of the page

  5. From an SSH console connected to the new v3.x instance (elastic IP), run the following command using your Deployment ID in place of <DepID#>

    • fwconsole sa activate <DepID#>​

​

​

STEP 4 (OPTIONAL):

If you were using S3Sync for Call Recordings or VoiceMail and/or are using the Auto File Deletion service on your old instance, you will need to manually set these up on the new server instance via SmartUpgrade EXPERT-MODE just as you originally did on the old server.

​

​

Everything should now be up and running on your new v3.x instance! As always, if you have any questions or encounter any issues, we are here to help. Click here to contact our support team.

​

​

-REVERTING TO YOUR OLD INSTANCE-

(in an emergency)

​

In the unfortunate event that you encounter major issues after you have swapped the new v3.x instance into production, you can quickly revert to the old v2.x instance by powering the old instance on and performing Phase Four again. This time, move the Elastic IP and Deployment ID back to the OLD v2.x instance and disable the Trunks on the new v3.x instance to prevent conflicts.

​

​

​

Introduction
Prerequisites
Phase One
Phase Two
Phase Three
Phase Four
Reverting to your Old Instance

Instance Migration from AMI v2.x to v3.x

bottom of page