Skip to main content

Install the Navin agent

This page installs the Navin agent on a host and registers it in a cluster of the Navin Manager. It is done by a system administrator with root rights on the host and takes about 5 minutes per host. Three ways exist: the register command, a seeded enroll.env file (no command to type, for cloud-init or configuration management), and the SSH bootstrap from the console.

Before you begin​

  • System: a certified system of the OS compatibility matrix, x86_64 or aarch64 for the Go agent. Check: cat /etc/os-release and uname -m.
  • Network: the host reaches the Manager on 8460/tcp and 8461/tcp. Check: curl -sk https://<manager-fqdn>:8460/api/v1/version.
  • A bootstrap token and the CA fingerprint: in the console, Nodes > Add nodes, or on the Manager host sudo runuser -u navin-manager -- navin-manager enroll-token --cluster <cluster-name> --uses 1 --hours 1, which prints bootstrap token, server, ca-sha256 and tls-sha256.
  • Clock synchronized: the request signatures are refused beyond 300 seconds of skew.

Steps​

  1. Install the package. The Go agent is one static binary: no Python, no OpenSSL. The package enables navin-manager-agent.service and the enrollment units.

    SystemCommand
    RHEL, Rocky Linux, AlmaLinux, Oracle Linux, CentOS Streamsudo dnf install navin-manager-agent-go or sudo dnf install ./navin-manager-agent-go-<version>-1.<arch>.rpm
    Ubuntu, Debiansudo apt install navin-manager-agent-go or sudo apt install ./navin-manager-agent-go_<version>_<debarch>.deb
    Arch Linuxsudo pacman -S navin-manager-agent-go or sudo pacman -U ./navin-manager-agent-go-<version>-1-<arch>.pkg.tar.zst
    Without package managersudo tar -xzf navin-manager-agent-go-<version>-linux-<arch>.tar.gz -C / && sudo systemctl daemon-reload

    <arch>: x86_64 or aarch64; <debarch>: amd64 or arm64. The repositories are configured as in Install the Navin Manager. Check the files first with sha256sum -c --ignore-missing SHA256SUMS.

    The Python agent (navin-manager-agent, RPM noarch, DEB all, pacman any) needs Python 3.9 or newer (RHEL 8: dnf install python39) and openssl; it uses the same command, file and unit. The two packages conflict: installing one replaces the other and keeps the registration.

    Expected result: nm-agent --version prints the version; nm-agent status prints Not registered.

    If it fails: on RHEL 8 with the Python agent, Python 3.9 or newer is required (RHEL 8: dnf install python39).

  2. Register the host. Run the command shown by the console. The agent pins the CA by its fingerprint.

    sudo nm-agent register --server https://<manager-fqdn>:8460 --token <token> --ca-sha256 <fingerprint>

    <token>: the bootstrap token. <fingerprint>: the ca-sha256 value. While the console still has the self-signed certificate of the installation, add --ca-file <file> with a copy of /etc/navin-manager/tls/server.crt of the Manager.

    Expected result: Host registered: id <id>, cluster <cluster>. Credentials stored in /var/lib/navin-manager-agent.

    If it fails: see Troubleshoot the Navin agent (register_failed, ca_mismatch, network_error).

  3. Start the agent.

    sudo systemctl enable --now navin-manager-agent

    Expected result: systemctl is-active navin-manager-agent prints active; the host appears in Hosts with its facts and its preflight checks.

Register without a command​

Seed /etc/navin-manager-agent/enroll.env (mode 0600, root) before or after installing the package:

NM_SERVER=https://<manager-host>:8460
NM_TOKEN=<token>
NM_CA_SHA256=<fingerprint>
NM_REGISTER_ARGS="--ca-file /etc/navin-manager-agent/manager-tls.pem"

navin-manager-agent-enroll.service registers the host once, starts the agent and deletes the file (the token is used once). navin-manager-agent-enroll.timer retries every minute while the Manager cannot be reached. The variables are described in the configuration reference.

Register by SSH​

In the console, Nodes > Add nodes > SSH from the Manager: give the machines (one per line, name:port when needed), the identity of each one (SHA256 fingerprint or public key of its host key), an account with sudo without a password and the private key (OpenSSH or PEM, a passphrase is accepted), or an OpenSSH certificate of an approved authority, and a bastion when the machines are only reachable through it. The Manager checks the identity of every machine and of the bastion, then runs the same install as the command to paste (operation host.ssh_bootstrap). Root and passwords are refused; the key and the token stay in memory during the operation and are never stored. The corporate proxy of Settings is applied to the package manager.

Register a cloud instance​

Nodes > Add nodes > Cloud instance gives the script navin-user-data.sh to set as user data of the instance (AWS, Azure, OVHcloud, OpenStack, Scaleway, Oracle, Outscale, cloud-init) or as startup script (Google Cloud). The instance registers at its first boot; on a machine already registered the script does nothing. Image or automation gives the Ansible command, the Terraform lines and the enroll.env file.

Guided installation​

On a node, navin-install node from the offline archive of its family checks the host, installs the agent and registers it; it refuses a Manager whose certificate is not the one of the join command:

sudo ./navin-install node --server https://<manager-fqdn>:8460 --token-file <file> --ca-sha256 <fingerprint> --tls-sha256 <tls-fingerprint>

Verify​

sudo nm-agent status
sudo navinctl status

Expected result: Registered: host <id>, cluster <cluster>, Driver: systemd, rootless: False, and navin-manager-agent.service enabled and active.

Next steps​

Troubleshooting​

See Troubleshoot the Navin agent.