速さの理由を知る。安全の仕組みを知る。WordPress運用の「なぜ？」を解く技術コラム。

KUSANAGIの設定ファイルのカスタマイズ (PHP編)

石川英典
技術解説
KUSANAGI
OSSPHPLinuxKUSANAGI
This entry is in the series KUSANAGI開発メンバーの課題解決手法

GMOプライム・ストラテジー「KUSANAGI」開発チームの石川です。

KUSANAGIでは、ほとんどの設定をKUSANAGIコマンドを使用して行うように設計されています。そのため、KUSANAGIコマンドを使用して環境の構築を行っていれば設定ファイルを直接編集することはほぼありませんが、様々な事情で設定をカスタマイズしたい場合があると思います。

これまでの KUSANAGIの設定ファイルのカスタマイズ (Nginx編) と KUSANAGIの設定ファイルのカスタマイズ (Apache HTTP Server編) に続いて、今回は「設定ファイルのカスタマイズ (PHP編)」として、PHPの設定ファイルをカスタマイズする方法を解説します。

設定ファイルのパス

KUSANAGIでは複数のミドルウェアを使用しています。しかし、標準のAlmaLinux OSのRPMではなく、KUSANAGI開発元のGMOプライム・ストラテジーが提供しているRPMパッケージがあります。PHPもそのようなパッケージの1つです。

GMOプライム・ストラテジーで提供しているパッケージでは、AlmaLinux OSのRPMパッケージと競合 (conflict) しないように、標準とは異なるパスにインストールしています。そのため、設定ファイルのパスが標準とは異なっています。

KUSANAGIではPHPの設定ファイルは /etc/opt/kusanagi/php.d 以下にあります。これをPHPの設定ファイルのディレクトリと呼びます。また、利用するモジュールをロードする extension を定義した設定ファイルは /etc/opt/kusanagi/php.d/extensions 以下にあります。

KUSANAGIではphp-fpmを利用して、NginxやApache HTTP ServerからPHPを実行しています。このphp-fpmの設定ファイルが /etc/opt/kusanagi/php-fpm.d 以下にあります。これをphp-fpmの設定ファイルのディレクトリと呼びます。

なお、KUSANAGI Security EditionではKUSANAGI Free Edition, Business Edition, Premium Editionとはパスが異なります。KUSANAGI Security Editionではミドルウェアの複数のバージョンを組み合わせて運用できるようするために、バージョンごとにパスを変えているためです。KUSANAGI Security Editionにおけるパスについては「ミドルウェアの設定ファイル・ログファイルのパス」を合わせて参照してください。

KUSANAGIのPHPのモジュール構成

PHPには標準の組み込みモジュールに加えて、必要に応じて追加できるPECL拡張モジュールがあります。KUSANAGIではWordPressに代表されるCMSの動作に必要なモジュールをデフォルトで提供しています。

  • 標準モジュール
    • bcmath
    • bz2
    • calendar
    • Core
    • ctype
    • curl
    • date
    • dom
    • exif
    • FFI
    • fileinfo
    • filter
    • ftp
    • gd
    • gettext
    • gmp
    • hash
    • iconv
    • imap
    • intl
    • json
    • ldap
    • libxml
    • mbstring
    • mysqli
    • mysqlnd
    • openssl
    • pcntl
    • pcre
    • PDO
    • pdo_mysql
    • pdo_pgsql
    • pdo_sqlite
    • pgsql
    • Phar
    • posix
    • random
    • readline
    • Reflection
    • session
    • SimpleXML
    • soap
    • sockets
    • SPL
    • sqlite3
    • standard
    • sysvsem
    • sysvshm
    • tidy
    • tokenizer
    • xml
    • xmlreader
    • xmlwriter
    • xsl
    • Zend OPcache
    • zip
    • zlib
  • PECL拡張モジュール
    • apcu
    • imagick
    • msgpack
    • redis
    • sodium
    • ssh2
    • xmlrpc
    • yaml

デフォルトで読み込まれるモジュールについては以下のコマンドで確認できます。

# /opt/kusanagi/php/bin/php -m
または (X.Yはバージョン)
# /opt/kusanagi/php-X.Y/bin/php -m

利用できるPECL拡張モジュールは以下に配置されています。

/opt/kusanagi/php/lib64/extensions
または (X.Yはバージョン)
/opt/kusanagi/php-X.Y/lib64/extensions

PHPのバージョン、および、KUSANAGIでリンクしているライブラリとそのバージョンの違いから、AlmaLinux OSやEPEL等の他のRPMで配布されているモジュールを利用することはできません。PECL拡張モジュールを追加する方法については、後半で説明します。

KUSANAGIの設定ファイルの構成

php.ini

一般的にPHPの共通設定は php.ini に記載します。 php.ini はPHPの設定ファイルのディレクトリにあります。KUSANAGIにも php.ini はありますが、KUSANAGIコマンドで設定を行えるように、直接 php.ini を編集しないように設計されています。

PHPでは php.ini に加えて、追加の設定ファイルを読み込むスキャンディレクトリがあります。KUSANAGIのスキャンディレクトリは利用するモジュールを定義した設定ファイルがある /etc/opt/kusanagi/php.d/extensions です。このスキャンディレクトリを活用して、編集できる 他の設定ファイル を読み込むようにしています。

ファイル名備考
/etc/opt/kusanagi/php.d/php.ini編集しない
/etc/opt/kusanagi/php.d/extensions/*.iniファイルがあれば読み込む

これにより extensions (ロードするモジュールの設定ファイルのディレクトリ) の *.ini を読み込みます。この仕組みを利用して、後述するモジュールの設定ファイルを読み込んでいます。

php-fpm.conf

php-fpmの共通設定は php-fpm.conf に記載します。php-fpm.conf は /etc/opt/kusanagi にあります。php.ini と同様に、KUSANAGIコマンドで設定を行えるように、直接 php-fpm.conf を編集しないように設計されています。

php-fpmでは他の設定ファイルを読み込む include というディレクティブがあります。KUSANAGIはこのディレクティブを活用して、編集しない php-fpm.conf から編集できる 他の設定ファイル を読み込むようにしています。

ファイル名抜粋備考
php-fpm.confinclude=/etc/opt/kusanagi/php-fpm.d/*.confphp-fpm.d/*.conf を読み込む

これにより php-fpm.d の *.conf を読み込みます。この仕組みを利用して、デフォルトの設定を記述した設定ファイルを読み込んでいます。

カスタマイズできない設定ファイル

php.ini、php-fpm.conf、および、利用するモジュールを定義した設定ファイルには、RPMパッケージの更新によって上書きされるものがあります。そのため、これらの設定ファイルはカスタマイズできません。

以下はその一例です。なお、デフォルトで使用されないファイルは除いています。(全て /etc/opt/kusanagi からの相対パスです)

ファイル名
php.d/extensions/10-opcache.ini
php.d/extensions/20-ffi.ini
php.d/extensions/40-apcu.ini
php.d/extensions/50-imagick.ini
php.d/extensions/50-intl.ini
php.d/extensions/50-redis.ini
php.d/extensions/50-sodium.ini
php.d/extensions/50-ssh2.ini
php.d/extensions/50-xmlrpc.ini
php.d/extensions/50-yaml.ini
php.d/extensions/openssl.ini
php-fpm.d/www.conf

カスタマイズの指針

KUSANAGIの設定ファイルの構成と、カスタマイズできない設定ファイルから、具体的にどのようにカスタマイズを行えばよいかを説明します。

なお、NginxやApache HTTP Serverの設定ファイルと異なり、kusanagiコマンドで行えるカスタマイズはありません。

PHPに設定する場合

PHPで有効にしたい設定がある場合には、 /etc/opt/kusanagi/php.d/extensions 以下に既存のファイル名と被らない設定ファイルを作成し、 スキャンディレクトリにより自動的に読み込ませる方法を推奨します。

また、php.ini や既に存在するファイル (例えば 10-opcache.ini ) で定義されている設定を変更したい場合には、後から読み込まれるようにする必要があります。PHPのスキャンディレクトリはアルファベット順で設定ファイルを読み込むため、 z (ゼット) で始まる設定ファイル (例えば z-opcahce.ini ) を作成することで、既存の 10-opcahce.ini よりも後に読み込むことができます。

ここで有効にした設定は、phpコマンドから実行する場合と、php-fpmから実行する場合の両方で有効になります。

例えば php.ini で定義されている max_execution_time を 300 に伸ばしたい場合には、以下のような内容で php.d/extensions/max_execution_time.ini を作成します。

[PHP]
max_execution_time = 300

また、ディレクティブによっては、PHPのスクリプト中に ini_set() を使用して設定できる場合もあります。 memory_limit のように、スクリプトで個別に設定したい場合は ini_set() を使用するのもよいでしょう。

なお、 PHPではApche HTTP Serverを使用している場合には .htaccess や httpd.confによる設定方法がありますが、KUSANAGIは mod_php を利用していないため、この方法ではカスタマイズできません。

php-fpmに設定する場合

php-fpmで有効にしたい設定がある場合には、 /etc/opt/kusanagi/php-fpm.d 以下に既存のファイル名と被らない設定ファイルを作成し、 include により自動的に読み込ませる方法を推奨します。

また、php-fpm.conf や既に存在するファイル (例えば www.conf ) で定義されている設定を変更したい場合には、後から読み込まれるようにする必要があります。PHPのスキャンディレクトリはアルファベット順で設定ファイルを読み込むため、 z (ゼット) で始まる設定ファイル (例えば z-www.conf ) を作成することで、既存の www.conf よりも後に読み込むことができます。

例えば php-fpm.d/www.conf で定義されている pm.max_spare_servers を 30 に伸ばしたい場合には、以下のような内容で php-fpm.d/z_max_spare_servers.conf を作成します。

[www]
pm.max_spare_servers = 30

利用するモジュールを追加する場合

KUSANAGIではデフォルトで有効にしていないモジュールを利用したい場合は、 phpize コマンドによりPECL拡張モジュールをコンパイルして、/etc/opt/kusanagi/php.d/extensions 以下に既存のファイル名と被らない設定ファイルを作成し、スキャンディレクトリにより自動的に読み込ませる方法を推奨します。

phpizeコマンドは標準ではインストールされません。使用するにはRPMパッケージをインストールする必要があります。まず、現在使用しているPHPのバージョンを確認してください。以下の例では PHP 8.3 ということが分かります。

# /opt/kusanagi/php/bin/php -v
PHP 8.3.30 (cli) (built: Jan 21 2026 08:24:38) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.30, Copyright (c) Zend Technologies
    with Zend OPcache v8.3.30, Copyright (c), by Zend Technologies

dnf コマンドを使用して、 kusanagi-phpXX-devel (XXはバージョン) をインストールします。PHP 8.3 の場合は kusanagi-php83-devel となります。

# dnf install kusanagi-php83-devel

以下のパスに phpize がインストールされます。

# /opt/kusanagi/php/bin/phpize
または (X.Yはバージョン)
# /opt/kusanagi/php-X.Y/bin/phpize

phpize コマンドを利用してPECL拡張モジュールをビルドする方法については PHPの公式ドキュメント を参照してください。また、phpize コマンドを利用してビルドしたPECL拡張モジュールはPHPのバージョンに固有のものとなります。PHPのマイナーバージョンが変わる場合 (例えば 8.3から8.4に上げる) には、ビルドの再実行が必要になりますので、注意してください。

カスタマイズできない設定ファイルを変更する場合

どうしてもRPMパッケージが提供しているカスタマイズできない設定ファイルを変更する場合は、次の点に気を付けてください。

  • 変更が巻き戻る可能性があることを認識して、変更したファイルもバックアップしておく。
  • dnf upgrade等でアップデートを行った後は設定ファイルを確認し、必要に応じて変更を再度反映する。

カスタマイズの確認と反映

設定ファイルのテスト

設定ファイルに加えた変更をテストするには以下のコマンドを使用します。

# kusanagi php --test

設定ファイルの反映

設定ファイルに加えた変更を反映するには以下のコマンドを使用します。なお、--reloadを指定した場合には同時にテストも行います。この際にテストがエラーとなった場合にはリロードは行いません。

# kusanagi php --reload

KUSANAGI Security Editionでの注意事項

KUSANAGI Security EditionではWebサーバ構成で実行しているPHPのバージョンによって参照する設定ファイルが変わります。使用しているバージョンとカスタマイズ先のディレクトリを確認するようにしてください。

参考

KUSANAGIの設定ファイルのカスタマイズ (Apache HTTP Server編)

by 石川英典

Webサイト運用の課題解決事例100選 プレゼント

Webサイト運用の課題を弊社プロダクトで解決したお客様にインタビュー取材を行い、100の事例を108ページに及ぶ事例集としてまとめました。

・100事例のWebサイト運用の課題と解決手法、解決後の直接、間接的効果がわかる

・情報通信、 IT、金融、メディア、官公庁、学校などの業種ごとに事例を確認できる

・特集では１社の事例を3ページに渡り背景からシステム構成まで詳解

Webサイト運用 課題解決事例100選 プレゼント