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/netbox with its virtual environment at /opt/netbox/venv (Python 3.12). If yours lives elsewhere, set the netbox: paths in site.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 sets RQ_DEFAULT_TIMEOUT = 1200 in 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-tuning to the install command; it runs ALTER SYSTEM for these two settings and reloads PostgreSQL, nothing else.
  • pg_trgm: not required by these plugins. The test installs ran without it.
  • customer_url: your external_url ends in netos.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:

  1. Preflight again; any FAIL refuses.
  2. NetBox is stopped (netbox, netbox-rq). Your web server shows its own error page from here to step 8.
  3. 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.
  4. The bundle's packages are installed into the NetBox venv, from the bundle only (--no-index, hash-checked).
  5. 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.
  6. Database migrations run. This is the long step: 11 to 17 minutes on the test host. Then static files are collected.
  7. 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.
  8. NetBox and its workers start, including a new low-priority worker, netbox-rq-low, for long Netos jobs.
  9. Post-check: manage.py check, pip check, the installed versions against the bundle, NetBox answering on http://127.0.0.1:8001/login/ (it waits up to 5 minutes for the workers to load), and each plugin's first page.
  10. 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:

  1. Back up first: a database dump and a copy of /opt/netbox/venv, so you can return to where you started.

  2. Install the packages into NetBox's own virtual environment, /opt/netbox/venv.

  3. Add the plugins to PLUGINS in configuration.py, with Netos Core first:

    PLUGINS = ["netos", "netos_reporting", "netos_model_builder"]
    
  4. 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-input
    
  5. Restart NetBox and its workers, then check they are running:

    systemctl restart netbox netbox-rq
    systemctl status netbox netbox-rq
    
  6. Log 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.