How To Override Default Vendor Configurations

No direct changes to the default Unified Assurance configuration files are supported since future package updates will overwrite them every time. Unified Assurance does allow overrides to be made by following the instructions in this guide. Some configuration changes may have adverse affects on the overall Unified Assurance product, so all changes are recommended to be tested in a development or staging environment prior to deployment in production.

Note:

In the below examples, the "*" can be replaced with any text that would be descriptive of the configuration file's purpose. As an example, a file name of base-phptimeout.conf could be used when updating the user session length.

WARNING:

When using a multi-server redundant environment, some vendor service changes that are made to one server will usually also need to be made to its redundant pair.

Support Modifications

Apache

The default configuration can be customized by including any base*.conf or ssl*.conf files that are in the $A1BASEDIR/etc/apache/ directory:

$A1BASEDIR/etc/apache/*.conf

base*.conf files are included in the primary configuration section.
ssl*.conf files are included in the VirtualHost configuration section.

The Vendor Apache Configuration package distributes several example customizations that are located in the $A1BASEDIR/distrib/config/vendorApache/apache/ directory.

Use case example 1

Enable debugging with non-minified Javascript libraries.

Copy the $A1BASEDIR/distrib/config/vendorApache/apache/base-ui-debug.conf file to the $A1BASEDIR/etc/apache directory.
Use the following command to restart the web service:
```
service assure1-web restart
```

Use case example 2

Additional configuration settings may be required when using externally signed certificates.

In the $A1BASEDIR/etc/apache directory, create the file ssl-chain.conf with the following content:
```
SSLCertificateChainFile $A1BASEDIR/etc/ssl/intermediate.crt
```
Use the following command to restart the web service:
```
service assure1-web restart
```

Elasticsearch

The default configuration can be customized by providing an elasticsearch.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorElasticsearch directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named elasticsearch.d if it does not already exist:
```
mkdir elasticsearch.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Elasticsearch should write log files into a custom location.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
In the $A1BASEDIR/etc/elasticsearch.d/overrides/ directory, create the file elasticsearch.override with the following content:

Note:

Be sure to replace the [[$A1BASEDIR]] placeholder with the actual path of the installation.
```
path.logs: [[$A1BASEDIR]]/logs/VendorElasticsearchCustom
```
Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart elasticsearch when done:
```
$A1BASEDIR/bin/ConfigHelper merge-restart Elasticsearch
```
Note:

Be sure to call ConfigHelper passing in the arguments as above as otherwise Elasticsearch configurations will not be merged.

Filebeat

The default configuration can be customized by providing a filebeat.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorFilebeat directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named filebeat.d if it does not already exist:
```
mkdir filebeat.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Filebeat should ignore log files with Metric in the name.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/filebeat.d/overrides/ directory, create the file filebeat.override with the following content:

Note:

Be sure to replace the [[$A1BASEDIR]] placeholder with the actual path of the installation.

filebeat.inputs:
- type: log
  paths:
   - [[$A1BASEDIR]]/logs/*.log
  exclude_files: ['.*relocate.*', '.*Vendor.*', '.*Metric.*']
  close_removed: true
  pipeline: "assure1-log"
  json.keys_under_root: true
  json.add_error_key: true
  json.overwrite_keys: true
  json.message_key: level

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart filebeat when done:
```
$A1BASEDIR/bin/ConfigHelper
```

Use case example 2

Filebeat should ignore Debug log messages.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/filebeat.d/overrides/ directory, create the file filebeat.override with the following content:

Note:

Be sure to replace the [[$A1BASEDIR]] placeholder with the actual path of the installation.

filebeat.inputs:
- type: log
  paths:
   - [[$A1BASEDIR]]/logs/*.log
  exclude_files: ['.*relocate.*', '.*Vendor.*']
  close_removed: true
  pipeline: "assure1-log"
  json.keys_under_root: true
  json.add_error_key: true
  json.overwrite_keys: true
  json.message_key: level
  exclude_lines: ['^DEBUG']

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart filebeat when done:
```
$A1BASEDIR/bin/ConfigHelper
```

Grafana

The default configuration can be customized by providing an assure1.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorGrafana directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named grafana.d if it does not already exist:
```
mkdir grafana.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Grafana should use a different log file location.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
In the $A1BASEDIR/etc/grafana.d/overrides/ directory, create the file assure1.override with the following content:

Note:

Be sure to replace the [[$A1BASEDIR]] placeholder with the actual path of the installation.
```
[paths]
data = [[$A1BASEDIR]]/var/grafana
logs = [[$A1BASEDIR]]/logs/VendorGrafanaNewLocation
```
Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart grafana when done:
```
$A1BASEDIR/bin/ConfigHelper
```

InfluxDB

The default configuration can be customized by providing an influxdb.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorInfluxDB directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named influxdb.d if it does not already exist:
```
mkdir influxdb.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

InfluxDB should not log queries performed.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/influxdb.d/overrides/ directory, create the file influxdb.override with the following content:

[data]
  # Whether queries should be logged before execution. Very useful for troubleshooting, but will
  # log any sensitive data contained within a query.
  query-log-enabled = false

[http]
  # Determines whether HTTP request logging is enabled.
  log-enabled = false

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart InfluxDB when done:
```
$A1BASEDIR/bin/ConfigHelper merge-restart InfluxDB
```
Note:

Be sure to call ConfigHelper passing in the arguments as above as otherwise InfluxDB configurations will not be handled.

Kafka

The default configuration can be customized by providing an server.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorKafka directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named kafka.d if it does not already exist:
```
mkdir kafka.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Kafka should retain log files for 2 hours rather than the default 72 hours.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/kafka.d/overrides/ directory, create the file server.override with the following content:

############################# Log Retention Policy #############################

# The following configurations control the disposal of log segments. The policy can
# be set to delete segments after a period of time, or after a given size has accumulated.
# A segment will be deleted whenever *either* of these criteria are met. Deletion always happens
# from the end of the log.

# The minimum age of a log file to be eligible for deletion due to age
# Assure1 default set to 72 hours (3 days) OTB default was 168 hours (7 days)
log.retention.hours=2

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart kafka when done:
```
$A1BASEDIR/bin/ConfigHelper
```

Kibana

The default configuration can be customized by providing an kibana.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorKibana directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named kibana.d if it does not already exist:
```
mkdir kibana.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Kibana logs should have a 2 megabyte size limit instead of the default 50 megabytes.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/kibana.d/overrides/ directory, create the file kibana.override with the following content:

Note:

Be sure to replace the [[$A1BASEDIR]] placeholder with the actual path of the installation.

logging:
  appenders:
    file:
      type: rolling-file
      fileName: [[$A1BASEDIR]]/logs/VendorKibana.log
      policy:
        type: size-limit
        size: 2mb
      strategy:
        type: numeric
        pattern: '-%i'
        max: 2
      layout:
        type: json
  events:
    requests: "*"
    response: "*"
  root:
    appenders: [default, file]
    level: info
  loggers:
    - name: server
      level: info
      appenders: [default, file]
    - name: plugins
      level: info
      appenders: [default, file]

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart kibana when done:
```
$A1BASEDIR/bin/ConfigHelper
```

MySQL

The default configuration can be customized by including any *.cnf files that are in the $A1BASEDIR/etc/mysql/ directory.

$A1BASEDIR/etc/mysql/*.cnf

The Vendor MySQL Configuration package distributes several example customizations that are located in the $A1BASEDIR/distrib/config/vendorMySQL/mysql/ directory.

Use case example 1

The default maximum number of connections is 100. This can be updated, if required.

In the $A1BASEDIR/etc/mysql/ directory, create the file custom-max_connections.cnf with the following content:
```
[mysqld]
max_connections = 200
```
Use the following command to restart the database service.
```
service assure1-db restart
```

Use case example 2

The default INNODB Buffer Pool Size the database can use is 128 megabytes. This can be updated, if required.

In the $A1BASEDIR/etc/mysql/ directory, create the file custom-innodb_buffer_pool_size.cnf with the following content:
```
[mysqld]
innodb_buffer_pool_size = 256M
```
Use the following command to restart the database service:
```
service assure1-db restart
```

Use case example 3

The group_concat_max_len value is the maximum permitted result length in bytes for the GROUP_CONCAT() function.

The maximum allowed value is 18446744073709551615, the minimum is 4.

To check what group_concat_max_len is currently set to:

Switch to the assure1 user
```
su - assure1
```
Connect to the database as root user
```
a1dbroot
```
Run the following command to see what the value is currently set to
```
SELECT @@group_concat_max_len;
```

To update group_concat_max_len to a new value.

Switch to the assure1 user:
```
su - assure1
```
Add the file custom-group_concat_max_len.cnf in the $A1BASEDIR/etc/mysql/ directory.
Add the following to the file to update the value to 10000000:
```
[mysqld]
group_concat_max_len = 10000000
```
Switch to the root user:
```
su - root
```
Use the following command to restart the database service:
```
systemctl restart assure1-db
```

Neo4j

The default configuration can be customized by changing the neo4j.conf file that is in the $A1BASEDIR/etc/neo4j/ directory.

$A1BASEDIR/etc/neo4j/neo4j.conf

Use case example 1

The default amount of memory Neo4j will use is 1 gigabyte. This can be updated, if required.

In the $A1BASEDIR/etc/neo4j/ directory, edit the neo4j.conf file.

Find and comment the existing lines in the conf file:

dbms.memory.heap.initial_size=1g
dbms.memory.heap.max_size=1g

Copy and paste the below lines with a new value to change the amount of memory being used:
```
dbms.memory.heap.initial_size=2g
dbms.memory.heap.max_size=2g
```
Login to the UI and go to the broker control Services UI:

Configuration -> Broker Control -> Services
Find and select the "Neo4j" service, then click on the "Restart" button.

PHP

The default configuration can be customized by including any base-php*.conf files that are in the $A1BASEDIR/etc/apache/ directory.

$A1BASEDIR/etc/apache/base-php*.conf

Note:

PHP cannot include custom files, but Apache can. Apache can pass additional configuration options to PHP.
This does not include loading new PHP Modules.

Use case example 1

The default user session will timeout 8 hours after the last API call is made by the browser. This includes refresh calls made by interfaces that auto-refresh like Dashboards or the Event List. This can be extended for all users by updating the PHP variable in a custom Apache include file.

In the $A1BASEDIR/etc/apache/ directory, create the file base-php.conf if not already created.
Add the following in the conf file to set a session time out of 86400 seconds (one day):
```
php_value session.gc_maxlifetime 86400
```
Use the following command to restart the web service.
```
service assure1-web restart
```

Use case example 2

The default amount of memory a script can use is 128 megabytes. This can be updated, if required.

In the $A1BASEDIR/etc/apache/ directory, create the file base-php.conf if not already created.
Add the following in the conf file to set a higher maximum amount of memory that can be used:
```
php_value memory_limit 256M
```
Use the following command to restart the web service.
```
service assure1-web restart
```

Telegraf

The default configuration can be customized by providing an telegraf.override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

To find the applicable configuration file(s), navigate to the $A1BASEDIR/distrib/config/vendorTelegraf directory. The file(s) with the .local extension are the ones relevant on the local system and are handled by ConfigHelper. These are the files that can be overridden.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named telegraf.d if it does not already exist:
```
mkdir telegraf.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Telegraf should not gather metrics for overlay file systems.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/telegraf.d/overrides/ directory, create the file telegraf.override with the following content:

[[inputs.disk]]
## By default, telegraf gather stats for all mountpoints.
## Setting mountpoints will restrict the stats to the specified mountpoints.
# mount_points = ["/"]

## Ignore some mountpoints by filesystem type. For example (dev)tmpfs (usually
## present on /run, /var/run, /dev/shm or /dev).
ignore_fs = ["tmpfs", "devtmpfs", "overlay"]

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart telegraf when done:
```
$A1BASEDIR/bin/ConfigHelper
```

Use case example 2

Telegraf should run in a debug logging level.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
In the $A1BASEDIR/etc/telegraf.d/overrides/ directory, create the file telegraf.override with the following content:
```
[agent]
debug = true
```
Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart telegraf when done:
```
$A1BASEDIR/bin/ConfigHelper
```

Telegraf-Kafka

Note:

Telegraf-Kafka is listed separately here even though the telegraf-kafka.conf file is organized under the Kafka directory.

The default configuration can be customized by providing an override file containing the changes to be applied. This file will get merged with the default configuration file in a way that the custom changes will override the default configuration settings, and settings not added here will stay unchanged. Any commented out configuration items will be ignored completely in the merge process, so something commented out in the override file will not result in a change to that configuration item. Lastly, the resulting configuration file will not include any commented out text.

Preparation

Here are the steps to follow to prepare the installation for customized files.

Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```
As the assure1 user, navigate to the $A1BASEDIR/etc/ directory and create a folder named kafka.d if it does not already exist:
```
mkdir kafka.d
```
Still as the assure1 user, go into the newly created folder and create another folder named overrides if it does not already exist:
```
mkdir overrides
```

Use case example 1

Telegraf-Kafka should buffer 100,000 metrics instead of the default 10,000 in case writes fail.

The Preparation steps above should be followed before making any additional changes.
Login to the command line for the server, then change to the assure1 user:
```
su - assure1
```

In the $A1BASEDIR/etc/kafka.d/overrides/ directory, create the file telegraf-kafka.override with the following content:

# Configuration for telegraf agent
[agent]
  ## For failed writes, telegraf will cache metric_buffer_limit metrics for each
  ## output, and will flush this buffer on a successful write. Oldest metrics
  ## are dropped first when this buffer fills.
  ## This buffer only fills when writes fail to output plugin(s).
  metric_buffer_limit = 100000

Save and close the file.
Change to the root user.
Now, as the root user, run the ConfigHelper application to get the custom override merged in and the resulting configurations are used by the application. This command will also restart telegraf when done:
```
$A1BASEDIR/bin/ConfigHelper
```

Title and Copyright Information

Implementation Guide

F88952-01