Command line interface
Although not strictly a client library as such, the tdx Volt command line interface (CLI) exposes several aspects of the core tdx Volt API for use in shell scripts and other terminal-based processes. This, in combination with the tdx Volt wire
functionality, provides opportunities for useful and succinct workflows.
The tdx Volt CLI can also act as a server, and can be daemonised to run one or more Volts in the background.
The tdx Volt CLI supports several commands, and the arguments and syntax of each command varies. The basic format to invoke a command is:
Help is available for each command using the -h
or --help
switch, for example:
tdx Volt management commands
The commands in this section relate to tdx Volt management tasks, such as creating and running Volts.
battery options
There are some options that are common to the tdx Volt management commands, including those to do with configuration of the Battery in which the tdx Volt is contained.
The Battery name can be configured using the -b
switch. If this switch is omitted, the default Battery is used.
For example, to create a tdx Volt in a Battery named Household
:
Use the --bp
switch to specify an encryption passphrase and create a secure Battery:
As above, but using --bp .
to request a passphrase prompt:
Note that once an Battery is encrypted, the passphrase will be required for any subsequent tdx Volt command. For example to start a tdx Volt that is stored in a passphrase-protected Battery:
create command
The command to create a Volt.
In the following example, the tdx Volt will be created in the default Battery, with no passphrase protection or encryption on either the Battery storage or the tdx Volt itself.
To avoid having to copy and paste the UUID when subsequently referring to the tdx Volt, you can give it an alias using the -a
switch:
The alias can be substituted for the UUID, by prefixing it with @
:
Create a secure Volt
Use the -p
switch to specify a passphrase that will be used to encrypt the tdx Volt root key and storage.
By default, the tdx Volt will auto-generate a new key at creation and encrypt it with the given passphrase. The tdx Volt will not store the passphrase so you must remember it.
It is recommended to use a phrase rather than a single word for the passphrase, for example "I like cheese".
Use a period with the passphrase switch (-p .
) to force the CLI to prompt for the passphrase rather than include it explicitly in the command line.
There is currently no way to recover or reset the **tdx Volt** passphrase so if you lose it you will not be able to access the Volt.
Create a tdx Volt using a fixed host
By default when a tdx Volt is created its certificate is bound to the current (or first) ipv4 network interface address. If you would like to bind a tdx Volt to a specific IP address or domain name use the host
and port
command line switches.
Create a tdx Volt with a file-based key
By default the tdx Volt key is stored with the tdx Volt configuration in the Battery. If the Battery is encrypted with a strong passphrase this is a fairly safe option.
Alternatively you can create a tdx Volt using a key stored on the local file system.
If /path/to/key/file
does not exist it will be created.
If the key is encrypted (recommended) you can specify or prompt for the passphrase using the -p
switch as described above.
See the key strategy section for more information.
For full usage information:
run command
Use the run
command to start a Volt.
This command can be used to daemonise an instance of a Volt, using an init.d
script or similar.
To run a tdx Volt that is in the default Battery and is not passphrase-protected:
To run a passphrase-protected Volt, use the -p .
option to prompt for a passphrase:
If the tdx Volt is not in the default Battery, specify the path to the Battery using the -l
option:
For full usage information:
config command
The config
command can be used to show the available tdx Volt configurations, or see the detail of a particular tdx Volt configuration.
To list all Volts in the default Battery:
To list all Volts in a given Battery:
To view the full configuration for a given Volt, specify the tdx Volt id or alias:
For full usage information:
Client commands
The commands in this section are classed as tdx Volt client commands, and as such they require client credentials in order to authenticate with the target Volt.
There are two ways to specify the client credentials, either via a well-known file named volt.config.json
, or using a custom file name and passing it via the command line switch -c
.
See the connection section for more details about client credentials.
The following examples assume that the client credentials have been placed in the volt.config.json
file.
auth command
The auth
command can be used to create a new client identity and corresponding configuration file.
Specify the DID or URL of the tdx Volt to authenticate against:
You can also override the default configuration file:
Alternatively, you can specify the URL of the tdx Volt to authenticate with rather than the DID:
If your client configuration session has expired, you can use the --renew
switch to renew the session:
For full usage information:
download command
Download a file or folder from the tdx Volt to the local disk:
In the example above, the .
prefix of ./shares/images
indicates that the path is relative the ‘home’ folder of the client.
To specify a path relative to the root of the tdx Volt itself, use a /
prefix:
For full usage information:
upload command
Upload a file or folder to the Volt.
The .
prefix on ./shares
indicates the target resource is relative to the ‘home’ folder of the client.
To upload to a resource relative to the root of the tdx Volt itself, use a /
prefix:
For full usage information:
list command
List resources on the tdx Volt (similar to ls
or dir
shell commands).
For full usage information:
terminal-server command
The terminal-server
command can be used to start a terminal server that allows others to remotely access the local machine.
To create and/or start a terminal server:
If the configuration file doesn’t contain a service_id
field, a new service will be created and the service_id
will be written to the configuration file. Otherwise, the existing service will be started.
All Volts support a built-in terminal server that provides access to the Volt local machine. This requires explicit activation in the Volt settings via the fusebox, as well as access permission for command-invoke
.
For full usage information:
terminal-client command
The terminal-client
command can be used to connect to a terminal server running on a remote machine.
You will need command-invoke
permission on the terminal-server service in order to be able to connect to a terminal server.
To connect to a terminal server, specify the service id or alias:
To connect to the default (built-in) terminal of a Volt, use the __terminal-server
alias:
For full usage information:
whoami command
The whoami
command can be used to display details of the current client configuration.
As with other client commands, you can specify a custom configuration file using the -c
switch:
For full usage information:
wire command
Subscribe or publish to wire resources.
publish
To publish to a wire, specify the wire identifier or alias:
The wire data is read from STDIN
. This enables flows such as:
subscribe
To subscribe to a wire, add the -s
switch to the command line:
All wire data will be written to STDOUT. This enables flows such as:
For full usage information:
wire-remote command
The wire-remote command can be used to control a locally running command or executable remotely via wires.
The default command is /bin/sh
, but you can specify a different command using the --cmd
switch.
The example above will start a new zsh shell and connect the STDIN and STDOUT of the shell to the wires specified. This means that all data published to the @stdin
wire will be sent to the STDIN of the zsh shell, and any data written to the STDOUT of the zsh shell will be published to the @stdout
wire.
To use a command other than /bin/sh
, specify the command using the --cmd
switch:
As with other client commands, you can specify a custom configuration file using the -c
switch:
For full usage information:
Utility commands
logger command
Split data arriving on a wire or STDIN
into files on the local disk.
This command was developed for use with the Protobuf Database Sync utility, but it may be useful in other scenarios.
The logger
command listens for incoming data on a Volt wire or STDIN
, splitting the input into multiple files of a
configured maximum size in a configured folder. It makes no attempt to interpret the incoming data.
If a header is given
as part of the tdx Volt Logger configuration it will populate and write a ProtobufSyncConfigurationHeader
message to the start of each file it creates.
Once a file reaches the configured size (logFileSize
) it will be moved to the ingestion folder, where it
will get picked up by the protoDbSync process if one is running. The logger will then create a new file to continue
logging the incoming data.
This enables scenarios such as:
An example logger configuration when reading from STDIN
is shown below.
If reading from a wire, the configuration should include details of a standard client connection, as shown below. The credentials given should have subscribe
access to the source wire.
STDIN logger performance
Reading asynchronously from STDIN
is surprisingly difficult. The method used by the logger command involves a background
thread that reads data from STDIN
one byte at a time, and when the accumulated data reaches the configured log size the
data is flushed to disk.
On its own this approach causes problems whereby a flush might occur in the middle of an incoming packet, thus breaking the protobuf binary format.
To guard against this, the Volt logger uses a second thread thread which is responsible for flushing the buffer, and will only do
so after 50ms of inactivity on STDIN
(the interval is configurable via the flushIdleInterval
property in the configuration file). As a consequence, the produced log file size may slightly exceed that configured in logFileSize
.
The flushing thread described above helps reduce the frequency of split packets, but they can still occur due to network latency or other timing blips on the incoming data. Fortunately the protoDbSync utility can recover from these split packets the majority of the time.
Support for more commands in the Volt CLI is coming soon...