After every update you apply you must run the installation process again. In case of minor version updates, you can just overwrite the old files and use your current config. In case of major upgrades, you should make a clean install. It is advisable to read the Release Notes in order to know if any additional action is required. Note that the files and database from v3 are NOT compatible with v4.

It's a good practice to backup your old installation files and database. As additional step you can remove the AbyssGuard include file in your protected sites in order to ensure that eventual installation error won't take down your site.

Upgrading from v3 to v4
  1. Remove the abyssguard.php include from your protected sites.
  2. Backup your current AbyssGuard Client database and folder.
  3. Rename your current AbyssGuard Client folder and extract the contents of the new version in folder with the same name as the old one.
  4. Navigate to /install with your browser and follow the installation steps. You may be asked to log in first, after you do that, navigate to /install again.
  5. Just follow the steps and your current AbyssGuard Client database will be upgraded to v4 and won't be usable by v3 anymore.
To avoid complications, it's advisable to start with clean install.
Note that if you want to use your v3 database, you have to use the same prefix, if any, in the config as the old one.



Note that this process may differ from system to system!

In case you get Internal Server Error 500, add in the .htaccess trailing slash "/" in front of index.php. This may happen on some servers depending on their configuration.

  1. Navigate to your Apache2 sites-enabled dir and create a new file abyssguard_client or use existing one and edit it.
  2. Add the following code for AbyssGuard Client installed on a abyss.yourdomain.com:
    <VirtualHost *:80>
        DocumentRoot /system/path/to/your/abyss
        ServerAlias abyss.yourdomain.com
        ServerName abyss.yourdomain.com
    <Directory /system/path/to/your/abyss>
        AllowOverride All
    <Directory "/system/path/to/your/abyss/app/">
        Order Deny,Allow
        Deny from all
    <Directory "/system/path/to/your/abyss/cache/">
        Order Deny,Allow
        Deny from all
    <Directory "/system/path/to/your/abyss/config/">
        Order Deny,Allow
        Deny from all
    <Directory "/system/path/to/your/abyss/lib/">
        Order Deny,Allow
        Deny from all
    Where DocumentRoot is the location of the folder on your server and ServerAlias / ServerName is the address you use to access the installation from internet. Then forbid access to system folders that shouldn't be public.
  3. Save and exit the file.
  4. Reload Apache2 so the changes can take effect.


Note that this process may differ from system to system!

  1. Navigate to your Nginx sites-enabled dir and create a new file abyssguard_client or use existing one and edit it.
  2. Add the following code for AbyssGuard Client installed on a subdomain.yourdomain.com
    server {
        listen 80;
        server_name abyss.yourdomain.com;
        root /system/path/to/your/abyss;
        index index.php;
        location ~* ^/(app|cache|config|lib)(.*)$ {
        try_files $uri $uri/ /index.php?$args;	
        location ~ \.php$ {
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            fastcgi_pass unix:/var/run/php5-fpm.sock;
            fastcgi_index index.php;
            include fastcgi_params;
    Where root is the location of the folder on your server and server_name is the address you use to access the installation from internet.
  3. Save and exit the file.
  4. Reload Nginx so the changes can take effect.


  1. Extract the archive into a folder of your choice that you can access from the web.
  2. Make sure the /cache directory is writable (0777), no matter of the cache method you are going to use.
  3. Locate the file agconfig.example.php in AbyssGuard root folder and configure it, then rename it to agconfig.php
  4. Navigate with your web browser to the AbyssGuard installation folder with /install at the end to start the setup and just follow the steps. There is no physical install directory in the archive, but this doesn't mean that it won't work!
  5. After the installation complete, you have to add your AbyssGuard API key in your Client's Settings page. It's advisable to try the Simulation page after where you can make sure that everything works correctly!

You will also have to provide your Server IP address in your AbyssGuard Website Profile page. Without AbyssGuard API Key and Server IP you won't be recognized by the API. Always test your setup in the Simulation page as the Server IP may be different than the one displayed in your Dashboard or you may have error in your API Key.

Rerunning again the installation process won't affect your logs. If there is a valid AbyssGuard Client installation already, you will be asked to provide username and password before you can access the installation process again.

You must provide valid MySQL username and password in order to install AbyssGuard. These credentials are NOT your AbyssGuard ones and are strictly for your hosting! In case you don't know it, contact your server administrator or the support of your hosting company. If you don't want to use existing MySQL user you may create a new one. If you are using cPanel please refer to their manual. If you are using phpMyAdmin you can go to the Home page of your phpMyAdmin and click on Users. There you will see list of the current MySQL users that you may use. To create a new one click on the "Add user" link below the table. There you can choose Username and Password. Select "localhost" when asked for Host and check all privileges.

Always test your new installation in the Simulation room of your Client!

Setting up AbyssGuard

Go to your AbyssGuard Client Settings page and make sure AbyssGuard is enabled and set according your needs. AbyssGuard won't work without valid AbyssGuard API Key! You must also provide your server's IP address in your Profile page!

During the installation your IP address will be recorded by your AbyssGuard Client as Test IP and won't be banned for any activity on your AbyssGuard protected websites instead only the error page will be served with the reason for the ban. This is done for testing purposes so you can know what and why is happening. If you need to change this IP address to a different one or to remove it, you can do so on the Simulation page.

It's best if you test your setup on the Simulation page once you finish with the installation process.

Setting up the web sites you wish to protect

  1. Locate the index.php file in the root folder of the website you wish to protect and include the script at the beginning of the file like this:
    <?php include_once "/absolute/path/to/abyssguardfolder/abyssguard.php"; ?>
     The absolute path is usually something like "/home/username/public_html/yourabyssguardfolder/".
    Using relative paths like "../abyssguardfolder" may cause many problems and it's not recommended.

  2. Alternatively if your website doesn't have index.php or it works differently, you may include the script in header.php. In order to be effective the script must be executed before any other content. You may also include it only to pages you wish to protect.

For WordPress you should include the script in the following files too:

  1. wp-comments-post.php
  2. wp-login.php

For WordPress opened for registrations and with multiple people logging in it's probably best not to make the wp-login.php include as some people may get banned. This is measure mostly for private blogs targeted by bruteforce attacks.

Keep in mind in case of CMS (WordPress, Drupal, Jumla...) after you make major upgrades the files with the includes may get replaced so you might have to include the script again.

If you are using custom defined 404 error page outside of your website, it's advisable to include the script there. Requests for pages such as login.php, admin.php, etc often indicate that a person or robot is trying to find a way in to your website. You can stop them dead - from the very first attempt, even if they try to access a non-existent webpage. Simply add the include for the AbyssGuard script at the start of your own 404 webpage, and such visitors will receive your 403 Forbidden page instead of the user-friendly 404 page that invites them to explore your website. And don't worry - normal, well-behaved visitors who mistype your URL or arrive via an obsolete link will continue to get your customised 404 webpage.

AbyssGuard and your Cache

In case you are using a caching plugin that holds the whole web page and serves it to your visitors without any connection with the backend first, the AbyssGuard Client won't be able to execute properly and check your visitors. Such cache methods are not recommended to be used anyway.