haproxy-auth-request ¶

The first Lua program ¶

I searched for the documentation of Lua in haproxy and started reading. There are four main things I could register into haproxy:

action

Allows to modify requests.

converters

Allows to modify samples.

fetches

Allows to add samples.

service

Allows to answer requests.

At first I misunderstood what a service does and tried to use that one to handle the auth requests. But as I needed to modify requests and then pass them to a backend I needed an action:

core.register_action("auth-request", { "http-req" }, function(txn)
	-- code here
end)

global
	lua-load auth-request.lua

frontend http
	mode http
	option httplog

	bind :::80 v4v6

	http-request lua.auth-request

haproxy would now call my function for each HTTP request. While looking around the Lua documentation I found the print_r function, which would make debugging easier, as I did not have to put the information into response headers. I promptly added it to my script. When running haproxy using the -d option it would print the parameter to my console.

The first HTTP request ¶

Next thing was searching for a Lua HTTP library, I really did not want to implement HTTP on my own. I quickly found socket.http and installed it using apt-get install lua-socket. A quick test proofed successful: I was able to make HTTP requests from within my function:

core.register_action("auth-request", { "http-req" }, function(txn)
	local b, c, h = http.request {
		url = "http://127.0.0.1"
	}
	print_r(b)
	print_r(c)
end)

haproxy's Sockets ¶

I however noticed the Socket class in haproxy's documentation before and thought that there must be a reason why it exists. Possibly the default Socket class would block haproxy's event loop. Luckily the developers of socket.http imagined that use case and support passing a custom constructor as create to the http.request function. I quickly added it and tried it out: Nothing happened. An strace confirmed that haproxy was not even connecting to the host. Poking around in the http.socket module revealed that commenting out the call to settimeout would allow it to set up the socket. I figured I would find out what haproxy's Socket is doing differently later:

core.register_action("auth-request", { "http-req" }, function(txn)
	local b, c, h = http.request {
		url = "http://127.0.0.1",
		create = core.tcp
	}
	print_r(b)
	print_r(c)
end)

Now haproxy was sending the HTTP request and even reading the response. First success! Unfortunately instead of the response code it now was printing: connection closed. to my console. By aging that message in haproxy's source code I could find that the issue must be somewhere inside the receive method. print_ring the results of the receive calls in socket.http lead me to the receiveheaders function. For some reason that line was returning an empty string instead of a valid HTTP header, it did however read the HTTP status line in receivestatusline successfully before. I figured to explicitly add the default parameter of "*l" to instruct it to read a line. With success.

haproxy must be incorrectly handling the default parameter, despite explicitely documenting that no parameter equals *l. As I did not want to patch all of http.lua I tried to find out whether I could monkey patch the Socket class inside of Lua:

function create_sock()
	local sock = core.tcp()

	sock.old_receive = sock.receive
	sock.receive = function(socket, pattern, prefix)
		local a, b
		if pattern == nil then pattern = "*l" end
		if prefix == nil then
			a, b = sock:old_receive(pattern)
		else
			a, b = sock:old_receive(pattern, prefix)
		end
		return a, b
	end

	return sock
end
core.register_action("auth-request", { "http-req" }, function(txn)
	local b, c, h = http.request {
		url = "http://127.0.0.1",
		create = create_sock
	}
	print_r(b)
	print_r(c)
end)

It now correctly printed the response code. I was able to make HTTP requests with haproxy's Socket class. On to find out why the call to settimeout inside socket.http caused the request to fail, despite settimeout working from within my Lua code. Poking around in the source code of socket and haproxy revealed that haproxy was returning 0, while the original socket class was returning 1. For my workstation I fixed the return code in haproxy and recompiled it. With success. For production I did not want to run a self compiled haproxy and thus monkey patched settimeout as well:

function create_sock()
	local sock = core.tcp()

	sock.old_receive = sock.receive
	sock.receive = function(socket, pattern, prefix)
		local a, b
		if pattern == nil then pattern = "*l" end
		if prefix == nil then
			a, b = sock:old_receive(pattern)
		else
			a, b = sock:old_receive(pattern, prefix)
		end
		return a, b
	end

	sock.old_settimeout = sock.settimeout
	sock.settimeout = function(socket, timeout)
		socket:old_settimeout(timeout)

		return 1
	end

	return sock
end
core.register_action("auth-request", { "http-req" }, function(txn)
	local b, c, h = http.request {
		url = "http://127.0.0.1",
		create = create_sock
	}
	print_r(b)
	print_r(c)
end)

The actual patch in haproxy probably occured later, as I fixed the bug in the receive function before fixing settimeout. I fixed IPv6 support first as well.

Making DNS requests ¶

Lua in haproxy is documented to not support DNS requests. I did not want to hardcode an IP address in my configuration, however. While searching through haproxy's Lua documentation I noticed that I could get information about the backends using core.backends, with the Server class carrying a get_addr method. Would that give me the resolved IP address? It turned out that it does:

global
	lua-load auth-request.lua

frontend fe
	mode http
	bind :::8080 v4v6

	http-request lua.auth-request

	default_backend be

backend be
	mode http
	server s example.com:80

core.register_action("auth-request", { "http-req" }, function(txn)
	local b, c, h = http.request {
		url = "http://" .. core.backends["be"].servers["s"]:get_addr(),
		create = create_sock
	}
	print_r(b)
	print_r(c)
end)

Better! While the name of the backend still is hardcoded the IP address is not. At first I used the txn:get_var("txn.foo") method to read a variable I set using http-request set-var("txn.foo") string("be"), but while making the bug fixes to haproxy I noticed that I was able to pass additional parameters to my Lua action:

global
	lua-load auth-request.lua

frontend fe
	mode http
	bind :::8080 v4v6

	http-request lua.auth-request be

	default_backend be

backend be
	mode http
	server s example.com:80

core.register_action("auth-request", { "http-req" }, function(txn, be)
	local b, c, h = http.request {
		url = "http://" .. core.backends[be].servers["s"]:get_addr(),
		create = create_sock
	}
	print_r(b)
	print_r(c)
end, 1)

This later evolved into looping through all the servers in that backend and checking their health status.

I am now able to make HTTP requests to some easily changed backend. I now needed to return the response information back to haproxy:

Telling haproxy the result of the auth-request ¶

Similarly to my first attempt of passing the backend name I could pass variables back to haproxy using txn:set_var("txn.foo", true). This was fairly straight forward:

core.register_action("auth-request", { "http-req" }, function(txn, be)
	txn:set_var("txn.auth_response_successful", false)
	local b, c, h = http.request {
		url = "http://" .. core.backends[be].servers["s"]:get_addr(),
		create = create_sock
	}
	if 200 <= c and c < 300 then
		txn:set_var("txn.auth_response_successful", true)
	end
end, 1)

Passing request headers ¶

The only thing missing is passing all the request headers to my auth service (as it needed to know whether a specific cookie is set or not). This required me to convert from haproxy's header representation to the one of socket.http: haproxy passes header values as a table to support duplicate headers. socket.http only supports a single header name to string mapping. Luckily RFC 7230 allows me to support this without losing information:

A recipient MAY combine multiple header fields with the same field name into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field value to the combined field value in order, separated by a comma. The order in which header fields with the same field name are received is therefore significant to the interpretation of the combined field value; a proxy MUST NOT change the order of these field values when forwarding a message.

core.register_action("auth-request", { "http-req" }, function(txn, be)
	txn:set_var("txn.auth_response_successful", false)

	local headers = {}
	for header, values in pairs(txn.http:req_get_headers()) do
		for i, v in pairs(values) do
			if headers[header] == nil then
				headers[header] = v
			else
				headers[header] = headers[header] .. ", " .. v
			end
		end
	end

	local b, c, h = http.request {
		url = "http://" .. core.backends[be].servers["s"]:get_addr(),
		create = create_sock,
		headers = headers
	}
	if 200 <= c and c < 300 then
		txn:set_var("txn.auth_response_successful", true)
	end
end, 1)

Debian Package ¶

I am not a fan of manually placing files in the file system, that's why I wanted to pack the thing up into a Debian package. This is not my first Debian package, I built one to deploy configuration and files in my personal server. But for this I tried to “do it right”. My personal package is missing a description for example and has a few unnecessary files in it. Also it's a bunch of unrelated services munched together.

I followed the Debian New Maintainers' Guide to create a so-called “native” package. The difference, as I understand it, is that a native package does not ship with patchfiles.

As I only needed to install a single static file I did not need to make large changes to the autogenerated package. I added a Makefile with an install target and a README.md for documentation, but I would have created the latter anyways. The remaining changes boil down to removing a few files I did not need, filling out a few placeholders and adding the required dependencies.

You can view the changes I did after the automated generation of the package on GitHub. One thing I am not sure about is the Suggests dependency to haproxy. Should that be a hard Depends? While not strictly required (the file cannot do harm if haproxy is not installed) it just does not make sense without haproxy. I'm open for feedback from people more experienced with Debian packaging :-).