Enabling Visual Explorer
Turn on the Platform UI and Visual Explorer on a NetBox Enterprise Embedded Cluster install, add the first platform administrator, and fix the common setup problems
Preview
Visual Explorer and the Platform UI are in preview on NetBox Enterprise. Setup steps and behavior may change in future releases.
On NetBox Enterprise, Visual Explorer runs inside the Platform UI, which has its own sign-in, separate from NetBox. This page covers NetBox Enterprise 2.5.0 on Embedded Cluster, with people signing in to the Platform UI using local accounts.
To have people sign in with your organization's identity provider instead, see Platform Single Sign-On. This guide does not cover it.
NetBox stops answering on its IP address
With the Platform UI on, NetBox answers only on its hostname. Requests to a node IP address fail. The Admin Console on port 30000 still answers by IP. Tell your users and update any integrations that reach NetBox by IP before you turn it on.
Before you start
- Your license includes Visual Explorer. Without it, everything else deploys but Visual Explorer never appears. Contact your NetBox Labs account representative to add it.
- Two DNS names that point at the cluster, for example
netbox.example.comfor NetBox andui.example.comfor the Platform UI. The Platform UI hostname needs three or more parts and must differ from the NetBox hostname. - An install with internet access. Visual Explorer is not supported on air-gapped installs in this release.
- Access to the Admin Console (
https://<node-ip>:30000) and SSH withsudoto a controller node. - Recommended: a TLS certificate covering both names. List both as subject alternative names (SAN) rather than using a wildcard. Without a certificate, every user has to accept a browser warning on both hostnames.
- Optional: the
netbox-bgpplugin, needed only for Visual Explorer's BGP views.
Turn on the Platform UI
- In the Admin Console, open Config.
- Tick Enable the Platform UI.
- Set Platform UI Hostname, for example
ui.example.com. - Set NetBox Hostname, for example
netbox.example.com. Do not leave it blank. A blank NetBox hostname deploys and reports Ready, but the Platform UI never loads. - If you have a certificate for both names, upload it. See TLS and Ingress.
- Select Save config, then Deploy the new version. Saving alone does not apply the change.
Add the first platform administrator
A fresh install has no Platform UI accounts and no administrator. NetBox accounts, including the NetBox superuser, cannot sign in to the Platform UI.
The nbe-bootstrap-admin.sh script creates the first account and makes it an administrator. On a controller node, in the directory that holds the netbox-enterprise installer, download and check it:
curl -fsSLO https://netboxlabs.com/docs/files/enterprise/nbe-bootstrap-admin.sh
curl -fsSLO https://netboxlabs.com/docs/files/enterprise/nbe-bootstrap-admin.sh.sha256
sha256sum -c nbe-bootstrap-admin.sh.sha256Then open the cluster shell and run it, using the full path to the script:
sudo ./netbox-enterprise shell
bash /path/to/nbe-bootstrap-admin.shThe script asks for:
- The person's email address, then whether to create a local account for it (answer
y) - A username, first name and last name
- A temporary password, which the person changes at first sign-in
It then shows a summary and changes nothing until you confirm. On confirmation it creates the account, adds it to Initial Platform Administrators in the Admin Console, keeping anyone already listed, and deploys. Wait a few minutes for the deploy to finish before signing in.
Run the script again for each additional administrator.
Connect your NetBox account
- Open
https://<platform-ui-hostname>/and sign in as the administrator. - Go to Settings > User mapping.
- Connect your Platform UI account to your NetBox account, then select Save changes.
Until an account is connected to a NetBox account, the Platform UI shows no NetBox data for that person. Repeat for each person. See Identity Mapping for more on connecting accounts.
Verify
- Open
https://<platform-ui-hostname>/. It redirects to a sign-in page. - Sign in. You land in the Platform UI.
- Settings > Users lists you with the platform role Admin.
- Visual Explorer is in the menu and shows your NetBox data.
If a step fails, find what you see in the table below.
Troubleshooting
| What you see | Cause | Fix |
|---|---|---|
| The Platform UI hostname shows the NetBox login page, and NetBox still answers on its IP address. The Admin Console reports Ready. | The NetBox Hostname is blank. | Set the NetBox Hostname and deploy. |
| The Platform UI hostname does not resolve. | Your DNS does not have the Platform UI name. | Add a DNS record for it. |
| The Platform UI loads but spins indefinitely. | The browser does not trust the certificate on the NetBox hostname. Accepting the warning for the Platform UI hostname does not cover the NetBox hostname. | Open https://<netbox-hostname>/, accept the warning, then reload the Platform UI. To remove this step for everyone, upload a certificate covering both names. |
| The sign-in page rejects your NetBox username and password. | Platform UI accounts are separate from NetBox accounts. | Add the first platform administrator. |
The sign-in page rejects the username and password from the netbox-keycloak-admin secret. | That secret holds the administrator of Keycloak's own admin console, in the master realm. The Platform UI signs in to the netbox realm, which starts with no accounts. | Add the first platform administrator. |
| You can sign in, but Settings > Users and User mapping say "You do not have access to this page". | No platform administrator exists yet. | Add the first platform administrator. |
| You are signed in, but Visual Explorer is not in the menu. | Your license does not include Visual Explorer. | Ask your account representative to add it, sync the license in the Admin Console, then deploy. |
| You are signed in and licensed, but Visual Explorer is still not in the menu. | NetBox Python Configuration Overrides in the Admin Console mentions netbox_floorplan, even in a comment. Visual Explorer cannot run alongside the NetBox Floorplan plugin in this release. | To use Visual Explorer, remove every mention of netbox_floorplan from the overrides and deploy. To keep the Floorplan plugin, leave Visual Explorer off for now. |
| Visual Explorer is in the menu but shows nothing from NetBox. | Your Platform UI account is not connected to a NetBox account. | Connect your NetBox account. |
| Visual Explorer shows "NetBox has no data. The instance may be running an older NetBox version, or the plugin that provides this data may not be installed." | Usually the optional netbox-bgp plugin is missing. Only the BGP views need it. Other views still work. | If you do not need the BGP views, dismiss the message. Otherwise install netbox-bgp, checking that it supports your NetBox version. |
| A deploy stays in Deploying for several minutes after a config change. | Turning on the Platform UI or adding an administrator restarts several services in sequence. | Wait for it to finish. |
Turning it off
In the Admin Console, untick Enable the Platform UI and deploy. NetBox answers on its IP address again.
To take administrator rights away from someone, removing them from Initial Platform Administrators is not enough. See Removing an administrator.