vici: Document the available vici command and event messages
authorMartin Willi <martin@revosec.ch>
Wed, 8 Oct 2014 16:13:31 +0000 (18:13 +0200)
committerMartin Willi <martin@revosec.ch>
Fri, 10 Oct 2014 09:42:18 +0000 (11:42 +0200)
src/libcharon/plugins/vici/README.md

index 598be1f..2c3a4df 100644 (file)
@@ -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