This document details subjects related to the administration of the VendorN Ltd OneDDI product (OneDDI).
The OneDDI User Guide documents in detail all aspects of the OneDDI Web User Interface (WebUI), including all sections of the WebUI related to administration.
This document is aimed at product administrators.
The WebUI is available using HTTPS. A default self-signed certificate will be installed following an initial installation. This can be modified post installation, and any change will be retained during any future upgrades.
The HTTPS certificate and key must be PEM formatted. The certificate and key can exist in separate files.
A different certificate can be specified simply by editing the
/opt/oneddi/config/master.json file, updating the following options:
"http": {
"main": {
"tls": {
"certfile": "config/tls-cert.pem",
"keyfile": "config/tls-key.pem"
},
...
},
...
},
After updating the above configuration the oneddi-master service must be
restarted.
By default following an initial installation the WebUI will be available on TCP port 443. This can be modified post installation, and any change will be retained during any future upgrades.
A different port can be specified simply by editing the
/opt/oneddi/config/master.json file, updating the port option:
"http": {
"main": {
...
"listen": {
"address": "0.0.0.0",
"port": 443
},
...
},
...
},
After updating the above configuration the oneddi-master service must be
restarted.
By default following an initial installation TLS version 1.0 and onwards will be supported. This can be modified post installation to require a newer TLS version.
The minimum required version can be specified simply by editing the
/opt/oneddi/config/master.json file, updating the following option:
"http": {
"main": {
"tls": {
...
"minimumVersion": "1.0"
},
...
},
...
},
Valid values are 1.0, 1.1, 1.2 and 1.3. Any other value will result in
1.0 being used.
After updating the above configuration the oneddi-master service must be
restarted.
By default after an initial installation all in-active sessions within the WebUI will expire after 3600 seconds, i.e. 1 hour. This can be modified post installation, and any change will be retained during any future upgrades.
A different value can be specified simply by editing the
/opt/oneddi/config/master.json file, updating the following option:
"http": {
"main": {
...
"sessionTimeout": 3600,
...
},
...
},
After updating the above configuration the oneddi-master service must be
restarted.
The OneDDI Login page will display a Message of the Day (MOTD) section. This an be modified post installation, and any change will be retained during any future upgrades.
This can be customized by editing the /opt/oneddi/config/motd.txt file. This
file can contain text, and will be displayed as is.
After updating the above configuration the oneddi-master service must be
restarted.
Users are permitted to change their own password in the OneDDI WebUI. When new users are defined in the OneDDI WebUI administrators must specify a password. In both cases the password must meet the complexity requirements of the configured password policy.
The password policy is configured in the /opt/oneddi/config/master.json file,
under the passwordPolicy attribute, for example:
"passwordPolicy": {
"description": "Password must be at least 8 characters and contain at least 1 upper case letter, 1 lower case letter, 1 number and 1 of '!@#$%^&*'",
"regex": "^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.*[!@#\\$%\\^&\\*])(?=.{8,})"
},
By default, the configured regex requires:
Administrators can modify this regular expression to restrict the requirements further simply by editing this attribute.
NOTE Modifying this attribute will not affect existing passwords.
After updating the above configuration the oneddi-master service must be
restarted.
The OneDDI agent and sensor components to not store any persistent, therefore do not require any backup or restore. All sections relating to Redundancy apply to the main OneDDI application.
All OneDDI data is stored in the /opt/oneddi/database/master.sqlite3 database.
This can be accessed using the sqlite3 tool, for example:
sqlite3 /opt/oneddi/database/master.sqlite3 "select count(*) from auditEntries"
To backup a OneDDI instance simply use the .backup command and then compress
the resulting file:
sqlite3 database/master.sqlite3 ".backup /tmp/master.sqlite3"
gzip /tmp/master.sqlite3
This will write a copy of the database to the /tmp/master.sqlite3 file which
is then compressed to the /tmp/master.sqlite3.gz file. This compressed file
is essentially a copy of the database as is. The main advantage over simply
copying the database file is that the .backup command can be used while the
OneDDI application is still running.
Once the compressed backup file has been created simply copy to some form of backup medium for storage.
To restore the compressed backup, copy the file over to the OneDDI server, stop the OneDDI application and re-instate the backup file over the top of the existing database:
systemctl stop oneddi-master
rm /opt/oneddi/database/master.sqlite3-shm
rm /opt/oneddi/database/master.sqlite3-wal
gunzip -c /tmp/master.sqlite3.gz > /opt/oneddi/database/master.sqlite3
systemctl start oneddi-master
Following this the backup will have been re-instated.
Backup instances should use the above commands to acquire a backup and restore to themselves. This can be done via cron and SSH commands.
There is no need to stop any of the services on the backup instances, other than to prevent users from accessing the backup servers while the live is online, and making changes that would otherwise be lost the next time the backup is restored.
The Settings / Redundancy / Replication Operation & Management section in the User Guide details how replication is implemented and managed.
In brief, two OneDDI instances are required to form a replication pair. One instance is active and replicates changes to the other standby instance. Once configured a standby instance will connect to its configured peer, the active instance, to receive and apply replication changes to its database.
There are two methods by which replication can be managed. If the active peer is available, the Settings / Redundancy page in the WebUI of the active peer can be used. The Settings / Redundancy section in the User Guide documents the various replication functions which can be performed using the WebUI.
If the active peer is not available the replication command must be used. See the Redundancy / Replication / The Replication Command section for how to use the replication command. Various other sections under the Redundancy / Replication section document how to use the replication command for specific use cases.
Details of how to backup of a single OneDDI instance, and restore the backup, is detailed in the Redundancy / Backup & Restore section. Depending on requirements, the real-time replication feature provided by OneDDI can be used in conjunction with the backup and restore feature.
For example, four OneDDI instances can be used, divided into two replication pairs, with replication configured. One pair would be backed up and restored into the other pair. One pair can be considered “live” while the other the “backup”, with the backup from the “live” active peer being restored into the “backup” active peer, and the backup from the “live” standby peer being restored into the “backup” standby peer.
The replication command can be used to manage specific replication functions for a single active or standby instance, with some functions applying only to one of these roles.
The replication command is located under the OneDDI installation directory, and is executed as follows:
cd /opt/oneddi
sudo ./replication
Run with no arguments some basic usage is displayed:
sudo ./replication
usage: ./replication deconfigure <config-file>
./replication configure-as-active <config-file>
./replication configure-as-standby <config-file>
./replication synchronise-database <config-file>
Each function supported by the replication command requires a <config-file>
parameter. This is the same master.json configuration file used by the
OneDDI master server, which contains several parameters required to interact
with replication features. This file is located under the /opt/oneddi/config
directory.
When run with all the correct parameters all functions will print the following message:
Please confirm the action by appending the command-line switch '--confirm' at the end of the command
This is a simple safety measure to ensure the intended action is in fact required. Running the command again with the extra parameter will then execute that command.
For example, if an instance is a standby peer, to force it to synchronise its database with the active peer, the following command would be run on the standby peer:
sudo ./replication synchronise-database config/master.json
This will result in the following message being displayed:
sudo ./replication synchronise-database config/master.json
Please confirm the action by appending the command-line switch '--confirm' at the end of the command
Only after appending the --confirm parameter will the command actually be
run, as follows:
sudo ./replication synchronise-database config/master.json --confirm
Synchronising local database from active peer...
Local database synchronised!
For automation, or to bypass this check, this parameter can simply be appended in the first instance.
Failover of a standby peer (so that it has an active role) can be performed using the WebUI on the active peer. The WebUI will automatically reconfigure the roles on both the active and standby so that only one is active and one is standby. If the active peer is not available the replication command can be used to change the role of a standby peer to be active.
If the active peer is still available, or becomes available, both peers will have an active role. In this case, one of the peers should be reconfigured to be the standby peer. The Redundancy / Replication / Failback an Active Peer section can be followed to reconfigure an active peer to be a standby peer.
The following command can be used to failover a standby peer - so that it has an active role:
sudo ./replication configure-as-active config/master.json
Failback of an active peer (so that it has a standby role) is automatically performed when using the WebUI on the active peer to failover. The WebUI will automatically reconfigure the roles on both the active and standby so that only one is active and one is standby. The WebUI cannot be used in the case there are two active pairs, e.g. failover was performed so that the standby is now active following a disaster recovery scenario. In this case the replication command can be used to change the role of an active peer to be standby.
The following command can be used to failback an active peer - so that it has a standby role:
sudo ./replication configure-as-standby config/master.json
In the event an active peer is lost failover should be invoked to reconfigure the standby peer to be an active peer. Once the originally active peer is recovered, either via a reinstallation or it is simply available again, some steps are required to restore the active/standby relationship and ensure changes are being replicated again.
If the recovered active peer still has OneDDI installed it can simply be reconfigured as the standby peer and it will automatically synchronise its database from the now active peer. The following command can be run on the recovered active peer to reconfigure the peer to be the standby peer:
sudo ./replication configure-as-standby config/master.json
If the recovered active peer no longer has OneDDI installed the WebUI on the now active peer can be used to deconfigure replication for the now active peer, and following the installation of OneDDI on the recovered active peer, the WebUI can then be used to configure replication again.
For both the methods above, if the recovered active peer should be active again, the WebUI on the now active peer can be used to failover so that the replication relationship is as it was before the recovered active peer was lost.
In the event the standby peer is lost and then recovered, and OneDDI was reinstalled, some steps are required to restore the active/standby relationship.
If OneDDI was not reinstalled, and the instance is still configured to be the standby peer, no steps are required. Upon starting, the standby peer will connect to the active peer and process all the replication changes which have been queued while the standby was unavailable.
If the recovered standby peer no longer has OneDDI installed the WebUI on the active peer can be used to deconfigure replication for the active peer, and following the installation of OneDDI on the recovered standby peer, the WebUI can then be used to configure replication again.
Replication can be deconfigured using the WebUI on the active peer. The WebUI will automatically deconfigure replication on both the active and standby peers. If the active peer is not available the replication command can be used to deconfigure replication on a standby peer.
The following command can be used to deconfigure replication:
sudo ./replication deconfigure config/master.json