Lua Plugin¶

This module embeds Lua, via the LuaJIT engine (>2.0.4), 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.

Installation¶

This plugin is only built if LuaJIT (>2.0.4) is installed. The configure option

--with-luajit=<path to luajit prefix>

can be used to specify a LuaJIT install. Otherwise, configure will use pkg-config to find a viable installation.

Example Scripts¶

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
        ts.debug(argtb[0] .. ' hostname parameter required!!')
        return -1
    end
    HOSTNAME = argtb[1]
end

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

test_global_hdr.lua

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

function do_global_read_request()
    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)
end

Usage with Example Scripts¶

This module acts as remap plugin of Traffic Server, so we should realize 'do_remap' or 'do_os_response' function in each lua script. The path referencing a file with the lua script can be relative to the configuration directory or an absolute path. 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_vconn_start'
'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'

We can write this in plugin.config:

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

Configuration for number of Lua states¶

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

The maximum number of allowed states is set to 256 which is also the default states value. The default value can be globally changed by adding a configuration option to records.yaml.

records:
   plugin:
     lua:
       max_states: 64

Any per plugin --states value overrides this default value but must be less than or equal to this value. This setting is not reloadable since it must be applied when all the lua states are first initialized.

For remap instances, the LuaJIT garbage collector can be set to be called automatically whenever a remap instance is created or deleted. This happens when the remap.config file has been modified, and the configuration has been reloaded. This does not apply to global plugin instances since these exist for the life-time of the ATS process, i.e., they are not reloadable or reconfigurable by modifying plugin.config while ATS is running.

By default, the LuaJIT garbage collector will run on its own according to its own internal criteria. However, in some cases, the garbage collector should be run in a guaranteed fashion.

For example, in Linux, total Lua memory may be limited to 2GB depending on the LuaJIT version. It may be required to release memory on demand in order to prevent out of memory errors when running close to the memory limit. Note that the memory usage is doubled during configuration reloads since the ATS must hold both the current and new configurations during the transition. If garbage collection occurs does not occur immediately, memory usage may exceed this double usage.

On demand garbage collection can be enabled by adding the following to each remap line. A value of '1' means enabled. The default value of '0' means disabled.

map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/XXX/tslua.so @pparam=--ljgc=1 @pparam=/script/test.lua

Configuration for JIT mode¶

We can also turn off JIT mode for LuaJIT for Traffic Server. The default is on (1). We can write this in plugin.config to turn off JIT

tslua.so --jit=0 /etc/trafficserver/script/test_global_hdr.lua

An example when using the plugin in remap.config

map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/XXX/tslua.so @pparam=--jit=0 @pparam=/script/test.lua

Profiling¶

The lua module collects runtime statistics about the lua states, for remap and global instances. Per state stats are constantly maintained and are made available through a lifecycle hook. These may be accessed through:

traffic_ctl plugin msg ts_lua stats_print

Sample output:

[Feb  5 19:00:15.072] ts_lua (remap) id:    0 gc_kb:   2508 gc_kb_max:   3491 threads:  417 threads_max:  438
[Feb  5 19:00:15.072] ts_lua (remap) id:    1 gc_kb:   1896 gc_kb_max:   3646 threads:  417 threads_max:  446
[Feb  5 19:00:15.072] ts_lua (remap) id:    2 gc_kb:   3376 gc_kb_max:   3740 threads:  417 threads_max:  442

Max values may be reset at any time by running:

traffic_ctl plugin msg ts_lua stats_reset

Summary statistics are aggregated every 5s and are available as metrics.

traffic_ctl metric match lua

Sample output:

plugin.lua.global.states 8
plugin.lua.remap.gc_bytes_min 4804608
plugin.lua.remap.gc_bytes_mean 5552537
plugin.lua.remap.gc_bytes_max 5779456
plugin.lua.remap.threads_min 31
plugin.lua.remap.threads_mean 44
plugin.lua.remap.threads_max 146

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_VCONN_START_HOOK	TS_LUA_HOOK_VCONN_START	NO	NO	YES
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_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_REQUEST _CLIENT_HOOK	TS_LUA_REQUEST_CLIENT	YES	NO	YES
TS_HTTP_RESPONSE _CLIENT_HOOK	TS_LUA_RESPONSE_CLIENT	YES	YES	YES
TS_HTTP_TXN _CLOSE_HOOK	TS_LUA_HOOK_TXN_CLOSE	YES	YES	YES

Lua Plugin¶

Installation¶

Example Scripts¶

Usage with Example Scripts¶

Configuration for number of Lua states¶

Configuration for JIT mode¶

Profiling¶

TS API for Lua¶

Introduction¶

ts.process.uuid¶

ts.now¶

ts.debug¶

ts.is_debug_tag_set¶

ts.error¶

ts.fatal¶

ts.emergency¶

ts.status¶

ts.note¶

ts.warning¶

ts.alert¶

TS Basic Internal Information¶

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_url¶

ts.client_request.get_pristine_url¶

ts.client_request.header.HEADER¶

ts.client_request.header_table¶

ts.client_request.get_headers¶

ts.client_request.get_header_block¶

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.client_request.get_ssl_reused¶

ts.client_request.get_ssl_protocol¶

ts.client_request.get_ssl_cipher¶

ts.client_request.get_ssl_curve¶

ts.http.set_cache_url¶

ts.http.get_cache_lookup_url¶

ts.http.set_cache_lookup_url¶

ts.http.redo_cache_lookup¶

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.header_table¶

ts.cached_response.get_headers¶

ts.server_request.get_uri¶