kusanagi migrateコマンドによる移行手順

kusanagi migtate コマンドは KUSANAGI 8 では 8.6.6 から、KUSANAGI 9 では 9.1.9 で追加されました。

kusanagi migrate コマンドは文字通り、KUSANAGIのプロファイルを古い移行元の環境からエクスポート (export) して、新しい移行先の環境でインポート (import) するコマンドになります。
気を付けていただきたいのは、 KUSANAGI 8 はエクスポートのみの対応という点です。
KUSANAGI 9 はエクスポートとインポートの両方に対応しています。

kusanagi migrate コマンドが移行するのは以下の内容になります。

• プロファイル (/home/kusanagi/プロファイル) 配下のディレクトリとファイル
• プロファイルのデータベース (MariaDBのみ)
• プロファイルの設定 (FQDN、DB名、DBユーザ、DBパスワードなど)
• SSL証明書 (※KUSANAGI 8 は 8.7.9 以降、 KUSANAGI 9 は 9.2.16 以降)

また、確実に移行を進めるために注意していただきたい点があります。

• 移行元と移行先の PHP/MariaDB のバージョンを合わせる
• 移行元の PHP/MariaDB が古い場合は、移行元において事前に更新して動作確認をする
• Let's Encrypt SSL証明書を利用している場合は、移行元の自動更新を止めて、移行先で自動更新を有効にする

それでは KUSANAGI 8 または KUSANAGI 9 (CentOS Stream 8) から KUSANAGI 9 (AlmaLinux OS 8) へ移行する、というシナリオで実際に使い方を紹介します。

まずは、KUSANAGI 8 の移行シナリオから紹介します。
KUSANAGI 9 を使用している方は「KUSANAGI 9 の移行シナリオ」を参照してください。

KUSANAGI 8 の移行シナリオ

移行元を最新化して動作検証する

まず、移行元の環境を最新化します。

yum update --enablerepo=remi,remi-php56
kusanagi restart

アップデートでエラーが出なければ、移行元の環境は最新化されます。

次に、KUSANAGI 9 で利用するミドルウェアとバージョンを合わせます。
以下が KUSANAGI 8 と KUSANAGI 9 で使えるミドルウェアの対応表になります。

ミドルウェア	移行元 KUSANAGI 8	移行先 KUSANAGI 9	備考
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	執筆時点（2024/5/17）
MariaDB	MariaDB 10.5	MariaDB 10.5

PHP

上記の表で確認しましたように、KUSANAGI 8 と KUSANAGI 9 の共通の PHP のバージョンは 7.4 / 8.0 / 8.1 になります。
その中で、KUSANAGI 8 のコマンドで選択できる PHP は PHP7.4 と PHP 8.1 になります。

• PHP 7.4

kusanagi php7

• PHP 8.1

kusanagi php8

しかし、 PHP 7.4 は 2022/11/28 で、PHP 8.0 は 2023/11/26 で EOL となっていますので、PHP 8 系のアップデートができない、違うバージョンでの検証ができないなどの事情がない限り、 PHP 8.1 に上げるのが望ましいです。

また PHP 8.1 も 2025/12/31 でEOLとなる予定です。
KUSANAGI 8 においては、 PHP 8.2 に対応する予定はございません。
KUSANAGI 8 から KUSANAGI 9 へのマイグレーションをお考えの方は、KUSANAGI 9 で PHP 8.1 が使用できる間にマイグレーションをすることを推奨します。

MariaDB

上記の表で確認しましたように、KUSANAGI 8 と KUSANAGI 9 の共通の MariaDB のバージョンは 10.5 になります。
10.5 より前のバージョンを使用している場合には、下記コマンドでデータベースの アップグレードを実施してください。

kusanagi upgrade mariadb 10.5

MariaDB 10.5 は 2025/1/24 でEOLとなる予定です。
KUSANAGI 8 においては、 MariaDB 10.5 以降のバージョンに対応する予定はございません。
KUSANAGI 8 から KUSANAGI 9 へのマイグレーションをお考えの方は、KUSANAGI 9 で MariaDB 10.5 が使用できる間にマイグレーションをすることを推奨します。

なお、 KUSANAGI 8 および KUSANAGI 9 では MariaDB 10.3 にも対応していますが、以下の理由により省いております。

• MariaDB 10.3 は 2023/5/25 で既に EOL となっており、リポジトリからも削除されている。
• MariaDB 10.3 は AlmaLinux OS 9 / CentOS Stream 9 に対応していない。

PHP および MariaDB のバージョンを変更した状態で、移行元環境が正常に動作するかを、まず確認してください。

移行元からエクスポートする

kusanagi migrate コマンドはプロファイル (/home/kusanagi/プロファイル) 配下の全てのディレクトリとファイルをエクスポートします。
作業用のディレクトリや過去のバックアップなど、移行が不要なディレクトリや ファイルが存在する場合は、プロファイルとは別のディレクトリに移動しておくと、 エクスポートするファイルのサイズを小さくできます。
同様に過去のログファイルも移行が不要であれば、移動しておくとよいです。

全ての準備が整ったら、移行元のサイトはメンテナンス中などに 切り替えておくのがよいでしょう。
エクスポートした後に変更や更新されたデータは、再度エクスポートしない限り反映することができません。

kusanagi migrate --export プロファイル

コマンドが正常に終了すれば、/home/kusanagi配下に プロファイル-日付.tar.gz という ファイルが作成されています。
このファイルをFTPなどを利用して、移行先の環境へ持っていってください。

PST (WEXAL) 環境の場合

PST (WEXAL) を利用している場合ですが、 kusanagi migrate コマンドは PST 環境のマイグレーションには対応しておりません。
そのため、まず移行元からエクスポートする前に PST 環境を削除し、その後エクスポートする必要があります。

pst remove プロファイル
kusanagi migrate --export プロファイル

移行先にインポートする

移行先の環境では kusanagi init コマンドまで済ませておきましょう。

dnf update
kusanagi init --passwd kusanagiユーザのパスワード --nophrase --dbrootpass DBのrootパスワード --php81 --mariadb10.5

上記のコマンドは PHP のバージョンは 8.1 、 MariaDB のバージョンは 10.5 、 Web サーバーは Nginx になります。
PHP のバージョンを変えたい場合は、 --php81 をそれぞれ以下のように変えてください。

• PHP 7.4 : --php74
• PHP 8.0 : --php80

Webサーバーを Nginx ではなく、 Apache HTTPD を使用したい場合は、 --httpd24 オプションを付けてください。

PHP のバージョンや Web サーバーの指定は、 init した後から kusanagi コマンドで変更することもできます。

• PHP 7.4

kusanagi php --use php74

• PHP 8.0

kusanagi php --use php80

• Apache HTTPD

kusanagi httpd

KUSANAGIの初期設定が完了したら、kusanagi migrate コマンドでインポートします。

kusanagi migrate --import プロファイル-日付.tar.gz

コマンドが正常に終了すれば、 /home/kusanagi/プロファイル 配下に移行が完了します。

なお、いくつか手動で対応する必要があるものがあるので、注意してください。

• Nginx/Apache HTTPDの設定ファイルを手で変更している場合は反映されません
  • /home/kusanagi/プロファイル/conf に移行元のファイルがあるので確認してください
• CRONなどOSに行っていた設定は反映されません
• Let's Encrypt SSL証明書を利用している場合は、移行元の自動更新を停止して、移行先で kusanagi ssl --email コマンドを実行して自動更新を有効にします。
  ただし、後述のサーバのIPアドレスを変更するまではコマンドを実行できないので注意してください。

DNSのFQDNのレコードを移行先のサーバのIPアドレスに書き換えてしまう前に、hostsファイルの書き換えやブラウザの機能を使って、新しい環境でも問題なく表示できるか確認しましょう。

PST (WEXAL) 環境の場合

PST (WEXAL) を利用している場合ですが、 kusanagi migrate コマンドは PST 環境のマイグレーションには対応しておりません。
移行先にエクスポートしたファイルをインポートしてから、対象のプロファイルに対して PST 環境を初期化します。

kusanagi migrate --import プロファイル-日付.tar.gz
pst init インポートしたプロファイル

PST の設定は初期化されますので、再度設定をお願いいたします。

KUSANAGI 9 の移行シナリオ

移行元を最新化して動作検証する

まず、移行元の環境を最新化します。

dnf update
kusanagi restart

アップデートでエラーが出なければ、移行元の環境は最新化されます。

次に、KUSANAGI 9 で利用するミドルウェアとバージョンを合わせます。

PHP

この記事を記載時点（2024/5/17）で KUSANAGI 9 が対応している PHP のバージョンは 7.4 / 8.0 / 8.1 / 8.2 / 8.3 になります。
もし、移行元環境が 7.4 より前のバージョンを使用している場合は、 7.4 以上のバージョンに上げてください。

• 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 php83

しかし、 PHP 7.4 は 2022/11/28 で、PHP 8.0 は 2023/11/26 で EOL となっていますので、PHP 8 系のアップデートができない、違うバージョンでの検証ができないなどの事情がない限り、 PHP 8.1 以上に上げるのが望ましいです。

MariaDB

この記事を記載時点（2024/5/17）で KUSANAGI 9 が対応している MariaDB のバージョンは 10.5 / 10.6 / 10.11 になります。
もし、移行元環境が MariaDB 10.5 より前のバージョンを使用している場合は、 10.5 以上のバージョンに上げてください。

• 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.11

なお、 KUSANAGI 9 では MariaDB 10.3 / 10.4 にも対応していますが、以下の理由により省いております。

• MariaDB 10.3 は 2023/5/25 で既に EOL となっており、リポジトリからも削除されている。
• MariaDB 10.4 は 2024/6/18 で EOL となる。
• MariaDB 10.3 / 10.4 とも AlmaLinux OS 9 / CentOS Stream 9 に対応していない。

PHP および MariaDB のバージョンを変更した状態で、移行元環境が正常に動作するかを、まず確認してください。

移行元からエクスポートする

kusanagi migrate コマンドはプロファイル (/home/kusanagi/プロファイル) 配下の全てのディレクトリとファイルをエクスポートします。
作業用のディレクトリや過去のバックアップなど、移行が不要なディレクトリや ファイルが存在する場合は、プロファイルとは別のディレクトリに移動しておくと、 エクスポートするファイルのサイズを小さくできます。
同様に過去のログファイルも移行が不要であれば、移動しておくとよいです。

全ての準備が整ったら、移行元のサイトはメンテナンス中などに 切り替えておくのがよいでしょう。
エクスポートした後に変更や更新されたデータは、再度エクスポートしない限り反映することができません。

kusanagi migrate --export プロファイル

コマンドが正常に終了すれば、/home/kusanagi配下に プロファイル-日付.tar.gz という ファイルが作成されています。
このファイルをFTPなどを利用して、移行先の環境へ持っていってください。

PST (WEXAL) 環境の場合

PST (WEXAL) を利用している場合ですが、 kusanagi migrate コマンドは PST 環境のマイグレーションには対応しておりません。
そのため、まず移行元からエクスポートする前に PST 環境を削除し、その後エクスポートする必要があります。

pst remove プロファイル
kusanagi migrate --export プロファイル

移行先にインポートする

移行先の環境では kusanagi init コマンドまで済ませておきましょう。

dnf update
kusanagi init --passwd kusanagiユーザのパスワード --nophrase --dbrootpass DBのrootパスワード --php81 --mariadb10.5

上記のコマンドは PHP のバージョンは 8.1 、 MariaDB のバージョンは 10.5 、 Web サーバーは Nginx になります。
PHP のバージョンを変えたい場合は、 --php81 をそれぞれ以下のように変えてください。

• PHP 7.4 : --php74
• PHP 8.0 : --php80
• PHP 8.2 : --php82
• PHP 8.3 : --php82

MariaDB のバージョンを変えたい場合は、 --mariadb10.5 をそれぞれ以下のように変えてください。

• MariaDB 10.6 : --mariadb10.6
• MariaDB 10.11 : --mariadb10.11

Webサーバーを Nginx ではなく、 Apache HTTPD を使用したい場合は、 --httpd24 オプションを付けてください。

PHP のバージョンや MariaDB のバージョン、Web サーバーの指定は、 init した後から kusanagi コマンドで変更することもできます。

• 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 httpd

KUSANAGIの初期設定が完了したら、kusanagi migrate コマンドでインポートします。

kusanagi migrate --import プロファイル-日付.tar.gz

コマンドが正常に終了すれば、 /home/kusanagi/プロファイル 配下に移行が完了します。

なお、いくつか手動で対応する必要があるものがあるので、注意してください。

• Nginx/Apache HTTPDの設定ファイルを手で変更している場合は反映されません
  • /home/kusanagi/プロファイル/conf に移行元のファイルがあるので確認してください
• CRONなどOSに行っていた設定は反映されません
• Let's Encrypt SSL証明書を利用している場合は、移行元の自動更新を停止して、移行先で kusanagi ssl --email コマンドを実行して自動更新を有効にします。
  ただし、後述のサーバのIPアドレスを変更するまではコマンドを実行できないので注意してください。

DNSのFQDNのレコードを移行先のサーバのIPアドレスに書き換えてしまう前に、hostsファイルの書き換えやブラウザの機能を使って、新しい環境でも問題なく表示できるか確認しましょう。

PST (WEXAL) 環境の場合

PST (WEXAL) を利用している場合ですが、 kusanagi migrate コマンドは PST 環境のマイグレーションには対応しておりません。
移行先にエクスポートしたファイルをインポートしてから、対象のプロファイルに対して PST 環境を初期化します。

kusanagi migrate --import プロファイル-日付.tar.gz
pst init インポートしたプロファイル

PST の設定は初期化されますので、再度設定をお願いいたします。

移行を完了する

最後にDNSのFQDNのレコードを移行元のサーバのIPアドレスから、移行先のサーバのIPアドレスに変更して作業は完了となります。
Let's Encrypt SSL証明書を利用している場合は、IPアドレス変更後に kusanagi ssl --email コマンドでLet's Encrypt SSL証明書を再設定することを忘れないでください。