Skip to content
|
search
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

Custom fields and headers

By Kong Inc.
You are browsing documentation for an outdated plugin version. See the latest documentation here.

Looking for the plugin's configuration parameters? You can find them in the HTTP Log configuration reference doc.

Custom headers

The log server that receives these messages might require extra headers, such as for authorization purposes.

...
  - name: http-log
    config:
      headers:
        Authorization: 
          - "Bearer <token>"
...

Custom fields by Lua

The custom_fields_by_lua configuration allows for the dynamic modification of log fields using Lua code. Below is a snippet of an example configuration that removes the route field from the logs:

curl -i -X POST http://localhost:8001/plugins \
... 
  --data config.custom_fields_by_lua.route="return nil"

Similarly, new fields can be added:

curl -i -X POST http://localhost:8001/plugins \
... 
  --data config.custom_fields_by_lua.header="return kong.request.get_header('h1')"

Limitations

Lua code runs in a restricted sandbox environment, whose behavior is governed by the untrusted_lua configuration properties configuration properties.

Sandboxing consists of several limitations in the way the Lua code can be executed, for heightened security.

The following functions are not available because they can be used to abuse the system:

  • string.rep: Can be used to allocate millions of bytes in one operation.
  • {set|get}metatable: Can be used to modify the metatables of global objects (strings, numbers).
  • collectgarbage: Can be abused to kill the performance of other workers.
  • _G: Is the root node which has access to all functions. It is masked by a temporary table.
  • load{file|string}: Is deemed unsafe because it can grant access to the global environment.
  • raw{get|set|equal}: Potentially unsafe because sandboxing relies on some metatable manipulation.
  • string.dump: Can display confidential server information (such as implementation of functions).
  • math.randomseed: Can affect the host system. Kong Gateway already seeds the random number generator properly.
  • All os.* (except os.clock, os.difftime, and os.time). os.execute can significantly alter the host system.
  • io.*: Provides access to the hard drive.
  • dofile|require: Provides access to the hard drive.

The exclusion of require means that plugins must only use PDK functions kong.*. The ngx.* abstraction is also available, but it is not guaranteed to be present in future versions of the plugin.

In addition to the above restrictions:

  • All the provided modules (like string or table) are read-only and can’t be modified.
  • Bytecode execution is disabled.

Further, as code runs in the context of the log phase, only PDK methods that can run in said phase can be used.