Skip to main content


The duty of this module is to offload HTTPS connections, and help our CaptchaHttp and WAF module to work properly with HTTPS requests. If you enable SslTerminating it will try to download and install bitninja-ssl-termination package to /opt/bitninja-ssl-termination, which is basically a HAProxy 1.8.9. We decided to build and publish our self-built HAProxy, because it will not depend on official repositories, and it will not interfere with other HAProxy installations and configurations. After installation succeeds, it will try to find currently active virtual hosts using HTTPS and extract any information which can be used to generate a valid haproxy.cfg. The module is responsible for collecting and generating pem files every 5 minutes, which can be used by bitninja-ssl-termination to offload HTTPS requests.

The module works with CaptchaHttp and WAF 2.0 modules. When a challenge listed IP tries to connect to your server on 443 it will be redirected to bitninja-ssl-termination's frontend. The CAPTCHA will appear, and the innocent visitor can solve it.

Certificate miners

To gather certificate information, SSL Terminating module currently uses three certificate miner implementations. These miners are: ApacheCertMiner, NginxCertMiner, LiteSpeedCertMiner.

A certificate miner implementation should consist of the following steps:

  • Collect the public key, the private key and the chain file for the SSL Certificate and put them in a pem file.
  • Put the newly created pem file location in /opt/bitninja-ssl-termination/etc/haproxy/cert-list-lst file, with every domain that belongs to this certificate, separated with spaces. Like this: /opt/bitninja-ssl-termintion/etc/haproxy/certs/ \*

An example bash implementation for DirectAdmin:

echo > /opt/bitninja-ssl-termination/etc/haproxy/cert-list.lst
for i in `ls /usr/local/directadmin/data/users/*/domains/* | grep ".key" | awk -F "/" {'print $9'} | sed 's/\.[^.]*$//'` ;


cat /usr/local/directadmin/data/users/*/domains/"$i".key /usr/local/directadmin/data/users/*/domains/"$i".cert > /opt/bitninja-ssl-termination/etc/haproxy/certs/"$i".pem
echo "/opt/bitninja-ssl-termination/etc/haproxy/certs/$i.pem $i www.$i *.$i" >> /opt/bitninja-ssl-termination/etc/haproxy/cert-list.lst


You can make your custom cert miner as default. To use your custom certificate miner instead of the ConfigParser module:

  • Disable the useConfigParserModule variable and enable the allowCertListFileEditio option.
  • Move your certificate miner to the /etc/bitninja/SslTerminating/cert_miners/ directory.
  • Currently only BASH scripts are supported.
  • The script has to be a .sh file.
  • The owner of the script has to be ROOT

The cert miner will run automatically when the SslTerminating module is started or restarted.


The Apache certificate miner tries to retrieve VirtualHost information using apache2ctl/apachectl/httpd -S (depending on the current OS). If this miner fails to find the apachectl binary, you can add it's path to the config.ini webserver section with: apachectlBinaryLocation = 'path/to/binary'


The Nginx certificate miner tries to retrive the main Nginx configuration file using nginx -V. It will follow includes and collect every virtual host using SSL certificates. If this miner fails to find your Nginx binary, you can add its path to the config.ini webserver section with: nginxBinaryLocation = 'path/to/binary'

If you are using a different main configuration which was configured at Nginx build time, you can add your main configuration file to the config.ini webserver section with: nginxMainConfigFileLocation = 'path/to/nginx.conf'


LiteSpeed certificate miner currently tries to parse the Apache main configuration file, follow includes and collect every virtual host using SSL certificates. If you are using a different main configuration file, you can add it to the config.ini webserver section with: apacheMainConfigFileLocation = 'path/to/apache.conf'

Pattern certificate will be coming soon and it will be able to collect certificates with file patterns like: keyfiles= 'path/to/*/domains/*.key' and pemfiles= 'path/to/*/domains/*.pem'

Manual certificate mapping

Since version 3.1.0 you can manually add each domain's SSL cert's location if neccesary.



CLI options

You can use CLI to enable and disable SslTerminating module with:

   bitninjacli --module=SslTerminating --enabled
bitninjacli --module=SslTerminating --disabled

HAProxy configuration can be reloaded, if they were manually edited with:

   bitninjacli --module=SslTerminating --reload

HAProxy configuration can be regenerated, if module configurations were edited:

   bitninjacli --module=SslTerminating --regenerate


The module can be configured in /etc/bitninja/SslTerminating/config.ini. This config file contains 9 config sections. The first two are for HAProxy and Apache binary settings. The other seven sections are for configuring different sections of the haproxy.cfg, if needed.

; Bitninja [SslTerminating] Module configuration file

; SslTerminating module uses HAProxy 1.5.8. This section define basic configurations.

; Allow edition of the cert-list.lst file, when Certificate miners found any certificate.
; When Certificate miners fail to find any valid certificate, manually creation and mantaining the list file
; are not changed.

; Allow run of the Certificate finder cron, which runs every 5 minutes.

; Certiicate miner need to read the webserver's configuration file which can be huge.
; We need to increase the module memory limit to avoid out of memory fatal errors.
; Memory limit value is in Mega bytes default. Default value is 2024 Mega byte (2Gb).
; The minimum value is 100 Mb.

; Maximum requests per domain every 'perDomainRateLimitInterval' seconds (see below)
; If set to 0, rate limiting is disabled
; perDomainRateLimit = 0
; How many seconds should take before resetting the rate limit counter
; perDomainRateLimitInterval = 0

; Always generate haproxy configuration based on config.ini setting.
;generate_config_on_startup = 1

;; where is the haproxy binary
;; where should we look for haproxy config file
;; where could haproxy work
;; where could SslTerminating put collected cert files
;certDir = '/opt/bitninja-ssl-termination/etc/haproxy/certs'
;; where is the cert list file
;certListFile = '/opt/bitninja-ssl-termination/etc/haproxy/cert-list.lst'
;; user for haproxy
;; Https Captcha backend port
;haproxyPort = 60413
;; front end port
;httpsPort = 443
;; Captcha front and backend settings
;CaptchaFrontEndSettings[name]= 'Captcha-https'
;CaptchaFrontEndSettings[iface]= '*'
;CaptchaFrontEndSettings[port]= 60413
;CaptchaBackEndSettings[name]= 'Captcha-https-backend'
;; WAF front and backend setting
;; not used for now
;WafFrontEndSettings[name]= 'waf-https'
;WafFrontEndSettings[iface]= '*'
;WafFrontEndSettings[port]= '60414'
;WafBackEndSettings[name]= 'waf-https-backend'

; Web server settings
;; if binary location not set SslTerminating module tries to find where is apache.
;apachectlBinaryLocation = '/usr/sbin/apache2ctl'
;apachectlBinaryLocation = '/usr/sbin/httpd'
;apachectlBinaryLocation = '/opt/sp/apache/bin/apachectl'
;listVirtualHostParameter= '-S'

; Haproxy global settings. Every ini key value will be converted to a haproxy configuration.
; E.g.: chroot = '/var/lib/bitninja/SslTerminating'
; Will be converted to:
; chroot = /var/lib/bitninja/SslTerminating
; If you whan to add multiple values use ini arrays.
; E.g.: log[] = '/dev/log local0'
; log[] = '/dev/log local1 notice'
; This will be converted to:
; log = /dev/log local0
; log = /dev/log local1 notice
; See more about haproxy configuration at:
;log[] = '/dev/log local0'
;log[] = '/dev/log local1 notice'
;chroot = '/var/lib/bitninja/SslTerminating'
;stats[] = 'socket /var/lib/bitninja/SslTerminating/admin.sock mode 660 level admin'
;stats[] = 'timeout 30s'
;user = 'bitninja-ssl-termination'
;group = 'bitninja-ssl-termination'
;; Default SSL material locations
;ca-base = '/etc/ssl/certs'
;crt-base = '/etc/ssl/private'

;; Default ciphers to use on SSL-enabled listening sockets.
;; For more information, see ciphers(1SSL). This list is from:
;; An alternative list with additional directives can be obtained from
;ssl-default-bind-options = 'no-sslv3 no-tlsv10'
;tune.ssl.default-dh-param = 2048

; Haproxy default Settings
;log = 'global'
;mode = 'http'
;option[] = 'httplog'
;option[] = 'dontlognull'
;option[] = 'forwardfor'
;timeout[] = 'connect 5000'
;timeout[] = 'client 50000'
;timeout[] = 'server 50000'
;errorfile[] = '400 /opt/bitninja-ssl-termination/etc/haproxy/errors/400.http'
;errorfile[] = '403 /opt/bitninja-ssl-termination/etc/haproxy/errors/403.http'
;errorfile[] = '408 /opt/bitninja-ssl-termination/etc/haproxy/errors/408.http'
;errorfile[] = '500 /opt/bitninja-ssl-termination/etc/haproxy/errors/500.http'
;errorfile[] = '502 /opt/bitninja-ssl-termination/etc/haproxy/errors/502.http'
;errorfile[] = '503 /opt/bitninja-ssl-termination/etc/haproxy/errors/503.http'
;errorfile[] = '504 /opt/bitninja-ssl-termination/etc/haproxy/errors/504.http'

; Stat page setting. For security reason please Change uri, auth
;bind = '*:1936'
;mode = 'http'
;log = 'global'
;maxconn = 10
;timeout queue = '100s'
;stats[] = 'enable'
;stats[] = 'hide-version'
;stats[] = 'refresh 30s'
;stats[] = 'show-node'
; Haproxy stat page auth setting. Change it before enabling stat page.
;stats[] = 'auth user:password'
; Haproxy stat page uri setting. Change it before enabling stat page.
;stats[] = 'uri /haproxy?stats'

; Haproxy Captcha frontend settings.
; Don't use Haproxy bind configuration in thes section.
;option[]= "httpclose"
;reqadd = 'X-Forwarded-Proto:\ https'

; Haproxy Captcha backend settings
;redirect = 'scheme https if !{ ssl_fc }'
;server= 'captcha-1 *:60412 check'

; Haproxy WAF frontend settings.
; Not used yet.
;reqadd = 'X-Forwarded-Proto:\ https'
;default_backend = 'waf-https-backend'

; Haproxy WAF backend settings.
; Not used yet.
;redirect = 'scheme https if !{ ssl_fc }'
;server 'waf-1 *:60045 check'


Regenerating certificate information

If the SslTerminating is using expired certificate information on your server for some reason, you can regenerate the certificate information by running the following commands:

chmod +x /opt/bitninja/modules/Cli/scripts/

This script contains the following commands, which you can also run manually, one after the other, if needed:

rm -f /opt/bitninja-ssl-termination/etc/haproxy/certs/*
rm -f /opt/bitninja-ssl-termination/etc/haproxy/cert-list.lst
rm -f /opt/bitninja-ssl-termination/etc/haproxy/haproxy.cfg
bitninjacli --module=SslTerminating --regenerate
bitninjacli --module=SslTerminating --reload

Enhance Control Panel

BitNinja has been compatible with Enhance Control Panel since version 3.3.0. The Config Parser module can now parse and find the corresponding configuration files. The WAF, captcha, and TrustedProxy modules work seamlessly with the control panel.

However, there are still some limitations, unfortunately, that require further development.

  • The LogAnalysis and Defense Robot modules cannot process back-end web server logs with Enhance Control Panel.
  • OpenLiteSpeed is not supported yet
  • The PortHoneypot module will not start in a dockerized environment. Therefore, it is not enabled in this case either.

In order to ensure complete protection for the entire cluster, it is necessary to install BitNinja on all servers within the setup. Merely installing it on the control panel node will not suffice.