Legacy Netagent v1 Configuration

  • Updated on Sep 04, 2024

Note: Netagent v2 has been released. This article describes legacy Netagent v1 configuration, via config.yaml. For details on how to configure the latest Netagent v2, refer to the Access Tier local config API specification and API object.

Netagent v1 gets its runtime configuration from the config.yaml file, which will be located in the /opt/banyan folder after Netagent has been set up. The following configuration parameters can be customized in this file.

Standard

Standard parameters need to be set to custom values for your deployment.

Parameter Default Value Description
shield_address cluster-address:cluster-port Shield address as IP_ADDRESS:PORT. You can find this value in the Command Center by navigating to Directory & Infrastructure > Clusters, then locating the applicable Shield and copying the Shield Address.
one_time_key   One Time Key (available from Banyan Command Center) to register Netagent. You can find this value in the Command Center by navigating to Directory & Infrastructure > Clusters, then locating the applicable Shield and copying the One-time Key.
site_name   Display name of the Access Tier.
site_address   Public domain name or IP address of the Access Tier.

Logs and Metrics

Netagent produces robust logs and metrics. In production, you may need to tweak these parameters based on your operations tooling.

Parameter Default Value Description
console_log_level ERR Console log level: ERR,WARN,INFO,DEBUG
file_log_level INFO File log level: ERR,WARN,INFO,DEBUG
file_log true Log output to LOGFILENAME
log_num 10 Number of log files (auto-rotations).
log_size 50 Max size of each log file in megabytes
statsd false Turn on metrics collection using statsd
statsd_address 127.0.0.1:8125 Address to send statsd messages: “hostname:port” for UDP, “unix:///path/to/socket” for UDS

Events

Netagent generates Access Events every time a client accesses a protected resource. In production, you may need to tweak these parameters based on load.

Parameter Default Value Description
access_event_credits_limiting true Enable rate limiting of Access Event generation based on a credit-based rate control mechanism. The mechanism consumes one “credit” each time an Access Event is generated. If there are no credits available, the Access Event is not generated (skipped). Netagent obtains new credits at a specified rate, which is 1 credit every 1 minute, by default. Credits are accumulated up to a maximum limit (default limit is 1000 credits). When a new Access Event is ready to be generated, it is first subjected to rate limiting by key (see access_event_key_limiting below). If the Access Event survives rate limiting by key, it then passes to rate limiting by credits. If it survives both rate limiters, then the Access Event is generated and sent to the Command Center.
access_event_credits_per_interval 5 Number of new credits obtained in each time period.
access_event_credits_interval 1m Periodic time interval for obtaining new credits.
access_event_credits_max 5000 Upper limit on number of credits that Netagent can accumulate. This bounds the maximum burst size for Access Event generation.
access_event_key_limiting true Enable rate limiting of Access Event generated based on a derived “key” value. Each key has a separate rate limiter, and events with the same key value are subjected to the rate limiter for that key. The key value is a combination of the source IP address, the destination IP and port, and the client’s email address. One Access Event can be generated for each key value each time interval (default 9 minutes). When a new Access Event is ready to be generated, it is subjected to rate limiting by key. If the Access Event survives rate limiting by key, it then passes to rate limiting by credits (see access_event_credits_limiting above). If it survives both rate limiters, then the Access Event is generated and sent to the Command Center.
access_event_key_expiration 9m Time interval to allow generating one Access Event for each key value.

Hosted Web Services

Parameter Default Value Description
redirect_to_https true Automatically redirect all port 80 http requests to port 443 https
groups_by_userinfo true Obtain user groups by querying the userinfo endpoint instead of including groups claim in the trust token (useful when a user can be long to a large number of groups causing token size to exceed browser limits on cookie length)
forward_trust_cookie false Forward the banyan trust cookie to upstream servers. This may be enabled if upstream servers wish to make use of information in the banyan trust cookie.

Infrastructure Services

Parameter Default Value Description
http_connect true Support Banyan services that specify to proxy connections to upstream servers using HTTP CONNECT
maximum_session_timeout 43200s Maximum lifetime of a TCP connection.

Denial of Service (DOS) Protection

Parameter Default Value Description
bad_actor false Enable Denial of Service protection to block bad actors. This feature detects clients that continually make unauthorized accesses to services and then places the “bad actor” in “jail” by setting a firewall rule to ignore their traffic (via IP address) temporarily, similar to tools like SSHGuard and Fail2ban.
infraction_count 10 Bad actor: Number of infractions to put a client address in the jail.
sentence_time 10m Time period that a bad actor client address stays in the jail.

Other Parameters

These parameters can be modified according to your organization’s needs.

Parameter Default Value Description
secure_bootstrap true Set to true if Shield requires secure bootstrapping
access_tier true Deploy Netagent in Access Tier mode (true) or Host Agent mode (false)
site_domain_names “*” Comma-separated list of domain names that can alias the site_address. This setting is REQUIRED if access_tier=true.
host_tags   List of arbitrary key: value pairs that Netagent will use in attribute matching for Banyan services. For example, suppose Netagent is configured with the following two host tags: ostype: linux, and deployment: prod. Then, a Banyan service with attribute com.banyanops.hosttag.deployment=prod would match this Netagent. In addition, in Host Agent mode, all local processes and containers will be assigned virtual labels with these host tags.
listen_port 9999 TCP listen port on localhost for proxying incoming connections
listen_port_health 9998 TCP listen port on all local IPs for Netagent health check
https_proxy   Establish control connection to Shield using an HTTP CONNECT proxy (when non-empty, this setting overrides the value of the HTTPS_PROXY environment variable)
site_autoscale false Indicate to the command center that this Access Tier site is autoscale-enabled.
public_ip_source default Method that Netagent will use to determine the host’s public IP. Possible values for this setting are: AWS, GCE, default, none
cpu_limit 100 Max percentage usage of each CPU core [1-100]. Controlled using Linux cgroups.

Debugging Parameters

These parameters are typically used only while debugging Netagent:

Parameter Default Value Description
http_backend_log false Turn on verbose logging of HTTP backend traffic
visibility_only false Visibility-only mode. In this mode, Netagent will not intercept traffic or provide any policy enforcement.
shield_timeout 0 If Shield is unavailable for this duration, then all policies are treated as though they were in permissive mode (default is 0=disabled).
keep_alive true Enable TCP keepalive messages.
keep_idle 59s Idle time before sending TCP keepalive.
keep_interval 59s Time between consecutive TCP keepalives.
keep_count 3 Number of missing keepalive ACKs before closing connection.
cpu_profile   Enable CPU profiling by providing a pathname for the profiling output file.
mem_profile false Enable memory usage profiling.
host_only true Host-only mode (set to false only for debugging).
disable_docker false Disable monitoring Docker.
send_zeros false Send all-zero data points to Shield.
period 20 Statistics reporting interval [secs].
request_level_events true Enable request level access events.
address_transparency true Provide client address transparency (forced to false when access_tier is true).
use_rsa false Use RSA instead of ECDSA keys.
full_server_cert_chain true Include non-root CA certs in the TLS handshake server cert chain.
code_flow true Enable OpenID Connect code flow.
inactivity_timeout 3600s HTTP timeout.
client_timeout 20s Client identification timeout.

Deprecated Parameters

Parameter Default Value Description
services_from_file false Read service specifications from a local file.
services_file_name /opt/banyan/services.json Filename for service specifications (only relevant if services_from_file=true)
kubelet false Access Kubernetes kubelet for pod info.
kubelet_addr http://localhost:10255 Kubernetes kubelet “addr:port”.
istio false Use Istio.
istio_address http://localhost:10259 Address to access Istio data.
istio_auth_listen “localhost:9990” Address to listen for Istio authorization requests.
forward false Forwarding gateway mode, e.g., VPN.
forward_ingress   List of ingress CIDRs for forwarding gateway mode (for example, VPN).
oidc_strict_host false Perform redirects for OpenID Connect only if HTTP request host matches domain name in service spec.
cert_lifetime 24h Certificate lifetime. Certificates renewal occurs automatically prior to expiry.
kafka_log_num 2 Number of kafka log files (auto-rotations).
kafka_log_size 50 Max size of each kafka log file in megabytes.
kernel true Use the kernel module (true) or not (false – debug-only setting).
disable_layer_7 true Disable L7 protocol parsing (this setting only affects traffic visibility)
ignore_traffic   This setting only affects traffic visibility (primarily for Host Agent mode). It is a list of local process names to ignore for traffic visibility reporting.