Skip to content

Documentation

This guide covers advanced configurations and special use cases for the ONEInsight Agent that are not required for standard usage. These features are intended for experienced users who need fine-grained control over their deployment.

Supported Platforms

Note

Please note that Agent Modules may support different platforms. You can find the supported platforms in the Agent Modules Documentation.

Windows

OS Version Architectures Lifecycle
Windows 10 Client Version 1607+ x64 Windows
Windows 11 Version 22000+ x64 Windows
Windows Server 2012+ (*) x64 Windows Server
Windows Server Core 2012+ (*) x64 Windows Server
Nano Server Version 1809+ x64 Windows Server

* Windows Server 2012 and Windows Server 2012 R2 are supported with Extended Security Updates installed

Linux

OS Version Architectures Lifecycle
Alpine Linux 3.16+ x64 Alpine
Debian 11+ x64 Debian
Fedora 38+ x64 Fedora
openSUSE 15+ x64 OpenSUSE
Oracle Linux 8+ x64 Oracle
Red Hat Enterprise Linux 8+ x64 Red Hat
SUSE Enterprise Linux (SLES) 12 SP5+ x64 SUSE
Ubuntu 20.04+ x64 Ubuntu

ONEInsight Agent

Installation

  1. Download the latest ONEInsight Agent from ONEInsight Portal. An active account is required to log in.
  2. Extract the archive to a folder
  3. Run oneinsight-agent.exe with elevated permissions
  4. Follow the installation instructions in the terminal

Info

The agent will be installed in the current directory. Avoid moving the directory after installation and do not install in protected system directories like C:/Program Files.

  1. Download the latest ONEInsight Agent from ONEInsight Portal. An active account is required to log in.
  2. Extract the archive to /opt/oneinsight
  3. Run oneinsight-agent install with elevated permissions
  4. Create and start the systemd service: 
    sudo nano /etc/systemd/system/oneinsight-agent.service

    [Unit]
Description=OneInsight Agent Service
After=network.target

[Service]
Type=simple
ExecStart=/opt/oneinsight/oneinsight-agent server
Restart=on-failure
User=root
Group=root

[Install]
WantedBy=multi-user.target

    sudo systemctl daemon-reload
sudo systemctl enable oneinsight-agent
sudo systemctl start oneinsight-agent

Update

  1. Download the latest ONEInsight Agent from ONEInsight Portal
  2. Extract the archive to a temporary folder
  3. Run oneinsight-agent.exe with elevated permissions
  4. Follow the on-screen instructions

Info

After updating, delete both the binary file and the "data" folder from the temporary directory to free up space.

  1. Download the latest ONEInsight Agent package from ONEInsight Portal
  2. Stop the ONEInsight agent service: 
    sudo systemctl stop oneinsight-agent
  3. Extract the new package to /opt/oneinsight, replacing the existing binary
  4. Restart the ONEInsight agent service: 
    sudo systemctl start oneinsight-agent
  5. Verify the service status: 
    sudo systemctl status oneinsight-agent

Password reset

If you forgot the password, you are able to reset it via the ONEInsight Agent CLI.

Execute the command oneinsight-agent.exe reset-password in the installation folder with elevated permission.

Execute the command oneinsight-agent reset-password in the installation folderwith elevated permission.

The command generates a cryptographically secure temporary password that satisfies the active password policy profile.

Password policy

The password policy is selected in ./data/settings.ini. Changes take effect after restarting the ONEInsight Agent service.

[Authentication:Password]
Profile=Enhanced
Profile Minimum length Lowercase Uppercase Digit Special character
Standard 6 No No No No
Enhanced 12 Yes Yes Yes No
Strict 16 Yes Yes Yes Yes
NistInspired 15 No No No No

Standard, Enhanced, and Strict form a progressively stronger set of product and audit profiles. Standard retains the previous six-character minimum for compatibility and provides a lower security level than the other profiles.

NistInspired is a separate, length-based alternative. It follows the NIST recommendation of a 15-character minimum for passwords used as a single authentication factor and does not impose character-composition rules. It is not fully NIST-compliant because ONEInsight Agent does not compare new passwords against a blocklist of common or compromised passwords.

New installations use Enhanced. Existing configuration files with a missing or empty Profile value use Standard. Profile names are case-insensitive. An unknown value prevents startup and reports the allowed values.

The documented initial administrator password is a bootstrap exception and is created independently of the selected profile. The active profile applies when the password is changed and when reset-password generates a temporary password. Existing password hashes remain valid after changing profiles.

Uninstall

  1. Run oneinsight-agent uninstall with elevated permissions.
  2. Delete the folder where the ONEInsight Agent is installed.
  1. Stop the ONEInsight agent service 
    sudo systemctl stop oneinsight-agent
  2. Delete the ONEInsight agent service 
    sudo rm /etc/systemd/system/oneinsight-agent.service
  3. Delete the folder where the ONEInsight Agent is installed. 
    rm -r /opt/oneinsight

Configuration User Interface

The ONEInsight Agent serves a webpage for configuration. If you did not change the hosting port, the webpage is accessable at https://localhost:5002.

The ONEInsight Agent is only accessable after login.
Please use following credentials:

Default credentials

  • Username: admin
  • Password: OneInsight123!

After the first login, you will be asked to change your password. We highly recommend to change your password!

You will then see a newly generated password to login. Please change your password afterwards!

Agent Modules

The ONEInsight Platform analyzes data highly specialized for each system type. For that, there is a individual Agent Module for each system type.

Download Agent Module

Note

Please visit https://portal.mentiq.com/downloads and download the agent module for your target system type.

Installation

You can install or update an agent module either through the Web Interface or manually by following the steps outlined below:

  1. Navigate to the "Agent Modules" section in the Web Interface.
  2. Click the "Install" button.
  3. Upload the downloaded agent module file (Zip Archive or binary file).
  4. Click "Install" to complete the process.
  1. Copy the downloaded agent module into the <AgentInstallationFolder>/data/agent-modules directory
    • If you have downloaded a ZIP archive, ensure that you extract the binary file before proceeding.
  2. Ensure that the agent module has its own dedicated folder within /data/agent-modules. The folder name must match the name of the agent module's main executable. For example, if the executable is datadomain.exe, the folder should be /data/agent-modules/datadomain/.
  3. Go to the "Agent Modules" section on the Web Interface.
  4. Click the "Refresh" button. The ONEInsight Agent will detect and display the newly added agent modules.

Configure new system

  1. Navigate to "Systems" on the Webpage
  2. Click "Add New" Button
  3. Select the Agent Module you want to use
  4. Insert the connection details and click "Save & Test Connection"
  5. Please wait. After the connection test ended, you are redirected to saved system settings. You can see if the connection test was successfull

Web Server Configuration (Advanced)

ONEInsight Agent uses an INI file for web server configurations. You can find this file at ./data/settings.ini.

AllowedHosts = * ; The allowed hosts for the application

[Logging]
Verbose=false ; Set to true to enable verbose logging

[Authentication:Password]
# Allowed values: Standard, Enhanced, Strict, NistInspired. Restart required after changes.
Profile=Enhanced

[Server]
Port=5002 ; The port the server will listen on

[Server:Https]
Enabled=true ; Set to true to enable HTTPS
CertificatePath= ; Full path to the certificate file (required if Https is enabled)
CertificatePassword= ; The password for the certificate file

[Server:Https:Hsts]
Enabled=false ; HSTS is an explicit opt-in
Hosts= ; Comma-separated DNS host names, for example: agent01.example.internal
MaxAgeSeconds=86400 ; Start with one day; allowed range: 0-31536000

Firewall Rules for external access

To enable external access to the ONEInsight Agent Web UI, configure your firewall to allow the necessary connections.

Execute the following command: 

netsh advfirewall firewall add rule name="ONEInsight Agent" protocol=TCP dir=in localport=5002 action=allow description="Allow access to ONEInsight Agent web and REST API interface"

Execute the following command: 

sudo ufw allow 5002/tcp comment 'Allow access to ONEInsight Agent web and REST API interface'

Execute the following commands: 

sudo firewall-cmd --permanent --add-port=5002/tcp

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" port port="5002" protocol="tcp" accept log prefix="ONEInsight Agent: Allow access to web and REST API interface"'

sudo firewall-cmd --reload

SSL Certificate

By default, the ONEInsight Agent creates a self-signed SSL certificate during installation. Browsers will show a security alert when visiting the User Interface because the SSL certificate is not from an authorized provider. You can either ignore the security alert, trust the self-signed certificate, or use your own certificate.

Trust SSL Certificate (Windows)

To trust the self-signed SSL certificate, open the file ./data/cert.pfx and install it as a Trusted Root Certificate. You can find the certificate password in ./data/settings.ini.

Use your own SSL Certificate

Open ./data/settings.ini and change the Path and Password of the certificate in the section [Server:Https].

HTTP Strict Transport Security (HSTS)

HSTS support is available as an explicit opt-in and is disabled by default. Existing configuration files without a [Server:Https:Hsts] section continue to run with HSTS disabled.

Enable HSTS only when the Agent is always accessed through a stable DNS host name, HTTPS is permanently available, the certificate contains that host name, and every client trusts the certificate without a browser warning.

[Server:Https:Hsts]
Enabled=true
Hosts=agent01.example.internal
MaxAgeSeconds=86400

Hosts accepts one or more exact DNS host names separated by commas. Wildcards, URLs, localhost, names below .localhost, and IP addresses are rejected. HSTS headers are returned only for HTTPS requests whose host exactly matches this list. Subdomains are not included, and the HSTS preload directive is not used.

Access scenario Recommendation Reason
localhost with the generated self-signed certificate Do not enable HSTS Little additional protection for local traffic; certificate replacement or expiry can make browser access harder to recover.
IP address with a self-signed certificate Do not enable HSTS Standards-compliant browsers do not store HSTS policies for IP addresses. The certificate would also need the exact IP address as an IP SAN.
Server host name with an untrusted self-signed certificate Do not enable HSTS A browser should only learn HSTS over error-free, trusted HTTPS. Accepting a certificate warning is not a reliable HSTS deployment.
Stable server host name with a matching self-signed certificate trusted on every client May enable HSTS HSTS can prevent later HTTP use, but future certificate errors become non-bypassable while the policy is cached.
Stable internal/public DNS name with a matching certificate from a trusted CA Recommended where operationally appropriate This is the intended HSTS deployment model.

Warning

HSTS is cached by browsers for the configured duration and applies to the host name across ports, not only to the Agent port. Once a browser has learned the policy, certificate expiry, a name mismatch, or an untrusted replacement certificate normally cannot be bypassed. Verify certificate renewal and recovery procedures before enabling it.

Start with MaxAgeSeconds=86400 (one day). After successful operation and certificate-renewal testing, it can be increased up to 31536000 (one year).

To remove an existing browser policy safely:

  1. Keep HTTPS and the trusted certificate operational.
  2. Set Enabled=true and MaxAgeSeconds=0.
  3. Restart the Agent and access every configured host over HTTPS so clients receive Strict-Transport-Security: max-age=0.
  4. Then set Enabled=false if desired.

Changing HSTS configuration requires an Agent restart. Enabling HSTS without enabled HTTPS, without a host, or with a localhost/IP/wildcard host prevents startup and reports the invalid setting.

Transmission

E-Mail transmission

The collected autosupport data is transmitted by E-Mail to the ONEInsight Platform.

  1. Navigate to "Transmission" on the Webpage
  2. Select "Email" as Transmission Mode
  3. Insert your SMTP data

  4. Click "Save"

    Tip

    Please ensure that emails can be successfully sent to external mailboxes. To verify this, you can send a test email to an external address, such as your personal email. To do so, please click "Send Test Email" on the Transmission page. The ONEInsight Agent will send E-Mails to one of the following mailboxes: 

    autosupport01@mentiq.com
autosupport02@mentiq.com
autosupport03@mentiq.com
autosupport04@mentiq.com
autosupport05@mentiq.com
autosupport06@mentiq.com
autosupport07@mentiq.com
autosupport08@mentiq.com
autosupport09@mentiq.com
autosupport10@mentiq.com
    This list can change in future updates.

Folder transmission

For special use cases, the ONEInsight Agent can be set so that the Autosupport data is stored as a text file in a folder. Please see the special use cases section for more details.

  1. Navigate to "Transmission" on the Webpage
  2. Select "Folder" as Transmission Mode
  3. Insert your Folder Path
  4. Click "Save"

Special Use Cases

Host does not allow sending emails

If the host on which the ONEInsight Agent is installed does not allow sending emails, you can use folder transmission.

Install a ONEInsight Agent (1) on the host you want to monitor that does not have permission to send emails. Configure this agent to use Folder transmission and specify a shared folder.

Install a second ONEInsight Agent (2) on a host that can send emails. Configure it to use Email Delivery. Download and install the Folder transmission agent module, create a new system with this module, and use the shared folder in the configuration.

The ONEInsight Agent (1) collects autosupport data and writes it to the shared folder. The ONEInsight Agent (2) monitors this shared folder for new autosupport data. When new autosupport data is written, the ONEInsight Agent (2) reads the data and sends it via email to the ONEInsight platform.

Both ONEInsight Agents have cleanup routines to ensure that the shared folder does not become cluttered and that autosupport data is not sent twice.

sequenceDiagram
    participant Host 1 as ONEInsight Agent (1)
    participant Folder as Shared Folder
    participant Host 2 as ONEInsight Agent (2)
    participant Email as ONEInsight Platform

    Host 1->>Folder: Collects autosupport data and writes it
    Host 2->>Folder: Monitors for new autosupport data
    Folder->>Host 2: New autosupport data detected
    Host 2->>Email: Sends autosupport data via email
    Host 1-->>Folder: Cleanup routine (removes old data)
    Host 2-->>Folder: Cleanup routine (ensures no duplicates)

Using Mtree replication in CR Vault

If you want to monitor systems in a CR Vault, you do not have access to shared folders outside that vault and you cannot send email. In this case, you can use Mtree replication from the CR Vault to your production environment. Use the same setup as described in Host does not allow sending emails, but use your Mtree mount point as the folder.

sequenceDiagram
    participant Host 1 as ONEInsight Agent (1)
    participant Mtree 1 as Mtree Mount Point Vault DD
    participant Mtree 2 as Mtree Mount Point Production DD
    participant Host 2 as ONEInsight Agent (2)
    participant Email as ONEInsight Platform

    Host 1->>Mtree 1: Collects autosupport data and writes it
    Host 2->>Mtree 2: Monitors for new autosupport data
    Mtree 2->>Host 2: New autosupport data detected
    Mtree 1->>Mtree 2: Mtree Replication
    Host 2->>Email: Sends autosupport data via email
    Host 1-->>Mtree 1: Cleanup routine (removes old data)
    Host 2-->>Mtree 2: Cleanup routine (ensures no duplicates)

Agent CLI

The ONEInsight Agent provides a CLI. Use oneinsight-agent -h to see all available options.

install

oneinsight-agent install

Installs the ONEInsight Agent. Please refer to the Install section.

uninstall

oneinsight-agent uninstall

Windows only. Uninstalls the ONEInsight Agent. Please refer to the Uninstall section.

reset-password

oneinsight-agent reset-password

Resets the admin password.

create-ssl

oneinsight-agent create-ssl

Creates a new self-signed SSL certificate.

Note

This command will overwrite the file ./data/cert.pfx and adjust the ./data/settings.ini file. This may overwrite your custom SSL certificate.

Troubleshooting

Collecting Logs

If you encounter any errors or unexpected behavior with the agent, please follow these troubleshooting steps:

  1. Enable verbose logging as described below
  2. Reproduce the issue while monitoring the log files in ./data/logs
  3. For additional guidance, refer to the Help page which contains detailed information about common errors

Enabling Verbose Logging

Add the --verbose flag to your command. For example: oneinsight-agent.exe reset-password --verbose

Edit the ./data/settings.ini file and set Logging:Verbose to true. After modifying the configuration, restart the ONEInsight Agent service for the changes to take effect.

If you are unable to resolve the issue, please: 1. Open the ONEInsight Agent UI in your browser 2. Navigate to the Support page 3. Click Download Log Bundle

This will generate a diagnostic package containing all relevant logs and system information that you can share with mentIQ support for further assistance.

Appendix

Configuration of DataDomain Autosupport Emails

The simple way to enable the DataDomain to send autosupport emails to ONEInsight Portal are the following steps:

Login in to the DataDomain system with SSH (On Windows use Putty to login via SSH) as “sysadmin” user. The following command will enable detailed and alert autosupport messages: 

autosupport add asup-detailed emails autosupport@mentiq.com 
autosupport add alert-summary emails autosupport@mentiq.com 
alerts notify-list add default emails autosupport@mentiq.com

The following command will ONLY enable alert autosupport messages: 

autosupport add alert-summary emails autosupport@mentiq.com 
alerts notify-list add default emails autosupport@mentiq.com

Scheduling autosupport messages. Set the detailed autosupport and alert summary message schedule with the following commands for 6am and 7am: 

autosupport set schedule alert-summary daily 0600 
autosupport set schedule asup-detailed daily 0700

Verify configuration with the following commands: 

autosupport show all 
alerts show all

Functionality check. To test the detailed autosupport function, run the following command: 

autosupport send

To send a test alert message, run the following command: 

alerts notify-list test group default

Note

Email configuration must be enabled and configured on the DataDomain system. It is important that the DataDomain System can send email outside the organization. The SMTP email gateway must allow relaying of the DataDomain emails.

Integrate into 3rd Party Monitoring

The ONEInsight Agent can be integrated in 3rd party monitoring tools. The ONEInsight Agent can be integrated into third-party monitoring tools. The agent provides the URL /api/health for this purpose. Other monitoring tools can use this endpoint to query the status of the ONEInsight Agent.

ONEInsight Agent API

The ONEInsight Agent provides an API that allows for configuration and automation without requiring the use of the web interface. The OpenAPI v3 specification for this API can be accessed at: /swagger/v1/swagger.json.

Note

Please note that the API is currently in an unstable state and may undergo changes. Additionally, detailed endpoint descriptions are not yet available. If you are interested in utilizing this API, please reach out to mentIQ for further assistance.