-
Notifications
You must be signed in to change notification settings - Fork 231
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_base_directory
Path to the Lua base directory full of configuration files for Gatekeeper.
lua_policy_file
Path appended to lua_base_directory that is a Lua file representing the policy that Grantor will enforce. This file 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.
- frag_bucket_num
- frag_bucket_entries
- frag_max_entries
- frag_max_flow_ttl_ms
- frag_scan_timeout_ms
The GT instances may need to reassemble fragmented packets before making policy decisions. To do so, it utilizes the 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 are punished.
frag_bucket_num is the number of buckets in the fragmentation table.
frag_bucket_entries is the number of entries per bucket. It should be a power of two.
frag_max_entries is the maximum number of entries that could be stored in the fragmentation table.
frag_max_flow_ttl_ms is the maximum TTL for each packet (in milliseconds).
frag_scan_timeout_ms is the interval for scanning the entire fragmentation table (in millseconds).
- batch_interval
- max_ggu_notify_pkts
Policy decisions (from Grantor servers to Gatekeeper servers) are 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. To flush after every receiving iteration, set to 1.
Policies are batched on a per-Gatekeeper server basis. max_ggu_notify_pkts represents the maximum number of Gatekeeper servers for which to keep policy decision notification packet buffers.
These variables likely only need to be changed under extreme circumstances or for deployment-specific reasons.
ggu_src_port & ggu_dst_port
These variables represent the UDP port numbers used in packets sent from Grantor to the GT-GK Unit. They essentially identify packets as being a part of the GGU protocol. They are typically set to 0xA0A0 and 0xB0B0 respectively, and must match the corresponding port numbers configured for the GGU block.
The dynamic configuration enables the user to get the configuration parameters of an LPM table using the following function:
int, int lpm_get_paras(struct rte_lpm *lpm)- lpm is an LPM object handle
int, int lpm6_get_paras(struct rte_lpm6 *lpm)- lpm is an LPM6 object handle
The Grantor policy can be updated by calling update_gt_lua_states() in the dynamic configuration. It accepts as a parameter a GT configuration structure (struct gt_config) set with a new policy file.
For examples, see lua/examples/example_of_dynamic_config_request.lua.