update to 10.2.0 (Mar 7, 2018)

1 files changed, 330 insertions, 0 deletions

diff --git a/USER-GUIDE.txt b/USER-GUIDE.txt
new file mode 100644
index 0000000..93bb3c7
--- /dev/null
+++ b/USER-GUIDE.txt
@@ -0,0 +1,330 @@
+ionCube Loader 10 User Guide

+============================

+

+This document describes the available php.ini configuration options of the

+ionCube Loader that relate to processing of PHP encoded files, and also the

+ionCube24 service. It also describes which encoded files can be run by each

+ionCube Loader.

+

+PERFORMANCE OF ENCODED FILES

+----------------------------

+

+We recommend that the encoded paths feature (see below) is used 

+with encoded files in order to maximise performance.

+

+ENCODED FILES  

+-------------

+

+INI entry: ioncube.loader.encoded_paths

+

+Purpose:   Specify the locations of encoded files

+

+  The ionCube Loader will normally examine a PHP file before processing

+  to test whether it is encoded, and will run the file itself if necessary.

+  Although this checking is very efficient, restricting which files the

+  Loader tests for being encoded may give extra performance. If set to 

+  a series of paths or files, only files in those locations are tested.

+

+  Entries should be separated by a : on Unix and ; on Windows. 

+  A path may be prefixed with + or - to add or remove that path from

+  the possible locations. + is assumed if no character is given.

+

+

+Examples: (... means ioncube.loader.encoded_paths)

+

+  * Site with a single encoded module in /var/www/html/modules/RSS

+

+... = "/var/www/html/modules/RSS"

+

+

+  * As above, with a site configuration file encoded too.

+

+... = "/var/www/html/modules/RSS:/var/www/html/config/config.php"

+

+

+  * Encoded files may be anywhere except for /var/www/html/framework

+

+... = "/:-/var/www/html/framework"

+

+

+  * Site with most modules encoded except for one

+

+... = "/var/www/html/modules:-/var/www/html/modules/plain"

+

+

+  * As above, with an encoded config file in the plain directory

+

+... = "/site/modules:-/site/modules/plain:/site/modules/plain/config.php"

+

+

+Locations:

+

+  The ioncube.loader.encoded_paths property can be set in a php.ini

+  file, in a .htaccess file (when using Apache), in a .user.ini file

+  (when using CGI PHP 5.3+) or using ini_set within a PHP script. In ini

+  files only the last value will be used for the encoded_paths property. If

+  you wish to build up the value in several lines then, for PHP 5.1+, you

+  can use the following syntax:

+

+ioncube.loader.encoded_paths = "/path1"  

+ioncube.loader.encoded_paths = ${ioncube.loader.encoded_paths}":/path2"  

+; etc...

+

+LIMITATIONS OF LOADERS AND ENCODED FILES

+----------------------------------------

+

+Encoded files can, in general, run on versions of PHP equal to

+or greater than the source language of the Encoder used to

+produce them. So a file produced by the Encoder for PHP 5.3

+can be run by the Loaders for PHP 5.3, 5.4, 5.5 and PHP 5.6. This 

+means that the Loaders are highly backwards compatible. However, there

+are the following limitations:

+

+  * The Loader for PHP 7.1 can only run files produced by the

+    Encoder for PHP 7.1 included in the version 10 Encoder.

+

+  * The Loader for PHP 7.0 can only run files produced by the

+    Encoder for PHP 5.6.

+

+  * The Loaders for PHP 5.5 and PHP 5.6 cannot run files 

+    produced by the PHP 4 Encoder.

+

+

+IONCUBE24 : real-time intrusion protection and PHP error reporting

+---------

+### (Available for Linux 32 and 64 bit x86 servers)

+

+ionCube24 (https://ioncube24.com) is an ionCube service that uses the

+ionCube Loader to provide both real-time protection against the exploit of

+website vulnerabilities and alerting of website errors.

+

+Vulnerabilities in PHP applications are common, particularly in sites using 

+Wordpress and other plugin based systems. Exploits result in website

+defacement or customer data being compromised, and ionCube24 provides a 

+uniquely powerful defense. 

+

+PHP errors can cause intermittent or even persistent blank pages or errors for

+visitors until discovered, and without active monitoring this could go

+undetected indefinitely. ionCube24 active monitoring ensures you are always

+aware of problems in your website code.

+

+ionCube24 is free to try, with the server side support built into the Linux

+Loaders as standard. With the Loader installed, ionCube24 can be activated

+at any time to give active intrusion protection and error reporting.

+

+## php.ini settings

+

+ionCube24 has a powerful real-time web interface to configure, monitor and

+manage things, and there are also settings that can be used in a php.ini

+file as summarised below.

+

+The setup process at https://ioncube24.com automatically gives the settings

+that you need to get started, but you may wish to make changes yourself

+once setup. The default values are given with each example.

+

+### Global settings

+

+INI entry: ic24.enable ; default 0

+

+Purpose: Enable or disable all ionCube24 features. 

+

+This defaults to 0 (off), and in this case no ionCube24 behaviour is

+activated.

+

+Example:

+

+  ic24.enable = 1

+

+----------

+

+INI entry: ic24.api_access_key ; provided during setup

+

+Purpose: An authentication key for adminstration requests. 

+

+  This value is provided when adding a server to ionCube24.

+

+----------

+

+INI entry: ic24.api_check_ip ; default 1

+

+Purpose: Specify whether the IP for admin requests should be validated

+

+  If set, ionCube24 refuses access to API functions unless the calling IP

+  is a known ionCube IP address. This option should be left with the

+  default setting unless web requests pass through a proxy and your site

+  appears to be accessed from the IP of the proxy instead of ionCube. Note

+  that access to API functions will still be authenticated by access key.

+

+----------

+

+INI entry: ic24.api_max_timeout ; default 7

+

+Purpose: Maximum timeout period when sending notifications to ionCube24.

+

+  The actual period is adaptive so that a brief increase in typical latency

+  will favour a timeout followed by a retry rather than a longer than usual

+  timeout.

+

+----------

+

+INI entry: ic24.home_dir ; no default

+

+Purpose: The home directory for ionCube24 related system files. 

+

+  A location outside of the web root is recommended.  It should be writable

+  by the web server during startup.

+

+Example:

+

+ic24.home_dir = /var/www/ic24_home

+

+----------

+

+INI entry: ic24.update_domains_retry_interval ; default 30

+

+Purpose: The number of seconds to wait before retrying a fetch of the set

+of domains being managed.

+

+

+### Security related settings

+

+INI entry: ic24.sec.enable ; default "auto"

+

+Purpose: Enable the intrusion protection feature of ionCube24.

+

+Accepted values:

+

+   * "auto" (default) - allow setting from the ionCube24 control panel.

+   * 1 : always enabled.

+   * 0 : disabled.

+

+----------

+

+INI entry: ic24.sec.initial_state ; default 1

+

+Purpose: The default for whether security should be enabled or

+disabled. The default is to enable protection. Any files on a protected

+domain will become blocked if they are changed, so setting this to 0 will

+avoid accidental blocking when using ionCube24 for the first time.

+Protection may be enabled and disabled using the ionCube24 control panel and

+also via the User API.

+

+Accepted values:

+

+   * 1 : protection will be active when ionCube24 initialises.

+   * 0 : protection will be disabled.

+

+----------

+

+INI entry: ic24.sec.initial_action ; default "block"

+

+Purpose: The initial setting for how new and modified files should be

+treated when about to execute. The default is to block. The action is taken

+only if protection is enabled, and the setting may be changed via the

+ionCube24 control panel.

+

+Accepted values:

+

+   * "block" : prevent execution of new or modified files

+   * "allow" : allow execution of new or modified files

+

+Note that depending on the notification settings, a notification may still

+be generated when a new or modified file is about to execute even if it is

+not blocked.

+

+----------

+

+INI entry: ic24.sec.initial_notify ; default "always"

+

+Purpose: The initial setting for whether a notification is generated the 

+first time an unacknowledged new or modified file is attempted to be

+executed. This setting can be changed via the ionCube24 control panel.

+

+Accepted values:

+

+   * "always" : always notify of a new modification 

+   * "once"   : only the first detected modification is reported

+   * "never"  : never notify of new and modified files

+

+----------

+

+INI entry: ic24.sec.exclusion_key ; provided during setup

+

+Purpose: A key that if present at the start of a file, will identify the

+file as trusted. This value is provided when adding a server to ionCube24.

+

+----------

+

+INI entry: ic24.sec.trusted_include_paths ; no default

+

+Purpose: List paths from where files can be included and automatically

+trusted.

+

+Example:

+

+ic24.sec.trusted_include_paths = "/var/cache:/var/cache2"

+

+Directories can be excluded from the list by prefixing with a minus

+character -. e.g.

+

+"/var/cache:-/var/cache/subdir"

+

+This is useful if your site creates and/or modifies files by itself from

+time to time, e.g. in a cache directory. Requests that *directly* access

+files on a trusted include path will be blocked but the file itself will

+not be blocked, so requests that use the file as intended will still work.

+See ioncube24.com for more details once signed up.  As an alternative, if

+possible we recommend producing files that include the exclusion key.

+

+----------

+

+INI entry: ic24.sec.block_uploaded_files ; default 1

+

+Purpose: If set, block any uploaded files in ionCube24 that are processed

+using the standard PHP mechanism for uploaded files. This applies even if

+the file is subsequently included and where included files being

+automatically approved with the previous setting.

+

+----------

+

+INI entry: ic24.sec.block_stdin ; default 1

+

+Purpose: Refuse code that PHP sees via stdin.  If disabled, code via

+stdin will run without security checking as there is no filepath. This

+setting should be left on as PHP would normally never receive a script via

+stdin.

+

+### PHP Error reporting settings

+

+INI entry: ic24.phperr.enable ; default "auto"

+

+Purpose: Enable reporting of PHP errors to ionCube24.  When enabled, any

+non-ignored errors are reported to ionCube24 in realtime, triggering

+alerting so errors can be investigated as necessary.

+

+Accepted values:

+

+   * "auto" (default) - allow setting from the ionCube24 control panel.

+   * 1 : always enabled.

+   * 0 : disabled.

+

+----------

+

+### Deprecated settings

+

+Deprecated settings are subject to removal in a future

+release.

+

+INI entry: ic24.phperr.ignore ; default 0

+

+Purpose: Specify default error levels to always ignore for all domains.

+

+Note that default and per-domain errors to ignore can also be set via the

+web interface, and are combined with this setting. Leaving this unset and

+using the web interface is recommended for maximum flexibility.

+

+Example: 

+

+ic24.phperr.ignore = E_NOTICE | E_DEPRECATED

+

+(c) ionCube Ltd. 2017