vf-agent

vf-agent is the command-line tool that comes with Endeavor Engineering (EEI) connectors. It runs on the host where your Seeq agent runs, and does the jobs that would otherwise mean editing files by hand: managing the credentials your connectors use to sign in to your source systems, checking a connector's configuration, and adding, changing and removing its connections.

This page is the reference: how to run it, and every command and option. For step-by-step tasks (add a connection, change a password, retire a connection), see Using vf-agent. Each connector's user guide gives the values for that connector.

Which products include it

Product	Product ID (used in commands)	Included from
ABB Knowledge Manager connector	seeq-connector-abbkm	The release after 100.35.137
Metadata connector	—	A later release

vf-agent is not installed or licensed separately. Each connector that includes it installs it on the agent host when it starts. This page describes vf-agent 0.2; vf-agent version shows yours.

Where it is

The connector installs vf-agent into the Seeq agent's data folder, the folder that holds configuration and vforge:

Copy	Path	Use
Installed by the connector	<data folder>\vforge\bin\vf-agent.cmd on Windows, <data folder>/vforge/bin/vf-agent on Linux	Normally. It already knows the data folder
In the connector package	bin\vf-agent.cmd in the unpacked zip	Before the connector has started for the first time. Add --data-folder <data folder> to every command

Each start of the connector refreshes the installed copy. When several EEI connectors run on one agent, the newest vf-agent among them is the one used; an older connector never replaces a newer one. Your PATH is not changed.

Set it up in your shell

Open a shell in the data folder, then paste the lines for your shell once per session. They store the full path, so they keep working if you change folder, and give you a short vfa command.

PowerShell:

$vf = "$PWD\vforge\bin\vf-agent.cmd"
function vfa { & $vf @args }
vfa version

Without the vfa function, every call needs PowerShell's call operator &: & $vf secrets list. Leaving the & out is a PowerShell error ("Unexpected token"). From inside vforge\bin, write .\vf-agent.cmd: PowerShell does not run a program from the current folder by its name alone.

Command Prompt:

set "VF=%CD%\vforge\bin\vf-agent.cmd"
doskey vfa="%VF%" $*
vfa version

In a batch file, write call "%VF%" secrets list instead; without call, the batch file stops after the first vf-agent command.

bash (Linux):

VF="$PWD/vforge/bin/vf-agent"
vfa() { "$VF" "$@"; }
vfa version

Run it as the account that runs the Seeq agent, so the files it writes belong to that account.

Linux agents. Seeq currently supports the Seeq agent on Windows. The Linux instructions are kept here, and kept up to date, for when Seeq supports Linux agents again.

To keep the setup, put the PowerShell lines in your $PROFILE, or the bash lines in ~/.bashrc, with the data folder's full path in place of $PWD.

The examples on these pages are written vfa ....

How a command is built

vf-agent [--data-folder <path>] [--json] [--yes] <group> <command> [<arguments and options>]
vf-agent version
vf-agent help [<group>]

Commands come in groups: secrets (credentials), config (checking a connector's configuration) and datasources (its connections). For example, vfa secrets list.

Option	Meaning
--data-folder <path>	The Seeq agent's data folder. Not needed with the installed copy. Can also come from the VFORGE_DATA_FOLDER environment variable
--json	Print the result as one JSON document, for scripts
--yes	Answer yes to a confirmation (see below). Also accepted at the end of the command

vf-agent version shows the version and the Java it runs on.

Help at every level: vfa --help lists every command; vfa datasources --help one group's; vfa datasources add --help one command's, with what each option does and examples. Help changes nothing.

What it prints

Each command prints its own result (a list, a plan, a note), then a PASS/FAIL table of every check it made, ending with failed: 0 when all is well. With --json, the same result is one JSON document with the keys tool, version, command, result (pass or fail), checks and data. Questions are asked on the console, never in that output, so a script can always read it.

Exit code	Meaning
0	Everything checked passed, and anything asked for was done
1	A check failed, or the command refused (something it would change is blocked, or you did not answer yes)
2	The command was not understood: an unknown option, a missing argument, no data folder, or a question with no one to answer it
3	It could not work: a file it must change cannot be read, another program held the store's lock, or a disk error

It asks before removing or replacing anything

A command that removes or replaces something first says what it will change and asks you to type yes. It asks before it prompts for a password, so you never type a password only to cancel.

You	Result
Type yes	It goes ahead
Type anything else	Nothing is changed (exit 1)
Add --yes	It goes ahead without asking: for scripts
Run it from a script with no --yes	Nothing is changed (exit 2)

Commands that can preview (migrate, remove, remove-shared) only show their plan until you add --apply, and ask only then.

What it never does

• It never takes a password on the command line, where it would stay in your shell history. It asks for it without showing what you type, or reads it from standard input with --stdin.
• It never shows a password. Not in its output, not in a log.
• It is safe to run while the Seeq agent is running, except where a command says otherwise. Changes to the credentials file are locked and written in one step, so the connector never reads half a change. Changing a connector's configuration (secrets migrate --apply) needs the Seeq agent stopped.
• It makes no network calls. It works only with files on the agent host.

The secrets commands

Connectors keep the credentials they use to sign in to your source systems in one file on the agent host, <data folder>\vforge\secrets\credentials.json, rather than in their configuration, which Seeq administrators can read. Each connection's credential is found by the connection's ID. In a connector's configuration, VFORGE_SECRETS in a credential field means "take this from the store". What the store protects, and what it does not, is described in Keeping Credentials Out of the Configuration.

Word	Meaning
product	The connector a credential belongs to, by its product ID (see the table above)
entry	One connection's credential in the store, or its link to a shared one
shared credential	One named credential that several connections use
filled	The entry holds everything it needs. A connector adds an empty entry for a new connection
stale	An entry whose connection is no longer in the connector's configuration, or a shared credential no connection uses

secrets list

vfa secrets list [--product <product ID>]

Lists what the store holds: product, connection ID, name, type, filled or not. Never a password. Changes nothing. --product lists one product's entries only.

secrets set

vfa secrets set <product ID> <connection ID> --username <user> [--domain <domain>] [--stdin]

Stores a connection's own credential. It asks for the password twice, without showing it, and stops if the two differ. Asks first if the connection already has a filled credential.

Option	Meaning
--username <user>	The account's user name. Required for a user-name-and-password credential
--domain <domain>	The account's Windows domain, if it has one
--stdin	Read the password from standard input instead of asking (for scripts)
--name <text>	The connection's name, for your reference. Normally kept from the entry
--type <type>	Only for products whose credential is not a user name and password

secrets set-shared

vfa secrets set-shared <shared name> --username <user> [--domain <domain>] [--stdin]

Stores a credential under a name of your choice, for several connections to use. Same options as set. Asks first when replacing a filled one.

secrets use

vfa secrets use <product ID> <connection ID> <shared name>

Points a connection at a shared credential. Asks first if the connection already has its own filled credential, or uses a different shared one.

secrets verify

vfa secrets verify [--product <product ID>] [--require-store] [--allow-access <account> ...]

Checks the store and, for every connection in your connectors' configurations, whether it has a usable credential and where it comes from: the store, a shared credential, or (deprecated) the configuration itself. Changes nothing, and does not sign in to the source system.

Option	Meaning
--product <product ID>	One product's connections only
--require-store	Also fail any connection whose password is still in the configuration. The evidence for a security review
--allow-access <account>	An account you have deliberately given access to the store, such as a backup account. Repeatable; listed in the result

It also checks the file's permissions: on Windows, only the agent's account, SYSTEM and Administrators should have access.

secrets migrate

vfa secrets migrate --product <product ID> (--all | --datasource <connection ID> ...) [--apply --agent-stopped]

Moves passwords from a connector's configuration into the store, and puts VFORGE_SECRETS in their place.

Option	Meaning
--all	Every connection in the configuration, including disabled ones
--datasource <connection ID>	Only this connection. Repeatable
--apply	Make the change. Without it, nothing is written: you see the plan
--agent-stopped	Required with --apply: you confirm the Seeq agent service is stopped
--config <path>	A configuration file other than the product's usual one

Its plan shows each connection's action: harvest+replace (copy, then replace), replace (already in the store), none (already done), or blocked (it would leave the connection with no credential; the row says why, and nothing is changed while any row is blocked). With --apply it asks first, makes a copy of the configuration with passwords masked, changes it, and checks the result. Running it again is harmless.

secrets remove

vfa secrets remove <product ID> (<connection ID> ... | --stale) [--apply]

Removes connections' credentials from the store, the last step of retiring a connection. --stale selects every credential whose connection is no longer in the configuration.

It removes a credential only if its connection is disabled in the configuration, or no longer in it. A connection that is still enabled is refused, since it would lose its credential. Shows its plan until you add --apply; then asks first. There is no undo: to restore a credential, set it again.

secrets remove-shared

vfa secrets remove-shared (<shared name> ... | --stale) [--apply]

Removes shared credentials. Refused while any connection still uses one; the row names which. --stale selects every shared credential no connection uses.

The config and datasources commands

These change or check a connector's configuration file, the one in <data folder>\configuration\link that lists its connections. They need a small description of the connector, which the connector writes each time it starts (vforge\products\<product ID>\connector-profile.json): the file's name and fields, the starting values for a new connection, and the values it accepts. If it is missing, start the connector once.

Rules for every change to a configuration

• It shows its plan and changes nothing until you add --apply.
• With --apply, say whether the Seeq agent is running: --agent-stopped (recommended) or --agent-running. One of the two is required. Seeq can also change this file while the agent runs, so a change made at the same moment can be lost; with --agent-running, check datasources list after.
• It checks the result the way config check does, and refuses to write a file that would not pass.
• It keeps a copy of the file before changing it, with passwords masked, in vforge\config-backups.
• It writes the file once, in one step. Each time the file is saved, the connector restarts its connections.
• It never removes the last connections. Seeq keeps its own copy of the configuration and matches it to the file by each connection's ID. Keep at least one existing connection when you make changes; delete refuses to remove them all.

config check

vfa config check <product ID>

Checks the configuration file without changing it, and fails on: a formatting error in the file (with its line and column), a Version line the connector does not recognize (Seeq would start the connector with an empty configuration; the check names the value to write), a connection with no ID or the same ID as another, a connection with no name, Enabled written as text ("true" in quotes) instead of true, a required field left empty, or a value the connector does not accept. Run it after any change made by hand.

datasources list

vfa datasources list <product ID>

Lists each connection: ID, name, enabled or not, and where its credential comes from.

datasources enable and datasources disable

vfa datasources disable <product ID> <connection ID> ... --apply --agent-stopped

Turns connections on or off. A disabled connection stops connecting; its items stay in Seeq.

datasources add

vfa datasources add <product ID> --name <name> [--set <Field>=<value> ...] [--enabled] [--use <shared name>] --apply --agent-stopped

Adds a connection, starting from the connector's own defaults, with a new ID and the name you give. It starts disabled unless you add --enabled. Its credential fields say VFORGE_SECRETS; after adding it, the output gives the vf-agent secrets set line to fill in its credential, or with --use it takes a shared credential you already stored.

Option	Meaning
--set <Field>=<value>	Change one of the connection's settings, such as the server name. Repeatable. For a setting inside a group, name the path: --set VForge.Http.Tls.Trust=System
--enabled	Turn it on now
--use <shared name>	Use a shared credential
--id <id>	Choose its ID instead of a new one

Credentials cannot be set with --set: they belong in the store.

datasources copy

vfa datasources copy <product ID> <connection ID> --name <name> [--set <Field>=<value> ...] [--enabled] --apply --agent-stopped

Adds a connection identical to an existing one, except for a new ID, the name you give, and starting disabled unless you add --enabled. Use --set for what differs, such as the server. Its credential is the original's: the same shared credential, or a copy of its own in the store. --new-credential leaves it empty instead; --use <shared name> gives it a shared one. To Seeq the copy is a new datasource, with its own items. Seeq lists a new connection only once it has been enabled.

datasources delete

vfa datasources delete <product ID> <connection ID> ... [--with-credential] [--seeq-items archived|keep] --apply --agent-stopped

Removes connections from the configuration only. Seeq then stops listing the datasource, but its items stay in Seeq, and it can no longer be archived from Seeq Administration. To remove a datasource and its items, archive it in Seeq instead (see Retire a connection); this command is not needed then.

So --apply stops and asks you to type archived (it is already archived in Seeq) or keep (keep its items in Seeq); anything else, including yes, changes nothing. In a script, answer with --seeq-items archived or --seeq-items keep: --yes alone is not accepted here. With --with-credential, it also removes their credentials from the store. Refuses to remove every connection in the file: disable the last one instead.

What the connector's log is telling you

Connector log says	What to do
No credential yet / not filled in, ending Fill it with: vf-agent secrets set ...	Run that line, with USER and DOMAIN replaced. See Add a connection
Credential taken from the connector configuration ... deprecated	Move it into the store: Move passwords out of the configuration
Entry ... matches no configured datasource	A retired connection's credential is still stored: Clean up
store file ... cannot be used (or cannot be read)	The credentials file has been damaged, often by a hand edit. A running agent keeps its last good copy, but after a restart every connection stays inactive. Do not restart the agent: see Recover a damaged credentials file
grants access to ...	More accounts than needed can read the store: Restrict the folder

Getting help

If a command does something you do not expect, keep its output (or its --json output) and contact EEI support. The output never contains a password, so it is safe to send.