agent

package module
v0.25.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 9, 2026 License: AGPL-3.0 Imports: 33 Imported by: 0

README

Viam Agent

A self-updating service manager that maintains the lifecycle for viam-server (as built from RDK) and other Viam provided system services.

For more information, see the Viam Agent documentation.

Agent is designed to run as a systemd service. First-time setup is sudo ./viam-agent --install and it will automatically update itself when new updates are released.

Development

Required tools

We use mise-en-place to manage golangci-lint. In the future this may expand to include other development tools. You can install it on MacOS and most Linux distributions with the following command:

curl https://mise.run | sh

Mise is also available in Homebrew and several package repositories. See the official documentation for a list of installation methods.

Makefile Targets
  • make will build a viam-agent for your current CPU architecture. Note that as only linux is supported, this will be a linux binary.
  • make arm64 arm64 specific build.
  • make amd64 amd64 specific.
  • make all will build for all (both) supported architectures.
  • make lint to lint.
Version Tagging

The makefile will attempt to get a tagged version from Git. If you want to manually force a version, set TAG_VERSION=0.1.2 in the make command.
Note that there is no "v" in the actual version, though it is expected in git. E.g. a git tag of v0.1.2 becomes TAG_VERSION=0.1.2
Ex: make all TAG_VERSION=0.1.2

DevMode

Agent can be run directly (./viam-agent) outside of systemd for local development purposes. It will only manage viam-server by default. Network and system configuration management can be enabled with --enable-networking and --enable-syscfg. --viam-dir can be used to override the default /opt/viam location. See --help for the full list of options.

Systemd

The service configration lives in both viam-agent.service and preinstall.sh, and the two should be kept in sync when making changes.

Testing via serial

Some end-to-end workflows can be tested by connecting to a Raspberry Pi with a serial adapter. These tests can be run via a mise task but require additional setup:

  • You must have a USB to serial adapter or some other means to connect to the serial port on your Raspberry Pi.
  • Your Raspberry Pi must be configured to enable login on the serial port. This can be accomplished with the raspi-config cli or by manually editing config files. Refer to the upstream Raspberry Pi docs for details.
  • The serial connection must already have a shell logged in as a user that can use sudo to become root without a password. To log in over the serial connection we recommend picocom. You can use it to connect to the serial terminal and login with picocom -b 115200 /dev/ttyUSB0. Depending on your setup the previous command may require sudo and the path to the tty device may be different. Once you have logged in you can disconnect from the serial console by typing Ctrl-a Ctrl-x.
  • You must have a file named agent-test.toml in the root of this repo with app.viam API keys and other values required by the tests. You can also use this file to specify optional parameters, such as the path to the serial device. Refer to agent-test-example.toml for details.

Once these dependencies are satisfied you can execute the serial tests with mise r test-e2e-serial.

Documentation

Overview

Package agent is the viam-agent itself. It contains code to install/update the systemd service as well.

Package agent contains the public interfaces, functions, consts, and vars for the viam-server agent.

Index

Constants

View Source 
const (
	SubsystemName = "viam-agent"
)

Variables

This section is empty.

Functions

func Install added in v0.14.0 

func Install(ctx context.Context, logger logging.Logger, sdManager systemdManager) error

Install is directly executed from main() when --install is passed.

func InstallNewVersion added in v0.14.0 

func InstallNewVersion(ctx context.Context, logger logging.Logger) (bool, error)

InstallNewVersion runs the newly downloaded binary's Install() for installation of systemd files and the like.

func VersionCacheExists added in v0.22.2 

func VersionCacheExists() bool

Types

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the core of the agent process, and maintains the list of subsystems, as well as cloud connection.

func NewManager 

func NewManager(ctx context.Context, logger logging.Logger, cfg utils.AgentConfig, globalCancel context.CancelFunc) *Manager

NewManager returns a new Manager.

func (*Manager) CheckIfNeedsRestart added in v0.22.3 

func (m *Manager) CheckIfNeedsRestart(ctx context.Context) (time.Duration, bool)

CheckIfNeedsRestart returns the check restart interval and whether the agent (and therefore all its subsystems) has been forcibly restarted by app.

func (*Manager) CheckUpdates 

func (m *Manager) CheckUpdates(ctx context.Context) time.Duration

CheckUpdates retrieves an updated config from the cloud, and then passes it to SubsystemUpdates().

func (*Manager) CloseAll 

func (m *Manager) CloseAll()

CloseAll stops all subsystems and closes the cloud connection.

func (*Manager) CreateNetAppender added in v0.4.0 

func (m *Manager) CreateNetAppender() (*logging.NetAppender, error)

CreateNetAppender creates or replaces m.netAppender. Must be called after config is loaded.

func (*Manager) Exit added in v0.18.0 

func (m *Manager) Exit(reason string)

func (*Manager) GetConfig 

func (m *Manager) GetConfig(ctx context.Context) (time.Duration, error)

GetConfig retrieves the configuration from the cloud.

func (*Manager) GetNetAppender added in v0.17.0 

func (m *Manager) GetNetAppender() logging.Appender

GetNetAppender is a somewhat ugly workaround to pass the (constructed later) netAppender to the syscfg subsystem.

func (*Manager) LoadAppConfig added in v0.14.0 

func (m *Manager) LoadAppConfig() error

func (*Manager) SelfUpdate 

func (m *Manager) SelfUpdate(ctx context.Context) (bool, error)

SelfUpdate is called early in startup to update the viam-agent subsystem before any other work is started.

func (*Manager) StartBackgroundChecks 

func (m *Manager) StartBackgroundChecks(ctx context.Context)

StartBackgroundChecks kicks off go routines that loop on a timerr to check for updates, health checks, and restarts.

func (*Manager) StartSubsystem added in v0.1.0 

func (m *Manager) StartSubsystem(ctx context.Context, name string) error

StartSubsystem may be called early in startup when no cloud connectivity is configured.

func (*Manager) SubsystemHealthChecks 

func (m *Manager) SubsystemHealthChecks(ctx context.Context)

SubsystemHealthChecks makes sure all subsystems are responding, and restarts them if not.

func (*Manager) SubsystemUpdates 

func (m *Manager) SubsystemUpdates(ctx context.Context)

SubsystemUpdates checks for updates to configured subsystems and restarts them as needed.

type VersionCache added in v0.14.0 

type VersionCache struct {
	ViamAgent   *Versions `json:"viam_agent"`
	ViamServer  *Versions `json:"viam_server"`
	LastCleaned time.Time `json:"last_cleaned"`
	// contains filtered or unexported fields
}

func NewVersionCache added in v0.14.0 

func NewVersionCache(logger logging.Logger) *VersionCache

func (*VersionCache) AgentVersion added in v0.14.0 

func (c *VersionCache) AgentVersion() string

func (*VersionCache) CleanCache added in v0.18.0 

func (c *VersionCache) CleanCache(ctx context.Context)

func (*VersionCache) CleanPartials added in v0.23.0 

func (c *VersionCache) CleanPartials(ctx context.Context) error

CleanPartials is called by CleanCache and cleans up incomplete partial downloads that have not been modified for 3 days. The 3-day grace period is 1) to avoid breaking ongoing downloads and 2) to give spotty connections a chance to resolve.

func (*VersionCache) MarkViamServerRunningVersion added in v0.14.0 

func (c *VersionCache) MarkViamServerRunningVersion()

func (*VersionCache) Update added in v0.14.0 

func (c *VersionCache) Update(cfg *pb.UpdateInfo, binary string) error

Update processes data for the two binaries: agent itself, and viam-server.

func (*VersionCache) UpdateBinary added in v0.14.0 

func (c *VersionCache) UpdateBinary(ctx context.Context, binary string) (bool, error)

UpdateBinary actually downloads and/or validates the targeted version. Returns true if a restart is needed.

func (*VersionCache) ViamServerRunningVersion added in v0.14.0 

func (c *VersionCache) ViamServerRunningVersion() string

func (*VersionCache) ViamServerVersion added in v0.14.0 

func (c *VersionCache) ViamServerVersion() string

type VersionInfo 

type VersionInfo struct {
	Version      string
	URL          string
	DlPath       string
	DlSHA        []byte
	UnpackedPath string
	// the sha256 field of the UpdateInfo proto
	UnpackedSHA []byte
	SymlinkPath string
	Installed   time.Time

	// Last-Modified field from http header, if available
	LastModified      time.Time
	LastModifiedCheck time.Time
}

VersionInfo records details about each version of a subsystem.

type Versions added in v0.14.0 

type Versions struct {
	TargetVersion   string                  `json:"target_version"`
	CurrentVersion  string                  `json:"current_version"`
	PreviousVersion string                  `json:"previous_version"`
	Versions        map[string]*VersionInfo `json:"versions"`
	// contains filtered or unexported fields
}

Versions stores VersionInfo and the current/previous versions for (TODO) rollback.

Source Files

View all Source files

Directories

Path Synopsis
cmd
provisioning-client command
test-client command
A simple test client to fetch and print the results of DeviceAgentConfig() for use when testing changes in App.
 A simple test client to fetch and print the results of DeviceAgentConfig() for use when testing changes in App.
viam-agent command
internal
serialcontrol
Package serialcontrol provides utilities to control a Linux machine, probably a Raspberry Pi running Rasbian, via a serial terminal.
 Package serialcontrol provides utilities to control a Linux machine, probably a Raspberry Pi running Rasbian, via a serial terminal.
subsystems
networking
Package networking is the subsystem responsible for network/wifi management, and initial device setup via hotspot.
 Package networking is the subsystem responsible for network/wifi management, and initial device setup via hotspot.
syscfg
Package syscfg contains the system configuration agent subsystem.
 Package syscfg contains the system configuration agent subsystem.
viamserver
Package viamserver contains the viam-server agent subsystem.
 Package viamserver contains the viam-server agent subsystem.
Package utils contains helper functions shared between the main agent and subsystems
 Package utils contains helper functions shared between the main agent and subsystems
systemd
Package systemd provides helpers to manipulate systemd services that are specifict to viam-agent's needs.
 Package systemd provides helpers to manipulate systemd services that are specifict to viam-agent's needs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.