TS Lua Plugin¶

This module embeds Lua, via the standard Lua 5.1 interpreter, into Apache Traffic Server™. With this module, we can implement ATS plugin by writing Lua script instead of C code. Lua code executed using this module can be 100% non-blocking because the powerful Lua coroutines have been integrated into the ATS event model.

Synopsis¶

test_hdr.lua

function send_response()
    ts.client_response.header['Rhost'] = ts.ctx['rhost']
    return 0
end

function do_remap()
    local req_host = ts.client_request.header.Host
    ts.ctx['rhost'] = string.reverse(req_host)
    ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response)
    return 0
end

sethost.lua

local HOSTNAME = ''
function __init__(argtb)
    if (#argtb) < 1 then
        print(argtb[0], 'hostname parameter required!!')
        return -1
    end
    HOSTNAME = argtb[1]
end

function do_remap()
    ts.client_request.header['Host'] = HOSTNAME
    return 0
end

Installation¶

This plugin is only built if the configure option

--enable-experimental-plugins

is given at build time.

Configuration¶

This module acts as remap plugin of Traffic Server, so we should realize ‘do_remap’ or ‘do_os_response’ function in each lua script. We can write this in remap.config:

map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/XXX/tslua.so @pparam=/XXX/test_hdr.lua

Sometimes we want to receive parameters and process them in the script, we should realize ‘__init__’ function in the lua script, and we can write this in remap.config:

map http://a.x.cn/ http://b.x.cn/ @plugin=/X/tslua.so @pparam=/X/sethost.lua @pparam=a.st.cn

This module can also act as a global plugin of Traffic Server. In this case we should provide one of these functions in each lua script:

‘do_global_txn_start’
‘do_global_txn_close’
‘do_global_os_dns’
‘do_global_pre_remap’
‘do_global_post_remap’
‘do_global_read_request’
‘do_global_send_request’
‘do_global_read_response’
‘do_global_send_response’
‘do_global_cache_lookup_complete’
‘do_global_read_cache’
‘do_global_select_alt’

We can write this in plugin.config:

tslua.so /etc/trafficserver/script/test_global_hdr.lua

We can also define the number of Lua states to be used for the plugin. If it is used as global plugin, we can write the following in plugin.config

tslua.so --states=64 /etc/trafficserver/script/test_global_hdr.lua

If it is used as remap plugin, we can write the following in remap.config to define the number of Lua states

map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/XXX/tslua.so @pparam=--states=64 @pparam=/XXX/test_hdr.lua

TS API for Lua¶

Introduction¶

The API is exposed to Lua in the form of one standard packages ts. This package is in the default global scope and is always available within lua script. This package can be introduced into Lua like this:

ts.say('Hello World')
ts.sleep(10)

Hook Point	Lua Hook Point constant	Hook function be registered within do_remap() via ts.hook()?	Hook function be registered within do_os_response() via ts.hook()?	Hook function be registered within global context via ts.hook()?
TS_HTTP_TXN _START_HOOK	TS_LUA_HOOK _TXN_START	NO	NO	YES
TS_HTTP_READ _REQUEST_HDR_HOOK	TS_LUA_HOOK _READ_REQUEST_HDR	NO	NO	YES
TS_HTTP_PRE _REMAP_HOOK	TS_LUA_HOOK _PRE_REMAP	NO	NO	YES
TS_HTTP_POST _REMAP_HOOK	TS_LUA_HOOK _POST_REMAP	YES	NO	YES
TS_HTTP_SELECT _ALT_HOOK	TS_LUA_HOOK _SELECT_ALT	NO	NO	NO
TS_HTTP_READ _CACHE_HDR_HOOK	TS_LUA_HOOK _READ_CACHE_HDR	YES	NO	YES
TS_HTTP_OS _DNS_HOOK	TS_LUA_HOOK _OS_DNS	YES	NO	YES
TS_HTTP_CACHE _LOOKUP_COMPLETE_HOOK	TS_LUA_HOOK _CACHE_LOOKUP_COMPLETE	YES	NO	YES
TS_HTTP_SEND _REQUEST_HDR_HOOK	TS_LUA_HOOK _SEND_REQUEST_HDR	YES	NO	YES
TS_HTTP_READ _RESPONSE_HDR_HOOK	TS_LUA_HOOK _READ_RESPONSE_HDR	YES	YES	YES
TS_HTTP_SEND _RESPONSE_HDR_HOOK	TS_LUA_HOOK _SEND_RESPONSE_HDR	YES	YES	YES
TS_HTTP_REQUEST _TRANSFORM_HOOK	TS_LUA_REQUEST_TRANSFORM	YES	NO	YES
TS_HTTP_RESPONSE _TRANSFORM_HOOK	TS_LUA_RESPONSE_TRANSFORM	YES	YES	YES
TS_HTTP_TXN _CLOSE_HOOK	TS_LUA_HOOK_TXN_CLOSE	YES	YES	YES

TS Lua Plugin¶

Synopsis¶

Installation¶

Configuration¶

TS API for Lua¶

Introduction¶

ts.process.uuid¶

ts.now¶

ts.debug¶

Remap status constants¶

ts.remap.get_to_url_host¶

ts.remap.get_to_url_port¶

ts.remap.get_to_url_scheme¶

ts.remap.get_to_uri¶

ts.remap.get_to_url¶

ts.remap.get_from_url_host¶

ts.remap.get_from_url_port¶

ts.remap.get_from_url_scheme¶

ts.remap.get_from_uri¶

ts.remap.get_from_url¶

ts.hook¶

Hook point constants¶

ts.ctx¶

ts.client_request.get_method¶

ts.client_request.set_method¶

ts.client_request.get_version¶

ts.client_request.set_version¶

ts.client_request.get_uri¶

ts.client_request.set_uri¶

ts.client_request.get_uri_args¶

ts.client_request.set_uri_args¶

ts.client_request.get_uri_params¶

ts.client_request.set_uri_params¶

ts.client_request.get_url¶

ts.client_request.header.HEADER¶

ts.client_request.get_headers¶

ts.client_request.client_addr.get_addr¶

ts.client_request.client_addr.get_incoming_port¶

ts.client_request.get_url_host¶

ts.client_request.set_url_host¶

ts.client_request.get_url_port¶

ts.client_request.set_url_port¶

ts.client_request.get_url_scheme¶

ts.client_request.set_url_scheme¶

ts.http.set_cache_url¶

ts.http.get_cache_lookup_url¶

ts.http.set_cache_lookup_url¶

ts.http.get_parent_proxy¶

ts.http.set_parent_proxy¶

ts.http.get_parent_selection_url¶

ts.http.set_parent_selection_url¶

ts.http.set_server_resp_no_store¶

ts.http.set_resp¶

ts.http.get_cache_lookup_status¶

ts.http.set_cache_lookup_status¶

Http cache lookup status constants¶

ts.cached_response.get_status¶

ts.cached_response.get_version¶

ts.cached_response.header.HEADER¶

ts.cached_response.get_headers¶

ts.server_request.get_uri¶

ts.server_request.set_uri¶

ts.server_request.get_uri_args¶

ts.server_request.set_uri_args¶

ts.server_request.get_uri_params¶

ts.server_request.set_uri_params¶

ts.server_request.header.HEADER¶

ts.server_request.get_headers¶

ts.server_request.server_addr.set_addr¶

Socket address family¶

ts.server_request.server_addr.get_addr¶

ts.server_request.server_addr.get_ip¶

ts.server_request.server_addr.get_port¶

ts.server_request.server_addr.get_outgoing_port¶

ts.server_request.get_url_host¶

ts.server_request.set_url_host¶

ts.server_request.get_url_scheme¶

ts.server_request.set_url_scheme¶

ts.server_response.get_status¶

ts.server_response.set_status¶