-
Notifications
You must be signed in to change notification settings - Fork 232
Functional Block: GT
The Grantor (GT) block can be considered the main component of Grantor servers, as its task is to accept incoming packets from Gatekeeper servers, issue policy decisions for requests, and forward granted packets to their ultimate destination. It is in the data plane and can scale across multiple lcores. It only runs when the Gatekeeper executable is being run as a Grantor server (as opposed to a Gatekeeper Server).
The role of Grantor servers is to centralize the interpretation of the policy that Gatekeeper servers enforce at vantage points. The policy, which is defined by a Lua script, decides which capabilities to grant or decline, the maximum receiving rate of the granted capabilities, and when each decision expires.
An example policy is in lua/examples/policy.lua.
Note that only request packets and granted packets with capabilities about to expire go through a policy decision. The bulk of the traffic that Grantor servers receive are granted packets with non-expiring capabilities. Grantor servers handle these packets simply decapsulating and transmitting them to the ultimate destination. The GT block is the block that implements Grantor’s core functions.
To run the executable as a Grantor server (as opposed to a Gatekeeper server), then local gatekeeper_server in lua/main_config.lua should be set to false
All other static configuration variables can be configured in lua/gt.lua.
These variables are likely to change from deployment-to-deployment based on the operator's preferences.
n_lcores
The number of GT instances to run in parallel.
log_level
The log level for the GT block. Can be set to any one of the following values: RTE_LOG_EMERG, RTE_LOG_ALERT, RTE_LOG_CRIT, RTE_LOG_ERR, RTE_LOG_WARNING, RTE_LOG_NOTICE, RTE_LOG_INFO, RTE_LOG_DEBUG.
Since we typically use RTE_LOG_ERROR as the most severe log condition, we recommend not to set this value below RTE_LOG_ERROR.
lua_policy_file
Path to a Lua file that represents the policy that Grantor will enforce. It should have a function lookup_policy(pkt_info, policy) that the GT block will invoke with parameters struct gt_packet_headers *pkt_info and struct ggu_policy *policy.
It is not crucial to change these variables, and they only need to be changed to fine tune the performance of Gatekeeper. Otherwise, the default values are likely fine.
mailbox_max_entries_exp
The log (base 2) of the maximum size of the GT mailbox. For example, if the variable is set to 7, then room for 2^7 = 128 entries will be made in the mailbox.
Also used to determine how many entries will actually be available for use in the mailbox, which for efficiency reasons is one less than the maximum size of the mailbox (127 in the example above).
mailbox_mem_cache_size
Number of mailbox entries to keep in the cache for more efficient use of the mailbox. Set to 0 to disable the cache of the memory pool for the mailbox.
mailbox_burst_size
Maximum number of entries to receive in a burst every time the mailbox is checked.
log_ratelimit_interval_ms
The interval at which logs are rate limited (in milliseconds). For a given interval, only log_ratelimit_burst log entries are permitted. The count of entries is reset for each new interval.
log_ratelimit_burst
The number of entries per interval allowed to be logged. When the number of log entries exceeds this limit in a given interval, the entries will be dropped.
max_pkt_burst
Maximum number of packets received in each burst on the front interface. Grantor servers only receive packets on the front interface.
max_num_ipv6_neighbors
The maximum number of neighbor entries for the IPv6 forwarding table. For IPv4, the address space is small enough that we can allocate enough room for all possible neighbors. For IPv6, the address space is too large; therefore, we specify the expected maximum size of this table in the configuration.
Once the GT blocks make decisions on requests from Gatekeeper servers, GT blocks send out GGU packets to notify Gatekeeper servers about the decisions. As GGU packets are based on UDP, and one can identify the GGU packets based on the user specified pair of UDP port numbers. The two variables ggu_src_port and ggu_dst_port represents the UDP source and destination port numbers for GGU. Note that, these two variables should match the configuration in GGU block.
The GT blocks reassemble fragmented packets before making a policy decision. It utilizes DPDK IP Fragmentation and Reassembly Library, e.g., rte_ipv4_frag_reassemble_packet() for IPv4 packets and rte_ipv6_frag_reassemble_packet() for IPv6 packets.
Moreover, to avoid attackers overflowing the request channel with fragments that never complete, flows associated with fragments that have to be discarded before being fully assembled will be punished.
The following variables should be configured:
- frag_scan_timeout_ms: timeout for scanning the fragmentation table in ms.
- frag_bucket_num: the number of buckets in the fragmentation table.
- frag_bucket_entries: the number of entries per bucket. It should be a power of two.
- frag_max_entries: the maximum number of entries that could be stored in the fragmentation table.
- frag_max_flow_ttl_ms: the maximum TTL numbers are in ms.
Policy decisions (from Grantor servers to Gatekeeper servers) should be batched to reduce the number of packets that Gatekeeper has to handle. The variable batch_interval represents the number of iterations of packets processed by each GT block before flushing all policy decision notification packets. Set to 1 to flush after every RX iteration.
Variable max_ggu_notify_pkts represents the maximum number of Gatekeeper servers for which to keep policy decision notification packet buffers.
None.
There are various ways to configure and inspect the GT block at runtime using Gatekeeper's dynamic configuration.