Linux Harbour

Technology News of Linux & Open Source


Configuring HAProxy: Enabling Access to an API Server with Fixed IP for SaaS Cloud Systems

In the realm of Software-as-a-Service (SaaS) cloud systems, it is common to have an API server that should only be accessed by a fixed set of IP addresses or a range of IP addresses. To facilitate secure and controlled access to such an API server, HAProxy can be configured as a powerful reverse proxy and load balancer. In this article, we will explore how to configure HAProxy to enable SaaS cloud systems to access an API server with a fixed IP requirement. This setup ensures that only authorized systems can communicate with the API server, bolstering security while maintaining optimal performance.

To configure HAProxy to pass a client certificate from the frontend to the backend server, you need to modify the HAProxy configuration file. Here’s an example of how to do it:

1. Locate the HAProxy configuration file: Open the haproxy.cfg file in a text editor. The file is typically located in the /etc/haproxy/ directory.

2. Define a backend server: Specify the backend server for the API server. Use the backend keyword and provide the appropriate server configuration. Here’s an example:

backend my_api_server
    server api_server ssl verify none

In this example, my_api_server is the backend server’s name. represents the IP address and port of the API server. The ssl keyword indicates that the server is using SSL/TLS encryption. The verify none option disables SSL certificate verification. Adjust the IP address and port according to your setup.

3. Configure a frontend: Create a frontend section to handle incoming requests. Use the frontend keyword, specify the frontend’s name, and configure the SSL settings. Here’s an example:

frontend my_frontend
    bind *:443 ssl crt /etc/haproxy/certificate.pem
    default_backend my_api_server
    tcp-request inspect-delay 5s
    tcp-request content accept if { ssl_hello_type 1 }

In this example, my_frontend is the frontend’s name. The bind directive specifies that HAProxy should listen on port 443 for SSL/TLS connections. Replace /etc/haproxy/certificate.pem with the path to your SSL certificate file. You can refer the below section for self signed SSL certificate generation. The default_backend directive indicates that requests should be forwarded to the my_api_server backend server.

The tcp-request directives are used to inspect the SSL handshake. The inspect-delay directive adds a delay of 5 seconds to allow time for the client certificate to be sent. The tcp-request content accept if { ssl_hello_type 1 } directive checks if the SSL hello message contains a client certificate.

4. Save the configuration file.

5. Restart HAProxy: Restart the HAProxy service to apply the new configuration. The command to restart HAProxy may differ based on your operating system and installation method.

After restarting HAProxy with the modified configuration, it will listen on port 443 for incoming HTTPS requests. HAProxy will forward those requests to the backend server representing the API server. Additionally, if the client provides a client certificate during the SSL handshake, HAProxy will pass it along to the backend server.

Please note that the backend server must be configured to accept and validate the client certificate. The exact configuration on the backend server depends on the server software you are using.

Remember to adjust the configuration based on your specific environment, including the IP addresses, ports, SSL certificate path, and any additional settings required.

Generating a self-signed SSL certificate for HAProxy with OpenSSL

To generate a self-signed certificate for HAProxy, you can use OpenSSL to create a private key and a self-signed certificate. Here’s a step-by-step guide:

1. Generate a private key:

Use the following OpenSSL command to generate a private key:

openssl genpkey -algorithm RSA -out private.key

This command generates a private key file named private.key using the RSA algorithm. You can adjust the algorithm or other parameters as needed.

2. Generate a self-signed certificate:

Use the private key generated in the previous step to generate a self-signed certificate. Here’s an example command:

openssl req -new -x509 -key private.key -out certificate.pem -days 365

This command generates a self-signed certificate file named certificate.pem using the private key. The -days option specifies the validity period of the certificate in days. Adjust this value as per your requirements.

You will also be prompted to provide information such as the Common Name (CN), organization details, and other identifying information. Note that as this is a self-signed certificate, the information you provide does not need to be verified by a certificate authority.

3. Combine the private key and the self-signed certificate:

Concatenate the private key and the self-signed certificate into a single file. In most cases, you can simply append the contents of the private key file to the self-signed certificate file.

  1. cat private.key >> certificate.pem This will create a certificate.pem file that contains both the private key and the self-signed certificate.

Now you have a self-signed certificate that you can use with HAProxy. You can specify the path to the certificate.pem file in the bind directive of the frontend section in the HAProxy configuration.

It’s important to note that self-signed certificates are not trusted by default by web browsers and client applications, as they are not issued by a trusted certificate authority. Therefore, when using a self-signed certificate, you may encounter warnings or errors when accessing your server. Self-signed certificates are suitable for testing or internal use, but for production environments, it’s recommended to obtain a certificate from a trusted certificate authority.

How to troubleshooting HAProxy configuration

If you got any issues / errors from HAProxy, you can follow these steps to identify and resolve any issues:

1. Check the configuration file syntax:

Run the following command to validate the syntax of your HAProxy configuration file:

haproxy -c -f /etc/haproxy/haproxy.cfg

This command checks the syntax of the configuration file without starting HAProxy. If there are any syntax errors, the command will display an error message indicating the line number and the nature of the error.

2. Review the HAProxy logs:

Check the HAProxy log files for any error messages or warnings. The default log file for HAProxy is usually located at /var/log/haproxy.log. You can use a command like tail to view the last few lines of the log file in real-time:

tail -f /var/log/haproxy.log

Look for any error messages or warnings that might indicate configuration issues or other problems. The log messages can provide valuable information about the cause of the issue.

3. Enable debug mode:

If the issue is not apparent from the logs, you can enable debug mode in HAProxy to get more detailed information about the requests and responses. Edit your HAProxy configuration file and add the following line:


Save the configuration file and restart HAProxy. This will enable debug mode, and HAProxy will start logging additional information for each request. Remember to disable debug mode once you have finished troubleshooting, as it generates a large amount of log data.

4. Monitor HAProxy statistics:

HAProxy provides a built-in statistics page that can help you monitor the health and performance of your HAProxy instance. Ensure that the statistics page is enabled in your configuration file:

listen stats     bind *:9000
    stats enable
    stats uri /haproxy-stats 

After restarting HAProxy, you can access the statistics page by navigating to http://your-haproxy-ip:9000/haproxy-stats in a web browser. The statistics page provides real-time information about frontend and backend status, active connections, error rates, and more. It can help you identify any issues related to load balancing or backend server availability.

5. Validate network connectivity:

Ensure that there are no network connectivity issues between HAProxy and the backend servers. Verify that the backend servers are reachable from the HAProxy machine and that the ports and protocols are correct.

6. Test with simple configurations:

If you are experiencing issues with a complex HAProxy configuration, try simplifying it to a minimum working configuration. Gradually add complexity and test each step to identify the specific part of the configuration causing the issue.

By following these steps, you should be able to identify and resolve configuration-related issues in HAProxy. Remember to make backups of your configuration file before making any changes and refer to the HAProxy documentation for further troubleshooting guidance.

How to test the HAProxy configuration with web browser or curl ?

To test your HAProxy configuration using a web browser or curl, you can follow these steps:

1. Start HAProxy:

Ensure that HAProxy is running and listening on the configured port (e.g., port 80 or 443). If HAProxy is not running, start it using the appropriate command for your system.

2. Select either 2a (web browser) or 2b (curl) methods:

2a. Open a web browser

Open your preferred web browser and enter the URL or IP address associated with your HAProxy server. For example, if HAProxy is configured to listen on port 80, you can enter http://your-haproxy-ip/ in the browser’s address bar. If HAProxy is configured for SSL/TLS (HTTPS) and listening on port 443, use https://your-haproxy-ip/.

2b. Use curl:

Open a terminal or command prompt and use the curl command to make an HTTP request to your HAProxy server. For example, to make a GET request:

curl http://your-haproxy-ip/

If HAProxy is configured for SSL/TLS, use the -k option to bypass certificate verification:

curl -k https://your-haproxy-ip/

3. Analyze the response:

  • If the request is successful and you receive the expected response, it indicates that HAProxy is correctly forwarding the request to the backend server. You can examine the response in your web browser or the output of the curl command.
  • If you encounter any errors or unexpected behavior, you can analyze the response received from HAProxy. Check for any error messages, redirects, or other indications of issues. Additionally, review the HAProxy logs and debug output (if enabled) for more information about the request and the response.

4. Test different URLs or endpoints:

To further test your HAProxy configuration, you can try accessing different URLs or endpoints associated with your backend servers. This allows you to verify that HAProxy is correctly forwarding requests to the appropriate backend based on the configuration rules.

By testing your HAProxy configuration using a web browser or curl, you can verify its functionality and identify any issues that may need to be addressed.

Sammy Fung

Sammy is the founder of the Linux Harbour.