Overriding Default Vendor Configurations
Because package updates override Oracle Communications Unified Assurance configuration files with the latest default configurations, you cannot directly change the default configuration files. Instead, you can apply overrides in one of the following ways, depending on the vendor:
-
Create override files and merge them with the default configuration files using the ConfigHelper application. This applies to:
-
Grafana
-
InfluxDB
-
Kafka
-
OpenSearch
-
OpenSearch Dashboards
-
Telegraf
-
Telegraf-Kafka (included under Kafka)
-
-
Add custom configuration files to the configuration directory. This applies to:
-
Apache
-
MySQL
-
PHP
-
For other vendors, such as Neo4j, there are no supported update-safe overrides. You can change the default configuration file directly, but you will have to repeat this change manually every time you update Unified Assurance. See Editing Configuration Files Directly.
Oracle recommends testing all changes in a development or staging environment to identify and avoid any adverse affects changes may have on the overall Unified Assurance deployment.
Note:
If your environment uses redundant servers, you must make vendor configuration changes on both servers in the redundant pair. Changes made on one server are not automatically copied to the other server.
About Applying Override Files with ConfigHelper
You override default configurations by creating override files and applying them using ConfigHelper for the following vendors:
-
Grafana
-
InfluxDB
-
Kafka
-
OpenSearch
-
OpenSearch Dashboards
-
Telegraf
-
Telegraf-Kafka (included under Kafka)
The default configuration files for each vendor are in the vendor-specific subdirectories of the $A1BASEDIR/distrib/config directory. Base your override files on the configuration files with the .local extension. These are the version of the base configuration file that contains the settings localized for the local system and are handled by ConfigHelper.
When ConfigHelper merges the override files with the localized default configuration files, the custom changes override the default configuration settings, and any settings not included in the override file remain unchanged. In overrides for configuration files with no meaningful indentation or nested properties, you can include the properties you want to override only. See OpenSearch for an example. In overrides for configuration files with meaningful indentation or nested properties, such as those that include yaml formatting, you must include the top-level parent property of the property you want to override, and all of the parent property's contents. See Grafana for examples.
Anything commented out in override files is ignored completely. This means that commenting something out in the override file will not result in it being commented out in the merged configuration file. You can include comments to annotate the override file, but the resulting configuration file will not include any commented out text.
See Vendor Specific Information for details about the names and locations of default configuration files, override files, and merged configuration files, and examples of override file contents.
Applying Override Files with ConfigHelper
To create override files and apply them using ConfigHelper:
-
Log in to the command line for the server and change to the assure1 user:
su - assure1
-
Create vendor-specific directories for overrides on the Unified Assurance server:
mkdir -p $A1BASEDIR/etc/<vendor>.d/overrides
where <vendor> is the name of the vendor whose configuration you are overriding.
See Vendor Specific Information for the directory names to use for each vendor.
-
In the override directory, create the appropriate .override file containing the configuration parameters that you want to override. See Vendor Specific Information for the override file names to use for each vendor.
Tip:
In override files, you can use the $BASEDIR variable to represent the directory where you installed Unified Assurance and the $HOSTFQDN variable to represent the Unified Assurance host FQDN. In the merged configuration file, ConfigHelper substitutes these variables with their actual values. These are the only variables that are substituted automatically in overrides. You cannot use other typical Unified Assurance environment variables, such as $A1BASEDIR.
-
Change to the root user and set environment variables:
su - root source /<UA_home>/.bashrc
where <UA_home> is the directory where you installed Unified Assurance, typically /opt/assure1.
-
Do one of the following, depending on the vendor configuration you are overriding:
-
For InfluxDB, run ConfigHelper with the merge-restart InfluxDB argument:
$A1BASEDIR/bin/ConfigHelper merge-restart InfluxDB
-
For OpenSearch, run ConfigHelper with the merge-restart Opensearch argument:
$A1BASEDIR/bin/ConfigHelper merge-restart Opensearch
-
For other vendors, run ConfigHelper with no arguments:
$A1BASEDIR/bin/ConfigHelper
The application merges custom overrides with the default configuration files and restarts the vendor application using the resulting configurations.
-
Vendor Specific Information
The following sections contain reference information about the default configuration files, override files, and merged configuration files specific to each vendor. They also show examples of override file content.
Grafana
-
Default configuration file locations:
-
$A1BASEDIR/distrib/config/vendorGrafana
-
$A1BASEDIR/distrib/config/vendorGrafana/provisioning/datasources
-
-
Override file location: $A1BASEDIR/etc/grafana.d/overrides
-
Merged configuration file locations:
-
$A1BASEDIR/vendor/grafana/usr/share/grafana/conf
-
$A1BASEDIR/vendor/grafana/usr/share/grafana/conf/provisioning/datasources
-
-
File names: The following table lists the default overridable configuration files for Grafana, the corresponding override files, and the merged configuration files.
Default Configuration File Override File Merged Configuration File $A1BASEDIR/distrib/config/vendorGrafana/assure1.ini.local assure1.override $A1BASEDIR/vendor/grafana/usr/share/grafana/conf/assure1.ini $A1BASEDIR/distrib/config/vendorGrafana/provisioning/datasources/influxdb.yaml.local influxdb.override $A1BASEDIR/vendor/grafana/usr/share/grafana/conf/provisioning/datasources/influxdb.yaml -
Example assure1.override content: To change the location where Grafana writes log files, create an override file called assure1.override with the following content:
[paths] logs = /opt/assure1/logs/VendorGrafanaNewLocation
In assure1.override, you must include the property's heading. In the example, the heading is [paths]. Although assure1.ini.local contains multiple properties under each heading, you only have to include the property you are changing.
-
Example influxdb.override content: The base configuration file is in yaml, where indentation is meaningful. To avoid removing configurations, when changing a nested property, you must include its top-level parent property and all of the parent property's contents.
For example, to change timeInterval under jsonData, create an override file called influxdb.override with the following content, including the updated timeInterval property and everything else under the top-level datasources property:
datasources: - name: InfluxDB type: influxdb url: https://localhost/go/i/1 access: proxy database: Metric version: 3 basicAuth: true basicAuthUser: grafana basicAuthPassword: **** isDefault: true editable: false jsonData: timeInterval: 20s tlsAuth: false tlsAuthWithCACert: true tlsSkipVerify: true secureJsonData: basicAuthPassword: **** tlsCACert: $TLS_CABUNDLE_CERT_YAML
In this example, the password values have been anonymized.
InfluxDB
-
Default configuration file location: $A1BASEDIR/distrib/config/vendorInfluxDB
-
Override file location: $A1BASEDIR/etc/influxdb.d/overrides
-
Merged configuration file location: $A1BASEDIR/etc
-
File names: The following table lists the default overridable configuration file for InfluxDB, the corresponding override file, and the merged configuration file.
Default Configuration File Override File Merged Configuration File influxdb.conf.local influxdb.override influxdb.conf -
Example override content: To prevent InfluxDB from logging queries performed, create an override file called influxdb.override with the following content:
[data] query-log-enabled = false [http] log-enabled = false
You must include the property's heading. In the example, the headings are [data] and [http]. Although influxdb.conf.local contains multiple properties under each heading, you only have to include the property you are changing.
Kafka
-
Default configuration file location: $A1BASEDIR/distrib/config/vendorKafka
-
Override file location: $A1BASEDIR/etc/kafka.d/overrides
-
File names: The following table lists the default overridable configuration files for Kafka, the corresponding override files, and the merged configuration files.
Default Configuration File Override File Merged Configuration File consumer.properties.local consumer.override $A1BASEDIR/vendor/kafka/config/consumer.properties producer.properties.local producer.override $A1BASEDIR/vendor/kafka/config/producer.properties server.properties.local server.override $A1BASEDIR/vendor/kafka/config/server.properties telegraf-kafka.conf.local telegraf-kafka.override $A1BASEDIR/etc/telegraf-kafka.conf -
Kafka example: To have Kafka retain log files for 2 hours rather than the default 72 hours, create an override file called server.override with the following content:
log.retention.hours=2
-
Telegraf-Kafka example: To have Telegraf-Kafka include 100,000 metrics in the buffer in case writes fail, instead of the default 10,000, create an override file called telegraf-kafka.override with the following content:
[agent] metric_buffer_limit = 100000
You must include the property's heading. In the example, the heading is [agent]. Although telegraf-kafka.conf.local contains multiple properties under each heading, you only have to include the property you are changing.
OpenSearch
-
Default configuration file location: $A1BASEDIR/distrib/config/vendorOpenSearch
-
Override file location: $A1BASEDIR/etc/opensearch.d/overrides
-
Merged configuration file location: $A1BASEDIR/vendor/opensearch/config
-
File names: The following table lists the default overridable configuration files for OpenSearch, the corresponding override files, and the merged configuration files.
Default Configuration File Override File Merged Configuration File opensearch.yml.local opensearch.override opensearch.yml log4j2.properties.local log4j2.override log4j2.properties -
Example override content: To change the location where OpenSearch writes log files, create an override file called opensearch.override with the following content:
path.logs: /opt/assure1/logs/VendorOpenSearchNewLocation
-
Example nested override content: Some properties in opensearch.yml.local include meaningful indentation. To avoid removing configurations, when changing a nested property, you must include its top-level parent property and all of the parent property's contents.
For example, to add another node certificate to the distinguished names list, create an override file called opensearch.override with the following content, including all existing plugins.security.nodes_dn entries in addition to the new one:
plugins.security.nodes_dn: - "CN=assure1" - "CN=user2"
OpenSearch Dashboards
-
Default configuration file location: $A1BASEDIR/distrib/config/vendorOpenSearch-Dashboards
-
Override file location: $A1BASEDIR/etc/opensearchdashboards.d/overrides
-
Merged configuration file location: $A1BASEDIR/vendor/opensearchdashboards/config
-
File names: The following table lists the default overridable configuration file for OpenSearch Dashboards, the corresponding override file, and the merged configuration file.
Default Configuration File Override File Merged Configuration File opensearch_dashboards.yml.local kibana.override opensearch_dashboards.yml -
Example override content: To enable logging for all events, system usage information, and requests, and to log queries sent to OpenSearch, create an override file called kibana.override with the following content:
opensearch.logQueries: true logging.verbose: true
-
Example nested override content: Some properties in opensearch_dashboards.yml.local include meaningful indentation. To avoid removing configurations, when changing a nested property, you must include its top-level parent property and all of the parent property's contents.
For example, to change log rotation settings, create an override file called kibana.override with the following content, including everything under the top level logging property and updating the value of keepFiles:
logging: rotate: enabled: true everyBytes: 1100000 keepFiles: 30
Telegraf
-
Default configuration file locations:
-
$A1BASEDIR/distrib/config/vendorTelegraf (telegraf-temp.conf.local only)
-
$A1BASEDIR/distrib/config/vendorTelegraf/telegraf.d (all others)
-
-
Override file location: $A1BASEDIR/etc/telegraf.d/overrides
-
Merged configuration file location:
-
$A1BASEDIR/etc (telegraf.conf only)
-
$A1BASEDIR/etc/telegraf.d (all others)
-
-
File names: The following table lists the default overridable configuration files for Telegraf, the corresponding override files, and the merged configuration files.
Default Configuration File Override File Merged Configuration File telegraf-temp.conf.local telegraf.override telegraf.conf apache.conf.local apache.override apache.conf opensearch.conf.local opensearch.override opensearch.conf influxdb.conf.local influxdb.override influxdb.conf mysql.conf.local mysql.override mysql.conf a1procstat.conf.local a1procstat.override a1procstat.conf rabbitmq.conf.local rabbitmq.override rabbitmq.conf neo4j.conf.local neo4j.override neo4j.conf kafka.conf.local kafka.override kafka.conf system.conf.local system.override system.conf -
Example override content:
-
To prevent Telegraf from gathering metrics for overlay file systems, create an override file called 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"]
Although comments are included to annotate the override file, they do not appear in the final merged configuration file.
-
To change the logging level for Telegraf to debug, create an override file called telegraf.override with the following content:
[agent] debug = true
You must include the property's heading. In the examples, the headings are [[inputs.disk]] and [agent]. Although telegraf-temp.conf.local contains multiple properties under each heading, you only have to include the property you are changing.
-
Adding Custom Configuration Files
You can add custom configuration files for the following vendors:
-
Apache
-
PHP
-
MySQL
In the following sections, <purpose> represents any text that indicates the configuration file's purpose. For example, you could use file named base-phptimeout.conf when updating the user session length.
Apache and PHP
You can customize the default Apache or PHP configuration by adding custom .conf files to the $A1BASEDIR/etc/apache directory and restarting the web service. Although PHP does not support custom files, Apache does. You can use custom Apache configuration files to pass additional options to PHP. This does not include loading new PHP modules.
The .conf files must be named with the following format:
-
base-<purpose>.conf files are included in the primary Apache configuration section
-
ssl-<purpose>.conf files are included in the VirtualHost configuration section
-
base-php-<purpose>.conf files pass additional configuration options from Apache to PHP.
You can see sample custom configuration files in the $A1BASEDIR/distrib/config/vendorApache/apache directory.
To customize the default Apache or PHP configuration:
-
Change to the assure1 user:
su - assure1
-
In the $A1BASEDIR/etc/apache directory, add a custom configuration file called base-<purpose>.conf, ssl-<purpose>.conf, or base-php-<purpose>.conf. For example:
-
For Apache:
-
To enable debugging with non-minified Javascript libraries, copy the base-ui-debug.conf file from the $A1BASEDIR/distrib/config/vendorApache/apache directory.
-
To add additional configuration settings when using externally signed certificates, create a file called ssl-chain.conf with the following content:
SSLCertificateChainFile $A1BASEDIR/etc/ssl/intermediate.crt
-
-
For PHP:
-
To extend the time after the last API call before user sessions time out, including refresh calls made by UIs that refresh automatically, like dashboards or the event list, create the base-php.conf file with the following content:
php_value session.gc_maxlifetime 86400
-
To change the amount of memory a script can use from the default of 128 megabytes, create the base-php.conf file with the following content:
php_value memory_limit 256M
-
-
-
Change to the root user:
su - root
-
Restart the web service by running the following command:
service assure1-web restart
MySQL
You can customize the default MySQL configuration by adding <purpose>.cnf files to the $A1BASEDIR/etc/mysql directory and restarting the database service.
You can see sample custom configuration files in the $A1BASEDIR/distrib/config/vendorMySQL/mysql directory.
To customize the default MySQL configuration:
-
Change to the assure1 user:
su - assure1
-
In the $A1BASEDIR/etc/mysql directory, add a custom configuration file called <purpose>.cnf. For example:
-
To change the default maximum number of connections, create a file called custom-max_connections.cnf with the following content:
[mysqld] max_connections = 200
-
To change the INNODB buffer pool size that the database can use, create a file called custom-innodb_buffer_pool_size.cnf with the following content:
[mysqld] innodb_buffer_pool_size = 256M
-
To change the maximum permitted result length in bytes for the GROUP_CONCAT() function:
-
(Optional) Check the current group_concat_max_len setting by connecting to the database and running a query:
a1dbroot SELECT @@group_concat_max_len;
-
Create a file called custom-group_concat_max_len.cnf with the following content:
[mysqld] group_concat_max_len = 10000000
-
-
-
Change to the root user:
su - root
-
Restart the database service by running the following command:
service assure1-db restart
Editing Configuration Files Directly
For Neo4j, there are no update-safe overrides. You can edit the default configuration file directly to override it, then restart the Neo4j service. Because updating Unified Assurance restores default configuration files, you must redo these edits every time you update Unified Assurance.
The default Neo4j configuration file, neo4j.conf, is located in the $A1BASEDIR/etc/neo4j directory.
To edit the default Neo4j configuration file:
-
In the $A1BASEDIR/etc/neo4j directory, open the neo4j.conf file.
-
Update the lines you want to change in the file.
For example, to change the default amount of memory Neo4j uses:
-
Find the following lines:
dbms.memory.heap.initial_size=1g dbms.memory.heap.max_size=1g
-
Comment them out:
#dbms.memory.heap.initial_size=1g #dbms.memory.heap.max_size=1g
-
Add the following lines, with the new value for memory:
dbms.memory.heap.initial_size=2g dbms.memory.heap.max_size=2g
-
-
Save and close the file.
-
In the Unified Assurance UI, from the Configuration menu, select Broker Control, and then Services.
See Services in Unified Assurance User's Guide for information about this UI.
-
Select the Neo4j service and click the Restart button.