Support

Documentation

The component Options

You can access the component-wide options of Admin Tools through the Options button in its Control Panel page. Alternatively, you can go to your site's System, Global Configuration menu item and click on Admin Tools on the left hand sidebar.

Please note that this page is rendered and managed by Joomla! itself. We have very minimal control over it, namely on the names and types of the fields. The way that page displays and behaves is entirely controlled by Joomla! and your backend template. If you have observed a display or behavior issue the chances are we cannot help you since we will not (and must not!) modify core Joomla! code. Such bugs should be reported to Joomla! instead.

The page has several tabs, documented below.

Backend

Options which define how the backend of the component works.

Show graphs and statistics

Display graphs and statistics about blocked requests (Professional release only). This is useful visualisation to see the rate at which your site is being probed or attacked. If you feel that your clients may not fully understand that these are not meant to be Key Performance Indicators of the site protection we urge you to disable them using this option.

Automatically reorder the plugin

The System - Admin Tools plugin needs to be ordered as the first published plugin to work correctly. When you visit Admin Tools in the backend the plugin is automatically reordered to be the first one. In some rare cases other plugins need to be published first, for example integrations with third party email services for sending email from your site. In this case set this option to No.

If you set this option to No it's up to you to reorder the plugin. If a vulnerable plugin is published before the System - Admin Tools plugin your site can be hacked. Admin Tools will be unable to protect you in this case since it will not be running before the vulnerable code, therefore unable to detect the attack. Do not set this option to No unless you are absolutely sure you understand the risks.

Warn about manual edits on server configuration files

When this is enabled Admin Tools will check whether a file generated by .htaccess Maker, Nginx Conf Maker or web.config Maker has been modified outside of Admin Tools whenever you visit Admin Tools' main page in the backend of your site. This is done by comparing the checksum of the file with the one stored in your site's database when the file was generated. If the two checksums are different you will be asked whether you want to regenerate the file or ignore any such changes. The latter option changes this setting, "Warn about manual edits on server configuration files", to No.

We strongly recommend NOT changing generated files by hand. Instead, put any custom code in the provided areas for putting custom directives at the top or bottom of the file. In any other cases your manual changes will be overwritten every time you use Admin Tools' .htaccess Maker, Nginx Conf Maker or web.config Maker on your site.

Enable anonymous PHP, MySQL and Joomla! version reporting

Help us improve our software by anonymously and automatically reporting your PHP, MySQL and Joomla! versions. This information will help us decide which versions of Joomla!, PHP and MySQL to support in future versions.

Note: we do NOT collect your site name, IP address or any other directly or indirectly unique identifying information. Each site is assigned a randomly generated identifier. At the 7th of each month we generate aggregate information for the previous month and remove the individual data points collected over the last month.

Email sending

Options which control how Admin Tools sends emails for blocked requests. These options only apply in the Professional edition.

Timezone for emails

All dates and times in the emails sent by Admin Tools to warn you about potential security issues will be expressed in the selected timezone. use the option Server Timezone to let Admin Tools use the Server Timezone setting in your site's System, Global Configuration page.

Default: GMT

Blocked request email throttling

When enabled, Admin Tools will only send up to a certain number of emails over a specific of time. This protects your email from getting flooded when your site is under attack. You need to have blocked request logging enabled for all blocking reasons you are sending emails for. Furthermore, the maximum number of log entries you keep — per the system plugin's configuration – must be equal to or higher then the maximum number of emails configured below. In any other case your security exception emails will NOT be throttled.

Blocked request email throttling

When enabled, Admin Tools will only send up to a certain number of emails over a specific of time. This protects your email from getting flooded when your site is under attack. You need to have blocked request logging enabled for all blocking reasons you are sending emails for. Furthermore, the maximum number of log entries you keep — per the system plugin's configuration – must be equal to or higher then the maximum number of emails configured below. In any other case your security exception emails will NOT be throttled.

Maximum number of blocked requests to send emails for

The maximum number of blocked requests for which emails may be sent within the period of time defined below. Keep in mind that during a sustained attack more emails than this may be sent depending on how slow your web, database and mail servers respond when your site is under very heavy load. Furthermore, keep in mind that this only affects the blocked requests logged in the database and which with a block reason which is NOT in the configured reasons for which to never send emails.

Period for email throttling

Email throttling works by checking how many blocked requests have been logged in this many seconds, minutes, hours or days. You select the time unit of measurement below.

Time unit of measurement

The period above is expressed in the time unit of measurement selected here. Please note that for the purpose of these calculations one minute is 60 seconds, 1 hour is 3600 seconds, 1 day is 86400 seconds. This many be different than wall clock minutes, hours and days on years with leap seconds and on the cusp between Daylight Savings and Standard Time (or vice versa). Timekeeping is a rather convoluted subject.

File Scanner

Configure how the PHP File Change Scanner works. This option only makes sense in the Professional edition which has the PHP File Change Scanner feature.

Enable frontend scheduling

When enabled it allows you to the PHP File Change Scanner without logging in to the backend. This option is NOT required for using the CLI script.

Secret Word

Required to authorize a remote PHP File Change Scanner execution. Also protects that feature against Denial of Service attacks by requiring you to pass this secret word in the front-end PHP File Change Scanner URL.

Please note that if you use any character other than a-z, A-Z and 0-9 you MUST NOT use the secret word verbatim in the front-end URL. Instead, you have to URL-encode it. The PHP File Change Scanner Scheduling page does that automatically for you. Just go to Components, Admin Tools, click PHP File Change Scanner Scheduling, scroll all the way down and use one of the tabs to get the URL or command line you need to use with the secret word properly encoded in the URL.

For security reasons, you must use a complex enough secret word. Admin Tools enforces that by disabling the front-end scanner feature if you are using a Secret Word with a low complexity. We strongly recommend using a "secret word" consisting of at least 16 random, mixed case alphanumeric characters. It should not be a dictionary word or based off a dictionary word. One good resource for truly random secret words is Random.org's password generator.

[Note]Note

Why is this field not a password field? The Secret word is transmitted in the clear when you load the page and is also visible when you view the source of the page or right click on the field and choose Inspect Element. In other words, as long as someone has access to the component configuration page they can trivially find out the secret word. Not to mention that the secret work is also plainly visible in the PHP File Change Scanner Scheduling page. Always use HTTPS with a commercially signed SSL certificate when configuring or scanning your site.

Send results to this email

When you make a scan from the site's frontend or through the CLI script the scan results will be automatically sent to this email address. If you leave it blank no email will be sent in this case.

Email only on actionable items

When enabled (default) the PHP File Change Scanner will send you an email with the scan results summary only when actionable items (added, modified or suspicious files) are detected. If nothing has changed you will get no email. Please remember that being sent an email requires setting up the Send results to this email option above.

Log Level

The detail of the log file kept while scanning your site. Set to Warnings on production sites, Debug when you need to file a support request. The log file is saved in your site's logs folder, as configured in Joomla's Global Configuration.

Minimum Request Time

The minimum amount of time each request to the PHP File Change Scanner will take. Increase this if your server throws an error because requests are coming in too frequent or you otherwise hit CPU / resource limits.

The minimum request time is mostly useful in the case of steps (bursts of PHP File Change Scanner activity) cut short. This can happen, for example, before scanning very big .php files and while listing the contents of directories with more than a hundred files. In these cases the work on the step may be cut off less than 0.1 seconds into the step in some cases. The difference between the time elapse and the minimum request time will be used as idle time, reducing the rate in which requests to the PHP File Change Scanner hit your server. This is useful in preventing AJAX Error messages on servers which apply request limiting (most shared hosting environments).

Recommended values are 2.0 to 7.0. Some high-end servers may be able to use a value of 0.0 which makes scanning faster.

Maximum Work Time

The maximum amount of time consumed scanning your site in each request to the PHP File Change Scanner. The difference between the maximum work time and the minimum request time is idle time. Therefore setting this value lower than the minimum request time will create an idle period where the PHP File Change Scanner does nothing, therefore reducing CPU / resource usage and spacing out the requests to the server.

Recommended values are 3.0 to 7.0.

Work Time Bias

A value between 50 and 100 which affects how aggressively the PHP File Change Scanner will predict if it's about to hit the Maximum Work Time limit. 50 is most aggressive and will result in scanning taking about half of Maximum Work Time in most requests to the PHP File Change Scanner. 100 is the least aggressive but in this case the PHP File Change Scanner might overshoot the Maximum Work Time.

Recommended value: 75

You can use the combination of the minimum / maximum / bias values to work around AJAX Error messages. Here are some useful combinations:

Min 0.0 / Max 10.0 / Bias 80. Very fast scanning on beefy servers without resource limitations. Scanning is mostly split in 8 to 10 second steps (bursts of activity). There is no waiting time between successive steps. Recommended for dedicated servers.

Min 2.0 / Max 5.0 / Bias 75. The default settings, medium scanning speed. Scanning is split in roughly 3 to 5 seconds steps. Successive steps will be spaced at least 2 seconds apart. Recommended for most users.

Min 7.0 / Max 5.0 / Bias 50. Slow scanning speed. Scanning is split in 2.5 to 5 second steps followed by 2 to 4.5 seconds idle time to reduce CPU and resource usage per steps. Successive steps will be spaced at least 7 seconds apart. Recommended if you get AJAX Error messages every time you try to scan your site.

Min 7.0 / Max 2.0 / Bias 50. Glacial scanning speed. Scanning is split in 1 to 2 second steps followed by 5 to 6 seconds idle time to reduce CPU and resource usage per steps. Successive steps will be spaced at least 7 seconds apart. Only recommended if the 7/5/50 settings still result in AJAX Error messages.

Max. number of Folders per batch

The maximum number of folders to list in a directory at once. If the PHP File Change Scanner detects more than this number of folders it will immediately stop the work, regardless of the Maximum Work Time, and enter into idle mode until the Minimum Request Time is reached. This prevents PHP timing out when listing the contents of massive folders, with hundreds of folders contained directly inside them.

Please note that the time to list the contents of a folder is exponentially proportional to the number of files and folders contained in them -- in computer speak, it's O(N^2). In simple terms, listing the contents of a folder with 1000 contained folders and files will take 100 times longer than doing so for a folder with 100 contained folders and files. This is a limitation of how Operating Sytems and their filesystem drivers work. It's nothing us, Joomla or PHP itself can do about. You are strongly advised to exclude massive folders and take steps to prevent having folders with thousands of directly contained files and folders. It's best to nest your folders deeply.

Max. number of Files per batch

Similar to the previous setting, but applies to contained files instead of folders.

Excluded folders

Folders to exclude from the scan. One item per line. Wildcard characters (like ? and *) are NOT allowed.

Give the folder names relative to your site's root folder. For example, enter administrator/components/com_example. Do not enter something like /var/www/mysite/administrator/components/com_example.

Excluded files

PHP files to exclude from the scan. One item per line. Wildcard characters (like ? and *) are NOT allowed.

Give the file names relative to your site's root folder. For example, enter administrator/components/com_example/foo.php. Do not enter something like /var/www/mysite/administrator/components/com_example/foo.php.

Extensions to scan

Comma-separated list of file extensions to scan. Do not include the leading dot. Please only enter extensions of text files containing PHP code; any other file types will most likely result in false positives.

Default setting: php, phps, phtml, php3, inc

Large file threshold

The PHP File Change Scanner will immediately stop work right before scanning file which are at least this many bytes big. This prevents an accidental PHP timeout when scanning really big files at the tail end of the allotted Maximum Work Time.

Recommended value: 525288 (that's 512KB expressed in bytes)

Calculate diffs when scanning

When this option is enabled, Admin Tools will calculate a "diff" for each modified file detected by the PHP File Scanner feature. The "diff" is a compact summary of the differences between the original and the current file. In order for this to be possible, Admin Tools has to keep a copy of each and every .php file on your site inside the database. Be advised that this consumes a lot of database space, about 20M for a relatively low to medium complexity site.

This option is generally discouraged unless you are trying to figure out why a particular set of files keeps changing all the time.

Do not report files with a zero Threat Score

STRONGLY NOT RECOMMENDED. When this option is enabled any new or modified file with a zero threat score will not be reported.

We do not recommend turning on this option. It does not make the scan faster, it does not reduce the database storage significantly but it does have an impact on the security threats which will be reported. It is conceivable that a malicious file may have a zero threat score if its payload is written in a very sneaky way which makes it look like a legitimate, if a bit messy and naively coded, file. This kind of underhanded hacks will not be reported when this option is enabled. When this option is disabled they WILL be reported. A human operator may quickly spot a file that shouldn't have changed / be created at all and get rightfully alarmed. Therefore we recommend that you never enable this option. Its only reason of existence is debugging and troubleshooting conducted by the developers of Admin Tools.

Oversize file threshold

Files over this size in bytes will not have their Threat Score evaluated. The will still be reported as New or Changed if applicable, but their threat score will be zero.

The idea is that legitimate .php files containing executable code are rarely if ever bigger than one or two Megabytes. Files bigger than that are typically log files with a .php extension and a die statement on top to make them inaccessible over the web. Scanning this kind of non-executable files can result in scan failures or false positives. It's best to report them with a zero threat score instead. Better yet, try to exclude log files with .php extension in the Excluded Files setting above.

Recommended value: 5242880 (that 5MB in bytes).

Permissions

This is the standard Joomla! ACL permissions setup tab. Admin Tools fully supports supports Joomla! ACLs.