'''ImportBuddy''' (importbuddy.php) is the tool that allows you to [[BackupBuddy:_Migrations|migrate]] or [[BackupBuddy:_Restore|restore]] a site with BackupBuddy. Keep a copy of the ImportBuddy script with your backups for restoring sites directly from backups. '''For complete documentation on migrating or restoring your site with BackupBuddy, please visit the [[BackupBuddy:_Manual_Migration|Manual Migration]] and [[BackupBuddy:_Magic_Migration|Magic Migration]] pages.'''

−

==Getting Started==

+

−

The following will describe what is needed to start migrating or restoring a backup.

+

−

* Download ImportBuddy from within BackupBuddy by navigating to the `Backup & Restore` page and clicking the `ImportBuddy` or `Restore / Migrate` button depending on your version.

+

−

* Decide on the server directory that you would like to migrate or restore the backup to (using an empty directory is best).

+

−

* Upload importbuddy.php and the backup zip file (don't rename the zip file!) to that directory.

+

−

* Navigate to the importbuddy.php file in your web browser after it has been uploaded.

+

−

** Example: <nowiki>http://newsite.com/importbuddy.php</nowiki>

+

−

* Follow the directions provided for each ImportBuddy step.

+

−

* If you encounter problems note the logging information displayed on the problem step when contacting support.

+

+

<br />

−

==Step 0: Password Authentication==

+

=ImportBuddy Password=

−

This step asks for the password associated with the importbuddy.php file.

+

−

* Is set in BackupBuddy's Settings page and required to continue.

+

−

** The password is attached to the importbuddy.php file when it is made so if you change the password will need to download and upload a new importbuddy.php file

+

+

To use ImportBuddy, you'll first need to set a password. ImportBuddy requires this to protect unauthorized access to your site and backup files before you have finished restoring. This password is encoded inside your ImportBuddy file when it is made, so:

+

*If you share this ImportBuddy file to another for usage with a backup file you will need to provide the corresponding password.

+

*If you change the password will need to download a new copy of ImportBuddy. Changing the password will NOT change it in existing ImportBuddy files.

−

==Step 1==

−

On this step there is a dropdown list of the backup zip files that can be restored or use to migrate with. Also has an Upload tab to upload a backup .zip file by browsing for it.

−

This step also allows the user to set advanced troubleshooting options to customize the importbuddy process.

+

#To set your password, navigate to '''BackupBuddy > Settings''' and enter the password you'd like to use in the [[BackupBuddy_Settings:_General#ImportBuddy_.26_RepairBuddy_password|ImportBuddy & RepairBuddy password]] section.<br /><br /><br />[[File:IBPassword.png|IBPassword.png|link=]]<br /><br /><br />

−

* Wipe database on import. Use with caution.

+

#You can also set a password when you [[#Download|download ImportBuddy]]. If you set a password when downloading ImportBuddy, it overrides the password you created in your BackupBuddy Settings. If you leave the option blank, it will use the default password you created in your settings.<br /><br /><br />[[File:ImportBuddyDownloadPassword.png|ImportBuddyDownloadPassword.png|link=]]<br /><br /><br />

−

** This option will blank out the current database at the location, if not the option you needed to use then could lose data

+

#An ImportBuddy password can also be set during the [[BackupBuddy:_Quick_Setup#2._Create_a_password_for_restoring_or_migrating_your_backups|Quick Setup]] page after first installing BackupBuddy.

−

* Ignore SQL errors & hide them.

+

−

* Skip zip file extraction.

+

−

** This option is mainly used if the files are manually being unzipped instead of using the importbuddy file extraction process.

+

−

* Skip import of database.

+

−

* Skip migration of database.

+

−

* Skip migration of .htaccess file.

+

−

* Force medium speed compatibility mode (ZipArchive).

+

−

* Force slow speed compatibility mode (PCLZip).

+

−

* Show detailed PHP warnings.

+

−

* PHP Maximum Execution Time

+

−

** Setting this a little lower can help force importbuddy to chunk the importing and migration of the database into multiple steps if large

+

−

* Error Logging to importbuddy.txt

+

+

<br />

−

==Step 2==

+

=Accessing ImportBuddy=

−

The file extraction process occurs during this step, and the extraction method used is displayed.

+

+

After setting your ImportBuddy password, there are two ways you can access ImportBuddy:

−

==Step 3==

+

*Manually downloading (and then uploading to destination server)

−

This step is used to set the URL and database connection information. The information shown in parentheses is what importbuddy sees the values where previously, useful for a restore when most if not all of the information will be the same.

+

*Sending to destination from within BackupBuddy

−

* WordPress Address

+

−

** This field will be pre-set using the information for the current directory the user is restoring/migrating to.

+

−

* MySQL Server

+

−

** This is the address to the mySQL server where your database will be stored. 99% of the time this is localhost. The location of your mySQL server will be provided to you by your host if it differs.

+

−

* Database Name

+

−

** This is the name of the database you want to import your blog into. The database user must have permissions to be able to access this database. If you are migrating this blog to a new host you will need to create this database (ie using CPanel or phpmyadmin) and create a mysql database user with permissions.

+

−

* Database User

+

−

** This is the database user account that has permission to access the database name in the input above. This user must be given permission to this database for the import to work.

+

−

* Database Pass

+

−

** This is the password for the database user.

+

−

* Database Prefix

+

−

** This is the prefix given to all tables in the database. If you are cloning the site on the same server AND the same database name then you will want to change this or else the imported database will overwrite the existing tables.

+

−

After entering the database information there is a button labelled "test database settings" that will test the validity of that connection information.

+

+

<br />

−

==Step 4==

+

==Manually Downloading and Uploading to Destination Server==

−

The database information is imported straight into the database.

+

+

To manually download ImportBuddy and upload to your destination server, follow these steps:

−

==Step 5==

+

<br />

−

Importbuddy looks through the database and updates any URLs, paths, settings, etc. The wp-config.php information is set and the links are changed during this step.

+

−

* Use the link of the site provided to verify that the site is fully migrated and complete before continuing to step 6.

+

−

* Can choose which of the import files get deleted in next step if desired. By default is all of them.

+

+

===Manually Downloading ImportBuddy===

−

==Step 6==

+

<br />

−

Cleanup step. This step attempts to delete

+

−

* backup zip archive

+

−

* importbuddy.php

+

−

* temporary import files (db_1.sql, backupbuddy_dat.php, etc.)

+

−

* importbuddy.txt log file

+

+

#To download ImportBuddy, navigate to the '''Restore/Migrate''' page in BackupBuddy and click the '''Download ImportBuddy''' button. This will initiate the download of the ImportBuddy file.<br /><br /><br />[[File:DownloadImportBuddy.png|DownloadImportBuddy.png|link=]]<br /><br /><br />

+

#Save the file to your computer.

+

#You will next [[BackupBuddy:_ImportBuddy_Rough_Draft#Uploading_ImportBuddy_to_your_destination_server|upload the ImportBuddy file to your destination server]] to begin using it.

−

[[Category:PluginBuddy]]

+

<br />

+

+

===Uploading ImportBuddy to your destination server===

+

+

<br />

+

+

#Decide on the FTP directory that you would like to migrate or restore the backup to (using an empty directory is best) that corresponds to the web URL you want your destination site to be at. For example, if you want your new site's URL to be <code><nowiki>http://your.com/mybuddy/</nowiki></code> then your server directory MIGHT be something like <code> /user/yourusername/public_html/mybuddy/</code>. This is the directory you will then put importbuddy.php into. '''Note:''' The directory structure varies host to host but often follows a similar format.

Instead of manually downloading ImportBuddy, you can send ImportBuddy directly to the location of your migration/restoration from within BackupBuddy.

+

+

<br />

+

+

#To send ImportBuddy to a destination, navigate to the '''Restore/Migrate''' page in BackupBuddy and click the '''Send ImportBuddy to a Destination'''.<br /><br /><br />[[File:ImportBuddySendtoDestination.png|ImportBuddySendtoDestination.png|link=]]<br /><br /><br />

+

#In the window that opens, you be given options for where to send the ImportBuddy file. You'll find a list of your current remote destinations and an option to create a new destination.<br /><br /><br />[[File:ImportBuddyDestinationOptions.png|ImportBuddyDestinationOptions.png|link=]]<br /><br /><br />

+

#Follow the steps for [[BackupBuddy:_Manual_Migration|Manual Migration]].

+

+

<br />

+

+

=The 6 ImportBuddy Steps=

+

+

For more information on the ImportBuddy migration/restore process, visit the following links:

ImportBuddy's '''Advanced Options''' allow customization of various ImportBuddy functionality for custom purposes or troubleshooting. '''Exercise caution as some advanced options may have unforeseen effects if not used properly, such as overwriting existing files or erasing existing database content.'''

+

+

Advanced Options can be located after clicking the '''Advanced Options''' button during Step 1 and 4 the [[BackupBuddy:_ImportBuddy_Rough_Draft#The_6_ImportBuddy_Steps|6 ImportBuddy Steps]].

+

+

<br />

+

+

[[File:Step1-advanced-options.png|link=]]

+

+

<br />

+

+

'''Step 1 Advanced Options:'''

+

+

*'''ZIP Archive Extraction (Step 2)'''

+

**'''Skip zip file extraction''' - Checking this box will prevent extraction/unzipping of the backup ZIP file. You will need to manually extract it either on your local computer then upload it or use a server-based tool such as cPanel to extract it. This feature is useful if the extraction step is unable to complete for some reason.

*'''Import Logging''' - Errors and other debugging information will be written to importbuddy.txt in the same directory as importbuddy.php. This is useful for debugging any problems encountered during import. Support may request this file to aid in tracking down any problems or bugs.

+

+

<br />

+

+

[[File:Screen Shot 2013-08-13 at 12.33.03 PM.png|link=]]

+

+

<br />

+

+

'''Step 4 Advanced Options''':

+

+

*'''Database Import (Step 4)'''

+

**'''Skip import of database'''

+

**'''Delete database tables that match new prefix on import''' - WARNING: Checking this box will have this script clear ALL existing data from your database that match the new database prefix prior to import, possibly including non-WordPress data. This is useful if you are restoring over an existing site or repairing a failed migration. Use caution when using this option and double check the destination prefix. This cannot be undone.

+

**'''Delete ALL database tables, erasing ALL database content''' - WARNING: Checking this box will have this script clear ALL existing data from your database, period, including non-WordPress data found. Use with extreme caution, verifying you are using the exact correct database settings. This cannot be undone.

+

**'''Force database import compatibility (pre-v3.0) mode'''

+

**'''Ignore existing WordPress tables and import (merge tables) anyways''' - When checked ImportBuddy will allow importing database tables that have the same name as existing tables. This results in a merge of the existing data with the imported database being merged. Note that this is does NOT update existing data and only ADDS new database table rows. All other SQL conflict errors will be suppressed as well. Use this feature with caution.

**'''Skip extended brute force migration of URLS/paths in database''' - By default BackupBuddy will extensively examine and migrate unknown database tables. Sometimes however this can cause timeouts on larger sites. You may skip this intensive procedure to reduce required runtime for database migration steps. Note that some URLs or paths may not be updated if skipping this step. All major WordPress URLs and paths will still be updated however.

Revision as of 16:36, August 13, 2013

ImportBuddy (importbuddy.php) is the tool that allows you to migrate or restore a site with BackupBuddy. Keep a copy of the ImportBuddy script with your backups for restoring sites directly from backups. For complete documentation on migrating or restoring your site with BackupBuddy, please visit the Manual Migration and Magic Migration pages.

ImportBuddy Password

To use ImportBuddy, you'll first need to set a password. ImportBuddy requires this to protect unauthorized access to your site and backup files before you have finished restoring. This password is encoded inside your ImportBuddy file when it is made, so:

If you share this ImportBuddy file to another for usage with a backup file you will need to provide the corresponding password.

If you change the password will need to download a new copy of ImportBuddy. Changing the password will NOT change it in existing ImportBuddy files.

You can also set a password when you download ImportBuddy. If you set a password when downloading ImportBuddy, it overrides the password you created in your BackupBuddy Settings. If you leave the option blank, it will use the default password you created in your settings.

An ImportBuddy password can also be set during the Quick Setup page after first installing BackupBuddy.

Accessing ImportBuddy

After setting your ImportBuddy password, there are two ways you can access ImportBuddy:

Manually downloading (and then uploading to destination server)

Sending to destination from within BackupBuddy

Manually Downloading and Uploading to Destination Server

To manually download ImportBuddy and upload to your destination server, follow these steps:

Manually Downloading ImportBuddy

To download ImportBuddy, navigate to the Restore/Migrate page in BackupBuddy and click the Download ImportBuddy button. This will initiate the download of the ImportBuddy file.

Uploading ImportBuddy to your destination server

Decide on the FTP directory that you would like to migrate or restore the backup to (using an empty directory is best) that corresponds to the web URL you want your destination site to be at. For example, if you want your new site's URL to be http://your.com/mybuddy/ then your server directory MIGHT be something like /user/yourusername/public_html/mybuddy/. This is the directory you will then put importbuddy.php into. Note: The directory structure varies host to host but often follows a similar format.

The 6 ImportBuddy Steps

Advanced Options

ImportBuddy's Advanced Options allow customization of various ImportBuddy functionality for custom purposes or troubleshooting. Exercise caution as some advanced options may have unforeseen effects if not used properly, such as overwriting existing files or erasing existing database content.

Advanced Options can be located after clicking the Advanced Options button during Step 1 and 4 the 6 ImportBuddy Steps.

Step 1 Advanced Options:

ZIP Archive Extraction (Step 2)

Skip zip file extraction - Checking this box will prevent extraction/unzipping of the backup ZIP file. You will need to manually extract it either on your local computer then upload it or use a server-based tool such as cPanel to extract it. This feature is useful if the extraction step is unable to complete for some reason.

Import Logging - Errors and other debugging information will be written to importbuddy.txt in the same directory as importbuddy.php. This is useful for debugging any problems encountered during import. Support may request this file to aid in tracking down any problems or bugs.

Step 4 Advanced Options:

Database Import (Step 4)

Skip import of database

Delete database tables that match new prefix on import - WARNING: Checking this box will have this script clear ALL existing data from your database that match the new database prefix prior to import, possibly including non-WordPress data. This is useful if you are restoring over an existing site or repairing a failed migration. Use caution when using this option and double check the destination prefix. This cannot be undone.

Delete ALL database tables, erasing ALL database content - WARNING: Checking this box will have this script clear ALL existing data from your database, period, including non-WordPress data found. Use with extreme caution, verifying you are using the exact correct database settings. This cannot be undone.

Force database import compatibility (pre-v3.0) mode

Ignore existing WordPress tables and import (merge tables) anyways - When checked ImportBuddy will allow importing database tables that have the same name as existing tables. This results in a merge of the existing data with the imported database being merged. Note that this is does NOT update existing data and only ADDS new database table rows. All other SQL conflict errors will be suppressed as well. Use this feature with caution.

Skip extended brute force migration of URLS/paths in database - By default BackupBuddy will extensively examine and migrate unknown database tables. Sometimes however this can cause timeouts on larger sites. You may skip this intensive procedure to reduce required runtime for database migration steps. Note that some URLs or paths may not be updated if skipping this step. All major WordPress URLs and paths will still be updated however.