From: Charles-Henri Bruyand Date: Wed, 30 Jun 2021 10:03:30 +0000 (+0200) Subject: document the two new ffi functions X-Git-Tag: dnsdist-1.7.0-alpha1~106^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7c39f378eeeb0c17594478299a4132acf7f3ea7d;p=thirdparty%2Fpdns.git document the two new ffi functions --- diff --git a/pdns/recursordist/docs/lua-scripting/ffi.rst b/pdns/recursordist/docs/lua-scripting/ffi.rst new file mode 100644 index 0000000000..df9264e3d1 --- /dev/null +++ b/pdns/recursordist/docs/lua-scripting/ffi.rst @@ -0,0 +1,143 @@ +Lua FFI API +=========== + +We provide a set of functions available through the LUA FFI library that allow you to interact with the the :func:`gettag_ffi` parameter. + +Functions +--------- + +.. function:: pdns_ffi_param_get_qname(pdns_ffi_param_t* ref) -> const char* + + Get the query's qualified name + +.. function:: pdns_ffi_param_get_qtype(const pdns_ffi_param_t* ref) -> uint16_t + + Get the query's type + +.. function:: pdns_ffi_param_get_remote(pdns_ffi_param_t* ref) -> const char* + + Get the sender's IP address + +.. function:: pdns_ffi_param_get_remote_port(const pdns_ffi_param_t* ref) -> uint16_t + + Get the sender's port + +.. function:: pdns_ffi_param_get_local(pdns_ffi_param_t* ref) -> const char* + + Get the local IP address the query was received on + +.. function:: pdns_ffi_param_get_local_port(const pdns_ffi_param_t* ref) -> uint16_t + + Get the local port the query was received on + +.. function:: pdns_ffi_param_get_edns_cs(pdns_ffi_param_t* ref) -> const char* + + Get query's EDNS client subnet + +.. function:: pdns_ffi_param_get_edns_cs_source_mask(const pdns_ffi_param_t* ref) -> uint8_t + + Get query's EDNS client subnet mask + +.. function:: pdns_ffi_param_get_edns_options(pdns_ffi_param_t* ref, const pdns_ednsoption_t** out) -> size_t + + Get query's EDNS options. Returns the length of the resulting `out` array + +.. function:: pdns_ffi_param_get_edns_options_by_code(pdns_ffi_param_t* ref, uint16_t optionCode, const pdns_ednsoption_t** out) -> size_t + + Get query's EDNS option for a given code. Returns the length of the resulting `out` array + +.. function:: pdns_ffi_param_get_proxy_protocol_values(pdns_ffi_param_t* ref, const pdns_proxyprotocol_value_t** out) -> size_t + + Get query's proxy protocol values. Returns the length of the resulting `out` array + +.. function:: pdns_ffi_param_get_edns_cs_raw(pdns_ffi_param_t* ref, const void** net, size_t* netSize) -> void + + Fill out `net` with query's EDNS client subnet + +.. function:: pdns_ffi_param_get_remote_raw(pdns_ffi_param_t* ref, const void** addr, size_t* addrSize) -> void + + Fill out `addr` with sender's IP address + +.. function:: pdns_ffi_param_get_qname_raw(pdns_ffi_param_t* ref, const char** qname, size_t* qnameSize) -> void + + Fill out `qname` with query's qualified name + +.. function:: pdns_ffi_param_get_local_raw(pdns_ffi_param_t* ref, const void** addr, size_t* addrSize) -> void + + Fill out `addr` with local IP address the query was received on + +.. function:: pdns_ffi_param_set_tag(pdns_ffi_param_t* ref, unsigned int tag) -> void + + Tag the query with the given number + +.. function:: pdns_ffi_param_add_policytag(pdns_ffi_param_t* ref, const char* name) -> void + + Add the given tag to the query + +.. function:: pdns_ffi_param_set_requestorid(pdns_ffi_param_t* ref, const char* name) -> void + + Set query's requestor ID + +.. function:: pdns_ffi_param_set_devicename(pdns_ffi_param_t* ref, const char* name) -> void + + Set query's device name + +.. function:: pdns_ffi_param_set_deviceid(pdns_ffi_param_t* ref, size_t len, const void* name) -> void + + Set query's device ID + +.. function:: pdns_ffi_param_set_routingtag(pdns_ffi_param_t* ref, const char* name) -> void + + Set routing tag which is used as an extra name to identify records in the record cache, see :func:`gettag` + +.. function:: pdns_ffi_param_set_variable(pdns_ffi_param_t* ref, bool variable) -> void + + Mark as variable and ensure it’s not inserted into the packetcache + +.. function:: pdns_ffi_param_set_ttl_cap(pdns_ffi_param_t* ref, uint32_t ttl) -> void + + Cap the max TTL of the returned records + +.. function:: pdns_ffi_param_set_log_query(pdns_ffi_param_t* ref, bool logQuery) -> void + + Turn on/off query logging + +.. function:: pdns_ffi_param_set_log_response(pdns_ffi_param_t* ref, bool logResponse) -> void + + Turn on/off response logging + +.. function:: pdns_ffi_param_set_rcode(pdns_ffi_param_t* ref, int rcode) -> void + + Set response RCode + +.. function:: pdns_ffi_param_set_follow_cname_records(pdns_ffi_param_t* ref, bool follow) -> void + + Instruct the recursor to do a proper resolution in order to follow any CNAME records added + +.. function:: pdns_ffi_param_set_extended_error_code(pdns_ffi_param_t* ref, uint16_t code) -> void + + Set extended DNS error info code + +.. function:: pdns_ffi_param_set_extended_error_extra(pdns_ffi_param_t* ref, size_t len, const char* extra) -> void + + Set extended DNS error extra text + +.. function:: pdns_ffi_param_set_padding_disabled(pdns_ffi_param_t* ref, bool disabled) -> void + + Disable padding + +.. function:: pdns_ffi_param_add_record(pdns_ffi_param_t* ref, const char* name, uint16_t type, uint32_t ttl, const char* content, size_t contentSize, pdns_record_place_t place) -> bool + + Adds a record. Returns true if it was correctly added, false otherwise + +.. function:: pdns_ffi_param_add_meta_single_string_kv(pdns_ffi_param_t* ref, const char* key, const char* val) -> void + + .. versionadded:: 4.5.3 + + This function allows you to add an arbitrary string value for a given key in the ``meta`` field of the produced :doc:`protobuf <../lua-config/protobuf>` log message + +.. function:: pdns_ffi_param_add_meta_single_int64_kv(pdns_ffi_param_t *ref, const char* key, int64_t val) -> void + + .. versionadded:: 4.5.3 + + This function allows you to add an arbitrary int value for a given key in the ``meta`` field of the produced :doc:`protobuf <../lua-config/protobuf>` log message diff --git a/pdns/recursordist/docs/lua-scripting/hooks.rst b/pdns/recursordist/docs/lua-scripting/hooks.rst index 471c355680..68d1e18f08 100644 --- a/pdns/recursordist/docs/lua-scripting/hooks.rst +++ b/pdns/recursordist/docs/lua-scripting/hooks.rst @@ -115,8 +115,8 @@ Interception Functions The ability to craft answers was added. This function is the FFI counterpart of the :func:`gettag` function, and offers the same functionality. - It accepts a single, scalable parameter which can be accessed using FFI accessors. - Like the non-FFI version, it has the ability to set a tag for the packetcache, policy tags, a routing tag, the :attr:`DNSQuestion.requestorId` and :attr:`DNSQuestion.deviceId`values and to fill the :attr:`DNSQuestion.data` table. It also offers ways to mark the answer as variable so it's not inserted into the packetcache, to set a cap on the TTL of the returned records, and to generate a response by adding records and setting the RCode. It can also instruct the recursor to do a proper resolution in order to follow any `CNAME` records added in this step. + It accepts a single, scalable parameter which can be accessed using :doc:`FFI accessors `. + Like the non-FFI version, it has the ability to set a tag for the packetcache, policy tags, a routing tag, the :attr:`DNSQuestion.requestorId` and :attr:`DNSQuestion.deviceId` values and to fill the :attr:`DNSQuestion.data` table. It also offers ways to mark the answer as variable so it's not inserted into the packetcache, to set a cap on the TTL of the returned records, and to generate a response by adding records and setting the RCode. It can also instruct the recursor to do a proper resolution in order to follow any `CNAME` records added in this step. .. function:: prerpz(dq) -> bool diff --git a/pdns/recursordist/docs/lua-scripting/index.rst b/pdns/recursordist/docs/lua-scripting/index.rst index d11c4da8bc..a93d215055 100644 --- a/pdns/recursordist/docs/lua-scripting/index.rst +++ b/pdns/recursordist/docs/lua-scripting/index.rst @@ -26,6 +26,7 @@ For extra performance, a Just In Time compiled version of Lua called `LuaJIT