1Installation 2============ 3 4Snuffleupagus is tested against `various PHP 7+ versions <https://travis-ci.org/jvoisin/snuffleupagus/>`_. 5 6Manual installation 7------------------- 8 9Depending on the system, we might already offer binary packages. 10You can check our :doc:`download`. In that case you only need to activate 11the extension inside your ``php.ini`` and to configure it. 12 13Requirements 14^^^^^^^^^^^^ 15 16The only dependency (at least on Debian) to compile Snuffleupagus is 17`php7.0-dev <https://packages.debian.org/search?keywords=php7.0-dev>`_ or onwards. 18 19Quickstart 20^^^^^^^^^^ 21 22:: 23 24 git clone https://github.com/jvoisin/snuffleupagus 25 cd snuffleupagus/src 26 phpize 27 ./configure --enable-snuffleupagus 28 make 29 make install 30 31This should install the ``snuffleupagus.so`` file in your extension directory. 32The final step is adding an extension loading directive, and to specify the 33location of the :doc:`configuration file <config>`, either in a 34``conf.d/20-snuffleupagus.ini`` file, or directly in you ``php.ini`` if you 35prefer: 36 37:: 38 39 extension=snuffleupagus.so 40 41 # This is only an example, 42 # you can place your rules wherever you want. 43 sp.configuration_file=/etc/php/conf.d/snuffleupagus.rules 44 45 46Be careful, on some distribution, there are separate configurations for 47cli/fmp/cgi/… be sure to edit the right one. 48 49If you're using `Gentoo <https://gentoo.org>`__, you might encounter the 50following error: 51 52:: 53 54 $ make 55 $ /bin/sh /root/snuffleupagus-0.5.0/src/libtool --mode=compile cc -I. -I/root/snuffleupagus-0.5.0/src -DPHP_ATOM_INC -I/root/snuffleupagus-0.5.0/src/include -I/root/snuffleupagus-0.5.0/src/main -I/root/snuffleupagus-0.5.0/src -I/usr/lib64/php7.3/include/php -I/usr/lib64/php7.3/include/php/main -I/usr/lib64/php7.3/include/php/TSRM -I/usr/lib64/php7.3/include/php/Zend -I/usr/lib64/php7.3/include/php/ext -I/usr/lib64/php7.3/include/php/ext/date/lib -DHAVE_CONFIG_H -g -O2 -Wall -Wextra -Wno-unused-parameter -Wformat=2 -Wformat-security -D_FORTIFY_SOURCE=2 -fstack-protector -c /root/snuffleupagus-0.5.0/src/snuffleupagus.c -o snuffleupagus.lo 56 libtool: Version mismatch error. This is libtool 2.4.6, but the 57 libtool: definition of this LT_INIT comes from an older release. 58 libtool: You should recreate aclocal.m4 with macros from libtool 2.4.6 59 libtool: and run autoconf again. 60 make: *** [Makefile:193: snuffleupagus.lo] Error 63 61 $ 62 63This is a `documented php bug <https://bugs.php.net/bug.php?id=58979>`__, 64solvable via: 65 66 67:: 68 69 rm -f aclocal.m4 70 phpize 71 aclocal && libtoolize --force && autoreconf 72 ./configure --enable-snuffleupagus 73 make 74 75 76Heroku installation 77------------------- 78 79Heroku's official `buildpack <https://github.com/heroku/heroku-buildpack-php/>`_ 80uses ``Composer`` to install all dependencies required by your PHP application. 81Careful with the `default set of rules 82<https://github.com/jvoisin/snuffleupagus/blob/master/config/default.rules>`__, 83since it might block the composer deployment, leading to the following errors: 84 85:: 86 87 heroku[web.1]: Starting process with command `vendor/bin/heroku-php-apache2 -F fpm_custom.conf public/` 88 heroku[web.1]: Stopping all processes with SIGTERM 89 app[web.1]: Stopping httpd... 90 app[web.1]: SIGTERM received, attempting graceful shutdown... 91 app[web.1]: Stopping php-fpm... 92 app[web.1]: Shutdown complete. 93 heroku[web.1]: Process exited with status 143 94 app[web.1]: [heroku-exec] Starting 95 app[web.1]: Unable to determine Composer vendor-dir setting; is 'composer' executable on path or 'composer.phar' in current working directory? 96 heroku[web.1]: Process exited with status 1 97 heroku[web.1]: State changed from starting to crashed 98 99Requirements 100^^^^^^^^^^^^ 101 102To install snuffleupagus on heroku, simply follow the `documentation <https://devcenter.heroku.com/articles/php-support#custom-compile-step>`_, 103and edit the ``composer.json`` file, as well as the ``Procfile`` to load the additional PHP-FPM configuration. 104 105composer.json 106""""""""""""" 107 108:: 109 110 { 111 "require": { 112 "php": "~7.4.6" 113 }, 114 "config": { 115 "platform": { 116 "php": "7.4.6" 117 } 118 }, 119 "scripts": { 120 "compile": [ 121 "git clone https://github.com/jvoisin/snuffleupagus /tmp/snuffleupagus", 122 "cd /tmp/snuffleupagus/src && phpize && ./configure --enable-snuffleupagus && make && make install", 123 "echo 'extension=snuffleupagus.so\nsp.allow_broken_configuration=on\nsp.configuration_file=/dev/null' > /app/.heroku/php/etc/php/conf.d/999-ext-snuffleupagus.ini" 124 ] 125 } 126 } 127 128This configuration will compile Snuffleupagus to shared library, install it to the proper 129location and specify an empty configuration in ``sp.configuration_file`` to ensure 130that the ``composer`` deployment phase won't get killed by some rules. 131 132PHP-FPM 133""""""" 134 135:: 136 137 ; ext-snuffleupagus 138 php_admin_flag[sp.allow_broken_configuration] = off 139 php_admin_value[sp.configuration_file] = /app/default.rules 140 141The final step is to point ``sp.configuration_file`` to a rule set by setting 142the preference in an additional `PHP-FPM 143configuration <https://devcenter.heroku.com/articles/custom-php-settings#php-fpm-configuration-include>`_. 144 145You should now be running Snuffleupagus in PHP on heroku: 146 147:: 148 149 app[web.1]: [05-Jul-2020 07:45:22 UTC] PHP Fatal error: [snuffleupagus][0.0.0.0][disabled_function] Aborted execution on call of the function 'exec', because its argument '$command' content (id;whoami) matched a rule in /app/public/test2.php on line 1 150 app[web.1]: 10.9.226.141 - - [05/Jul/2020:07:45:22 +0000] "GET /test2.php?cmd=id;whoami HTTP/1.1" 500 - "-" "curl/7.68.0 151 heroku[router]: at=info method=GET path="/test2.php?cmd=id;whoami" host=heroku-x-snuffleupagus.herokuapp.com request_id=012345678-9012-3456-7890-123456789012 fwd="1.2.3.4" dyno=web.1 connect=0ms service=7ms status=500 bytes=169 protocol=http 152 153 154Upgrading 155--------- 156 157Upgrading Snuffleupagus is as simple as recompiling it (or using a binary), replacing the file and restarting your webserver. 158