Support

Documentation

This documentation page is for Joomla! 3.x

This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.

Server protection
Prev The .htaccess maker Next

Server protection

Server protection

This is the most coveted feature of our software, offering a near-inclusive protection against the vast majority of known threats when enabled. This feature's mission statement can be summed up with a single phrase: nothing executes on your site unless you allowed it to. By blocking access to front-end and back-end elements (media files, Javascript, CSS and PHP files) it makes it extremely hard —but not outright impossible— for an attacker to hack your site, even if he manages to exploit a security vulnerability to upload malicious PHP code to your site. Additionally, it will deny direct access to resources not designed to be directly accessible from the web, such as translation INI files, which are usually used by attackers to find out which version of Joomla! you are running on your site to tailor an attack to your site. On the downside, you have to explicitly enable access to some extensions' PHP files which are designed to be called directly from the web and not through Joomla!'s main file, index.php and index2.php.

Do note that enabling this feature will kill the functionality of some extensions which create arbitrarily named PHP files throughout your site, such as RokGZipper. In our humble opinion the security risk of having your site unprotected outweighs the benefits of such solutions by a dramatic factor. As a result, we strongly suggest disabling RokGZipper and other similar software using similarly questionable security practices.

There are three sections of configuration settings controlling the functionality of the Server Protection feature. The first one is the Protection Toggles which allows you to enable or disable the four main aspects of protection:

Back-end protection

Disables direct access to most back-end resources, except those in the exceptions lists. It is generally recommended to turn it on to enhance the protection of your site, unless you have enabled the administrator password protection feature. In the latter case this option is redundant and we recommend turning it off.

Front-end protection

Disables direct access to most front-end resources, except those in the exceptions lists. It is generally recommended to turn it on to enhance the protection of your site.

Enabling this feature will prevent web access to all folders in your site's root, not just Joomla's folders (such as components). If you need to enable direct access to a folder you will need to place it in one of the front-end directory exception lists in the Fine-tuning or Exceptions section.

The next section is called Fine-tuning and contains the necessary options to tweak the protection's behaviour to suit your site. Before describing what each option does, a small explanation of how the protection works is in order. The protection code in the generated .htaccess file blocks direct web access to all files. Joomla!'s standard "entry point" or "main" file, index.php, is automatically exempt from this rule. However, your site also contains images, media, CSS and Javascript files inside certain directories. For each of the back-end and front-end protection we need a set of directories where such files are allowed and the file extensions of those files. These are what those options are all about. The default settings contain the most common file types you'd expect to find on a site and the standard Joomla! directories where they should be located. You only have to tweak them if you want to add more file extensions or have such static files in locations other than the default.

Back-end directories where file type exceptions are allowed

This is a list of back-end directories (that is, subdirectories of your site's administrator directory) where you expect media files to be present. Place one directory on each line. Subdirectories of those directories are automatically added to the exceptions list without having to explicitly list them here.

Back-end file types allowed in selected directories

The extensions of back-end files which allowed to pass through the server protection filter, as long as the files with those extensions are in the list above. Place one file extension per line, without the dot. For example, if you want to allow access to all PDF files you have to type in "pdf" (without the quotes) on a new line of this list. Do note that file extensions are case-sensitive. This means that PDF, Pdf, pdf and pDF are four different file extensions as far as your web server is concerned. As a rule of thumb, type in the extensions in lowercase and make sure that the extensions of the files you upload are also in lowercase.

Disable client-side risky behavior in backend static content

Please note that this option only applies to the “Back-end file types allowed in selected directories” which are under your site's administrator directory.

The files with extensions matching “Back-end file types allowed in selected directories” inside the “Back-end directories where file type exceptions are allowed” folders are, generally speaking, static files. However, some kinds of static files may contain client-side, dynamic content. For example, HTML and SVG files can contain JavaScript which executes on your browser. This kind of client-side, dynamic content can pose a security risk. For example, an attacker can upload a malicious HTML or SVG file which steals your login cookie and sends it to the attacker who can now impersonate you on your site, allowing them to take it over.

When you enable this option the .htaccess Maker sends a Content-Security-Policy header for these files which prevents them from executing any embedded client-side code in them. This is a far better protection than Joomla's recommendations to disable uploading HTML and SVG files and/or set the $live_site parameter in your configuration.php file. In fact, you DO NOT need to disable uploading HTML or SVG files and you DO NOT (actually: you MUST NOT!) set the $live_site parameter. This protection neutralizes any and all exploits which could be effected by malicious client-side code.

If you do have certain files or folders with static files that absolutely need executable, embedded, client-side code please add them to one of the three Exceptions features described further below. Any explicitly allowed files or folders will be exempt from the “Disable client-side risky behavior in backend static content”.

Front-end directories where file type exceptions are allowed

This is a list of front-end directories (that is, directories in your site's root) where you expect media files to be present. Place one directory on each line. Subdirectories of those directories are automatically added to the exceptions list without having to explicitly list them here.

Use this to allow access to specific types static media files inside specific directories. This is the least permissive exception to front-end blocking. Use this for folders which have a mix of public and private content, as long as the private content is NOT of an allowed file type (see below).

Front-end file types allowed in selected directories

The extensions of front-end files which allowed to pass through the server protection filter, as long as the files with those extensions are in the list above. Place one file extension per line, without the dot. For example, if you want to allow access to all PDF files you have to type in "pdf" (without the quotes) on a new line of this list. Do note that file extensions are case-sensitive. This means that PDF, Pdf, pdf and pDF are four different file extensions as far as your web server is concerned. As a rule of thumb, type in the extensions in lowercase and make sure that the extensions of the files you upload are also in lowercase.

Disable client-side risky behavior in frontend static content

Please note that this option only applies to the “Front-end file types allowed in selected directories” which are under your site's root.

Its reason for existence is the same as the “Disable client-side risky behavior in frontend static content” and works the same way, setting a Content-Security-Policy header.

Exceptions

Finally, we have the Exceptions section. This allows specific files or all files in specific directories to pass through the Server Protection filter without further questions. This is required for several reasons. For starters, some extensions need to directly access PHP files, without passing them through Joomla!'s main files. One such example is Akeeba Backup Professional's restore.php used in the integrated restoration feature, as it would be impossible to use the index.php of a site which is in a state of flux while the restoration is underway. Other prime examples are CSS and Javascript minifiers, either included in your template or installed on top of your site. Forum attachments are also part of the same problem, as they tend to create a dedicated directory for their attachments, avatar icons and so forth. Moreover, some extensions place PHP files inside your site's tmp and cache directories and expect them to be directly accessible from the web. While this is a stupid behaviour, contrary to the design goals of Joomla! itself, you still need a way to work around them and we have to provide it. Finally, you may have a third party script (e.g. Coppermine gallery, phpBB forum, WordPress blog, or even another Joomla! site in a subdirectory) which doesn't install as a Joomla! extension. The Server Protection feature would normally block access to it and you still need a way around this limitation. So here we have those workarounds:

Allow direct access to these files

Place one file per line which should be exempt from filtering, therefore accessible directly from the web. The default settings include Akeeba Backup Professional and, of course, Admin Tools itself.

Allow direct access, except .php files, to these directories

Direct access to all files (except for .php files) will be granted if they are inside any of the directories in this list. Normally you should only need to add your forum's attachments, avatars and image galleries directories, or other directories where you only intend to store media files. The example is Agora forum's user files directory. As with all similar options, add one directory per line, without a trailing slash.

Use this to allow access to all files, except executable .php files, in specific directories. This is a middle ground in front-end blocking. You should use this only for folders which have only public content, i.e. if it's in that folder you are OK with it being shared with the rest of the world.

Allow direct access, including .php files, to these directories

This option should be used as sparingly as possible. Each and every directory placed in this list is no longer protected by Server Protection and can be potentially used as an entry point to hacking your site. As far as we know there are only three cases when its use is even marginally justifiable:

  • If you have installed another Joomla!, WordPress, phpBB, Coppermine gallery or any other PHP application in a subdirectory of your site. For example, if you are trying to restore a copy of your site inside a directory named test in your site's root you have to add test to this list. This is the one and only usage scenario which doesn't compromise your site's security.

  • Some templates and template frameworks may wrap their CSS and Javscript inside PHP files in order to deliver them compressed to your browser. While this is a valid technique, it's possible that the list of PHP files is too big to track down and include in the first list of the Exceptions section. In this case you may consider putting the template subdirectory containing those files in this list.

  • Some extensions do something silly: they place files inside your site's tmp or cache directories and expect them to be directly accessible from the web. This is plain wrong because these directories are designed to be protected system directories where direct access should not be allowed, most notably because they might contain sensitive information. However, if you have such extensions —most notably certain Javascript and CSS minifiers— you need a way to allow direct access to those directories.

    If you decide that convenience is better than security we can't stop you. Add tmp and cache to this list and wish for the best. You are opening a security hole on your site and you do it at your own risk and potential peril.

Use this to allow full access to specific folders, as if the front-end protection does not exist. This is EXTREMELY dangerous! It's best to use the Allow direct access to these files feature if possible, allowing access only to very specific .php files.

Remember that an attacker who has found an upload vulnerability on your site can upload a malicious script inside one of these folders and use it to hack you. These folders are bare and unprotected. That's why we very strongly advise against using this feature unless it's absolutely necessary - keeping in mind that you are, at the same time, leaving a hole in your security defences. Holes in defences is what gets sites hacked.

In order to figure out which custom exceptions you need to add on your site, take a look at the How to determine which exceptions are required section.

[Warning]Warning

Windows users beware! Do not use Windows' path separator (the backslash - \) to separate directories! We are talking about directories as they appear in URLs, so you should always use the URL path separator (forward slash - /) in those settings. In other words some/long/path is correct, some\long\path is WRONG.

How to determine which exceptions are required

After applying the Server Protection settings you may notice that some aspects of your site no longer work properly or at all. This could be something obviously throwing an error; files being inaccessible with a 403 or 404 error message; or something more subtle, as if CSS and JavaScript no longer load. These are probably caused by the Server Protection settings disallowing access to files. We can find which files need to be accessed and add exceptions to them to restore the functionality of your site.

[Tip]Tip

There is no valid reason for software integrated with Joomla! to require such exceptions for .php files anymore. Since early 2013 Joomla! has shipped with com_ajax, a built-in method to access dynamic content without needing direct access to arbitrarily named .php files. Developers who have not caught up to this technology after so many years are less likely to follow security best practices. Moreover, most of these directly accessible .php files do not load Joomla!, therefore they do not load Admin Tools, meaning that you are no longer protected by Admin Tools' Web Application Firewall if malicious requests are being sent to those files. As a result, adding extensions for their software's .php files to be accessible directly from the web can compromise your site's security.

Exceptions for non-.php files – such as CSS, JavaScript, images, fonts etc – may still be required and are generally not a security issue. Some static content can be a security issue if it's accessible over the web (e.g. JSON files containing privileged information such as usernames, passwords and API keys) but these cases are rare and you shouldn't be overly worried about them.

The process of determining which exceptions are required is made relatively easy by modern browsers. All modern browsers include "developer tools" which give us insight on what is going on when the browser tries to load your page. They even highlight the errors for us, making our work much easier.

In the following example we are going to be using Mozilla Firefox. The process is very similar on Google Chrome, Opera, Safari and Microsoft Edge. If you are not sure how to open the developer tools for your browsers do a quick search on the Internet similar to developer tools <your browser name here>.

Our example makes use of RokBox, an extension by RocketTheme, which causes a problem when used through the Joomla! article editor in the backend of the site. The instructions also apply to the frontend of your site and any other extension which might be causing a problem.

After applying the Server Protection settings in the .htaccess Maker we get the following error when we click on the RokBox button in the editor:

This is a vague error message. We want it to be that way to not give away any information about our site to bad guys. At the same time it makes our life a bit harder. Click on Close to dismiss that non-functional dialog.

Click on Firefox' hamburger menu (the three horizontal lines button towards the top right of its window), Web Developer, Toggle Tools. This opens a side pane. On that pane there's a top menu. Click on the Network option. You may have to click on the >> arrows first to see it. Then click on the RokBox button on your editor. You now see something interesting happen in the Web Developer pane:

The pane shows the request made to your server and its error status 403 highlighted. 403 means access forbidden, 404 means not found. The former is an error code we definitely expect as the result of applying Server Protection. The latter can either mean that the file is genuinely not there or that Server Protection is preventing access to it. If you get a 404 always check if the file exists first. Since we have a 403 here we know it's a Server Protection issue.

Click on the line with the error code. You will see some details open below the list. Click on the Headers tab on top of those details. You see a lot of information but what is interesting to us is the Request URL. It tells us which URL the browser tried to access and failed to do so. However, it's truncated and doesn't help us any. So right click on it and choose Copy.

Now open a plain text editor application such as Notepad on Windows, TextEdit on macOS, gEdit or Kate on Linux and paste in the URL you copied.

Highlight the stuff between your site's root URL and the question mark (if there is no question mark, highlight to the end of the line). In our example the site's URL is http://test3.local.web and the highlighted portion is plugins/editors-xtd/rokbox/views/rokbox-picker.php which, as you may have guessed, is the relative path to the file blocked by Server Protection. Copy this.

Now go to Components, Admin Tools, .htaccess Maker and find the Allow direct access to these files box.

In a new line paste the relative file path you had highlighted previously. Make sure you do not include the leading slash or the trailing question mark. Click on Save and Create .htaccess in the toolbar to apply your changes. Now the extension works:

In case you see plenty of files or files with random and changing names; or you see files in the cache, tmp and logs folders

Sometimes the above method will show a long list of files; or files with random names; or files whose names change on every page or request. Typically, you see that they are all located in the same few folders. There are two different things you can do.

If the files you see do not have a .php extension the the easy way is to add the path to the folder to the Allow direct access, except .php files, to these directories list. For example, if all files are in the foobar/assets/static folder you need to add foobar/assets/static to the Allow direct access, except .php files, to these directories list.

The drawback to that is that all files without a .php extension in this folder and its subfolders will be accessible over the web. This might be a security risk if the same folder contains files with privileged information. You can mitigate that risk by adding an exception in a harder, but more secure, way. You'd need to add the folder's path to the Backend directories where file type exceptions are allowed or Frontend directories where file type exceptions are allowed lists in the .htaccess Maker. If the folder's relative path starts with administrator/ add it to the first list (backend) after removing the administrator/ prefix.

For example, if the files are in the administrator/components/com_example/media folder you need to add components/com_example/media to the Backend directories where file type exceptions are allowed list. Conversely, if the files are in the foobar/assets folder you need to add foobar/assets to the Frontend directories where file type exceptions are allowed list.

Please note that in this case (hard way) if the file extension is not in the Backend file types allowed in selected directories or Frontend file types allowed in selected directories lists you will need to add the file extension, without the dot, in those lists as well. Keep in mind that capitalization matters. For example, the extensions png, PNG and Png are different and have to be listed separately.

If the files you see have a .php extension things are easier but also more nuanced. You can always add the path to the folder in the Allow direct access, including .php files, to these directories list. This is potentially insecure. It allows direct web access to all files in that folder and all of its subdirectories, bypassing Joomla! and Admin Tools entirely. If there are files with privileged information they will be accessible to everyone. If the .php files have a security issue in them you will get hacked. This is why we DO NOT advise you to do that.

What we do advise you to do is contact the developer of the offending extension and ask them to fix their code to always go through Joomla's index.php files (e.g. using com_ajax). If they decline to do that you should consider using a different extension. There is absolutely no reason whatosever to have directly accessible .php files in Joomla! since 2013. Well, actually, there is one: when you are overwriting Joomla! itself. Since Joomla! is being overwritten with a different version you cannot also use it at the same time, thus making the only valid use case of not going through Joomla. This is exactly what the restore.php files in com_joomlaupdate (the Joomla! Update component which is part of Joomla! itself) and Akeeba Backup (when restoring a backup) do and that's why they are the only two built-in exceptions in Admin Tools. Both files were written by Akeeba Ltd, they are locked when you are not actively updating/restoring a site, they are protected with a password when you are actively updating/restoring a site and they have been audited by independent security researchers several times.

Finally, a special mention is due for extensions which try to access files stored in the cache, logs or tmp directories in the front- and backend of your site. These directories are NOT meant to be web accessible. In fact, they are designed in such a way that it's possible to move them outside of your site's web root. Moreover, their content is supposed to be transient, i.e. it is expected to be deleted at any point in time and the extension is supposed to not break when that happens. Web accessible files generated by extensions are supposed to go into the media folder in the root of your instead. This folder has been available since Joomla! 1.5.0 came out in 2007. Any developer who does not understand a concept introduced over a decade ago is certainly not following security best practices. As a result we very strongly recommend NOT using these extensions, ever, at all cost.

Prev Up Next
The .htaccess maker Home Custom .htaccess rules