The kusanagi migrate command was added to KUSANAGI in 8.6.6 for KUSANAGI 8 and in 9.1.9 for KUSANAGI 9.
The kusanagi migrate command literally exports (export) KUSANAGI profiles from the old source environment and imports (import) them into the new destination environment.
It is important to note that KUSANAGI 8 supports only export;
KUSANAGI 9 supports both export and import.
The kusanagi migrate command migrates the following contents.
- Directories and files under profile (/home/kusanagi/profile)
- Profile database (MariaDB only)
- Profile settings (FQDN, DB name, DB user, DB password, etc.)
- SSL certificate (*8.7.9 or later for KUSANAGI 8, 9.2.16 or later for KUSANAGI 9)
There are also some points to note to ensure that the transition proceeds.
- Match source and destination PHP/MariaDB versions
- If the source PHP/MariaDB is out of date, update it in advance and check its operation in the source.
- If you are using Let's Encrypt SSL certificates, stop auto-renewal at the source and enable auto-renewal at the destination.
Let's take a look at how to actually use KUSANAGI 8 or KUSANAGI 9 (CentOS Stream 8) in a migration scenario to KUSANAGI 9 (AlmaLinux OS 8).
We will start with "Migration Scenarios for KUSANAGI 8".
If you are using KUSANAGI 9, please refer to “Migration Scenarios for KUSANAGI 9”.
Migration Scenarios for KUSANAGI 8
Bring the migration source up-to-date and verify its operation.
First, bring the source environment up-to-date.
yum update --enablerepo=remi,remi-php56
kusanagi restartIf the update does not produce any errors, the source environment will be up-to-date.
Match the version with the middleware used in KUSANAGI 9.
Below is a table of middleware that can be used with KUSANAGI 8 and KUSANAGI 9.
| middleware | source of migration KUSANAGI 8 | destination of migration KUSANAGI 9 | remarks |
|---|---|---|---|
| PHP | PHP 7.4 | PHP 7.4 | 2022/11/28 EOL |
| PHP 8.0 | PHP 8.0 | 2023/11/26 EOL | |
| PHP 8.1 | PHP 8.1 | At the time of writing (May 17, 2024) | |
| MariaDB | MariaDB 10.5 | MariaDB 10.5 |
PHP
As confirmed in the table above, the common PHP versions for KUSANAGI 8 and KUSANAGI 9 are 7.4 / 8.0 / 8.1.
Among them, PHP 7.4 and PHP 8.1 can be selected by KUSANAGI 8 commands.
- PHP 7.4
kusanagi php7- PHP 8.1
kusanagi php8However, PHP 7.4 will be EOL on November 28, 2022, and PHP 8.0 will be EOL on November 26, 2023, so it is preferable to move up to PHP 8.1 unless there are circumstances where it is not possible to update the PHP 8 series or verify with a different version.
PHP 8.1 will also be EOL on 12/31/2025.
There are no plans to support PHP 8.2 in KUSANAGI 8.
If you are considering migrating from KUSANAGI 8 to KUSANAGI 9, we recommend that you do so while PHP 8.1 is still available on KUSANAGI 9.
MariaDB
As confirmed in the table above, the common MariaDB version for KUSANAGI 8 and KUSANAGI 9 is 10.5.
If you are using a version earlier than 10.5, please use the following command to upgrade your database.
kusanagi upgrade mariadb 10.5MariaDB 10.5 will be EOL on 1/24/2025.
KUSANAGI 8 will not support MariaDB 10.5 or later versions.
If you are considering migration from KUSANAGI 8 to KUSANAGI 9, we recommend that you do so while MariaDB 10.5 is available on KUSANAGI 9.
MariaDB 10.3 is also supported in KUSANAGI 8 and KUSANAGI 9, but is omitted for the following reasons.
- MariaDB 10.3 is already EOL as of 5/25/2023 and has been removed from the repository.
- MariaDB 10.3 does not support AlmaLinux OS 9 / CentOS Stream 9.
First check that the source environment works properly with the new versions of PHP and MariaDB.
Exporting from the source of migration
The kusanagi migrate command exports all directories and files under the profile (/home/kusanagi/profile).
If there are directories or files that do not need to be migrated, such as working directories or past backups, move them to a directory separate from the profile to reduce the size of the exported files.
Similarly, past log files should be moved if migration is not required.
When everything is ready, it is a good idea to switch to the source site while it is under maintenance, for example.
Data that is changed or updated after exporting cannot be reflected unless it is exported again.
kusanagi migrate --export profileIf the command completes successfully, a file named profile-date.tar.gz is created under /home/kusanagi.
Please bring this file to the destination environment using FTP or other means.
For PST (WEXAL) environment
If you are using PST (WEXAL), kusanagi migrate command does not support migration of PST environment.
Therefore, the PST environment must first be deleted before exporting from the migration source, and then exported.
pst remove profile
kusanagi migrate --export profileImporting to the migration destination
In the destination environment, complete up to the kusanagi init command.
dnf update
kusanagi init --passwd password --nophrase --dbrootpass dbrootpass --php81 --mariadb10.5The above command uses PHP version 8.1, MariaDB version 10.5, and Nginx as the web server.
If you want to change the PHP version, change --php81 to the following, respectively.
- PHP 7.4 :
--php74 - PHP 8.0 :
--php80
If you want to use Apache HTTPD instead of Nginx as your web server, add --httpd24 option.
The PHP version and web server specification can also be changed after init with the kusanagi command.
- PHP 7.4
kusanagi php --use php74- PHP 8.0
kusanagi php --use php80- Apache HTTPD
kusanagi httpdAfter the initial configuration of KUSANAGI is complete, import it using the kusanagi migrate command.
kusanagi migrate --import profile-date.tar.gzIf the command completes successfully, the migration is completed under /home/kusanagi/profile.
Note that there are a few things that need to be handled manually.
- If you have manually changed the Nginx/Apache HTTPD configuration file, it will not be reflected.
- Check /home/kusanagi/profile/conf for the original files to be migrated
- Settings made to the OS, such as CRON, will not be reflected.
- If you are using Let's Encrypt SSL certificates, stop auto-renewal at the source and run the kusanagi ssl --email command at the destination to enable auto-renewal.
Note, however, that the command cannot be executed until the IP address of the server is changed, as described below.
Before rewriting the DNS FQDN record to the IP address of the server to be migrated, rewrite the hosts file or use your browser's functions to make sure that the new environment will display it without problems.
For PST (WEXAL) environment
If you are using PST (WEXAL), kusanagi migrate command does not support migration of PST environment.
Import the exported files to the destination, then initialize the PST environment for the target profile.
kusanagi migrate --import profile-date.tar.gz
pst init imported-profileThe PST settings will be initialized, so please set them again.
Migration Scenarios for KUSANAGI 9
Bring the migration source up-to-date and verify its operation.
First, bring the source environment up-to-date.
dnf update
kusanagi restartIf the update does not produce any errors, the source environment will be up-to-date.
Match the version with the middleware used in KUSANAGI 9.
PHP
As of this writing (17/5/2024), KUSANAGI 9 supports PHP versions 7.4 / 8.0 / 8.1 / 8.2 / 8.3.
If the source environment is using a version earlier than 7.4, please upgrade to 7.4 or higher.
- PHP 7.4
kusanagi php --use php74- PHP 8.0
kusanagi php --use php80- PHP 8.1
kusanagi php --use php81- PHP 8.2
kusanagi php --use php82- PHP 8.3
kusanagi php --use php83However, PHP 7.4 will be EOL on November 28, 2022, and PHP 8.0 will be EOL on November 26, 2023, so unless there are circumstances where it is not possible to update the PHP 8 series or verify with a different version, it is advisable to raise it to PHP 8.1 or higher.
MariaDB
As of this writing (May 17, 2024), the MariaDB versions supported by KUSANAGI 9 are 10.5 / 10.6 / 10.11.
If the source environment is using a version of MariaDB prior to 10.5, please upgrade to 10.5 or higher.
- MariaDB 10.5
kusanagi upgrade mariadb --use mariadb10.5- MariaDB 10.6
kusanagi upgrade mariadb --use mariadb10.6- MariaDB 10.11
kusanagi upgrade mariadb --use mariadb10.11KUSANAGI 9 also supports MariaDB 10.3 / 10.4, but we omit it for the following reasons.
- MariaDB 10.3 is already EOL as of 5/25/2023 and has been removed from the repository.
- MariaDB 10.4 will be EOL on 6/18/2024.
- Neither MariaDB 10.3 / 10.4 nor AlmaLinux OS 9 / CentOS Stream 9 are supported.
First check that the source environment works properly with the new versions of PHP and MariaDB.
Exporting from the source of migration
The kusanagi migrate command exports all directories and files under the profile (/home/kusanagi/profile).
If there are directories or files that do not need to be migrated, such as working directories or past backups, move them to a directory separate from the profile to reduce the size of the exported files.
Similarly, past log files should be moved if migration is not required.
When everything is ready, it is a good idea to switch to the source site while it is under maintenance, for example.
Data that is changed or updated after exporting cannot be reflected unless it is exported again.
kusanagi migrate --export profileIf the command completes successfully, a file named profile-date.tar.gz is created under /home/kusanagi.
Please bring this file to the destination environment using FTP or other means.
For PST (WEXAL) environment
If you are using PST (WEXAL), kusanagi migrate command does not support migration of PST environment.
Therefore, the PST environment must first be deleted before exporting from the migration source, and then exported.
pst remove profile
kusanagi migrate --export profileImporting to the migration destination
In the destination environment, complete up to the kusanagi init command.
dnf update
kusanagi init --passwd password --nophrase --dbrootpass dbrootpass --php81 --mariadb10.5The above command uses PHP version 8.1, MariaDB version 10.5, and Nginx as the web server.
If you want to change the PHP version, change --php81 to the following, respectively.
- PHP 7.4 :
--php74 - PHP 8.0 :
--php80 - PHP 8.2 :
--php82 - PHP 8.3 :
--php82
If you want to change the MariaDB version, change --mariadb10.5 to the following, respectively.
- MariaDB 10.6 :
--mariadb10.6 - MariaDB 10.11 :
--mariadb10.11
If you want to use Apache HTTPD instead of Nginx as your web server, add --httpd24 option.
The PHP version, MariaDB version, and web server can also be changed after init with the kusanagi command.
- PHP 7.4
kusanagi php --use php74- PHP 8.0
kusanagi php --use php80- PHP 8.2
kusanagi php --use php82- PHP 8.3
kusanagi php --use php83- MariaDB 10.6
kusanagi upgrade mariadb --use mariadb10.6- MariaDB 10.11
kusanagi upgrade mariadb --use mariadb10.11- Apache HTTPD
kusanagi httpdAfter the initial configuration of KUSANAGI is complete, import it using the kusanagi migrate command.
kusanagi migrate --import profile-date.tar.gzIf the command completes successfully, the migration is completed under /home/kusanagi/profile.
Note that there are a few things that need to be handled manually.
- If you have manually changed the Nginx/Apache HTTPD configuration file, it will not be reflected.
- Check /home/kusanagi/profile/conf for the original files to be migrated
- Settings made to the OS, such as CRON, will not be reflected.
- If you are using Let's Encrypt SSL certificates, stop auto-renewal at the source and run the kusanagi ssl --email command at the destination to enable auto-renewal.
Note, however, that the command cannot be executed until the IP address of the server is changed, as described below.
Before rewriting the DNS FQDN record to the IP address of the server to be migrated, rewrite the hosts file or use your browser's functions to make sure that the new environment will display it without problems.
For PST (WEXAL) environment
If you are using PST (WEXAL), kusanagi migrate command does not support migration of PST environment.
Import the exported files to the destination, then initialize the PST environment for the target profile.
kusanagi migrate --import profile-date.tar.gz
pst init imported-profileThe PST settings will be initialized, so please set them again.
Complete the migration
Finally, the DNS FQDN record is changed from the IP address of the source server to the IP address of the destination server to complete the process.
If you are using a Let's Encrypt SSL certificate, remember to reconfigure your Let's Encrypt SSL certificate with the kusanagi ssl --email command after changing your IP address.
