Installing the Netos plugins on an offline NetBox
This installs the Netos plugins into an existing NetBox 4.5.10 that has no internet access. Nothing in this procedure reaches the network. Netos Cloud customers do not need it: Netos installs and upgrades your environments.
| Product name | Name in NetBox's PLUGINS and in site.yml |
|---|---|
| Netos Core | netos |
| Netos Insights | netos_reporting |
| Netos Projects | netos_model_builder |
The steps, outputs and timings below come from real runs on a 2 vCPU / 7 GB NetBox 4.5.10 host with all outbound traffic blocked.
%%{init: {"themeVariables": {"mainBkg": "#eef2f7", "textColor": "#1f2937"}}}%%
flowchart LR
A["1. Check the file<br/>sha256 + signature"] --> B["2. Write site.yml"]
B --> C["3. Preflight<br/>changes nothing"]
C -->|any FAIL| X["Fix, or send output<br/>to Netos"]
C -->|all PASS or WARN| D["4. Install<br/>about 23 min"]
D -->|RESULT: PASS| E["5. Check it<br/>status + browser"]
D -->|RESULT: FAIL| R["Rollback"]
classDef ok fill:#dcfce7,color:#14532d,stroke:#16a34a
classDef bad fill:#fee2e2,color:#7f1d1d,stroke:#dc2626
class E ok
class X,R bad
What you need
| Item | Where it comes from |
|---|---|
netos-bundle-<release>-netbox4.5.10-cp312-x86_64.tar.gz and its .sha256 |
Netos support |
netos-licence.json (your licence token and key) |
Netos support, sent separately from the bundle |
| The bundle's SHA-256, read to you or sent by a second channel | Netos support |
| The Ed25519 public key, supplied separately from the bundle | Netos support |
A root shell on the NetBox host (sudo -i) |
You |
| A change window of about 45 minutes. NetBox is down for about 20 minutes of it | See How long it takes |
| An admin login to NetBox, to check the result in a browser | You |
The NetBox host must have:
- NetBox 4.5.10, installed in
/opt/netboxwith its virtual environment at/opt/netbox/venv(Python 3.12). If yours lives elsewhere, set thenetbox:paths insite.yml(see Settings you may need). - glibc 2.27 or newer (Ubuntu 20.04+, RHEL 8+) and PostgreSQL 14 or newer.
- PostgreSQL on the same host with an OS user
postgres. Rollback uses it to restore the database. If your database is on another server, preflight says so and rollback prints the commands for your DBA instead. - Free disk for one snapshot (a copy of the venv, the static files and a database dump) plus the bundle. On the test host that was about 520 MB plus the 110 MB bundle; preflight computes your figure.
Every command below runs in a root shell. Start one with sudo -i and stay in it.
1. Check the file you received
Copy the bundle, its .sha256 and the licence file to the NetBox host, into a directory of your choice. This
guide uses /root/netos/. Put only one bundle in it at a time.
First compare the bundle's SHA-256 with the value Netos gave you by the second channel. Do this before unpacking anything:
cd /root/netos
sha256sum netos-bundle-*.tar.gz
The 64-character value it prints must equal the one Netos gave you. If it differs, stop and contact Netos. Then:
sha256sum -c netos-bundle-*.tar.gz.sha256 # must print: ...tar.gz: OK
tar --no-same-owner -xzf netos-bundle-*.tar.gz
cd netos-bundle-*/
./netos-install verify --trusted-key /root/netos/bundle-signing.pub --require-signature
Check the signature
Save the public key provided by Netos support as /root/netos/bundle-signing.pub, separately from the bundle.
The release signing key, issued 2026-10-19 and used from 2026.10.1, is:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAOKdJKoil0nAa3qTuGjd4ikGQivHQ3+JUy6fxgKyfFhs=
-----END PUBLIC KEY-----
Key ID 0de04e10b26b3647; full SHA-256 of the raw 32-byte public key
0de04e10b26b36476416b56700c3d3eb3d0e3fe5733f332c22478cdfef89f25b. Bundles up to and including 2026.10.0 are
unsigned.
Run ./netos-install verify --trusted-key /root/netos/bundle-signing.pub --require-signature. A signed bundle must print
signature verified (key <id>), where <id> is the first 16 hexadecimal characters of the SHA-256 of the raw
32-byte Ed25519 public key. Compare the key ID with the one supplied by support. For preflight, install, and
upgrade, pass the same --trusted-key and --require-signature options on first use. Successful install/upgrade pins that key in
/var/lib/netos/trusted.pub (or state_dir/trusted.pub from site.yml) for later bundles.
Pinning a key supplied only inside the bundle is trust-on-first-use and does not independently establish who signed it.
verify checks every file against SHA256SUMS. If it prints signature valid, key NOT independently trusted,
it used only the key inside the bundle; obtain the public key separately and run verify again. unsigned is a
warning during the rollout when no key has been pinned or explicitly supplied. Once a signing key is pinned or
supplied with --trusted-key, an unsigned bundle fails;
pass --allow-unsigned explicitly to override this with a warning (--trusted-key cannot authenticate an unsigned
bundle). Use --require-signature on verify, preflight, install, or upgrade to reject unsigned bundles always.
An invalid signature always fails.
Verification uses the NetBox venv's cryptography Ed25519 implementation (present in the NetBox 4.5.10 baseline
through social-auth-core); if it cannot be imported, it falls back to openssl pkeyutl -rawin and fails clearly
when neither backend is available.
2. Write the site profile
Create /root/netos/site.yml (for example with nano /root/netos/site.yml). Two values are required:
external_url and licence_file. Copy the rest as shown; the comments are optional.
profile_version: 1
site: acme-prod-nb01 # free text; appears in every log and support bundle
plugins: [netos, netos_reporting, netos_model_builder] # leave as is: a bundle installs all three
external_url: https://netbox.acme.example # REQUIRED: the URL your users open
csrf_trusted_origins: [https://netbox.acme.example] # usually the same as external_url
licence_file: /root/netos/netos-licence.json # REQUIRED: the licence file Netos sent
Keep site.yml next to the bundle. You will use it again for upgrades and support.
You can also run ./netos-install configure --site /root/netos/site.yml --licence-file /root/netos/netos-licence.json --external-url https://netbox.acme.example to fill these values in site.yml before installing.
To apply bundled content after the plugin post-check, add content_packages: [netbox-rbac]; see Content packages.
3. Preflight (changes nothing)
From inside the bundle directory:
./netos-install preflight --site /root/netos/site.yml
Preflight is read-only. It can run days before the change window, and you can send its output to Netos. It takes
about a minute, most of it a rehearsal: it copies the NetBox venv to a scratch directory, installs the bundle
into the copy, and runs pip check and manage.py check against it with a read-only database session. That is
what catches a conflict between Netos and another plugin you run, before your live NetBox is touched.
Every line is PASS, WARN, FAIL or SKIP. Any FAIL stops the install; see
Troubleshooting. The test host looked like this:
PASS netbox_version 4.5.10
PASS python_abi cp312
PASS glibc glibc=2.39 (want >= 2.27)
PASS postgres server=160015 (want >= 14)
PASS licence licence decrypts
PASS disk free=69925818368 bytes (want >= 520027788)
PASS database_tools postgres OS user; /usr/lib/postgresql/16/bin/pg_restore
PASS rehearsal copied venv passed pip check and manage.py check
WARN pg_trgm pg_trgm=absent (want installed)
WARN jit jit=on (want off; --apply-tuning)
WARN random_page_cost random_page_cost=4.0 (want 1.1; --apply-tuning)
WARN rq_timeout rq_timeout=300 (want >=1200)
PASS nginx nginx=True
PASS customer_url customer_url=netbox.acme.example
PASS secret_key secret_key=True
PASS api_peppers api_peppers=True
PASS upgrade_compatible installed=none
PASS current_plugins {}
WARN lines are advice and do not stop the install:
rq_timeout: the install setsRQ_DEFAULT_TIMEOUT = 1200in its own block, so this one clears itself.jit,random_page_cost: PostgreSQL tuning that speeds up Netos reports. Optional; leave it alone unless your DBA approves. With approval, add--apply-tuningto the install command; it runsALTER SYSTEMfor these two settings and reloads PostgreSQL, nothing else.pg_trgm: not required by these plugins. The test installs ran without it.customer_url: yourexternal_urlends innetos.io. Only Netos's own test hosts should see this; use your own NetBox URL.
4. Install
Run the install so that it survives your SSH session dropping. If the session drops mid-install, the install
is killed and the box needs a rollback (that case is tested and works, but it costs the change window). Either use
tmux or screen, or run it as a transient service. From inside the bundle directory:
systemd-run --unit netos-install --collect --working-directory "$PWD" \
"$PWD/netos-install" install --site /root/netos/site.yml --yes
journalctl -fu netos-install # follow it; Ctrl-C stops following, not the install
It is finished when systemctl is-active netos-install no longer prints active. The last line in the journal is
RESULT: PASS ... or RESULT: FAIL .... The full step-by-step log is
/var/log/netos/install-<timestamp>.log (tail -f it for the detail).
What happens, in order. It stops at the first failure and prints the exact rollback command:
- Preflight again; any
FAILrefuses. - NetBox is stopped (
netbox,netbox-rq). Your web server shows its own error page from here to step 8. - Snapshot to
/var/backups/netos/<timestamp>/: a database dump, a full copy of/opt/netbox/venv, the static files,configuration.py, the Netos secrets and the systemd units. - The bundle's packages are installed into the NetBox venv, from the bundle only (
--no-index, hash-checked). - A marked block is added to the end of
configuration.py(# BEGIN netos-install...# END netos-install). Your own settings and plugins outside it are not touched. - Database migrations run. This is the long step: 11 to 17 minutes on the test host. Then static files are collected.
- The Insights permission reconcile runs. On a first install it prints that the Netos RBAC permission set is not installed yet and carries on. That is expected.
- NetBox and its workers start, including a new low-priority worker,
netbox-rq-low, for long Netos jobs. - Post-check:
manage.py check,pip check, the installed versions against the bundle, NetBox answering onhttp://127.0.0.1:8001/login/(it waits up to 5 minutes for the workers to load), and each plugin's first page. - A receipt is written next to the log, and the last line is
RESULT: PASS.
Two warnings appear in the output on every NetBox 4.5.10 host and are harmless: Django's RuntimeWarning: Accessing the database during app initialization is discouraged, and staticfiles.W004 about
project-static/docs.
The first install took 22.5 and 23 minutes in the two test runs.
5. Check it
./netos-install status --site /root/netos/site.yml
prints one line:
acme-prod-nb01: 2026.10.0-rc2; PASS; /var/log/netos/install-20261018T215107Z-....json
Also check the services: systemctl is-active netbox netbox-rq netbox-rq-low must print active three times.
Then log in to NetBox as an admin. The navigation bar gains the Netos menus. If you see no Netos menus, or a page
saying the licence is invalid, run ./netos-install doctor --site /root/netos/site.yml and send the output to
Netos.
How long it takes
| Step | Test host (2 vCPU, 7 GB) |
|---|---|
verify |
seconds |
preflight |
about 1 minute |
First install |
22.5 to 23 minutes, NetBox down for about 20 |
upgrade to the next bundle |
about 6 minutes |
rollback |
1 to 3 minutes |
Settings you may need
Add these to site.yml only if they apply:
netbox:
root: /opt/netbox # where NetBox is installed
venv: /opt/netbox/venv
config: /opt/netbox/netbox/netbox/configuration.py
service_user: netbox # the user NetBox runs as
services: {web: netbox, rq: netbox-rq, rq_low: netbox-rq-low} # if your unit names differ
snapshot_root: /var/backups/netos # where snapshots go; needs the free space preflight asks for
Installing by hand
netos-install is the supported route. If you must install the plugins another way, for example with your own
automation, ask Netos support for the packages for your NetBox version first, and keep to the same rules the
installer follows:
Back up first: a database dump and a copy of
/opt/netbox/venv, so you can return to where you started.Install the packages into NetBox's own virtual environment,
/opt/netbox/venv.Add the plugins to
PLUGINSinconfiguration.py, with Netos Core first:PLUGINS = ["netos", "netos_reporting", "netos_model_builder"]Run the database migrations and collect the static files:
/opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py migrate /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py collectstatic --no-inputRestart NetBox and its workers, then check they are running:
systemctl restart netbox netbox-rq systemctl status netbox netbox-rqLog in to NetBox as an admin and check that the Netos menus appear.
If anything fails, see Troubleshooting.
Logs and what to send Netos
Every command writes /var/log/netos/<command>-<timestamp>.log; install, upgrade and rollback also write a .json
receipt. If anything goes wrong, run
./netos-install support-bundle --site /root/netos/site.yml
and send Netos the file it names. It holds the logs, receipts, a health report and redacted service logs.
Secrets, passwords and keys are reported as present or absent, never as values; on the test host no fragment of
the licence or the database password appeared in it.
Next: Upgrade, Roll back, Troubleshooting.