Upgrade Guide

Overview

Nefia upgrades are performed on both the CLI (operator side) and the agent (target PC side). All binaries are verified with Ed25519 signatures, ensuring that tampered binaries are never applied.

CLI Upgrade

Automatic Update

Use the nefia update command to update to the latest version:

nefia update

The update process:

1. Fetches the latest version information from the update server
2. Downloads the new binary
3. Verifies the Ed25519 signature
4. Replaces the current binary

Check for Updates Only

To check for a new version without installing:

nefia update --check

Update Notifications

Nefia checks for new versions in the background during command execution and displays a notification when an update is available. This notification is not shown for the update and version commands.

Manual Update

If automatic updates are not available (e.g., dev builds):

1. Download the latest binary from the Releases page
2. Replace the existing binary
3. Verify the version:

   bash

   nefia version

Agent Upgrade

There are two methods for upgrading agents.

Method 1: Remote Update (Pull-based)

The agent pulls the latest version from its own update server. This is the recommended method for large-scale environments.

# Update agents on all hosts to the latest version
nefia agent update --host "all"
 
# Specific host only
nefia agent update --host my-server
 
# Specify a particular version
nefia agent update --host my-server --version v1.1.0

This command performs the following:

1. Enables auto-update in the remote agent.yaml
2. (When --version is specified) Sets the pinned version
3. Restarts the agent service to trigger an update check

Method 2: Operator Push (Push-based)

Pushes the binary directly from the operator. This is for environments where the update server is not available.

nefia agent upgrade --host my-server
nefia agent upgrade --host my-server --agent-dir /path/to/binaries

Rolling Upgrade

When upgrading a large number of hosts at once, use --batch-size or --batch-percent to perform the upgrade in stages:

# Upgrade 5 hosts at a time
nefia exec --host "all" --batch-size 5 "sudo systemctl restart nefia-agent"
 
# 20% of all hosts at a time
nefia exec --host "all" --batch-percent 20 "sudo systemctl restart nefia-agent"

Auto-Update Configuration

Auto-update can be configured in the agent's agent.yaml:

update:
  enabled: true
  interval: "1h"           # Check interval (default: value of --auto-update-interval flag)
  pinned_version: ""       # Pin to a specific version (empty = latest)
  auto_rollback: true      # Automatic rollback on failure

Or configure via flags when starting the agent:

nefia-agent run --auto-update-interval 24h

MCP Tools

Agent management tools available via MCP:

Version Pinning

You can pin an agent to a specific version to prevent unintended updates:

# Pin to a version (version is a positional argument)
nefia agent pin v1.0.5 --host my-server
 
# Unpin
nefia agent unpin --host my-server

While pinned, even if auto-update runs, the agent will not be updated to any version other than the pinned one.

Rollback

Automatic Rollback

When auto_rollback: true is set in agent.yaml, automatic rollback is performed if an update fails.

How automatic rollback works:

Manual Rollback

If automatic rollback is not available:

# Linux
sudo systemctl stop nefia-agent
 
# macOS
sudo launchctl unload /Library/LaunchDaemons/com.nefia.agent.plist

# Linux / macOS
sudo cp /path/to/previous/nefia-agent /usr/local/bin/nefia-agent
sudo chmod +x /usr/local/bin/nefia-agent

# Linux
sudo systemctl start nefia-agent
 
# macOS
sudo launchctl load /Library/LaunchDaemons/com.nefia.agent.plist

Signature Verification

All updates are verified with Ed25519 digital signatures.

To check version information and signatures:

nefia version

Configuration Compatibility

After an upgrade, the configuration format of nefia.yaml or agent.yaml may change.

Automatic Configuration Migration

In general, new versions maintain backward compatibility with older configuration formats. New configuration fields operate with default values.

Post-Upgrade Verification

After upgrading, verify configuration integrity with nefia doctor:

nefia doctor

If a configuration validation error (E4001) occurs, check the latest configuration format in the Configuration Reference.

Upgrade Best Practices

1. Run nefia doctor before upgrading -- Identify any existing issues
2. Verify in a test environment first -- Test before rolling out to production
3. Gradual rollout -- Deploy incrementally with --batch-percent
4. Enable auto-rollback -- Update safely with auto_rollback: true
5. Run nefia doctor again after upgrading -- Confirm there are no issues

Next Steps