Nexapp - Controller

Controller

The NexappOS Controller is a central management application designed to remotely manage multiple NexappOS deployments, called units. The Controller can be hosted on a dedicated management server and provides orchestration, monitoring, and fleet-level operations.

Each NexappOS unit can also run fully standalone without a Controller. The Controller is optional, but strongly recommended for multi-site SD-WAN, MSP environments, or any deployment requiring centralized visibility and policy enforcement.

How the Controller Works

The Controller establishes a secure management channel between the central server and all units:

  1. Each unit registers to the Controller using the built-in client service.
  2. After registration, the Controller generates a VPN configuration for that unit.
  3. The unit downloads the configuration and automatically builds a secure VPN tunnel.
  4. All management traffic and telemetry flow through this encrypted channel.

This design ensures that Controller-to-unit communication remains secure even across public internet links.

Key Features

  • Centralized Management
    Manage many NexappOS units from one interface, including SD-WAN policies, firewall rules, VPN profiles, and system settings.

  • Secure Communication
    Creates an encrypted OpenVPN tunnel between Controller and units to protect provisioning and telemetry.

  • Remote Configuration
    Configure units directly from the Controller UI without logging into each device separately.

  • Monitoring and Log Collection
    Collect logs from connected units centrally. Logs are stored in Loki and can be searched for troubleshooting and auditing.

  • Metrics Visualization
    Units export metrics that can be visualized using built-in Grafana dashboards.
    Metrics are collected by Prometheus and stored in TimescaleDB where applicable.

  • Web-based SSH
    Open an SSH terminal to any unit directly from the Controller UI, without separate VPN clients.

Installation and Configuration

The Controller is installed on a supported management server from the Software Center as NexappOS Controller.

After installation, configure the following parameters from the server web interface:

Required Parameters

  • Controller hostname
    Fully qualified domain name (FQDN) for the Controller, for example:
    controller.example.com
    The hostname must be resolvable and reachable from all units.

  • Let’s Encrypt certificate
    Enable HTTPS certificate for secure access.
    Recommended: Enabled.

  • VPN network and netmask
    The OpenVPN address pool used for Controller-to-unit tunnels.
    Choose a subnet that does not overlap with networks used on any unit.
    Use a Class C subnet, e.g. 192.168.7.0/24.

  • Administrator user
    Primary Controller admin account.
    Only admin users can create and manage other users and unit groups.
    The same username is also used to access Grafana.

  • Administrator password
    Set a strong password and store it securely.
    The default password is shown only once.
    For best security, change the password after first login (Controller + Grafana).

Optional Parameters

  • Controller name
    Used to generate the VPN Certification Authority.
    Keep default unless you need a custom CA identity.

  • Log retention (days)
    How long logs remain in Loki.
    Default: 180 days.

  • Metrics retention (days)
    How long metrics remain in Prometheus and Timescale.
    Default: 15 days.

  • MaxMind license key
    Enables IP geolocation for clients and attackers.
    Grafana dashboards will show geographic maps if the GeoIP database is available.
    Obtain a free key from MaxMind and paste it here.

  • Allowed IPs
    Restrict access to the Controller UI by IP or CIDR.
    If left empty, access is allowed from anywhere.
    When enabled, units can still register via the public registration endpoint, while all other traffic uses the VPN.
    Requires NexappOS unit version 8.6+.

After configuration, access the Controller at:

  • https://<controller-fqdn>

Network Ports Required

For proper Controller operation, ensure these ports are reachable:

  • TCP 443 (HTTPS)
    Used for Controller WebUI access and unit registration/communication.

  • UDP OpenVPN Port (dynamic)
    Automatically assigned during setup.
    The active port is visible on the Controller status page under OpenVPN UDP Port.
    Ensure this port is allowed through any upstream firewall.

Users

The Controller supports two user types:

  • Administrator users
    Can manage all units, create users, and manage unit groups.

  • Standard users
    Can manage only units assigned to their unit group(s).
    If not assigned to a group, they cannot access any unit.

Managing Users

An administrator can:

  • create users with username, display name, and password
  • reset passwords
  • delete users
  • promote standard user to administrator

After login, each user should: - change their password
- generate an SSH key pair for unit access

Two-Factor Authentication (2FA)

Each Controller user can enable 2FA to secure access.
The setup steps are identical to NexappOS UI 2FA.

Administrators can view the 2FA status of users in the user list.

Units

A unit is a NexappOS gateway managed by the Controller.

Add a Unit

  1. In the Controller UI, click Add unit.
  2. The Controller will:
    • generate a unique Unit ID
    • allocate a VPN IP address
    • generate VPN certificates/config
    • store access credentials securely
  3. A Join Code is displayed.

Join the Unit to the Controller

  1. Log in to the unit web interface.
  2. Open the Controller page.
  3. Paste the Join Code into Join code field.
  4. Confirm.

The unit downloads the VPN configuration and connects securely.
When completed, the unit appears as Connected in the Controller.

Note
If the Controller does not have a valid HTTPS certificate, disable Verify TLS certificate on the unit before joining.

Important
The unit web interface must listen on port 9090 for Controller access.

Remove a Unit

  1. In the Controller UI, click Remove unit.
  2. The Controller deletes unit configuration and terminates VPN.

Then on the unit: 1. Open Controller page.
2. Click Disconnect unit.
3. The unit removes VPN configuration locally.

Unit Groups

Unit groups organize units and control user access.

Create a Unit Group

  1. Administrator opens Unit groups page.
  2. Click Add group.
  3. Enter:
    • group name
    • description
    • units to include

Assign a User to Unit Group

  1. Open Users list.
  2. Click Edit next to user.
  3. Select group(s) in Unit groups dropdown.

Users can access only units inside their assigned groups.

Remove a Unit Group

A group can be deleted only if no users are assigned to it.

  1. Verify no users use the group.
  2. Go to Unit groups.
  3. Click Delete.

Migrated Unit Group

When upgrading from Controller versions earlier than 2.0.0, a Migrated group is created automatically.
It contains all previously managed units and is assigned to existing users.

Delete it only when it is no longer required.

Logs Management

When a unit connects:

  • rsyslog is reconfigured to forward logs using syslog (RFC 5424)
  • log delivery may take a few minutes to start
  • logs are labeled using the unit hostname

To keep Controller linking accurate:

  • each unit FQDN must be unique
  • unit name should match its hostname

Open logs by clicking Open logs for a unit.
Logs are shown in Grafana with search and filter tools.

Note
Log retention is configured in the management server interface.

Metrics

Units export two categories of metrics:

  1. System metrics (CPU, RAM, disk, network)

    • collected through Netdata
    • stored in Prometheus
    • available to all users

  2. Gateway metrics (traffic, security, VPN)

    • sent at intervals to the Controller
    • stored in TimescaleDB
    • available only with active subscription

All metrics are timestamped in UTC for consistency.
Grafana dashboards can display data in local time zones via preferences.

Grafana

The Controller includes a pre-configured Grafana instance for log and metric dashboards.

Access:

  • https://<controller-fqdn>/grafana

Use the same credentials created during Controller setup.
Change the default password after first login.

Grafana allows: - custom dashboards
- alerts
- user/team/role management
- advanced filtering and queries

Prometheus Metrics

System metrics are scraped from units and stored in Prometheus.
Metrics labels include:

  • instance — unit VPN IP + Netdata port
  • job — fixed as node
  • node — unit VPN IP
  • unit — unit unique name

These metrics appear under Operating System dashboards.

Timescale Metrics

Subscription required
Available only when both Controller and unit have valid subscriptions.

TimescaleDB stores the same metrics seen in Real-time Monitoring but as historical time series.

  • units send data every 15 minutes
  • Controller aggregates every 15 minutes
  • dashboards update with 15–30 minute delay maximum

Dashboards include:

  • Network traffic
  • Traffic by client
  • Traffic by remote host
  • Security events
  • VPN statistics

Unit Updates from Controller

The Controller can update units remotely.

Package Updates

  1. Open unit menu → Check package updates
  2. Review list of updates
  3. Click Update

System Update

  1. If image update exists, a badge appears on unit list
  2. Open unit menu → System update
  3. Update immediately or schedule
  4. Mass update available under Actions → Update systems

Note
Older units may not refresh status during upgrade.
Use Sync unit info if required.

SSH Access from Controller

Open SSH for a unit by clicking Open SSH terminal.
A new browser tab opens with a web-based SSH client.

You can connect using:

Username and Password

Used when: - no SSH key is generated
- public key is not yet sent to unit

The UI prompts for unit credentials, then opens a terminal session.

SSH Key Authentication

SSH key pairs provide stronger authentication.

To use a key:

  1. Go to Account settings
  2. Click Generate SSH key pair
  3. Enter a passphrase
  4. Save the key

Send the public key to units:

  1. Open Unit manager → Actions
  2. Choose Send SSH public key
  3. Select target units
  4. Click Send SSH key

After that, opening SSH will request your passphrase instead of password.

You can revoke keys anytime via:

  • Revoke SSH public key

Auditing and Accounting

All Controller operations are logged in management server logs, including:

  • logins/logouts
  • user creation/modification/deletion
  • unit add/remove
  • configuration actions

Units also log Controller actions, identified by a dedicated RPC user.

SSH logins are recorded separately in unit logs, usually under root or key fingerprint.

Subscription and Limitations

Subscription required
Some Controller capabilities depend on subscription status.

Controller Without Subscription

  • up to 3 units can be registered
  • only community units can register
  • historical metrics not available

Controller With Subscription

  • unlimited units
  • only subscribed units can register
  • subscribed units send historical metrics

Version Awareness

Version Awareness prevents unsupported actions based on unit/controller version mismatch.

Scenarios:

  1. Compatible versions → normal access
  2. Unit much older → connection blocked to avoid errors
  3. Controller slightly older → warning shown, access allowed if confirmed

No action is required to enable this feature; it runs automatically.

Bypass Version Awareness (Advanced)

If you accept the risks:

  1. In Controller, open unit details and copy Unit ID
  2. Click Open SSH terminal once (window can be closed)
  3. Open a new tab at:

https://<controller-fqdn>/#/controller/manage/<unit-id>/dashboard

This opens unit UI without version checks.

Update Unit Using SSH

You can update a unit even if UI access is blocked.

After opening SSH:

Package Updates

Check:

```bash /usr/libexec/rpcd/ns.update call check-package-updates

Discard
Save
Draft
This page has been updated since your last edit. Your draft may contain outdated content. Load Latest Version

Previous Page

Left

Next Page

Right

On this page

Review Changes ← Back to Content
Message Status Space Raised By Last update on