Help & Documentation
Open Support Ticket

Restore Your Metric Insights Instance

The mi-app-restore tool will read a backup file generated by mi-app-backup and restore the machine to the state contained in the backup file.  To restore a backup file, there are many available options. The four common ones are:

  • Full restore
  • Restore when database resides on remote server
  • Restore with retained configuration files
  • Restore database only

Prerequisites:

  • You must have previously used mi-app-backup to Backup Your Metric Insights instance
  • The machine on which you run mi-app-restore needs to already have the Metric Insights application installed on it.
  • You will need root privileges to do the following commands. So either sign in as root, or do each command prefixed with "sudo".
  • The mi-app-restore will restore the database to the location configured in /opt/mi/config/insight.conf on the machine you run the restore. So before restoring on a machine, make sure its /opt/mi/config/insight.conf points to the location of the database to which you will restore.

IMPORTANT:

  1. You need to run the restore command inside the Web container ( run mi-web on the host to enter Web)
  2. Make sure the backup tarball is in /opt/mi/backup on the host in order to access it from inside the Web container (/opt/mi/backup is mounted as a volume inside the Web container).

NOTE: Beginning in v7.1.0, restore to a different hostname will update the External Applications credentials.

1. Execute a Full Restore process

To restore Metric Insights, including overwriting any configuration files you might have on the system on which the restore is executed, use the  mi-app-restore command:

mi-app-restore PATH_TO_BACKUP_FILE

2. Execute a Restore when the Database Resides on a Remote Server

If the application database resides on a remote server (i.e., not the Metric Insights application server), you can use the following command:

mi-app-restore -U admin_user -P admin_pass PATH_TO_BACKUP_FILE

...where admin_user and admin_pass are the admin credentials for the remote database server

3. Execute a Restore While Retaining Configuration Files

If you wish to keep your configuration files and only restore application state, you can use the following command:

mi-app-restore --no-config PATH_TO_BACKUP_FILE

4. Restore Only the Database

If you wish to only restore the database, you can use the following command:

mi-app-restore --include 'db' PATH_TO_BACKUP_FILE

5. Usage

To see all usage options:

mi-app-restore -h
Parameter Description
Positional Arguments
src_uri

Location of the backup file. This can point to a local file or a remote scp/ftp/s3 backup.
Optional Arguments
-h, --help            
 Show this help message and exit
--dry-run, -n        
Dry run. Print what would happen
 --verbose, -v        
Be verbose. More v's, more verbose
--version, -V        
Show program's version number and exit
--force, -f          
Don't ask for confirmation, just do the restore
--no-config          
Don't restore the config files in the backup
 --db-user DB_USER, -U DB_USER
 The DB user to use when loading the MI database. Default: root

 --db-pass DB_PASS, -P DB_PASS

 The DB password to use when loading the MI database
--user USER, -u USER  
 Optional user for logging into remote host

--password PASSWORD, -p PASSWORD

 Optional password for logging into remote host
 --ssh-key SSH_KEY, -i SSH_KEY
 SSH key file to use for remote server
 --include TYPE, -I TYPE
 What to include from the backup. Choose from 'db', 'files', or 'full'. Default: full
-convert, -c
Convert older backup data to be compatible with the newer installed version

6. Examples

Restore MI from the given backup:

    mi-app-restore /some/dir/my_file.tar.gz
    mi-app-restore file:///some/dir/my_file.tar.gz 

Read the backup from the remote machine machine.example.com.

  • This will use the ~/.ssh/id_rsa ssh key by default if it exists
  • Use -i SSH_KEY to modify this
    mi-app-restore ssh://machine.example.com/home/cru/backups/my_file.tar.gz     

 Backup from the file from ftp.example.com in the /upload/backups directory.

mi-app-restore -u <user> -p <pass> ftp://ftp.example.com/upload/backups/my_file.tar.gz

 

Read backup file from Amazon S3 bucket my-bucket. The @endpoint/bucket syntax will work for RIAK-CS and other s3-compatible cloud storage services.

mi-app-restore -u <S3_ID> -p <S3_KEY> s3://my-bucket/dir/my_file.tar.gz
mi-app-restore -u <S3_ID> -p <S3_KEY> s3://@my.s3.endpoint/my-bucket/dir/my_file.tar.gz

6.1. Example: Restore Amazon EC2 instance with RDS

1. Spin up new Amazon EC2

2. Spin up new Amazon RDS

On new EC2 instance:

3. Move EC2 local db to RDS

mi-db-move <rds host> <rds db admin> <rds db password>

(This will also rename the dashboard db to the "hostname/ip address" of the machine.

Note, you must define the mysql parameters appropriately for the remote db server. Please see http://kb.metricinsights.com/m/44498/l/412310-fine-tuning-mysql-parameters for more information.)

4. Optional: Rename db on RDS to be the same as what is in the restore

mi-db-rename -d <dashboard db name> -D <old dashboard db name> -U <rds db admin> -P <rds db password>

5. Get the backup file to restore from

scp root@<old EC2 host>:/var/backups/mi-app-backups/<backup file name> /var/backups/mi-app-backups/

6. Do the restore (This will upgrade, then restore)

mi-app-restore -U <rds db admin> -P <rds db password> /var/backups/mi-app-backups/<backup file name>