Using vf-agent

Each task below says what to type and what you should see. They work the same for every connector that includes vf-agent; the values for your connector (its product ID, its configuration file) are in its user guide. Every command and option is described on the vf-agent reference page.

Before you start: open a shell in the Seeq agent's data folder and set up the short vfa command, as in Set it up in your shell. The examples use the ABB Knowledge Manager connector, whose product ID is seeq-connector-abbkm; replace it with your connector's.

A first look

vfa version
vfa secrets verify
vfa secrets list

You should see:

• version names vf-agent 0.2 or later.
• verify lists every connection in your connectors' configurations, each with where its credential comes from, and ends failed: 0. A FAIL row says what is missing.
• list shows each stored credential's connection ID, name, type, and whether it is filled in, and never a password.

Move passwords out of the configuration

After upgrading a connector, its passwords may still be in its configuration. The connector copies them into the store and logs a warning; these steps take them out of the configuration.

1. Preview. Nothing is written:

vfa secrets migrate --product seeq-connector-abbkm --all

You should see every connection as harvest+replace or replace. A blocked row says what is missing; nothing will be changed until it is resolved. 2. Stop the Seeq agent service. 3. Apply, and type yes when asked:

vfa secrets migrate --product seeq-connector-abbkm --all --apply --agent-stopped

You should see Migration applied: and the number of connections moved. A copy of the configuration, with passwords masked, is kept in vforge\config-backups. 4. Start the Seeq agent, and check:

vfa secrets verify --require-store

You should see every connection taking its credential from the store, and failed: 0. In Seeq, the connector's configuration shows VFORGE_SECRETS where each password was.

To move one connection at a time, use --datasource <connection ID> instead of --all.

Add a connection

1. Add the connection to the connector's configuration, with VFORGE_SECRETS in its user name, password and domain fields, as in the connector's template. Your connector's user guide shows the fields. Saving the file restarts the connector.
2. The connector adds an empty entry for the new connection, keeps the connection inactive, and logs the command that fills it in, with the connection's ID already in it:

Fill it with: vf-agent secrets set seeq-connector-abbkm <connection ID> --username USER --domain DOMAIN

1. Run that line with USER and DOMAIN replaced (leave out --domain if the account has none), and type the password twice:

vfa secrets set seeq-connector-abbkm 1b6f9a0e-2d0c-4b1e-9d7a-5a8e3c2f1d00 --username svc-km --domain CORP

You should see the set check PASS. It does not ask for confirmation: the entry was empty. 4. Restart the Seeq agent, or wait for the connector to reconnect the connection, and it connects.

Use one account for several connections

Store the account once under a name, then point each connection at it:

vfa secrets set-shared km-service --username svc-km --domain CORP
vfa secrets use seeq-connector-abbkm <connection ID 1> km-service
vfa secrets use seeq-connector-abbkm <connection ID 2> km-service

You should see: vfa secrets verify shows both connections taking their credential from store-shared:km-service. If a connection already had its own password, use asks before replacing it.

Change a password

For one connection:

vfa secrets set seeq-connector-abbkm <connection ID> --username svc-km --domain CORP

For an account several connections share:

vfa secrets set-shared km-service --username svc-km --domain CORP

You should see: first the question Replace the credential stored for ...; type yes, then the new password twice. The connector uses it the next time the connection connects. Changing a shared account changes it for every connection that uses it.

Retire a connection

To remove a connection and its items in Seeq, start in Seeq:

1. Archive the datasource in Seeq: Administration → Datasources → the datasource → Archive, with its items. The Seeq agent can be running: Seeq turns the connection off in the agent's configuration straight away.
2. Restart the Seeq agent. Seeq removes the connection from the configuration, and no longer lists it.
3. Remove its credential, now that no connection uses it:

vfa secrets remove seeq-connector-abbkm --stale

You should see one row for it, remove. Run the same line again with --apply and type yes.

Deleting the connection from the configuration instead (by hand or with vfa datasources delete) leaves its items in Seeq, where it can then no longer be archived from Administration. To archive them later, add the connection back, disabled, with its old ID (vfa datasources add ... --id <old connection ID>), start the agent, and archive it in Seeq.

To stop a connection but keep it, disable it instead (for ABB Knowledge Manager, "Enabled": false on the connection, or vfa datasources disable), and remove its credential:

vfa secrets remove seeq-connector-abbkm <connection ID>
vfa secrets remove seeq-connector-abbkm <connection ID> --apply

The preview shows one row, remove, "disabled in the connector config"; --apply asks, then you should see Removed: 1 entry. If the connection is still enabled, remove refuses ("set Enabled to false first") and changes nothing. There is no undo: to restore the credential, set it again.

Run each command that asks a question on its own: a question reads the next line you type or paste, so pasting several commands at once answers it with the next one, which is refused.

Clean up after deleting connections

If you deleted connections from the configuration instead of disabling them, their credentials are still in the store, and the connector logs that they match no configured connection.

vfa secrets remove seeq-connector-abbkm --stale
vfa secrets remove seeq-connector-abbkm --stale --apply

You should see: the preview lists only credentials whose connection is no longer in the configuration. --apply asks, then removes them. Running the preview again shows nothing to remove.

To remove a shared account no connection uses any more:

vfa secrets remove-shared --stale --apply

A shared account still in use is refused, and the row names the connections using it.

Check a configuration after editing it by hand

vfa config check seeq-connector-abbkm

You should see: failed: 0. A formatting mistake shows as not valid JSON at line L, column C: look just before that point for a missing comma, quote or brace.

Add a connection with vf-agent

1. Preview the new connection, with its server's settings:

vfa datasources add seeq-connector-abbkm --name "KM Plant 2" --set WebServiceIP=km2.example.com --set WebServiceMethod=https --set WebServicePort=443

1. Stop the Seeq agent, then add it:

vfa datasources add seeq-connector-abbkm --name "KM Plant 2" --set WebServiceIP=km2.example.com --set WebServiceMethod=https --set WebServicePort=443 --apply --agent-stopped

You should see its new ID, the backup that was kept, and the vf-agent secrets set line for its credential.

1. Give it its credential, with the line from step 2 (replace USER and DOMAIN), and turn it on:

vfa secrets set seeq-connector-abbkm <new connection ID> --username svc-km --domain CORP
vfa datasources enable seeq-connector-abbkm <new connection ID> --apply --agent-stopped

1. Start the Seeq agent. You should see the connection connect, and the new datasource in Seeq.

If the account is shared with other connections, add --use <shared name> in step 2 and skip the secrets set in step 3.

Replace a connection

Seeq matches its copy of the configuration to the file by each connection's ID, so change it in two steps, never by replacing the whole file:

1. Add the new connection (above), start the Seeq agent, and check it connects.
2. Then retire the old one. To archive its items, archive it in Seeq and restart the agent (Retire a connection). To keep its items in Seeq (for analyses that use them), delete it from the configuration with the agent stopped:

vfa datasources delete seeq-connector-abbkm <old connection ID> --with-credential --apply --agent-stopped

Type keep when asked. Start the agent again.

Several connections configured alike

Set one up, then copy it for each server:

vfa datasources copy seeq-connector-abbkm <connection ID> --name "KM Plant 3" --set WebServiceIP=km3.example.com --apply --agent-stopped

Each copy gets a new ID and the original's credential, and starts disabled: datasources enable each one when it is ready.

Replace a connection with a copy

To move a connection to a new ID with the same settings and credential (for example after a change in Seeq that needs a fresh datasource): copy it, delete the original, and enable the copy, with the Seeq agent stopped for each step and started again at the end.

vfa datasources copy seeq-connector-abbkm <old connection ID> --name "<new name>" --apply --agent-stopped
vfa datasources delete seeq-connector-abbkm <old connection ID> --apply --agent-stopped
vfa datasources enable seeq-connector-abbkm <new connection ID> --apply --agent-stopped

The copy is a new datasource to Seeq: its signals are new items, and existing analyses keep pointing at the original's. Seeq lists the copy only once it is enabled. delete asks: type keep to keep the original's items in Seeq. To archive them instead, skip the delete: archive the original in Seeq, enable the copy, and start the agent. Keep at least one other connection in the file while you do this, so Seeq keeps recognizing the configuration.

Retire a connection with vf-agent

To stop a connection but keep it in Seeq:

vfa datasources disable seeq-connector-abbkm <connection ID> --apply --agent-stopped

Start the agent; the connection stops. To remove it later, together with its items, archive it in Seeq (Retire a connection). vfa datasources delete removes it from the configuration only, and leaves its items in Seeq.

Undo a change to the configuration

Each change keeps a copy of the file first, in vforge\config-backups, named <file>.bak-<date and time>-vf-agent. To go back: stop the Seeq agent, copy the newest one over the file in configuration\link (keeping the file's name), and start the agent. Passwords in the copy are masked: the connector takes credentials from the store, so nothing is lost.

Evidence for a security review

vfa --json secrets verify --require-store > verify.json

You should see: exit code 0 ($LASTEXITCODE in PowerShell), every connection taking its credential from the store, and the permissions check PASS. The file is the evidence that no connection's password is left in a configuration.

If permissions fails, restrict the store's folder to the account that runs the Seeq agent, SYSTEM and Administrators:

icacls ".\vforge\secrets" /inheritance:r /grant:r "<agent service account>:(OI)(CI)F" "SYSTEM:(OI)(CI)F" "Administrators:(OI)(CI)F"

If an account has access on purpose, such as a backup account, name it with --allow-access "<DOMAIN\account>". verify then accepts it and lists it in the result, so the evidence shows what was allowed.

Scripting

• Answer the questions with --yes. Without it, a script stops at the first question, changes nothing, and exits with 2.
• Pass the password on standard input with --stdin, from your own secret-management tooling. Never put it in the script itself.
• Read the result with --json, and check the exit code.
• Call it by its full path with & in a script, not through the vfa function: a PowerShell function does not pass piped input on to the program it calls, so --stdin would get nothing.

$vf = "<data folder>\vforge\bin\vf-agent.cmd"
# Get-MySecret stands for your own secret tooling; it should output the password and nothing else.
Get-MySecret km-service | & $vf --json --yes secrets set-shared km-service --username svc-km --domain CORP --stdin
if ($LASTEXITCODE -ne 0) { throw "vf-agent failed: $LASTEXITCODE" }

Windows PowerShell 5.1 sends piped text to a program as ASCII by default, which turns characters outside it into ?. For a password with such characters, first set $OutputEncoding = [System.Text.UTF8Encoding]::new($false), or use PowerShell 7.

When something goes wrong

You see	Why	Do
Unexpected token 'secrets' (PowerShell)	$vf secrets ... without the &	Use vfa ..., or & $vf ...
The term 'vf-agent.cmd' is not recognized (PowerShell)	Run by name from its own folder	.\vf-agent.cmd ...
no data folder (exit 2)	The copy from the connector package, without --data-folder	Use the installed copy, or add --data-folder <data folder>
needs confirmation (exit 2)	A script, or a remote session with no console, without --yes	Add --yes, or run it at a console
stop the Seeq agent service first (exit 2)	migrate --apply without --agent-stopped	Stop the agent, then add --agent-stopped
not confirmed; nothing was changed (exit 1)	Something other than the expected answer was typed, or a pasted line answered the question	Run the command on its own and type yes (for datasources delete: archived or keep)
verify fails store-parses; a change stops with exit 3	The credentials file is damaged, usually by a hand edit (a missing comma or quote)	Do not restart the Seeq agent: see Recover a damaged credentials file
Every connection inactive after a restart; the log says store file ... cannot be used	The same: the credentials file is damaged	Recover a damaged credentials file
exit 3, lock timeout	Another program was writing the credentials file	Run it again
A connection stays inactive after set	It tries again every 60 seconds	Wait a minute; no restart is needed. If it still does not connect, check its log line

Recover a damaged credentials file

vf-agent keeps no copy of the credentials file, vforge\secrets\credentials.json: a copy would be a second place holding the passwords. While the file is damaged, a running agent keeps working, but after a restart every connection on the agent stays inactive until the file is readable again. So do not restart the agent until vfa secrets verify passes. Then, in this order:

1. Fix the file. vfa secrets verify shows not valid JSON at line L, column C, without showing the file's contents. Correct the mistake just before that point, save, and run verify again.
2. Or restore it from a copy made before the edit, or from the host's own backup. Stop the agent, copy it over vforge\secrets\credentials.json, run verify, and start the agent. Treat any copy like the passwords themselves.
3. Or rebuild it, if neither works. You need each connection's password:
4. Stop the agent, and move the damaged file out of vforge\secrets; delete it once you are done.
5. Start the agent. The connector adds an empty entry for each connection and logs a Fill it with: line for each.
6. Fill them in: for one shared account, vfa secrets set-shared once and vfa secrets use for each connection (Use one account for several connections); otherwise vfa secrets set for each.

You should see: vfa secrets verify passes, and each connection reconnects within a minute, without a restart.

When you contact EEI support, include the command and its output, or its --json output. They never contain a password.