HQ

This page describe the Lenses Agent configuration.

HQ's configuration is defined in the config.yaml file

EULA

To accept the Lenses EULA, set the following in the lenses.conf file:

Without accepting the EULA the Agent will not start! See License.

It has the following top level groups:

Name	Required	Default	Type	Description
http	Yes	n/a	HTTPConfig	Configures everything involving the HTTP.
agents	Yes	n/a	AgentsConfig	Controls the agent handling.
database	Yes	n/a	DatabaseConfig	Configures database settings.
logger	Yes	n/a	LoggerConfig	Sets the logger behaviour.
metrics	Yes	n/a	MetricsConfig	Controls the metrics settings.
license	Yes	n/a	License	Holds the license key.
auth	Yes	n/a	AuthConfig	Configures authentication and authorisation

---

AuthConfig

Configures authentication and authorisation.

It has the following fields:

Name	Required	Default	Type	Description
administrators	No	[]	strings	Grants root access to principals.
saml	no	n/a	SAMLConfig	Contains SAML2 IdP configuration.
users	no	[]	Array	Creates initial users for password based authentication.

AuthConfig: administrators

Lists the names of the principals (users, service accounts) that have root access. Access control allows any API operation performed by such principals. Optional. If not set, it will default to [].

AuthConfig: saml

Contains SAML2 IdP configuration. Please refer here for its structure.

---

HTTPConfig

Configures everything involving the HTTP.

It has the following fields:

Name	Required	Default	Type	Description
address	Yes	n/a	string	Sets the address the HTTP server listens at.
accessControlAllowOrigin	No	["*"]	strings	Sets the value of the "Access-Control-Allow-Origin" header.
accessControlAllowCredentials	No	false	boolean	Sets the value of the "Access-Control-Allow-Credentials" header.
secureSessionCookies	No	true	boolean	Sets the "Secure" attribute on session cookies.
tls	Yes	n/a	TLSConfig	Contains TLS configuration.

HTTPConfig: address

Sets the address the HTTP server listens at.

Example value: 127.0.0.1:80.

HTTPConfig: accessControlAllowOrigin

Sets the value of the "Access-Control-Allow-Origin" header. This is only relevant when serving the backend from a different origin than the UI. Optional. If not set, it will default to ["*"].

HTTPConfig: accessControlAllowCredentials

Sets the value of the "Access-Control-Allow-Credentials" header. This is only relevant when serving the backend from a different origin than the UI. Optional. If not set, it will default to false.

HTTPConfig: secureSessionCookies

Sets the "Secure" attribute on authentication session cookies. When set, a browser sends such cookies not over unsecured HTTP (expect for localhost). If running Lenses HQ over unsecured HTTP, set this to false. Optional. If not set, it will default to true.

HTTPConfig: tls

Contains TLS configuration. Please refer here for its structure.

---

SAMLConfig

Contains SAML2 IdP configuration.

It has the following fields:

Name	Required	Default	Type	Description
metadata	Yes	n/a	string	Contains the IdP issued XML metadata blob.
baseURL	Yes	n/a	string	Defines base URL of HQ for IdP redirects.
uiRootURL	No	/	string	Controls where to redirect to upon successful authentication.
entityID	Yes	n/a	string	Defines the Entity ID.
groupAttributeKey	No	groups	string	Sets the attribute name for group names.
userCreationMode	No	manual	string	Controls how the creation of users should be handled in relation to SSO information.
groupMembershipMode	No	manual	string	Controls how the management of a user's group membership should be handled in relation to SSO information.

SAMLConfig: metadata

Contains the IdP issued XML metadata blob.

Example value: <?xml version="1.0" ... (big blob of xml) </md:EntityDescriptor>.

SAMLConfig: baseURL

Defines the base URL of Lenses HQ; the IdP redirects back to here on success.

Example value: https://hq.example.com.

SAMLConfig: uiRootURL

Controls where the backend redirects to after having received a valid SAML2 assertion. Optional. If not set, it will default to /.

Example value: /.

SAMLConfig: entityID

Defines the Entity ID.

Example value: https://hq.example.com.

SAMLConfig: groupAttributeKey

Sets the attribute name from which group names are extracted in the SAML2 assertions. Different providers use different names. Okta, Keycloak and Google use "groups". OneLogin uses "roles". Azure uses "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups". Optional. If not set, it will default to groups.

Example value: groups.

SAMLConfig: userCreationMode

Controls how the creation of users should be handled in relation to SSO information. With the 'manual' mode, only users that currently exist in HQ can login. Users that do not exist are rejected. With the 'sso' mode, users that do not exist are automatically created. Allowed values are manual or sso. Optional. If not set, it will default to manual.

SAMLConfig: groupMembershipMode

Controls how the management of a user's group membership should be handled in relation to SSO information. With the 'manual' mode, the information about the group membership returned from an Identity Provider will not be used and a user will only be a member of groups that were explicitly assigned to him locally. With the 'sso' mode, group information from Identity Provider (IdP) will be used. On login, a user's group membership is set to the groups listed in the IdP. Groups that do not exist in HQ are ignored. Allowed values are manual or sso. Optional. If not set, it will default to manual.

AgentsConfig

Controls the agent handling.

It has the following fields:

Name	Required	Default	Type	Description
address	Yes	n/a	string	Sets the address the agent server listens at.
tls	Yes	n/a	TLSConfig	Contains TLS configuration.

AgentsConfig: address

Sets the address the agent server listens at.

Example value: 127.0.0.1:3000.

AgentsConfig: tls

Contains TLS configuration. Please refer here for its structure.

---

TLSConfig

Contains TLS configuration.

It has the following fields:

Name	Required	Default	Type	Description
enabled	Yes	n/a	boolean	Enables or disables TLS.
cert	No	``	string	Sets the PEM formatted public certificate.
key	No	``	string	Sets the PEM formatted private key.
verboseLogs	No	false	boolean	Enables verbose TLS logging.

TLSConfig: enabled

Enables or disables TLS.

Example value: false.

TLSConfig: cert

Sets the PEM formatted public certificate. Optional. If not set, it will default to ``.

Example value: -----BEGIN CERTIFICATE----- EXampLeRanDoM ... -----END CERTIFICATE----- .

TLSConfig: key

Sets the PEM formatted private key. Optional. If not set, it will default to ``.

Example value: -----BEGIN PRIVATE KEY----- ExAmPlErAnDoM ... -----END PRIVATE KEY----- .

TLSConfig: verboseLogs

Enables additional logging of TLS settings and events at debug level. The information presented might be a bit too much for day to day use but can provide extra information for troubleshooting TLS configuration. Optional. If not set, it will default to false.

---

DatabaseConfig

Configures database settings.

It has the following fields:

Name	Required	Default	Type	Description
host	Yes	n/a	string	Sets the name of the host to connect to.
username	No	``	string	Sets the username to authenticate as.
password	No	``	string	Sets the password to authenticate as.
database	Yes	n/a	string	Sets the database to use.
schema	No	``	string	Sets the schema to use.
TLS	No	false	boolean	Enables TLS.
params	No	{}	DBConnectionParams	Provides fine-grained control.

DatabaseConfig: host

Sets the name of the host to connect to. A comma-separated list of host names is also accepted; each host name in the list is tried in order.

Example value: postgres:5432.

DatabaseConfig: username

Sets the username to authenticate as. Optional. If not set, it will default to ``.

Example value: johhnybingo.

DatabaseConfig: password

Sets the password to authenticate as. Optional. If not set, it will default to ``.

Example value: my-password.

DatabaseConfig: database

Sets the database to use.

Example value: my-database.

DatabaseConfig: schema

Sets the schema to use. Optional. If not set, it will default to ``.

Example value: my-schema.

DatabaseConfig: TLS

Enables TLS. In PostgreSQL connection string terms, setting TLS to false corresponds to sslmode=disable; setting TLS to true corresponds to sslmode=verify-full. For more fine-grained control, specify sslmode in the params which takes precedence. Optional. If not set, it will default to false.

Example value: true.

DatabaseConfig: params

Contains connection string parameters as key/values pairs. It allow fine-grained control of connection settings. The parameters can be found here: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS Optional. If not set, it will default to {}.

Example value: {"application_name":"example"}.

LoggerConfig

Sets the logger behaviour.

It has the following fields:

Name	Required	Default	Type	Description
mode	Yes	n/a	string	Controls the format of the logger's output.
level	No	info	string	Controls the level of the logger.

LoggerConfig: mode

Controls the format of the logger's output. Allowed values are text or json.

LoggerConfig: level

Controls the level of the logger. Allowed values are info or debug. Optional. If not set, it will default to info.

MetricsConfig

Controls the metrics settings.

It has the following fields:

Name	Required	Default	Type	Description
prometheusAddress	No	:9090	string	Sets the Prometheus address.

MetricsConfig: prometheusAddress

Sets the address at which Prometheus metrics are served. Optional. If not set, it will default to :9090.

License

Holds the license key.

It has the following fields:

Name	Required	Default	Type	Description
key	Yes	n/a	string	Sets the license key.
acceptEULA	Yes	fals	boolean	Accepts the Lenses EULA.

License: key

Sets the license key. An HQ key starts with "licensekey".

License: acceptEULA

Accepts the Lenses EULA.