DEBOPS.PHP(5)

NAME
debops.php - Manage PHP5/PHP7 environment using Ansible

SYNOPSIS

debops service/php [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.php role can be used to manage PHP Hypertext Preprocessor environment on a Debian/Ubuntu host. The role supports different PHP versions available in OS distributions (PHP5, PHP7) with PHP-FPM service and multiple PHP-FPM pools. Other Ansible roles can use it as a role dependency to offload PHP management for their own use.

GETTING STARTED

  Support for different PHP versions

The debops.php role supports management of multiple PHP versions; only one PHP version can be managed at a time. By default the role will install and configure the PHP version provided with the current OS release.

The role checks for existence of php7.3, php and php5.6 APT packages (by default in that order) and based on available versions installs either php7.3-*, the version preferred by the php package or php5.6-* APT packages. If multiple versions of the PHP packages are available, the first found one wins. To force an older version in case the newer one is installed, you can change the order of the packages used for the version detection using the php__version_preference list.

To learn how to specify different PHP packages for installation, refer to php__packages documentation.

  PHP packages provided by Ondřej Surý

Ondřej Surý <https://qa.debian.org/developer.php?login=ondrej%40debian.org> is a member of the Debian PHP Maintainers team and maintains Debian PHP5 <https://packages.qa.debian.org/p/php5.html> and PHP7 <https://packages.qa.debian.org/p/php7.0.html> packages. He also provides an external APT package repository <https://deb.sury.org/> of PHP5 and PHP7 packages (among other things) for Debian and Ubuntu distributions.

The debops.php role can use the packages from the Ondřej Surý repositories to provide PHP7 packages on Debian Jessie. Remember that these packages DO NOT fall under the Debian Stable security support and may contain bugs.

To enable the custom APT repository, add in the Ansible inventory:

php__sury: True

This will add the required OpenPGP keys and APT repositories. The order of the package versions should ensure that the PHP7 packages will be installed on Debian Jessie.

  Custom environment role

The debops.php provides a small, custom role debops.php/env which should be added to the playbook or role dependencies before the main role and other roles that use configuration from debops.php, like debops.logrotate. The debops.php/env role configures custom APT repositories if they are enabled and prepares the facts needed by other roles to function correctly. See the provided playbook to see an example usage.

  PHP Composer installation

The debops.php role will install the PHP Composer <https://getcomposer.org/>, a dependency manager for PHP. The version from the OS repositories will be preferred. On older OS releases (including Debian Stretch), a known upstream binary will be downloaded and installed instead.

  Layout of the php.ini configuration

The main /etc/php5,/7.0/*/php.ini files maintained by the OS distribution are not modified by the debops.php role to allow an easy upgrade process. Instead, a custom php.ini configuration is stored in /etc/php5,/7.0/ansible/*.ini files generated using a simple template, which are then linked to each of the PHP SAPI directories in /etc/php5,/7.0/*/conf.d/ which are read by the PHP interpreters. This allows for configuration synchronization between different PHP interpreters. To learn more about this process refer to php__configuration documentation.

  Information stored in Ansible local facts

The PHP version configured on a host is available for other Ansible roles through the Ansible local facts. The specific variables are:

ansible_local.php.version
    Short version of the PHP environment, used in package names. Either 5 or 7.0.

ansible_local.php.long_version
    Longer version of the PHP environment, used for version comparison. For example, 5.6.22 or 7.0.8. This variable might be inaccurate in case of the minor or major version upgrade.

    The Ansible local facts are used by the debops.php role to ensure idempotent operation. In case that you want to upgrade a host to a newer PHP release without uninstalling the older one, you can set php__reset to True, so that the role can re-detect the available PHP versions. After one role run, you should set php__reset back to its default value.

  Example inventory

To enable management of a PHP environment on a host, you need to include that host in the [debops_service_php] Ansible inventory group:

[debops_service_php]
hostname

The default configuration included in the role will install the base PHP cli and fpm packages and create a PHP-FPM pool meant to be used by the www-data user which is a common user account used to serve PHP applications packaged on Debian systems. To deploy your own applications you should consider creating a custom system account and a corresponding PHP-FPM pool to securely separate it from other applications. To learn how to do that, refer to the php__pools documentation.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.php role:

---
- name: Install and manage PHP environment
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_php' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Apply keyring configuration for php environment
      import_role:
        name: 'keyring'
      vars:
        keyring__dependent_apt_keys:
          - '{{ php__keyring__dependent_apt_keys }}'
      tags: [ 'role::keyring', 'skip::keyring', 'role::php' ]
    - name: Prepare php environment
      import_role:
        name: 'php'
        tasks_from: 'main_env'
      tags: [ 'role::php', 'role::php:env', 'role::logrotate' ]
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ php__apt_preferences__dependent_list }}'
    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]
    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ php__logrotate__dependent_config }}'
    - role: php
      tags: [ 'role::php', 'skip::php' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::php
    Main role tag, should be used in the playbook to execute all tasks.

role::php:config
    Generate the PHP and PHP-FPM configuration.

role::php:pools
    Generate only PHP-FPM pool configuration.

DEFAULT VARIABLE DETAILS

Some of debops.php default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  php__packages

The php__packages, php__group_packages, php__host_packages and php__dependent_packages lists can be used to install APT packages. The role automatically prepends the package names with correct prefix (php5- or php7.0-) to install packages for currently active PHP version. Because of that you should only use these lists to install PHP-related packages.

The packages with names in the form:

•   php-*

•   php5-*

•   php7.0-*

    will be detected correctly. Any other package names will have the current PHP version prepended to their name, which might result in incorrect installation requests.

  Examples

Install support for the MariaDB/MySQL and PostgreSQL databases for the current PHP version:

php__packages: [ 'mysql', 'pgsql' ]

Install support for the PEAR repository:

php__packages: [ 'php-pear' ]

  php__configuration

The management of the php.ini configuration is done using a set of YAML lists, named php__configuration, php__group_configuration and php__host_configuration. Each element of a list is a YAML dictionary with certain parameters.

The configuration is designed to allow easy creation of multiple configuration files located in /etc/php5,/7.0/ directories. By default, all files are created in the /etc/php5,/7.0/ansible/ directory with the .ini extension, and symlinked to the respective PHP SAPI configuration directories. If you need, you can create the configuration files directly in the PHP SAPI directories as well.

The role recognizes the parameters below:

filename
    Required. Name of the file to store the configuration data, for example 00-ansible. The .ini extension is added automatically at the end.

path
    Optional. Change the default path where a given configuration file should be created, relative to /etc/php5,/7.0/. By default this value is ansible/. You need to add the / character at the end of the path for the role to work correctly.

sections
    Optional. List of YAML dictionaries, each one describing a part of the given configuration file.

    The parameters below can be specified either in the main YAML dictionary, or in one of the YAML dictionaries on the sections list:

name
    Optional. An INI section name, for example PHP which will be written as [PHP] in the configuration file.

options
    A YAML text block with php.ini configuration options specified in the INI configuration file format.

comment
    Optional. A custom comment added before a specified configuration.

state
    Optional, either present or absent. If not specified or present, a given configuration file or its section will be created. If absent, a given configuration file or section will be removed.

  Examples

Create custom configuration file symlinked to all PHP SAPI directories:

php__configuration:
  - filename: '10-custom'
    name: 'PHP'
    options: |
      display_errors = On

Create custom configuration file with multiple sections directly in PHP-FPM directory:

php__host_configuration:
  - filename: '50-custom'
    path: 'fpm/conf.d/'
    sections:
      - name: 'CLI server'
        options: |
          cli_server.color = On
      - name: 'mail function'
        options: |
          SMTP = smtp.{{ ansible_domain }}
          smtp_port = 25

  php__pools

The php__pools, php__group_pools, php__host_pools and php__dependent_pools lists can be used to create PHP-FPM pools. Each list entry is a YAML dictionary with keys and values that represent options in the pool configuration file (with some additional parameters used by the role itself).

Most of the pool parameters have their corresponding default variables in the php__fpm_* namespace. To use them in the pool configuration, strip the php__fpm_ prefix from their variable name, for example:

php__fpm_access_log: True
php__pools:
  - name: 'www-data'
    access_log: False

Below are some parameters that don't have their corresponding defaults or are otherwise different:

name
    Required. Name of the PHP-FPM pool.

state
    Optional. If not specified or present, the PHP-FPM pool will be created. If specified and absent, the PHP-FPM pool will be removed.

user
    Optional. Name of the system user account which will be used to execute the given PHP-FPM pool. This account needs to exist before the pool will start correctly. If not specified, the item.name value will be used.

group
    Optional. The main group in which the PHP-FPM pool will be running in. If not specified, the item.name value will be used instead.

owner, home
    Optional. If specified, role will create an user account with specified home directory before restarting the PHP-FPM service. This permits easy creation of new PHP-FPM pools on separate user accounts. Ideally the item.owner value should be the same as item.user or item.name. It's defined separately to better control user/group creation process.

system
    Optional, boolean. If defined and True, the account and group will be created as a "system" account with UID/GID < 1000; this is the default. If False, the created user and group will have "normal" UID/GID selected.

listen
    Optional. Path to the PHP-FPM socket or IP:port on which a given pool should listen for connections. By default it's autogenerated in the format: /run/php5,7.0-fpm-{ item.name }.sock.

listen_owner
    Optional. The system user that will be the owner of the PHP-FPM socket. This should be the username of the webserver account, so that it can use the socket to communicate with the PHP-FPM process. This account needs to exist before the PHP-FPM process is started (the www-data account is created by default on Debian/Ubuntu systems). If not specified, the php__fpm_listen_owner value will be used instead.

listen_group
    Optional. The system group that will be the primary group of the PHP-FPM socket. This should be the group that the webserver belongs to, so that it can use the socket to communicate with the PHP-FPM process. This group needs to exist before the PHP-FPM process is started (the www-data group is created by default on Debian/Ubuntu systems). If not specified, the php__fpm_listen_group value will be used instead.

listen_acl_users
    Optional. Set POSIX Access Control Lists. If specified, listen_owner is ignored. The value must be a list of names.

listen_acl_groups
    Optional. Set POSIX Access Control Lists. If specified, listen_group is ignored. The value must be a list of names.

listen_mode
    Optional. The permissions applied to the PHP-FPM pool sockets. If not specified, the php__fpm_listen_mode value will be used instead.

listen_backlog
    Optional. The limit for socket connection backlog. If you tune this parameter, you should also consider sysctl parameters net.ipv4.tcp_max_syn_backlog, net.ipv4.ip_local_port_range, net.ipv4.tcp_tw_reuse and net.core.somaxconn. If not specified, the php__fpm_listen_backlog will be used instead.

environment
    Optional. A YAML dictionary with custom environment variables that should be specified in the PHP-FPM pool. Each dictionary key is a variable name and dictionary value is the variable value.

php_flags
    Optional. A YAML dictionary with custom php.ini flags that should be defined in the PHP-FPM pool. Each dictionary key is the flag name, and each dictionary value is the flag value.

php_values
    Optional. A YAML dictionary with custom php.ini values that should be defined in the PHP-FPM pool. Each dictionary key is the value name, and each dictionary value is the value contents.

php_admin_flags
    Optional. A YAML dictionary with custom php.ini admin flags that should be defined in the PHP-FPM pool. Each dictionary key is the admin flag name, and each dictionary value is the admin flag value.

php_admin_values
    Optional. A YAML dictionary with custom php.ini admin values that should be defined in the PHP-FPM pool. Each dictionary key is the admin value name, and each dictionary value is the admin value contents.

open_basedir
    Optional. String or list of paths which can be accessed by the PHP interpreter. By default not set.

pm_status
    Optional. If True, PHP-FPM status page is enabled. If not specified, the php__fpm_pm_status will be used instead.

pm_status_path
    Optional. URI path of PHP-FPM status page. If not specified, the php__fpm_pm_status_path will be used instead.

  Examples

Create a new PHP-FPM pool with custom user account:

php__host_pools:
  - name: 'custom-php-app'
    owner: 'custom-php-app'
    home: '/srv/custom-php-app'

Modify default PHP-FPM pool with custom environment variables:

php__default_pools:
  - name: 'www-data'
    environment:
      HOME: '/var/www'
      MAIL: 'root@{{ ansible_domain }}'

Remove the default PHP-FPM pool (you should have at least 1 pool configured, otherwise the PHP-FPM process manager won't start correctly):

php__default_pools:
  - name: 'www-data'
    state: 'absent'

AUTHOR
Mariano Barcia, Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others