gtctl

Introduction

gtctl is a tool that renders Drib's aggregates into Gatekeeper's Grantor policy scripts and submits them via dynamic configuration.

The submission of policy scripts takes Grantor's LPM configuration parameters into accout, updating or replacing the current policy as needed.

Installation

Debian or Ubuntu

Debian packages will be provided with the first gtctl release

$ wget https://
$ sudo dpkg -i ...

From source

gtctl will be added to crates.io on its first release

Use Rust's package manager, cargo, to install gtctl from source:

$ cargo install --git https://github.com/andrenth/gtctl

Running

gtctl can be run in two modes: dyncfg and estimate. In dyncfg mode, gtctl will read an aggregate file generated by Drib, compare it to the aggregate used in the previous execution, if any, and render a dynamic configuration script according to a configured template, as detailed below. Depending on the number of entries in the aggregate file and Gatekeeper's LPM table parameters, the policy will either be updated or completely replaced. In estimate mode, gtctl reads text files containing IP ranges in CIDR format (one per line), and outputs LPM parameters suitable for the number of input ranges.

Run in dyncfg mode:

$ gtctl dyncfg -a /path/to/drib/aggregate

Run in estimate mode:

$ gtctl estimate -4 /path/to/ipv4-ranges -6 /path/to/ipv6-ranges

As previously mentioned, the files given to the -4 and/or -6 flags consist of IP ranges of the respective protocol version, in CIDR format, one per line. These can be generated directly from a router's routing table.

For example, if using the Bird routing daemon, these files can be generated with commands similar to the ones below.

$ birdc show route table my_ipv4_table | grep / | awk '{print $1}' > ipv4-ranges
$ birdc show route table my_ipv6_table | grep / | awk '{print $1}' > ipv6-ranges

The commands above will read the default configuration file, /etc/gtctl/gtctl.yaml. To specify an alternative configuration file, use the -c or --config command line flag:

$ gtctl -c /path/to/config/file.yaml dyncfg -a /path/to/drib/aggregate
$ gtctl -c /path/to/config/file.yaml estimate -4 /path/to/ipv4-ranges -6 /path/to/ipv6-ranges

For further details, run gtctl help.

Configuration

socket

The path to Grantor's dynamic configuration socket (defaults to /var/run/gatekeeper/dyn_cfg.socket).

log_level

gtctl's log level. Valid values are error, warn, info, debug or trace (defaults to info).

state_dir

The directory where gtctl stores Drib aggregates across executions, as well as rendered policy scripts.

remove_rendered_scripts

A boolean value that indicates whether the policy scripts generated in state_dir are to be removed once they are submitted to Grantor via dynamic configuration.

estimate

The estimate sections defines settings for execution in estimate mode.

• rules_scaling_factor: a multiplier for the estimated number of rules; defaults to 1.
• tbl8s_scaling_factor: a multiplier for the estimated number of tbl8s; defaults to 1.

replace

This section defines parameters for the generation of policy scripts that replace the current policy. Three subsettings are expected:

• input refers to a template file (see the Templates section below for details) used to render the policy replacement scripts.
• output specifies the path of the rendered scripts.
• max_ranges_per_file, if given, limits the number of ranges rendered in a single output file.

The output path is itself a template, so a number of variables can be used to split the bootstrap output according to protocol (i.e. IPv4 and IPv6), using the {proto} variable, and kind (see the documentation below), using the {kind} variable. A third variable, {i}, corresponds to the ith script being generated, according to the max_ranges_per_file parameter. Once the number of ranges rendered in the replacement script reaches the max_ranges_per_file value, a new file will be generated, and the i variable will be incremented. This variable supports an integer modifier that indicates how many digits are used for the index, so, for example, {3i} will represent the index with 3 digits, padding it with zeros if necessary.

The file name template for the policy replacement scripts is used for all combinations of protocol and kinds. For example, if your groups configuration defines three different kinds, a total of six policy replacement scripts will be generated (three for IPv4 and three for IPv6). This means that if the {proto} and {kind} variables are not used in the output setting, a given rendered file may overwrite a previously generated one, depending on the contents of the aggregate file.

Example:

replace: {
  input: "/etc/gtctl/policy_replace.lua.tpl",
  output: "/var/lib/gtctl/policy_replace_{proto}_{kind}.{2i}.lua",
  max_ranges_per_file: 1500,
}

update

This section defines parameters for the generation of policy scripts that update the current policy. It supports the same parameters and templating variables as the ones available in the replace section.

Example:

update: {
  input: "/etc/gtctl/policy_update.lua.tpl",
  output: "/etc/gtctl/policy_update_{proto}_{kind}.{2i}.lua",
  max_ranges_per_file: 1500,
}

lpm

This section is concerned with the generation of dynamic configuration scripts that read LPM parameters from Grantor.

The following settings are supported.

• table_format: a template for the name of the LPM tables, supporting the {proto} and {kind} variables.
• parameters_script: a subsection with input and output settings describing, respectively, the template and output paths for the LPM configuration scripts; The output paths support the {proto} and {kind} variables.
• ipv4 and ipv6: these subsections contain two settings each: lpm_table_constructor, the name of the Lua function that initializes an LPM table, and lpm_get_params_function, the name of the Lua function that returns the current LPM parameter settings.

Example:

lpm: {
  table_format: "{kind}_lpm_{proto}",

  parameters_script: {
    input: "/etc/gtctl/lpm_params.lua.tpl",
    output: "/var/lib/gtctl/lpm_params_{proto}_{kind}.lua",
  },

  ipv4: {
    lpm_table_constructor: "lpmlib.new_lpm",
    lpm_get_params_function: "lpmlib.lpm_get_paras",
  },

  ipv6: {
    lpm_table_constructor: "lpmlib.new_lpm6",
    lpm_get_params_function: "lpmlib.lpm6_get_paras",
  },
}

Templates

gtctl uses the Rust crate Tera for its templating, which has a simple and intuitive syntax similar do Django templates.

For the replace and update scripts, gtctl provides the respective input templates of the given configuration sections with two global objects, ipv4 and ipv6. These are collections of entry elements of the respective protocol, each containing the following fields:

• kind: the kind associated to the range, as configured in Drib.
• class: the class associated to the range, also taken from Drib's configuration.
• range: the IP range itself.

The following variables are also available for replace and update script templates: script_index, an integer indicating which script is being rendered (starting at 0); is_first_script and is_last_script, boolean values indicating, respectively, whether the script is the first and/or last to be rendered; and proto, the name of the protocol for the current script (either "ipv4" or "ipv6").

For the LPM parameters script template, the lpm_table_constructor and lpm_get_params_function variables defined in the configuration file will be available, along with the lpm_table variable, whose contents will be derived from the table_format setting in the lpm configuration section.

Note that the LPM parameters script template is the same for IPv4 and IPv6, and will be rendered twice, once for each protocol version.

Examples of policy and parameter scripts can be found in the examples directory in the gtctl repository.