vici: Document the available vici command and event messages
This commit is contained in:
Martin Willi
parent
f684be6583
commit
56f17733c9
|
|
@ -103,7 +103,8 @@ the length field itself.
|
|||
|
||||
The interpretation of any value is not defined by the message format; it can
|
||||
take arbitrary blobs. The application may specify types for specific keys, such
|
||||
as strings or integer representations.
|
||||
as strings or integer representations. The vici plugin currently uses
|
||||
non-null terminated strings as values only; numbers get encoded as strings.
|
||||
|
||||
### Sections ###
|
||||
|
||||
|
|
@ -165,6 +166,513 @@ the following C array:
|
|||
1,
|
||||
};
|
||||
|
||||
## Client-initiated commands ##
|
||||
|
||||
Based on the packet layer, VICI implements commands requested by the client
|
||||
and responded to by the server using named _CMD_REQUEST_ and _CMD_RESPONSE_
|
||||
packets wrapping messages. The request message may contain command arguments,
|
||||
the response message the reply.
|
||||
|
||||
Some commands use response streaming, that is, a request triggers a series of
|
||||
events to consecutively stream data to the client before the response message
|
||||
completes the stream. A client must register for the appropriate event to
|
||||
receive the stream, and unregister after the response has been received.
|
||||
|
||||
The following client issued commands with the appropriate command input and
|
||||
output messages are currently defined:
|
||||
|
||||
### version() ###
|
||||
|
||||
Returns daemon and system specific version information.
|
||||
|
||||
{} => {
|
||||
daemon = <IKE daemon name>
|
||||
version = <strongSwan version>
|
||||
sysname = <operating system name>
|
||||
release = <operating system release>
|
||||
machine = <hardware identifier>
|
||||
}
|
||||
|
||||
### stats() ###
|
||||
|
||||
Returns IKE daemon statistics and load information.
|
||||
|
||||
{} => {
|
||||
uptime = {
|
||||
running = <relative uptime in human-readable form>
|
||||
since = <absolute startup time>
|
||||
}
|
||||
workers = {
|
||||
total = <total number of worker threads>
|
||||
idle = <worker threads currently idle>
|
||||
active = {
|
||||
critical = <threads processing "critical" priority jobs>
|
||||
high = <threads processing "high" priority jobs>
|
||||
medium = <threads processing "medium" priority jobs>
|
||||
low = <threads processing "low" priority jobs>
|
||||
}
|
||||
}
|
||||
queues = {
|
||||
critical = <jobs queued with "critical" priority>
|
||||
high = <jobs queued with "high" priority>
|
||||
medium = <jobs queued with "medium" priority>
|
||||
low = <jobs queued with "low" priority>
|
||||
}
|
||||
scheduled = <number of jobs scheduled for timed execution>
|
||||
ikesas = {
|
||||
total = <total number of IKE_SAs active>
|
||||
half-open = <number of IKE_SAs in half-open state>
|
||||
}
|
||||
plugins = [
|
||||
<names of loaded plugins>
|
||||
]
|
||||
mem = { # available if built with leak-detective or on Windows
|
||||
total = <total heap memory usage in bytes>
|
||||
allocs = <total heap allocation blocks>
|
||||
<heap-name>* = { # on Windows only
|
||||
total = <heap memory usage in bytes by this heap>
|
||||
allocs = <allocated blocks for this heap>
|
||||
}
|
||||
}
|
||||
mallinfo = { # available with mallinfo() support
|
||||
sbrk = <non-mmaped space available>
|
||||
mmap = <mmaped space available>
|
||||
used = <total number of bytes used>
|
||||
free = <available but unused bytes>
|
||||
}
|
||||
}
|
||||
|
||||
### reload-settings() ###
|
||||
|
||||
Reloads _strongswan.conf_ settings and all plugins supporting configuration
|
||||
reload.
|
||||
|
||||
{} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### initiate() ###
|
||||
|
||||
Initiates an SA while streaming _control-log_ events.
|
||||
|
||||
{
|
||||
child = <CHILD_SA configuration name to initiate>
|
||||
timeout = <timeout in seconds before returning>
|
||||
loglevel = <loglevel to issue "control-log" events for>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure or timeout>
|
||||
}
|
||||
|
||||
### terminate() ###
|
||||
|
||||
Terminates an SA while streaming _control-log_ events.
|
||||
|
||||
{
|
||||
child = <terminate a CHILD_SA by configuration name>
|
||||
ike = <terminate an IKE_SA by configuration name>
|
||||
child_id = <terminate a CHILD_SA by its reqid>
|
||||
ike_id = <terminate an IKE_SA by its unique id>
|
||||
timeout = <timeout in seconds before returning>
|
||||
loglevel = <loglevel to issue "control-log" events for>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure or timeout>
|
||||
}
|
||||
|
||||
### install() ###
|
||||
|
||||
Install a trap, drop or bypass policy defined by a CHILD_SA config.
|
||||
|
||||
{
|
||||
child = <CHILD_SA configuration name to install>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### uninstall() ###
|
||||
|
||||
Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
|
||||
|
||||
{
|
||||
child = <CHILD_SA configuration name to install>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### list-sas() ###
|
||||
|
||||
Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
|
||||
events.
|
||||
|
||||
{
|
||||
noblock = <use non-blocking mode if key is set>
|
||||
ike = <filter listed IKE_SAs by its name>
|
||||
ike_id = <filter listed IKE_SA by its unique id>
|
||||
} => {
|
||||
# completes after streaming list-sa events
|
||||
}
|
||||
|
||||
### list-policies() ###
|
||||
|
||||
List currently installed trap, drop and bypass policies by streaming
|
||||
_list-policy_ events.
|
||||
|
||||
{
|
||||
drop = <set to yes to list drop policies>
|
||||
pass = <set to yes to list bypass policies>
|
||||
trap = <set to yes to list trap policies>
|
||||
child = <filter by CHILD_SA configuration name>
|
||||
} => {
|
||||
# completes after streaming list-sa events
|
||||
}
|
||||
|
||||
### list-conns() ###
|
||||
|
||||
List currently loaded connections by streaming _list-conn_ events. This
|
||||
call includes all connections known by the daemon, not only those loaded
|
||||
over vici.
|
||||
|
||||
{
|
||||
ike = <list connections matching a given configuration name only>
|
||||
} => {
|
||||
# completes after streaming list-conn events
|
||||
}
|
||||
|
||||
### get-conns() ###
|
||||
|
||||
Return a list of connection names loaded exclusively over vici, not including
|
||||
connections found in other backends.
|
||||
|
||||
{} => {
|
||||
conns = [
|
||||
<list of connection names>
|
||||
]
|
||||
}
|
||||
|
||||
### list-certs() ###
|
||||
|
||||
List currently loaded certificates by streaming _list-cert_ events. This
|
||||
call includes all certificates known by the daemon, not only those loaded
|
||||
over vici.
|
||||
|
||||
{
|
||||
type = <certificate type to filter for, or ANY>
|
||||
subject = <set to list only certificates having subject>
|
||||
} => {
|
||||
# completes after streaming list-cert events
|
||||
}
|
||||
|
||||
### load-conn() ###
|
||||
|
||||
Load a single connection definition into the daemon. An existing connection
|
||||
with the same name gets updated or replaced.
|
||||
|
||||
{
|
||||
<IKE_SA config name> = {
|
||||
# IKE configuration parameters with authentication and CHILD_SA
|
||||
# subsections. Refer to swanctl.conf(5) for details.
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
}
|
||||
|
||||
### unload-conn() ###
|
||||
|
||||
Unload a previously loaded connection definition by name.
|
||||
|
||||
{
|
||||
name = <IKE_SA config name>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### load-cert() ###
|
||||
|
||||
Load a certificate into the daemon.
|
||||
|
||||
{
|
||||
type = <certificate type, X509|X509CA|X509AA|X509CRL|X509AC>
|
||||
data = <PEM or DER encoded certificate data>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### load-key() ###
|
||||
|
||||
Load a private key into the daemon.
|
||||
|
||||
{
|
||||
type = <private key type, RSA|ECDSA>
|
||||
data = <PEM or DER encoded key data>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### load-shared() ###
|
||||
|
||||
Load a shared IKE PSK, EAP or XAuth secret into the daemon.
|
||||
|
||||
{
|
||||
type = <private key type, IKE|EAP|XAUTH>
|
||||
data = <raw shared key data>
|
||||
owners = [
|
||||
<list of shared key owner identities>
|
||||
]
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### clear-creds() ###
|
||||
|
||||
Clear all loaded certificate, private key and shared key credentials. This
|
||||
affects only credentials loaded over vici, but additionally flushes the
|
||||
credential cache.
|
||||
|
||||
{} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### load-pool() ###
|
||||
|
||||
Load an in-memory virtual IP and configuration attribute pool. Existing
|
||||
pools with the same name get updated, if possible.
|
||||
|
||||
{
|
||||
<pool name> = {
|
||||
addrs = <subnet of virtual IP pool addresses>
|
||||
<attribute type>* = [
|
||||
# attribute type is one of address, dns, nbns, dhcp, netmask,
|
||||
# server, subnet, split_include, split_exclude or a numerical
|
||||
# attribute type identifier.
|
||||
<list of attributes for type>
|
||||
]
|
||||
}
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### unload-pool() ###
|
||||
|
||||
Unload a previously loaded virtual IP and configuration attribute pool.
|
||||
Unloading fails for pools with leases currently online.
|
||||
|
||||
{
|
||||
name = <virtual IP address pool to delete>
|
||||
} => {
|
||||
success = <yes or no>
|
||||
errmsg = <error string on failure>
|
||||
}
|
||||
|
||||
### get-pools() ###
|
||||
|
||||
List the currently loaded pools.
|
||||
|
||||
{} => {
|
||||
<pool name>* = {
|
||||
base = <virtual IP pool base address>
|
||||
size = <total number of addresses in the pool>
|
||||
online = <number of leases online>
|
||||
offline = <number of leases offline>
|
||||
}
|
||||
}
|
||||
|
||||
## Server-issued events ##
|
||||
|
||||
Based on the packet layer, the vici plugin raises event messages using named
|
||||
EVENT packets wrapping messages. The message contains event details.
|
||||
|
||||
### log ###
|
||||
|
||||
The _log_ event is issued to registered clients for each debug log message.
|
||||
This event is not associated with a command.
|
||||
|
||||
{
|
||||
group = <subsystem identifier for debug message>
|
||||
level = <log level, 0-4>
|
||||
thread = <numerical thread identifier issuing the log message>
|
||||
ikesa-name = <name of IKE_SA, if log is associated with any>
|
||||
ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
|
||||
msg = <log message text>
|
||||
}
|
||||
|
||||
### control-log ###
|
||||
|
||||
The _control-log_ event is issued for log events during active _initiate_ or
|
||||
_terminate_ commands. It is issued only to clients currently having such
|
||||
a command active.
|
||||
|
||||
{
|
||||
group = <subsystem identifier for debug message>
|
||||
level = <log level, 0-4>
|
||||
ikesa-name = <name of IKE_SA, if log associated with any>
|
||||
ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
|
||||
msg = <log message text>
|
||||
}
|
||||
|
||||
### list-sa ###
|
||||
|
||||
The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
|
||||
command.
|
||||
|
||||
{
|
||||
<IKE_SA config name> = {
|
||||
uniqueid = <IKE_SA unique identifier>
|
||||
version = <IKE version, 1 or 2>
|
||||
state = <IKE_SA state name>
|
||||
local-host = <local IKE endpoint address>
|
||||
local-id = <local IKE identity>
|
||||
remote-host = <remote IKE endpoint address>
|
||||
remote-id = <remote IKE identity>
|
||||
remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
|
||||
remote-eap-id = <remote EAP identity, if EAP-authenticated>
|
||||
initiator = <yes, if initiator of IKE_SA>
|
||||
initiator-spi = <hex encoded initiator SPI / cookie>
|
||||
responder-spi = <hex encoded responder SPI / cookie>
|
||||
encr-alg = <IKE encryption algorithm string>
|
||||
encr-keysize = <key size for encr-alg, if applicable>
|
||||
integ-alg = <IKE integrity algorithm string>
|
||||
integ-keysize = <key size for encr-alg, if applicable>
|
||||
prf-alg = <IKE pseudo random function string>
|
||||
dh-group = <IKE Diffie-Hellman group string>
|
||||
established = <seconds the IKE_SA has been established>
|
||||
rekey-time = <seconds before IKE_SA gets rekeyed>
|
||||
reauth-time = <seconds before IKE_SA gets re-authenticated>
|
||||
tasks-queued = [
|
||||
<list of currently queued tasks for execution>
|
||||
]
|
||||
tasks-active = [
|
||||
<list of tasks currently initiating actively>
|
||||
]
|
||||
tasks-passive = [
|
||||
<list of tasks currently handling passively>
|
||||
]
|
||||
child-sas = {
|
||||
<child-sa-name>* = {
|
||||
reqid = <reqid of CHILD_SA>
|
||||
state = <state string of CHILD_SA>
|
||||
mode = <IPsec mode, tunnel|transport|beet>
|
||||
protocol = <IPsec protocol AH|ESP>
|
||||
encap = <yes if using UDP encapsulation>
|
||||
spi-in = <hex encoded inbound SPI>
|
||||
spi-out = <hex encoded outbound SPI>
|
||||
cpi-in = <hex encoded inbound CPI, if using compression>
|
||||
cpi-out = <hex encoded outbound CPI, if using compression>
|
||||
encr-alg = <ESP encryption algorithm name, if any>
|
||||
encr-keysize = <ESP encryption key size, if applicable>
|
||||
integ-alg = <ESP or AH integrity algorithm name, if any>
|
||||
integ-keysize = <ESP or AH integrity key size, if applicable>
|
||||
prf-alg = <CHILD_SA pseudo random function name>
|
||||
dh-group = <CHILD_SA PFS rekeying DH group name, if any>
|
||||
esn = <1 if using extended sequence numbers>
|
||||
bytes-in = <number of input bytes processed>
|
||||
packets-in = <number of input packets processed>
|
||||
use-in = <seconds since last inbound packet, if any>
|
||||
bytes-out = <number of output bytes processed>
|
||||
packets-out = <number of output packets processed>
|
||||
use-out = <seconds since last outbound packet, if any>
|
||||
rekey-time = <seconds before CHILD_SA gets rekeyed>
|
||||
life-time = <seconds before CHILD_SA expires>
|
||||
install-time = <seconds the CHILD_SA has been installed>
|
||||
local-ts = [
|
||||
<list of local traffic selectors>
|
||||
]
|
||||
remote-ts = [
|
||||
<list of remote traffic selectors>
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
### list-policy ###
|
||||
|
||||
The _list-policy_ event is issued to stream installed policies during an active
|
||||
_list-policies_ command.
|
||||
|
||||
{
|
||||
<child-sa-config-name> = {
|
||||
mode = <policy mode, tunnel|transport|pass|drop>
|
||||
local-ts = [
|
||||
<list of local traffic selectors>
|
||||
]
|
||||
remote-ts = [
|
||||
<list of remote traffic selectors>
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
### list-conn ###
|
||||
|
||||
The _list-conn_ event is issued to stream loaded connection during an active
|
||||
_list-conns_ command.
|
||||
|
||||
{
|
||||
<IKE_SA connection name> = {
|
||||
local_addrs = [
|
||||
<list of valid local IKE endpoint addresses>
|
||||
]
|
||||
remote_addrs = [
|
||||
<list of valid remote IKE endpoint addresses>
|
||||
]
|
||||
version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
|
||||
|
||||
local*, remote* = { # multiple local and remote auth sections
|
||||
class = <authentication type>
|
||||
eap-type = <EAP type to authenticate if when using EAP>
|
||||
eap-vendor = <EAP vendor for type, if any>
|
||||
xauth = <xauth backend name>
|
||||
revocation = <revocation policy>
|
||||
id = <IKE identity>
|
||||
aaa_id = <AAA authentication backend identity>
|
||||
eap_id = <EAP identity for authentication>
|
||||
xauth_id = <XAuth username for authentication>
|
||||
groups = [
|
||||
<group membership required to use connection>
|
||||
]
|
||||
certs = [
|
||||
<certificates allowed for authentication>
|
||||
]
|
||||
cacerts = [
|
||||
<CA certificates allowed for authentication>
|
||||
]
|
||||
}
|
||||
children = {
|
||||
<CHILD_SA config name>* = {
|
||||
mode = <IPsec mode>
|
||||
local-ts = [
|
||||
<list of local traffic selectors>
|
||||
]
|
||||
remote-ts = [
|
||||
<list of remote traffic selectors>
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
### list-cert ###
|
||||
|
||||
The _list-cert_ event is issued to stream loaded certificates during an active
|
||||
_list-certs_ command.
|
||||
|
||||
{
|
||||
type = <certificate type>
|
||||
has_privkey = <set if a private key for the certificate is available>
|
||||
data = <ASN1 encoded certificate data>
|
||||
}
|
||||
|
||||
|
||||
# libvici C client library #
|
||||
|
||||
libvici is the reference implementation of a C client library implementing
|
||||
|
|
|
|||
Loading…
Reference in New Issue