Install the Navin Manager

This page installs the Navin Manager server (console, REST API, operations engine) on one host, from the packages, then starts it and signs in for the first time. It is done by a system administrator with root rights and takes about 30 minutes. Other methods: offline installation for a network without Internet access, the guided installer navin-install (section Guided installation), and the sandbox for a test on one workstation without root.

Before you begin

Item	Requirement	Check
System	Ubuntu 24.04 (DEB), RHEL family 8, 9 or 10: RHEL, Rocky Linux, AlmaLinux, Oracle Linux 8/9, CentOS Stream 9/10 (one RPM), Arch Linux (pacman), x86_64. Ubuntu 22.04 is a managed host only. The full matrix is in OS compatibility.	cat /etc/os-release
Python	python3.12 and python3.12-venv on Ubuntu, python3.12 on the RHEL family (AppStream on 8.10 and 9, BaseOS on 10), the python of Arch Linux the package was built for. The package installs the dependency.	python3.12 --version
Database	A PostgreSQL server: local on the host (postgresql or postgresql-server, set up by navin-manager-db local) or an external server reached with sslmode=require, verify-ca or verify-full.	psql --version
Name	A fully qualified host name that resolves. The self-signed certificate of the package is made for it.	hostname -f
Network	Port 8460/tcp (console, API, agent registration) open from the operators and the managed hosts; port 8461/tcp (agent API and mirror) open from the managed hosts.	ss -ltn shows both ports free
Rights	root or sudo.	sudo -v

Steps

1. Add the Navin repository, or copy the package. The packages are published in signed apt, dnf and pacman repositories made by os/repo.sh; without a repository, install the package file directly in step 2.

   Ubuntu:

   sudo curl -fsSLo /usr/share/keyrings/navin-archive-keyring.gpg https://<repo-host>/apt/navin-archive-keyring.gpg
   sudo curl -fsSLo /etc/apt/sources.list.d/navin.sources https://<repo-host>/apt/navin.sources
   sudo apt update

   RHEL, Rocky Linux, AlmaLinux:

   sudo curl -fsSLo /etc/yum.repos.d/navin.repo https://<repo-host>/rhel/navin.repo

   Arch Linux (trust the release key once, its fingerprint is in navin.conf):

   curl -fsSLO https://<repo-host>/arch/navin-archive-keyring.asc
   sudo pacman-key --add navin-archive-keyring.asc && sudo pacman-key --lsign-key <fingerprint>
   curl -fsSL https://<repo-host>/arch/navin.conf | sudo tee -a /etc/pacman.conf

   <repo-host>: address of the Navin repository or of its mirror in your organization. <fingerprint>: the key fingerprint written in navin.conf.

   Expected result: apt update, dnf repolist or pacman -Sy lists the navin repository.

   If it fails: check the proxy of the package manager and the certificate of the repository host.

2. Install a local PostgreSQL (optional) and the package. The package creates the account navin-manager, the application environment /opt/navin-manager/venv built from the wheelhouse shipped in the package (no network), the master key, a self-signed certificate, server.env and, when a PostgreSQL server is installed on the host, the local database.

   sudo apt install postgresql navin-manager                 # Ubuntu 24.04
   sudo dnf install postgresql-server navin-manager          # RHEL, Rocky Linux, AlmaLinux 9
   sudo pacman -S --needed postgresql && sudo pacman -S navin-manager   # Arch Linux

   Without a repository: sudo apt install ./navin-manager_<version>_amd64.deb, sudo dnf install ./navin-manager-<version>-1.el9.x86_64.rpm or sudo pacman -U ./navin-manager-<version>-1-x86_64.pkg.tar.zst.

   Expected result: the package prints initial account 'navin', one-time password in /etc/navin-manager/server.env and self-signed certificate created in /etc/navin-manager/tls. If the settings pass the production checks, the service is enabled and started; otherwise it prints not started, the settings are incomplete: run navin-manager check.

   If it fails: install-venv.sh reports a missing interpreter (dnf install python3.12, python3.12-venv, pacman -S python); a failed venv build restores the previous one.

3. Choose the database. navin-manager-db writes NM_DATABASE_URL in /etc/navin-manager/server.env and applies the migrations. The local database is reached through the UNIX socket only, with a random password.

   sudo navin-manager-db local

   For the PostgreSQL server of your organization (TLS required):

   sudo navin-manager-db external 'postgresql://navin_manager:<password>@<db-host>:5432/navin_manager?sslmode=verify-full&sslrootcert=/etc/navin-manager/tls/postgresql-ca.pem'

   <password>: password of the role navin_manager, owner of the database navin_manager.

   Expected result: navin-manager-db: NM_DATABASE_URL set to ... and the list of applied migrations; sudo navin-manager-db status shows every migration applied.

   If it fails: an external URL without sslmode=require, verify-ca or verify-full is refused; when the migrations fail on the new server, the previous NM_DATABASE_URL is restored.

4. Install the TLS certificate of your PKI. The self-signed certificate of the package (EC P-256, 397 days, names: FQDN, short name, localhost, 127.0.0.1) is only meant for the first start. See TLS certificates.

5. Check the settings. navin-manager check lists every setting that forbids a production start (TLS, client certificates, cookie flag, metrics token, scrypt cost, master key, sslmode, initial password).

   sudo runuser -u navin-manager -- navin-manager check

   Expected result: settings are valid for this environment.

   If it fails: fix each printed line; the settings are listed in the configuration reference.

6. Start the server. The unit applies the migrations (ExecStartPre=navin-manager migrate) then runs navin-manager serve, which creates the initial administrator.

   sudo systemctl enable --now navin-manager
   sudo firewall-cmd --permanent --add-port=8460/tcp --add-port=8461/tcp && sudo firewall-cmd --reload   # RHEL family
   sudo ufw allow 8460/tcp && sudo ufw allow 8461/tcp                                                    # Ubuntu with ufw

   Expected result: systemctl is-active navin-manager prints active; the journal shows administrator navin from the configuration: created (the password must be changed at the first sign in).

   If it fails: journalctl -u navin-manager -n 100 shows the refused setting or the database error.

7. Sign in and change the password. Read the one-time password, open the console and sign in as navin.

   sudo grep '^NM_ADMIN_PASSWORD=' /etc/navin-manager/server.env

   Open https://<manager-fqdn>:8460. The console asks for your own password at once (12 characters or more).

   Expected result: the Dashboard shows No cluster yet and the button Create cluster.

   If it fails: lost password: sudo runuser -u navin-manager -- navin-manager reset-admin sets the account back to NM_ADMIN_PASSWORD, to change again at the next sign in.

8. Back up the master key. /etc/navin-manager/master.key seals every stored secret.

   danger

   Without a copy of master.key, the stored secrets (connections, vault, SMTP password) cannot be recovered after a loss of the host. Keep a copy in the vault of your organization.

Initial administrator

Item	Value
User name	NM_ADMIN_USERNAME, default navin
Password	NM_ADMIN_PASSWORD in server.env, random value written by the package (Nm-<32 hex>-K9!)
Created	once, at the first start of navin-manager serve; a restart never sets it again
Lost password	navin-manager reset-admin
Other administrators	Administration > Users, or navin-manager create-admin --username <name> (password read twice, from --password-file or --password-stdin)
Second factor	off by default; NM_MFA_ENABLED=true brings back the TOTP step

TLS certificates

The Manager has two listeners with two certificates:

Listener	Port	Certificate	Client certificate
Console, API, registration	8460	tls_cert_file, tls_key_file (your PKI)	no
Agent API and mirror	8461	issued by the internal CA of the Manager (NM_PKI_DIR, default /var/lib/navin-manager/pki) for the FQDN and NM_AGENT_TLS_SANS	required (agent_client_cert_required)

To replace the self-signed certificate:

1. Copy the certificate and its key. The key is read by the service account only.

   sudo install -o root -g navin-manager -m 0644 manager.crt /etc/navin-manager/tls/server.crt
   sudo install -o root -g navin-manager -m 0640 manager.key /etc/navin-manager/tls/server.key

   manager.crt: the certificate (with its intermediate chain) issued for the FQDN used by the operators and the agents. manager.key: its private key.

2. Restart the server.

   sudo systemctl restart navin-manager

   Expected result: openssl s_client -connect <manager-fqdn>:8460 </dev/null | openssl x509 -noout -issuer shows the issuer of your PKI.

Other names for the agent listener (a virtual IP, a DNS alias): add NM_AGENT_TLS_SANS=<name1>,<name2> to server.env and restart. The CA certificate the agents pin is exported with navin-manager ca-export --out <file>, and its fingerprint is shown next to each bootstrap token.

Reverse proxy

The Manager serves TLS itself on both ports and needs no reverse proxy. It does not read the X-Forwarded-* headers (proxy_headers is off), and the agent listener checks the client certificate of each agent, so the agents must reach port 8461 directly, without a TLS termination in between. Set public_url and agent_url when the operators or the agents use another name than the FQDN of the host.

Guided installation

os/install/navin-install installs a standalone server or a cluster (the Manager, then its nodes) from an offline archive per family (navin-install-<version>-debian, -rhel, -arch), checks each host before any change, and resumes where it stopped when run again.

sha256sum -c navin-install-<version>-rhel.tar.gz.sha256
tar xzf navin-install-<version>-rhel.tar.gz && cd navin-install-<version>-rhel
sudo ./navin-install preflight manager
sudo ./navin-install manager --cluster <cluster-name> --mode production
sudo ./navin-install join-command --nodes 3 --hours 24

<cluster-name>: lower case letters, digits and hyphens. join-command prints the command to run on each node (see Install the Navin agent). The full guide is os/install/README.md.

Verify

sudo navinctl status
sudo navinctl check
curl -sk https://<manager-fqdn>:8460/api/v1/version

Expected result: navin-manager.service is enabled and active, navinctl check prints settings are valid for this environment, /api/v1/version returns the version of the server, and the console shows the System page with the database and the operations engine healthy.

Next steps

• Load the offline mirror
• Install the Navin agent on the hosts
• Configuration reference
• Console user guide
• Upgrade and uninstall

Troubleshooting

Symptom	Cause	Fix
not started, the settings are incomplete after the install	a production check fails (often the database)	sudo runuser -u navin-manager -- navin-manager check, then navin-manager-db local or external
NM_DATABASE_URL must use sslmode=require, verify-ca or verify-full in production	external URL without TLS	add sslmode=verify-full&sslrootcert=<ca-file>
master key file /etc/navin-manager/master.key is missing	key deleted or wrong master_key_file	restore the key from the vault; navin-manager init-key creates a new one only on a new installation
NM_ADMIN_PASSWORD must be a strong one-time password in production	weak initial password in server.env	set 12 characters or more, letters and digits, not navin
The browser warns about the certificate	the self-signed certificate is still in place	install the certificate of your PKI (TLS certificates)
Port 8460 is taken	another program listens on it	ss -ltnp 'sport = :8460'