1.8 Virtual Appliance Command Selection

Key Takeaways

  • Use timedatectl status to inspect the appliance’s time synchronization status.

  • On a standard Flatcar VA, sudo update_engine_client -status checks update state. The UPDATE_STATUS_UPDATED_NEED_REBOOT state calls for following the documented recovery procedure.

  • Use sudo docker logs otel_agent to inspect telemetry backend detection when diagnosing that agent.

  • Restart commands affect specific services. Use the command that matches the configuration change, and confirm the result.

Last updated: November 2026

Distinguish observing from changing

Choose a command based on the evidence needed on a specific VA. If an engineer sees an operating system update warning, the status command can confirm that an update is pending reboot. A command that simply inspects configuration should precede a service restart when the symptom alone does not identify the problem. The commands here are documented for the standard SailPoint appliance and the specific supported tasks shown below. Apply the operating system’s own guidance when using an approved customer-provided image.

NeedDocumented commandScope and expected outcome
Inspect time service statustimedatectl statusInspect the clock and synchronization state on this VA
Check a Flatcar update warningsudo update_engine_client -statusRead update engine state, including whether a reboot is pending
Inspect the telemetry container’s backend detectionsudo docker logs otel_agentRead the agent container log for the current configuration
Apply an approved change to the time server configurationsudo systemctl restart systemd-timesyncdRestart the time synchronization service on the member that was edited
Apply a documented source host mapping changesudo systemctl restart charonRestart the service SailPoint names when applying hosts.yaml edits
Apply a corrected observability agent configurationsudo systemctl restart otel_agentRestart the monitoring agent after configuring its export settings

On a standard VA, SailPoint documents managing an internal Network Time Protocol (NTP) configuration through /etc/systemd/timesyncd.conf. Place approved servers on the NTP= line, restart the corresponding service, and inspect time status. That is a per-appliance change. If the organization plans to remove the external NTP path, verify every VA has an alternative before the network change. Inventory the affected appliances by cluster and member and verify synchronization on each affected host. Updating a member does not change the time service on its peers.

For a connector implementation that specifically needs a static host entry, SailPoint documents /home/sailpoint/hosts.yaml. The configuration associates an address with the applicable host names, with indentation and exact host matching. Restart charon after saving that file and test the relevant source connection. This action is for the documented host-file use case. It does not establish that an upstream DNS problem has been repaired.

Choose the right host action

A Flatcar member reports that the OS update needs a reboot. First use the update status command and look for UPDATE_STATUS_UPDATED_NEED_REBOOT. Review the cluster’s other member and the affected operations before following the documented recovery. If the automatic update fails to reboot the VA, SailPoint’s management instructions direct the operator to the cluster restart procedure. Confirm that the update alert and member health change as expected. Restarting the telemetry agent would leave the OS update pending.

In another ticket, monitoring stopped after a metric backend migration. The updated otel.env points at an incorrect endpoint. Inspect the agent’s documented local file or container log, correct the endpoint in the approved configuration, restart the agent, then look for a fresh metric at the destination. Restarting the time service would leave the bad endpoint unchanged. Confirming only that the agent restarted gives no evidence that the receiver accepted the metric.

An edited hosts file also has a simple pass and fail test. Suppose a connection uses directory.example.org, but an entry provides only a short alias for that server. Verify that the file contains the connector’s exact fully qualified name with the expected address and correct YAML indentation before restarting the documented service. Then run a connection test through the cluster. Restarting a service with the wrong host mapping leaves the original configuration problem in place.

The procedure for the local sailpoint account is different again. SailPoint documents passwd followed by a VA reboot for changing that account’s password. That operation affects the appliance login. Cluster bootstrap commands set the shared passphrase and generate a pairing code. The source credential instead belongs to the connected target and is configured for that source. In an incident, a single word such as “password” is insufficient to select a command. Identify which credential or configuration is implicated first.

See SailPoint’s VA management and Flatcar status, internal NTP procedure, host mapping steps and telemetry commands.

Test Your Knowledge

A standard Flatcar VA reports an OS update warning. Which command queries whether the appliance is waiting for a reboot?

A

sudo systemctl restart otel_agent

B

sudo update_engine_client -status

C

timedatectl status

D

va-bootstrap pair

Test Your Knowledge

An engineer has saved an approved internal NTP server change in timesyncd.conf. Which documented action applies and verifies the change?

A

Restart charon and read ccg.log

B

Run va-bootstrap pair and check the tenant entry

C

Restart the OpenTelemetry agent and check the metrics destination

D

Restart systemd-timesyncd and inspect timedatectl status

Sections you finish are checked off in the contents.