Install the PHP microagent manually¶ The PHP microagent has two parts: a PHP extension and a Sqreen daemon. Sqreen requires both parts to secure your PHP web applications. The Sqreen PHP extension performs the PHP code instrumentation. It is a compiled extension (like the MySQL or ODBC extensions) that uses the PHP engine's API. It inspects the PHP internal state to collect signals and apply the configured plugins' actions. The Sqreen daemon for PHP provides a long-running background process. It enables the microagent to upload batches of reports to the Sqreen Platform, operate plugins, and perform asynchronous activities. Use the Sqreen installer The Sqreen installer works for most distributions. Try using the standard installation procedure before using one of the manual installation procedures below. Install on a custom PHP setup¶ Before installing the PHP microagent, begin by gathering information about your PHP application. Use the php command, or the phpinfo() function, to gather the following information about your custom setup. the PHP version (5.3, 5.4, 5.5, 5.6, 7.0, ...) the PHP binary extensions directory PHP's use of ZTS (Zend Thread Safety) the PHP configuration directory For example: $ php -i | grep 'PHP Version' PHP Version => 5.6.30 $ php -i | grep extension_dir extension_dir => /usr/local/Cellar/php56/5.6.30_6/lib/php/extensions/no-debug-non-zts-20131226 => /usr/local/Cellar/php56/5.6.30_6/lib/php/extensions/no-debug-non-zts-20131226 $ php -i | grep 'additional .ini files' Scan this dir for additional .ini files => /usr/local/etc/php/5.6/conf.d $ php -i | grep ZTS # If nothing is returned, then ZTS is not enabled Setting name Returned value Configuration value to use PHP version PHP Version => 5.6.30 5.6 PHP binary extensions directory extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20131226 => /usr/lib/php/extensions/no-debug-non-zts-20131226 /usr/lib/php/extensions/no-debug-non-zts-20131226 ZTS nothing! ZTS is not enabled. PHP configuration directory Scan this dir for additional .ini files => /usr/local/etc/php/5.6/conf.d /usr/local/etc/php/5.6/conf.d If have not already done so, sign up to create your Sqreen account. Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token. Retrieve the Sqreen extension files using one of the following methods: download it manually use the following commands to download and extract the agent files: curl https://download.sqreen.io/php/sqreen-php-extension/linux/sqreen-php-extension-latest-linux.tar.gz -o sqreen-php-extension.tar.gz tar xf sqreen-php-extension.tar.gz Add the binary extension to the PHP binary extensions directory using one of the following methods: if your PHP installation uses ZTS, use the following command: cp /usr/lib/sqreen/extensions/{PHP_VERSION}-zts/sqreen.so {PHP_BINARY_EXTENSION_DIR} if your PHP installation does not use ZTS, copy the binary extension to the PHP binary extensions directory: cp /usr/lib/sqreen/extensions/{PHP_VERSION}/sqreen.so /{PHP_BINARY_EXTENSION_DIR} Copy the sample configuration sqreen.ini file to the correct location: cp /usr/lib/sqreen/conf/sqreen.ini {PHP_CONFIG_DIR} Edit the sqreen.ini file to set your Sqreen token. sqreen.token = 'your token value' Set the priority so that Sqreen loads after other extensions, such as database drivers. Set the value to 50, then adjust according to the needs of your custom setup. priority = 50 Uninstall the microagent¶ To uninstall the Sqreen microagent, remove the PHP extension and the daemon from your application. Install on Debian or Ubuntu¶ If you have not already done so, sign up to create your Sqreen account. Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token. Add the repository for Sqreen Debian packages. sudo apt-get update sudo apt-get install debian-archive-keyring Install the apt-transport-https package to allow apt to fetch packages over https. sudo apt-get install -y curl gnupg apt-transport-https Install the GPG key that the system will use to sign repository metadata. curl -L https://packagecloud.io/sqreen/sqreen-public/gpgkey | sudo apt-key add - Create a file named /etc/apt/sources.list.d/sqreen_sqreen-public.list. Use the following commands to output the necessary repository configuration into the file you created. Replace the os and dist query parameters with the Linux distribution and version strings of your system (ubuntu or debian and a version string like cosmic or stretch). echo "deb https://packagecloud.io/sqreen/sqreen-public/ubuntu/ trusty main" > /etc/apt/sources.list.d/sqreen_sqreen-public.list echo "deb-src https://packagecloud.io/sqreen/sqreen-public/ubuntu/ trusty main" > /etc/apt/sources.list.d/sqreen_sqreen-public.list Update the package cache. sudo apt-get update Install the daemon sqreen-agent and the PHP extension sqreen-php-extension. sudo apt-get install sqreen-agent sqreen-php-extension Set your application name and Sqreen token. sudo /usr/bin/sqreen-installer config {YOUR_TOKEN_HERE} {YOUR_APPLICATION_NAME} # Alternatively, use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables: sudo /usr/bin/sqreen-installer config '${SQREEN_TOKEN}' '${SQREEN_APP_NAME}' Restart your web application server. Visit your website or query your server to complete the installation. Uninstall the microagent¶ To uninstall the Sqreen agent, use the following command to remove the packages. sudo apt-get remove sqreen-agent sqreen-php-extension Install on Red Hat or CentOS¶ If have not already done so, sign up to create your Sqreen account. Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token. To manually add the Sqreen yum repository, install pygpgme and yum-utils. This enables yum to handle GPG signatures, and installs tools to install source-based RPMs. sudo yum install pygpgme yum-utils Create a read token and output the necessary repository configuration. Replace UNIQUE_ID with a unique identifier of your choice for your system. UNIQUE_ID=`hostname -f` && curl "https://8dc0b36f0ea6f2f21b721765e10a7e02768cd1825b4551f4:@packagecloud.io/install/repositories/sqreen/sqreen/config_file.repo?os=el&dist=7&name=${UNIQUE_ID}" > /etc/yum.repos.d/sqreen_sqreen.repo Update the package cache. sudo yum -q makecache -y --disablerepo='*' --enablerepo='sqreen_sqreen' Install the sqreen-agent daemon and the PHP extension sqreen-php-extension. sudo yum install sqreen-agent sqreen-php-extension Set your application name and Sqreen token. sudo /usr/bin/sqreen-installer config {YOUR_TOKEN_HERE} {YOUR_APPLICATION_NAME} # Alternatively, use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables: sudo /usr/bin/sqreen-installer config '${SQREEN_TOKEN}' '${SQREEN_APP_NAME}' Restart your web application server. Visit your website or query your server to complete the installation. Uninstall the microagent¶ To uninstall the Sqreen agent, use the following command to remove the packages. sudo yum erase sqreen-agent sqreen-php-extension Install on Alpine Linux¶ If have not already done so, sign up to create your Sqreen account. Fetch your organization token. From the Sqreen Dashboard, access Account Settings > Environments & Tokens. Your token begins with env_org_. Take note of the token. Download and extract the apk packages. curl https://download.sqreen.com/php/sqreen-php-extension/alpine/sqreen-php-extension-latest-alpine.tar.gz -o sqreen-php-extension.tar.gz tar xf sqreen-php-extension.tar.gz Install the apk package that matches the version of PHP that your app uses. apk add --no-cache --allow-untrusted <PHP version>/sq-ext-alpine-*.apk If you use a Dockerfile, use the Dockerfile snippet: ENV PHP_VERSION 7.2 RUN mkdir /tmp/sqreen-apk ADD https://download.sqreen.com/php/sqreen-php-extension/alpine/sqreen-php-extension-latest-alpine.tar.gz /tmp/sqreen-apk RUN cd /tmp/sqreen-apk && \ tar -xzvf sqreen-php-extension-latest-alpine.tar.gz && \ apk add --no-cache --allow-untrusted ${PHP_VERSION}/sq-ext-alpine-*.apk && \ rm -r /tmp/sqreen-apk Install the Sqreen daemon. Sqreen does not provide packages for the sqreen-agent on Alpine Linux. Instead, run it within a dedicated container. (Read more about the PHP microagent Docker image.) docker run sqreen/php-agent Use your app's PHP version number to set up the correct version of the PHP extension. In the example below, the PHP version is 7.2. $ php -v PHP 7.2.0 (cli) (built: Dec 1 2017 01:02:32) ( NTS ) Copyright (c) 1997-2017 The PHP Group Zend Engine v3.2.0, Copyright (c) 1998-2017 Zend Technologies Retrieve the path where PHP expects the configuration files. $ php -i |grep -w ini Configuration File (php.ini) Path => /usr/local/etc/php Scan this dir for additional .ini files => /usr/local/etc/php/conf.d Using the path information you retrieved, place the conf.d files in the correct directory. The example in the preceding step indicates that the configuration file belongs in the /usr/local/etc/php/conf.d directory. Configure the following entries in the conf.d file. # Hardcode the token sqreen.token = 'The Sqreen token value from your dashboard' sqreen.app_name = 'The application name' # Or use the environment variable sqreen.token = ${SQREEN_TOKEN} sqreen.app_name = ${SQREEN_APP_NAME} In the conf.d file, configure the daemon address. sqreen.socket_path = 'sqreen-daemon:7773' Restart your web application server. Visit your website or query your server to complete the installation. Uninstall the microagent¶ To uninstall the Sqreen microagent, remove the PHP extension and the daemon from your application. Configure daemon startup manually¶ If you began by installing the PHP extension, the daemon starts automatically. If you prefer to have more control over the daemon process, you can install and launch the daemon manually. To prevent the PHP extension from starting the daemon, apply the following configuration variable in your sqreen.ini: sqreen.launch_daemon=0 Note that when the variable sqreen.socket_path contains a value other than localhost, the daemon does not start automatically. Install and run daemon manually¶ Download the Sqreen daemon from a static repository using one of the following methods: download it manually use the following commands: curl https://download.sqreen.com/php/sqreen-agent/linux/sqreen-agent-latest-linux.tar.gz -o sqreen-agent.tar.gz tar -xvzf sqreen-agent.tar.gz Copy the daemon binary. cp -r sqreen-agent /usr/lib/sqreen ln -sf /usr/lib/sqreen/sqreen-agent /usr/bin/sqreen-agent Run the daemon. $ /usr/bin/sqreen-agent [INFO][2017-10-17 17:23:36,620 #19.MainThread] sqreen-agent:182 sqreen-agent (1.0.2) starting up on TCP socket 0.0.0.0:7773 [INFO][2017-10-17 17:23:36,621 #19.MainThread] sqreen-agent:195 Sqreen-agent successfully started You can isolate the daemon in its own UNIX user account: useradd -rU sqreen mkdir -p -m 755 /var/log/sqreen chown sqreen:sqreen /var/log/sqreen Configure a common service manager to start the daemon¶ systemd¶ cp ./systemd/sqreen-agent.service /usr/lib/systemd/system/sqreen-agent.service systemctl enable sqreen-agent systemctl start sqreen-agent Debian or Ubuntu init.d¶ cp ./init.d/debian/sqreen-agent /etc/init.d/ chmod 755 /etc/init.d/sqreen-agent update-rc.d sqreen-agent defaults /etc/init.d/sqreen-agent start Red Hat or CentOS init.d¶ cp ./init.d/centos/sqreen-agent /etc/init.d/ chmod 755 /etc/init.d/sqreen-agent chkconfig --add sqreen-agent chkconfig sqreen-agent on /etc/init.d/sqreen-agent start Install and run the daemon using Docker¶ Use the Sqreen Docker image to install and run the daemon docker run sqreen/php-agent