175 lines
7.1 KiB
Text
175 lines
7.1 KiB
Text
+-----------------------------------------------------------------------
|
|
| Running ${PKGSTEM} on OpenBSD
|
|
+-----------------------------------------------------------------------
|
|
|
|
Connecting your web server software to php
|
|
==========================================
|
|
Web server programs such as httpd(8), nginx and Apache listen for
|
|
network requests and decide whether to respond themselves (as is the
|
|
case with simple "static" files) or pass the request on to other
|
|
software for handling. The web server must be configured to handle
|
|
this - different methods are used depending on the server software.
|
|
|
|
FastCGI: httpd(8), NGINX, lighttpd, etc
|
|
---------------------------------------
|
|
Most modern web servers support FastCGI which is a simple method of
|
|
interfacing to many kinds of application server. This is usually the
|
|
preferred method of passing requests to php, and is the only method
|
|
possible for many servers such as httpd(8), nginx and lighttpd.
|
|
|
|
The main OpenBSD php packages include php-fpm, FastCGI Process Manager.
|
|
This manages pools of FastCGI processes: starts/restarts them and
|
|
maintains a minimum and maximum number of spare processes as
|
|
configured. You can use rcctl(8) to enable php-fpm at boot,
|
|
and start it at runtime:
|
|
|
|
rcctl enable php${SV}_fpm
|
|
rcctl start php${SV}_fpm
|
|
|
|
php-fpm has its own configuration file, by default ${SYSCONFDIR}/php-fpm.conf.
|
|
This controls how the php processes are started. The default settings
|
|
are suitable for many standard cases, but can be changed to provide
|
|
greater control for sites handling high loads or to provide
|
|
separation between different php applications by running them
|
|
under different uids or in individual chroot(2) jails.
|
|
|
|
Your HTTP server needs to be configured to pass requests for PHP
|
|
resources to php-fpm, usually done by unix socket. See the documentation
|
|
and sample configuration. For nginx, see the "FastCGI server listening
|
|
on unix socket" example provided in ${LOCALBASE}/share/nginx/nginx.conf.
|
|
For OpenBSD base's httpd(8) you can use a configuration fragment like:
|
|
|
|
location "*.php" {
|
|
fastcgi socket "/run/php-fpm.sock"
|
|
}
|
|
|
|
If you need to run multiple versions of PHP on one machine, create
|
|
another configuration file (e.g. php-fpm-X.Y.conf) and set it to use a
|
|
different socket path. Configure rc.d(8) to pass the parameter when
|
|
starting php-fpm, for example
|
|
|
|
rcctl set phpXY_fpm flags -y /etc/php-fpm-X.Y.conf
|
|
|
|
NGINX Unit
|
|
----------
|
|
NGINX Unit (https://unit.nginx.org/) is a standalone application server,
|
|
distinct to the standard NGINX web server. It uses its own compiled module
|
|
to provide PHP support. Install the relevant package (e.g. unit-php${SV})
|
|
and follow the usual documentation for Unit.
|
|
|
|
Apache httpd
|
|
------------
|
|
For Apache, the most common option is with the mod_php Apache module
|
|
provided in the php-apache package. This is loaded directly as part of
|
|
the web server process. Configuration is fairly simple, but in this
|
|
case the operating system can't provide memory protection between
|
|
the two; therefore bugs in php can potentially do more damage.
|
|
|
|
Another option is to use FastCGI via php-fpm as in the above section;
|
|
you can use mod_proxy_fcgi to interface it with Apache.
|
|
|
|
If you wish to use the Apache module, make sure the php-apache-${PV}
|
|
package is installed, then enable it by creating a symbolic link:
|
|
|
|
# ln -sf ${MODPHP_CONFIG_PATH}/modules.sample/php-${PV}.conf \
|
|
${MODPHP_CONFIG_PATH}/modules/php.conf
|
|
|
|
To disable:
|
|
|
|
# rm -f ${MODPHP_CONFIG_PATH}/modules/php.conf
|
|
|
|
After making either of these changes, restart Apache.
|
|
|
|
php configuration
|
|
=================
|
|
The recommended php configuration has been installed to:
|
|
${SYSCONFDIR}/php-${PV}.ini.
|
|
|
|
Modify this as required for your use.
|
|
|
|
Extension modules
|
|
=================
|
|
Many language features in php are provided by extensions, which come
|
|
in several classes.
|
|
|
|
- some extensions are included in the main PHP package and are always
|
|
enabled; they don't need to be installed or enabled separately.
|
|
|
|
- opcache is in the main package but must be configured.
|
|
|
|
- some 'core' extensions with extra dependencies are packaged separately
|
|
(e.g. php-pdo_mysql, php-ldap, php-soap, and others) and can be installed
|
|
with pkg_add(1).
|
|
|
|
- various useful third-party extensions from the PECL repository have
|
|
also been packaged. Examples include pecl${SV}-memcached (for use with
|
|
sysutils/memcached), pecl${SV}-imagick (image manipulation using ImageMagick),
|
|
pecl${SV}-redis (for use with databases/redis), etc.
|
|
|
|
For all extensions packaged separately (and for opcache), you will find a
|
|
file named ${SYSCONFDIR}/php-${PV}.sample/(MODULE_NAME).ini. To enable it,
|
|
add a symlink into ${SYSCONFDIR}/php-${PV} and restart:
|
|
|
|
ln -sf ../php-${PV}.sample/MODULE_NAME.ini ${SYSCONFDIR}/php-${PV}/
|
|
|
|
To disable, remove the symlink from ${SYSCONFDIR}/php-${PV} and restart:
|
|
|
|
rm ${SYSCONFDIR}/php-${PV}/MODULE_NAME.ini
|
|
|
|
If you have installed a number of extensions and wish to enable them all,
|
|
you can use these shell commands:
|
|
|
|
# cd ${SYSCONFDIR}/php-${PV}.sample
|
|
# for i in *; do ln -sf ../php-${PV}.sample/$i ../php-${PV}/; done
|
|
|
|
After enabling or disabling extensions (or otherwise modifying php's
|
|
configuration), use rcctl(8) to restart php${SV}_fpm or Apache.
|
|
|
|
Living with chroot
|
|
==================
|
|
The chroot jail commonly used with PHP on OpenBSD means that only files
|
|
inside /var/www can be accessed, and path references should omit /var/www
|
|
prefixes.
|
|
|
|
File paths
|
|
----------
|
|
Sometimes it is hard to work with file paths in this case (for example
|
|
applications with some parts run from the web and some from the command
|
|
line); in those cases it can help to create a symlink so that /var/www
|
|
from _inside_ the chroot points to the expected locations. This can be
|
|
done with "mkdir -p /var/www/var; ln -s .. /var/www/var/www".
|
|
|
|
Socket paths for MariaDB
|
|
------------------------
|
|
See mariadb's pkg-readme file for information.
|
|
|
|
Making network connections
|
|
--------------------------
|
|
To resolve DNS host names, you will need to copy /etc/resolv.conf
|
|
into the ${CHROOT_DIR} chroot jail. To make TLS connections, you'll also
|
|
need /etc/ssl/cert.pem for CA certificates.
|
|
|
|
Additionally, if your scripts use PHP's key generation functions they
|
|
may need access to /etc/ssl/openssl.cnf.
|
|
|
|
To use these, copy the relevant files into the /var/www jail:
|
|
|
|
# mkdir -p ${CHROOT_DIR}/etc/ssl
|
|
# install -m 444 -o root -g bin /etc/resolv.conf ${CHROOT_DIR}/etc/
|
|
# install -m 444 -o root -g bin /etc/ssl/cert.pem /etc/ssl/openssl.cnf \
|
|
${CHROOT_DIR}/etc/ssl/
|
|
|
|
As these files are updated from time to time, you might like to add
|
|
the above "install" lines to /etc/rc.local.
|
|
|
|
Executing other commands
|
|
------------------------
|
|
To run commands from inside the chroot using PHP's file execution functions
|
|
(exec, passthru, popen, etc) or the old mail() function which executes
|
|
/usr/sbin/sendmail, you must either create a statically-linked binary,
|
|
or install the relevant libraries and support files inside the chroot.
|
|
Additionally you will need to provide /bin/sh inside the chroot, for
|
|
example: "cp /bin/sh /var/www/bin". Again you will want to make sure
|
|
that this is kept up to date. (In the specific case of mail, it is
|
|
normally preferred to use PHPMailer or similar, and submit the mail by
|
|
SMTP instead).
|