Skip to main content

HAProxy

HAProxy is a fantastic reverse proxy with a massive amount of features. Knocknoc has supported HAProxy for years, and integrates with it natively. HAProxy can be a little confusing at first due to its wide array of options and implementations, but for now we'll walk through some basic configuration for use in front of Confluence. 

Note: If you are reading this page, you should already have your Knocknoc Server and Agent setup as this guide will assume you are at least aware of the features being addressed.

HAProxy Configuration via the Admin Socket

Knocknoc supports HAProxy's admin socket, this interaction is how the access control list (ACL) within HAProxy is updated to allow your users to access the protected application behind. For this guide we are going to make a few assumptions, the first is that you have a Linux based system and the second is the Knocknoc Agent and HAProxy is installed already.

  1. Add the knocknoc-agent user to the HAProxy group. This allows the knocknoc-agent to read and modify the ACL.
    adduser knocknoc-agent haproxy
  2. Edit the HAProxy configuration file.
    vi /etc/haproxy/haproxy.cfg
  3. Check the socket configuration under the global section. This socket is what the agent connects to, in order to control HAProxy, hence the need for permissions. The line will list the location of the socket and access permissions. For example;
    stats socket /run/haproxy/admin.sock mode 0666 level admin user haproxy group haproxy

    Copy the path to the socket this will be required when setting up the backend in the Knocknoc admin interface below.

  4. The frontend definition, in this example, is listening for HTTP/s traffic on all interfaces on port 443 and HAProxy is providing the SSL verification from the certificates within the provided directory. 
    frontend https_frontend 
 mode http
 bind *:443 ssl crt /etc/ssl/private/ alpn h2,http/1.1
  5. Within the frontend definition, we have 3 ACL's;

    1. acl is_confluence hdr(host) confluence.mycompany.com any traffic hitting the url defined is marked with the ACL "is_confluence"

    2. acl is_http hdr(X-Forwarded-Proto) http any traffic that is HTTP and not HTTPS is marked with the ACL "is_http"

    3. acl knoc_confluence src -u 500 is the ACL-ID that Knocknoc-agent is interacting with in this example. Users who have authenticated to Knocknoc and via their groups are granted access to Confluence will have their IP added to that ACL-ID. Traffic from the IP's in that ACL-ID are marked with the ACL "knoc_confluence".

        
      acl is_confluence hdr(host) confluence.mycompany.com
acl is_http hdr(X-Forwarded-Proto) http
acl knoc_confluence src -u 500

       

  6. The below rule within the frontend definition redirects traffic marked with the ACL "is_http" from HTTP to HTTPS. Forcing all traffic to be encrypted. 
     redirect scheme https if is_http 

  7. Traffic that is marked with the ACL's "is_confluence" and "knoc_confluence" is directed to the backend "confluence_backend"

    use_backend confluence_backend if is_confluence knoc_confluence
  8. Any traffic not those ACL's receives a 503 error.
  9. Next is the backend definition the example contains;
    1. backend confluence_backend this has to match the use_backend confluence_backend from the frontend definition. 
    2. The mode, mode http, which should match the mode from the frontend definition. 
    3. The server line;
      1. This contains a recognizable name for the server, server confluence_server for easy identification and logging.
      2. The IP:Port of Confluence 192.168.0.200:443 behind HAProxy.
      3. The check statement, which tells HAProxy to check Confluence is up and responding on the IP:Port.
      4. ssl verify none this statement means HAProxy does not care if the Confluence SSL cert is valid as SSL termination is happening between the user and HAProxy.  
        backend confluence_backend 
 mode http
 server confluence_server 192.168.0.200:443 check ssl verify none

A lot, lot more that can be done with HAProxy the more familiar you become with it. Tied with Knocknoc's security integration it can become a fundamental cog in your security machine. Should you need further assistance feel free to reach out to one of our support partners.

Knocknoc Admin Interface Configuration for HAProxy

  1. Click Backends on the left.
  2. Click Create Backend on the right. 
    1. Enter a name that is sensible, for example Server name - HAProxy.
    2. Select the Knocknoc-agent that is installed on this server.
    3. Backend Type will be HAProxy. 
    4. Command Protocol will be Unix Socket
    5. Address will be the location of the HAProxy socket from the HAProxy config.Create HAProxy Backend.png
  3. Click Create.
  4. Click on ACLs on the left.
  5. Click Create ACL on the right.
    1. Description will be the name of the Application/Service the ACL is for.
    2. URL is the external URL the end users will want to reach.
    3. The Backend is the one just created.
    4. The ACL Name is the ACL-ID from the HAProxy config.
      Create ACL.png
  6. Under Groups on the left, Select the group that requires access to Confluence and click edit and check the box for the Confluence ACL.

Note: Group configuration varies, slightly depending on which Authentication source is being used. For guidance of Authentication, Groups and Users please review the documentation.

Additional HAProxy Configuration Information

HAproxy TCP Socket

The HAProxy backend also supports a TCP socket, in which case it still expects to talk to the Unix socket, but it can do so via a TCP redirect. This is most easily accomplished with the spiped utility.

Knocknoc-agent ships with a script make-spiped-tunnel.sh which can walk you through making an encrypted tunnel via spiped between your Knocknoc-agent machine and a remote HAProxy. It is often easier to deploy Knocknoc-agent directly to a machine, but in case this isn't possible, you can use the spiped tunnel for this purpose.

Further documentation on this will be added in the near future.

Error Responses

HAproxy can easily send custom 403 or 503 responses to users who aren't allowed to access the backend resource. For example:

image.png

This is configured as the default_backend error response in HAProxy config, so if the HTTP request doesn't match the right source IP or hostname, the above is shown in the browser. An admin can customize this to display anything, but keep in mind it's a HTTP response, not an HTML page, so there are limitations. You could of course link people to your Knocknoc instance in the error message, depending on your users and risk profile.

Further documentation on this will be added in the near future.

Example HAProxy configuration file

Below is a full example of a basic default HAProxy configuration file. It contains the settings from above to allow a 1:1 comparison.

global
  log /dev/log local0
  log /dev/log local1 notice
  stats socket /run/haproxy/admin.sock mode 0666 level admin user haproxy group haproxy
  user haproxy
  group haproxy
  daemon
  # 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:
  #  https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
  ssl-default-bind-ciphers kEECDH+aRSA+AES:kRSA+AES:+AES256:RC4-SHA:!kEDH:!LOW:!EXP:!MD5:!aNULL:!eNULL
  ssl-default-bind-options no-sslv3
  # Default ciphers to use on SSL-enabled listening sockets.
  # For more information, see ciphers(1SSL). This list is from:
  #  https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
  ssl-default-server-ciphers kEECDH+aRSA+AES:kRSA+AES:+AES256:RC4-SHA:!kEDH:!LOW:!EXP:!MD5:!aNULL:!eNULL
  ssl-default-server-options no-sslv3
  nbproc 1

# Defaults
defaults
  log global
  mode http
  option httplog
  option dontlognull
  timeout connect 5000
  timeout client 50000
  timeout server 50000
  errorfile 400 /etc/haproxy/errors/400.http
  errorfile 403 /etc/haproxy/errors/403.http
  errorfile 408 /etc/haproxy/errors/408.http
  errorfile 500 /etc/haproxy/errors/500.http
  errorfile 502 /etc/haproxy/errors/502.http
  errorfile 503 /etc/haproxy/errors/503.http
  errorfile 504 /etc/haproxy/errors/504.http

# Userlist

# Resolvers

# Listen

frontend https_frontend 
 mode http
 bind *:443 ssl crt /etc/ssl/private/ alpn h2,http/1.1

 acl is_confluence hdr(host) confluence.mycompany.com
 acl is_http hdr(X-Forwarded-Proto) http
 acl knoc_confluence src -u 500

 redirect scheme https if is_http 
 use_backend confluence_backend if is_confluence knoc_confluence

backend confluence_backend 
 mode http
 server confluence_server 192.168.0.1:443 check ssl verify none

Back to top