1421ab4d95f6e69487b4a36d03c1afcfeff6768b
[strongswan.git] / src / libcharon / plugins / vici / README.md
1 # The Versatile IKE Control Interface (VICI) protocol #
2
3 The vici plugin implements the server side of an IPC protocol to configure,
4 monitor and control the IKE daemon charon. It uses request/response and event
5 messages to communicate over a reliable stream based transport.
6
7 ## Transport protocol ##
8
9 To provide the service, the plugin opens a listening socket using a reliable,
10 stream based transport. charon relies on the different stream service
11 abstractions provided by libstrongswan, such as TCP and UNIX sockets.
12
13 A client connects to this service to access functionality. It may send an
14 arbitrary number of packets over the connection before closing it.
15
16 To exchange data, the transport protocol is segmented into byte sequences.
17 Each byte sequence is prefixed by a 32-bit length header in network order,
18 followed by the data. The maximum segment length is currently limited to 512KB
19 of data, and the length field contains the length of the data only, not
20 including the length field itself.
21
22 The order of byte sequences must be strict, byte sequences must arrive in the
23 same order as sent.
24
25 ## Packet layer ##
26
27 Within the byte sequences defined by the transport layer, both the client
28 and the server can exchange packets. The type of packet defines its structure
29 and purpose. The packet type is a 8-bit identifier, and is the first byte
30 in a transport layer byte sequence. The length of the packet is given by the
31 transport layer.
32
33 While a packet type may define the format of the wrapped data freely, currently
34 all types either contain a name, a message or both. The following packet types
35 are currently defined:
36
37 * _CMD_REQUEST = 0_: A named request message
38 * _CMD_RESPONSE = 1_: An unnamed response message for a request
39 * _CMD_UNKNOWN = 2_: An unnamed response if requested command is unknown
40 * _EVENT_REGISTER = 3_: A named event registration request
41 * _EVENT_UNREGISTER = 4_: A named event deregistration request
42 * _EVENT_CONFIRM = 5_: An unnamed response for successful event (de-)registration
43 * _EVENT_UNKNOWN = 6_: A unnamed response if event (de-)registration failed
44 * _EVENT = 7_: A named event message
45
46 For packets having a named type, after the packet type an 8-bit length header
47 of the name follows, indicating the string length in bytes of the name tag, not
48 including the length field itself. The name is an ASCII string that is not
49 null-terminated.
50
51 The rest of the packet forms the exchanged message, the length is determined
52 by the transport byte sequence length, subtracting the packet type and
53 the optional name tag in some messages.
54
55 ### Commands ###
56
57 Commands are currently always requested by the client. The server replies with
58 a response, or with a CMD_UNKNOWN failure message to let the client know
59 that it does not have a handler for such a command. There is no sequence number
60 to associate responses to requests, so only one command can be active at
61 a time on a single connection.
62
63 ### Events ###
64
65 To receive event messages, the client explicitly registers for events by name,
66 and also unregisters if it does not want to receive events of the named kind
67 anymore. The server confirms event registration using EVENT_CONFIRM, or
68 indicates that there is no such event source with EVENT_UNKNOWN.
69
70 Events may get raised at any time while registered, even during an active
71 request command. This mechanism is used to feed continuous data during a request,
72 for example.
73
74 ## Message format ##
75
76 The defined packet types optionally wrap a message with additional data.
77 Messages are currently used in CMD_REQUEST/CMD_RESPONSE, and in EVENT packets.
78 A message uses a hierarchial tree of sections. Each section (or the implicit
79 root section) contains an arbitrary set of key/value pairs, lists and
80 sub-sections. The length of a message is not part of the message itself, but
81 the wrapping layer, usually calculated from the transport byte sequence length.
82
83 The message encoding consists of a sequence of elements. Each element starts
84 with the element type, optionally followed by an element name and/or an element
85 value. Currently the following message element types are defined:
86
87 * _SECTION_START = 1_: Begin a new section having a name
88 * _SECTION_END = 2_: End a previously started section
89 * _KEY_VALUE = 3_: Define a value for a named key in the current section
90 * _LIST_START = 4_: Begin a named list for list items
91 * _LIST_ITEM = 5_: Define an unnamed item value in the current list
92 * _LIST_END = 6_: End a previously started list
93
94 Types are encoded as 8-bit values. Types having a name (SECTION_START,
95 KEY_VALUE and LIST_START) have an ASCII string following the type, which itself
96 uses an 8-bit length header. The string must not be null-terminated, the string
97 length does not include the length field itself.
98
99 Types having a value (KEY_VALUE and LIST_ITEM) have a raw blob sequence,
100 prefixed with a 16-bit network order length. The blob follows the type or the
101 name tag if available, the length defined by the length field does not include
102 the length field itself.
103
104 The interpretation of any value is not defined by the message format; it can
105 take arbitrary blobs. The application may specify types for specific keys, such
106 as strings or integer representations. The vici plugin currently uses
107 non-null terminated strings as values only; numbers get encoded as strings.
108
109 ### Sections ###
110
111 Sections may be opened in the implicit root section, or any previously section.
112 They can be nested to arbitrary levels. A SECTION_END marker always closes
113 the last opened section; SECTION_START and SECTION_END items must be balanced
114 in a valid message.
115
116 ### Key/Values ###
117
118 Key/Value pair elements may appear in the implicit root section or any explicit
119 sub-section at any level. Key names must be unique in the current section, use
120 lists to define multiple values for a key. Key/values may not appear in lists,
121 use a sub-section instead.
122
123 ### Lists ###
124
125 Lists may appear at the same locations as Key/Values, and may not be nested.
126 Only a single list may be opened at the same time, and all lists must be closed
127 in valid messages. After opening a list, only list items may appear before the
128 list closing element. Empty lists are allowed, list items may appear within
129 lists only.
130
131 ### Encoding example ###
132
133 Consider the following structure using pseudo-markup for this example:
134
135         key1 = value1
136         section1 = {
137                 sub-section = {
138                         key2 = value2
139                 }
140                 list1 = [ item1, item2 ]
141         }
142
143 The example above reprensents a valid tree structure, that gets encoded as
144 the following C array:
145
146         char msg[] = {
147                 /* key1 = value1 */
148                 3, 4,'k','e','y','1', 0,6,'v','a','l','u','e','1',
149                 /* section1 */
150                 1, 8,'s','e','c','t','i','o','n','1',
151                 /* sub-section */
152                 1, 11,'s','u','b','-','s','e','c','t','i','o','n',
153                 /* key2 = value2 */
154                 3, 4,'k','e','y','2', 0,6,'v','a','l','u','e','2',
155                 /* sub-section end */
156                 2,
157                 /* list1 */
158                 4, 5, 'l','i','s','t','1',
159                 /* item1 */
160                 5, 0,5,'i','t','e','m','1',
161                 /* item2 */
162                 5, 0,5,'i','t','e','m','2',
163                 /* list1 end */
164                 6,
165                 /* section1 end */
166                 2,
167         };
168
169 ## Client-initiated commands ##
170
171 Based on the packet layer, VICI implements commands requested by the client
172 and responded to by the server using named _CMD_REQUEST_ and _CMD_RESPONSE_
173 packets wrapping messages. The request message may contain command arguments,
174 the response message the reply.
175
176 Some commands use response streaming, that is, a request triggers a series of
177 events to consecutively stream data to the client before the response message
178 completes the stream. A client must register for the appropriate event to
179 receive the stream, and unregister after the response has been received.
180
181 The following client issued commands with the appropriate command input and
182 output messages are currently defined:
183
184 ### version() ###
185
186 Returns daemon and system specific version information.
187
188         {} => {
189                 daemon = <IKE daemon name>
190                 version = <strongSwan version>
191                 sysname = <operating system name>
192                 release = <operating system release>
193                 machine = <hardware identifier>
194         }
195
196 ### stats() ###
197
198 Returns IKE daemon statistics and load information.
199
200         {} => {
201                 uptime = {
202                         running = <relative uptime in human-readable form>
203                         since = <absolute startup time>
204                 }
205                 workers = {
206                         total = <total number of worker threads>
207                         idle = <worker threads currently idle>
208                         active = {
209                                 critical = <threads processing "critical" priority jobs>
210                                 high = <threads processing "high" priority jobs>
211                                 medium = <threads processing "medium" priority jobs>
212                                 low = <threads processing "low" priority jobs>
213                         }
214                 }
215                 queues = {
216                         critical = <jobs queued with "critical" priority>
217                         high = <jobs queued with "high" priority>
218                         medium = <jobs queued with "medium" priority>
219                         low = <jobs queued with "low" priority>
220                 }
221                 scheduled = <number of jobs scheduled for timed execution>
222                 ikesas = {
223                         total = <total number of IKE_SAs active>
224                         half-open = <number of IKE_SAs in half-open state>
225                 }
226                 plugins = [
227                         <names of loaded plugins>
228                 ]
229                 mem = { # available if built with leak-detective or on Windows
230                         total = <total heap memory usage in bytes>
231                         allocs = <total heap allocation blocks>
232                         <heap-name>* = { # on Windows only
233                                 total = <heap memory usage in bytes by this heap>
234                                 allocs = <allocated blocks for this heap>
235                         }
236                 }
237                 mallinfo = { # available with mallinfo() support
238                         sbrk = <non-mmaped space available>
239                         mmap = <mmaped space available>
240                         used = <total number of bytes used>
241                         free = <available but unused bytes>
242                 }
243         }
244
245 ### reload-settings() ###
246
247 Reloads _strongswan.conf_ settings and all plugins supporting configuration
248 reload.
249
250         {} => {
251                 success = <yes or no>
252                 errmsg = <error string on failure>
253         }
254
255 ### initiate() ###
256
257 Initiates an SA while streaming _control-log_ events.
258
259         {
260                 child = <CHILD_SA configuration name to initiate>
261                 timeout = <timeout in seconds before returning>
262                 loglevel = <loglevel to issue "control-log" events for>
263         } => {
264                 success = <yes or no>
265                 errmsg = <error string on failure or timeout>
266         }
267
268 ### terminate() ###
269
270 Terminates an SA while streaming _control-log_ events.
271
272         {
273                 child = <terminate a CHILD_SA by configuration name>
274                 ike = <terminate an IKE_SA by configuration name>
275                 child_id = <terminate a CHILD_SA by its reqid>
276                 ike_id = <terminate an IKE_SA by its unique id>
277                 timeout = <timeout in seconds before returning>
278                 loglevel = <loglevel to issue "control-log" events for>
279         } => {
280                 success = <yes or no>
281                 errmsg = <error string on failure or timeout>
282         }
283
284 ### install() ###
285
286 Install a trap, drop or bypass policy defined by a CHILD_SA config.
287
288         {
289                 child = <CHILD_SA configuration name to install>
290         } => {
291                 success = <yes or no>
292                 errmsg = <error string on failure>
293         }
294
295 ### uninstall() ###
296
297 Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
298
299         {
300                 child = <CHILD_SA configuration name to install>
301         } => {
302                 success = <yes or no>
303                 errmsg = <error string on failure>
304         }
305
306 ### list-sas() ###
307
308 Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
309 events.
310
311         {
312                 noblock = <use non-blocking mode if key is set>
313                 ike = <filter listed IKE_SAs by its name>
314                 ike_id = <filter listed IKE_SA by its unique id>
315         } => {
316                 # completes after streaming list-sa events
317         }
318
319 ### list-policies() ###
320
321 List currently installed trap, drop and bypass policies by streaming
322 _list-policy_ events.
323
324         {
325                 drop = <set to yes to list drop policies>
326                 pass = <set to yes to list bypass policies>
327                 trap = <set to yes to list trap policies>
328                 child = <filter by CHILD_SA configuration name>
329         } => {
330                 # completes after streaming list-sa events
331         }
332
333 ### list-conns() ###
334
335 List currently loaded connections by streaming _list-conn_ events. This
336 call includes all connections known by the daemon, not only those loaded
337 over vici.
338
339         {
340                 ike = <list connections matching a given configuration name only>
341         } => {
342                 # completes after streaming list-conn events
343         }
344
345 ### get-conns() ###
346
347 Return a list of connection names loaded exclusively over vici, not including
348 connections found in other backends.
349
350         {} => {
351                 conns = [
352                         <list of connection names>
353                 ]
354         }
355
356 ### list-certs() ###
357
358 List currently loaded certificates by streaming _list-cert_ events. This
359 call includes all certificates known by the daemon, not only those loaded
360 over vici.
361
362         {
363                 type = <certificate type to filter for, or ANY>
364                 subject = <set to list only certificates having subject>
365         } => {
366                 # completes after streaming list-cert events
367         }
368
369 ### list-authorities() ###
370
371 List currently loaded certification authority information by streaming
372 _list-authority_ events.
373
374         {
375                 name = <list certification authority of a given name>
376         } => {
377                 # completes after streaming list-authority events
378         }
379
380 ### get-authorities() ###
381
382 Return a list of currently loaded certification authority names.
383
384         {} => {
385                 authorities = [
386                         <list of certification authority names>
387                 ]
388         }
389
390 ### load-conn() ###
391
392 Load a single connection definition into the daemon. An existing connection
393 with the same name gets updated or replaced.
394
395         {
396                 <IKE_SA config name> = {
397                         # IKE configuration parameters with authentication and CHILD_SA
398                         # subsections. Refer to swanctl.conf(5) for details.
399                 } => {
400                         success = <yes or no>
401                         errmsg = <error string on failure>
402                 }
403         }
404
405 ### unload-conn() ###
406
407 Unload a previously loaded connection definition by name.
408
409         {
410                 name = <IKE_SA config name>
411         } => {
412                 success = <yes or no>
413                 errmsg = <error string on failure>
414         }
415
416 ### load-cert() ###
417
418 Load a certificate into the daemon.
419
420         {
421                 type = <certificate type, X509|X509CA|X509AA|X509CRL|X509AC>
422                 data = <PEM or DER encoded certificate data>
423         } => {
424                 success = <yes or no>
425                 errmsg = <error string on failure>
426         }
427
428 ### load-key() ###
429
430 Load a private key into the daemon.
431
432         {
433                 type = <private key type, RSA|ECDSA>
434                 data = <PEM or DER encoded key data>
435         } => {
436                 success = <yes or no>
437                 errmsg = <error string on failure>
438         }
439
440 ### load-shared() ###
441
442 Load a shared IKE PSK, EAP or XAuth secret into the daemon.
443
444         {
445                 type = <private key type, IKE|EAP|XAUTH>
446                 data = <raw shared key data>
447                 owners = [
448                         <list of shared key owner identities>
449                 ]
450         } => {
451                 success = <yes or no>
452                 errmsg = <error string on failure>
453         }
454
455 ### clear-creds() ###
456
457 Clear all loaded certificate, private key and shared key credentials. This
458 affects only credentials loaded over vici, but additionally flushes the
459 credential cache.
460
461         {} => {
462                 success = <yes or no>
463                 errmsg = <error string on failure>
464         }
465
466 ### load-authority() ###
467
468 Load a single certification authority definition into the daemon. An existing
469 authority with the same name gets replaced.
470
471         {
472                 <certification authority name> = {
473                         # certification authority parameters
474                         # refer to swanctl.conf(5) for details.
475                 } => {
476                         success = <yes or no>
477                         errmsg = <error string on failure>
478                 }
479         }
480
481 ### unload-authority() ###
482
483 Unload a previously loaded certification authority definition by name.
484
485         {
486                 name = <certification authority name>
487         } => {
488                 success = <yes or no>
489                 errmsg = <error string on failure>
490         }
491
492 ### load-pool() ###
493
494 Load an in-memory virtual IP and configuration attribute pool. Existing
495 pools with the same name get updated, if possible.
496
497         {
498                 <pool name> = {
499                         addrs = <subnet of virtual IP pool addresses>
500                         <attribute type>* = [
501                                 # attribute type is one of address, dns, nbns, dhcp, netmask,
502                                 # server, subnet, split_include, split_exclude or a numerical
503                                 # attribute type identifier.
504                                 <list of attributes for type>
505                         ]
506                 }
507         } => {
508                 success = <yes or no>
509                 errmsg = <error string on failure>
510         }
511
512 ### unload-pool() ###
513
514 Unload a previously loaded virtual IP and configuration attribute pool.
515 Unloading fails for pools with leases currently online.
516
517         {
518                 name = <virtual IP address pool to delete>
519         } => {
520                 success = <yes or no>
521                 errmsg = <error string on failure>
522         }
523
524 ### get-pools() ###
525
526 List the currently loaded pools.
527
528         {} => {
529                 <pool name>* = {
530                         base = <virtual IP pool base address>
531                         size = <total number of addresses in the pool>
532                         online = <number of leases online>
533                         offline = <number of leases offline>
534                 }
535         }
536
537 ## Server-issued events ##
538
539 Based on the packet layer, the vici plugin raises event messages using named
540 EVENT packets wrapping messages. The message contains event details.
541
542 ### log ###
543
544 The _log_ event is issued to registered clients for each debug log message.
545 This event is not associated with a command.
546
547         {
548                 group = <subsystem identifier for debug message>
549                 level = <log level, 0-4>
550                 thread = <numerical thread identifier issuing the log message>
551                 ikesa-name = <name of IKE_SA, if log is associated with any>
552                 ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
553                 msg = <log message text>
554         }
555
556 ### control-log ###
557
558 The _control-log_ event is issued for log events during active _initiate_ or
559 _terminate_ commands. It is issued only to clients currently having such
560 a command active.
561
562         {
563                 group = <subsystem identifier for debug message>
564                 level = <log level, 0-4>
565                 ikesa-name = <name of IKE_SA, if log associated with any>
566                 ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
567                 msg = <log message text>
568         }
569
570 ### list-sa ###
571
572 The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
573 command.
574
575         {
576                 <IKE_SA config name> = {
577                         uniqueid = <IKE_SA unique identifier>
578                         version = <IKE version, 1 or 2>
579                         state = <IKE_SA state name>
580                         local-host = <local IKE endpoint address>
581                         local-id = <local IKE identity>
582                         remote-host = <remote IKE endpoint address>
583                         remote-id = <remote IKE identity>
584                         remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
585                         remote-eap-id = <remote EAP identity, if EAP-authenticated>
586                         initiator = <yes, if initiator of IKE_SA>
587                         initiator-spi = <hex encoded initiator SPI / cookie>
588                         responder-spi = <hex encoded responder SPI / cookie>
589                         encr-alg = <IKE encryption algorithm string>
590                         encr-keysize = <key size for encr-alg, if applicable>
591                         integ-alg = <IKE integrity algorithm string>
592                         integ-keysize = <key size for encr-alg, if applicable>
593                         prf-alg = <IKE pseudo random function string>
594                         dh-group = <IKE Diffie-Hellman group string>
595                         established = <seconds the IKE_SA has been established>
596                         rekey-time = <seconds before IKE_SA gets rekeyed>
597                         reauth-time = <seconds before IKE_SA gets re-authenticated>
598                         tasks-queued = [
599                                 <list of currently queued tasks for execution>
600                         ]
601                         tasks-active = [
602                                 <list of tasks currently initiating actively>
603                         ]
604                         tasks-passive = [
605                                 <list of tasks currently handling passively>
606                         ]
607                         child-sas = {
608                                 <child-sa-name>* = {
609                                         uniqueid = <unique CHILD_SA identifier>
610                                         reqid = <reqid of CHILD_SA>
611                                         state = <state string of CHILD_SA>
612                                         mode = <IPsec mode, tunnel|transport|beet>
613                                         protocol = <IPsec protocol AH|ESP>
614                                         encap = <yes if using UDP encapsulation>
615                                         spi-in = <hex encoded inbound SPI>
616                                         spi-out = <hex encoded outbound SPI>
617                                         cpi-in = <hex encoded inbound CPI, if using compression>
618                                         cpi-out = <hex encoded outbound CPI, if using compression>
619                                         encr-alg = <ESP encryption algorithm name, if any>
620                                         encr-keysize = <ESP encryption key size, if applicable>
621                                         integ-alg = <ESP or AH integrity algorithm name, if any>
622                                         integ-keysize = <ESP or AH integrity key size, if applicable>
623                                         prf-alg = <CHILD_SA pseudo random function name>
624                                         dh-group = <CHILD_SA PFS rekeying DH group name, if any>
625                                         esn = <1 if using extended sequence numbers>
626                                         bytes-in = <number of input bytes processed>
627                                         packets-in = <number of input packets processed>
628                                         use-in = <seconds since last inbound packet, if any>
629                                         bytes-out = <number of output bytes processed>
630                                         packets-out = <number of output packets processed>
631                                         use-out = <seconds since last outbound packet, if any>
632                                         rekey-time = <seconds before CHILD_SA gets rekeyed>
633                                         life-time = <seconds before CHILD_SA expires>
634                                         install-time = <seconds the CHILD_SA has been installed>
635                                         local-ts = [
636                                                 <list of local traffic selectors>
637                                         ]
638                                         remote-ts = [
639                                                 <list of remote traffic selectors>
640                                         ]
641                                 }
642                         }
643                 }
644         }
645
646 ### list-policy ###
647
648 The _list-policy_ event is issued to stream installed policies during an active
649 _list-policies_ command.
650
651         {
652                 <child-sa-config-name> = {
653                         mode = <policy mode, tunnel|transport|pass|drop>
654                         local-ts = [
655                                 <list of local traffic selectors>
656                         ]
657                         remote-ts = [
658                                 <list of remote traffic selectors>
659                         ]
660                 }
661         }
662
663 ### list-conn ###
664
665 The _list-conn_ event is issued to stream loaded connection during an active
666 _list-conns_ command.
667
668         {
669                 <IKE_SA connection name> = {
670                         local_addrs = [
671                                 <list of valid local IKE endpoint addresses>
672                         ]
673                         remote_addrs = [
674                                 <list of valid remote IKE endpoint addresses>
675                         ]
676                         version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
677
678                         local*, remote* = { # multiple local and remote auth sections
679                                 class = <authentication type>
680                                 eap-type = <EAP type to authenticate if when using EAP>
681                                 eap-vendor = <EAP vendor for type, if any>
682                                 xauth = <xauth backend name>
683                                 revocation = <revocation policy>
684                                 id = <IKE identity>
685                                 aaa_id = <AAA authentication backend identity>
686                                 eap_id = <EAP identity for authentication>
687                                 xauth_id = <XAuth username for authentication>
688                                 groups = [
689                                         <group membership required to use connection>
690                                 ]
691                                 certs = [
692                                         <certificates allowed for authentication>
693                                 ]
694                                 cacerts = [
695                                         <CA certificates allowed for authentication>
696                                 ]
697                         }
698                         children = {
699                                 <CHILD_SA config name>* = {
700                                         mode = <IPsec mode>
701                                         local-ts = [
702                                                 <list of local traffic selectors>
703                                         ]
704                                         remote-ts = [
705                                                 <list of remote traffic selectors>
706                                         ]
707                                 }
708                         }
709                 }
710         }
711
712 ### list-cert ###
713
714 The _list-cert_ event is issued to stream loaded certificates during an active
715 _list-certs_ command.
716
717         {
718                 type = <certificate type>
719                 has_privkey = <set if a private key for the certificate is available>
720                 data = <ASN1 encoded certificate data>
721         }
722
723 ### list-authority ###
724
725 The _list-authority_ event is issued to stream loaded certification authority
726 information during an active_list-authorities_ command.
727
728         {
729                 <certification authority name> = {
730                         cacert = <subject distinguished name of CA certificate>
731                         crl_uris = [
732                                 <CRL URI (http, ldap or file)>
733                         ]
734                         ocsp_uris = [
735                                 <OCSP URI (http)>
736                         ]
737                         cert_uri_base = <base URI for download of hash-and-URL certificates>
738                 }
739         }
740
741 ### ike-updown ###
742
743 The _ike-updown_ event is issued when an IKE_SA is established or terminated.
744
745         {
746                 up = <yes or no>
747                 <IKE_SA config name> = {
748                         <same data as in the list-sas event, but without child-sas section>
749                 }
750         }
751
752 ### child-updown ###
753
754 The _child-updown_ event is issued when a CHILD_SA is established or terminated.
755
756         {
757                 up = <yes or no>
758                 <IKE_SA config name> = {
759                         <same data as in the list-sas event, but with only the affected
760                          CHILD_SA in the child-sas section>
761                 }
762         }
763
764 # libvici C client library #
765
766 libvici is the reference implementation of a C client library implementing
767 the vici protocol. It builds upon libstrongswan, but provides a stable API
768 to implement client applications in the C programming language. libvici uses
769 the libstrongswan thread pool to deliver event messages asynchronously.
770
771 ## Connecting to the daemon ##
772
773 This example shows how to connect to the daemon using the default URI, and
774 then perform proper cleanup:
775
776         #include <stdio.h>
777         #include <errno.h>
778         #include <string.h>
779
780         #include <libvici.h>
781
782         int main(int argc, char *argv[])
783         {
784                 vici_conn_t *conn;
785                 int ret = 0;
786
787                 vici_init();
788                 conn = vici_connect(NULL);
789                 if (conn)
790                 {
791                         /* do stuff */
792                         vici_disconnect(conn);
793                 }
794                 else
795                 {
796                         ret = errno;
797                         fprintf(stderr, "connecting failed: %s\n", strerror(errno));
798                 }
799                 vici_deinit();
800                 return ret;
801         }
802
803 ## A simple client request ##
804
805 In the following example, a simple _version_ request is issued to the daemon
806 and the result is printed:
807
808         int get_version(vici_conn_t *conn)
809         {
810                 vici_req_t *req;
811                 vici_res_t *res;
812                 int ret = 0;
813
814                 req = vici_begin("version");
815                 res = vici_submit(req, conn);
816                 if (res)
817                 {
818                         printf("%s %s (%s, %s, %s)\n",
819                                 vici_find_str(res, "", "daemon"),
820                                 vici_find_str(res, "", "version"),
821                                 vici_find_str(res, "", "sysname"),
822                                 vici_find_str(res, "", "release"),
823                                 vici_find_str(res, "", "machine"));
824                         vici_free_res(res);
825                 }
826                 else
827                 {
828                         ret = errno;
829                         fprintf(stderr, "version request failed: %s\n", strerror(errno));
830                 }
831                 return ret;
832         }
833
834 ## A request with event streaming and callback parsing ##
835
836 In this more advanced example, the _list-conns_ command is used to stream
837 loaded connections with the _list-conn_ event. The event message is parsed
838 with a simple callback to print the connection name:
839
840         int conn_cb(void *null, vici_res_t *res, char *name)
841         {
842                 printf("%s\n", name);
843                 return 0;
844         }
845
846         void list_cb(void *null, char *name, vici_res_t *res)
847         {
848                 if (vici_parse_cb(res, conn_cb, NULL, NULL, NULL) != 0)
849                 {
850                         fprintf(stderr, "parsing failed: %s\n", strerror(errno));
851                 }
852         }
853
854         int list_conns(vici_conn_t *conn)
855         {
856                 vici_req_t *req;
857                 vici_res_t *res;
858                 int ret = 0;
859
860                 if (vici_register(conn, "list-conn", list_cb, NULL) == 0)
861                 {
862                         req = vici_begin("list-conns");
863                         res = vici_submit(req, conn);
864                         if (res)
865                         {
866                                 vici_free_res(res);
867                         }
868                         else
869                         {
870                                 ret = errno;
871                                 fprintf(stderr, "request failed: %s\n", strerror(errno));
872                         }
873                         vici_register(conn, "list-conn", NULL, NULL);
874                 }
875                 else
876                 {
877                         ret = errno;
878                         fprintf(stderr, "registration failed: %s\n", strerror(errno));
879                 }
880                 return ret;
881         }
882
883 ## API documentation ##
884
885 More information about the libvici API is available in the _libvici.h_ header
886 file or the generated Doxygen documentation.
887
888 # vici ruby gem #
889
890 The _vici ruby gem_ is a pure ruby implementation of the VICI protocol to
891 implement client applications. It is provided in the _ruby_ subdirectory, and
892 gets built and installed if strongSwan has been _./configure_'d with
893 _--enable-vici_ and _--enable-ruby-gems_.
894
895 The _Connection_ class from the _Vici_ module provides the high level interface,
896 the underlying classes are usually not required to build ruby applications
897 using VICI. The _Connection_ class provides methods for the supported VICI
898 commands and an event listening mechanism.
899
900 To represent the VICI message data tree, the gem converts the binary encoding
901 to ruby data types. The _Connection_ class takes and returns ruby objects for
902 the exchanged message data:
903  * Sections get encoded as Hash, containing other sections as Hash, or
904  * Key/Values, where the values are Strings as Hash values
905  * Lists get encoded as Arrays with String values
906 Non-String values that are not a Hash nor an Array get converted with .to_s
907 during encoding.
908
909 ## Connecting to the daemon ##
910
911 To create a connection to the daemon, a socket can be passed to the
912 _Connection_ constructor. If none is passed, a default Unix socket at
913 _/var/run/charon.vici_ is used:
914
915         require "vici"
916         require "socket"
917
918         v = Vici::Connection.new(UNIXSocket.new("/var/run/charon.vici"))
919
920 ## A simple client request ##
921
922 An example to print the daemon version information is as simple as:
923
924         x = v.version
925         puts "%s %s (%s, %s, %s)" % [
926                 x["daemon"], x["version"], x["sysname"], x["release"], x["machine"]
927         ]
928
929 ## A request with closure invocation ##
930
931 The _Connection_ class takes care of event streaming by invoking a closure
932 for each event. The following example lists all loaded connections using the
933 _list-conns_ command and implicitly the _list-conn_ event:
934
935         v.list_conns { |conn|
936                 conn.each { |key, value|
937                         puts key
938                 }
939         }
940
941 ## API documentation ##
942
943 For more details about the ruby gem refer to the comments in the gem source
944 code or the generated documentation.
945
946 # vici Python egg #
947
948 The _vici Python egg_ is a pure Python implementation of the VICI protocol to
949 implement client applications. It is provided in the _python_ subdirectory, and
950 gets built and installed if strongSwan has been _./configure_'d with
951 _--enable-vici_ and _--enable-python-eggs_.
952
953 The _vici_ module provides a _Session()_ constructor for a high level interface,
954 the underlying classes are usually not required to build Python applications
955 using VICI. The _Session_ class provides methods for the supported VICI
956 commands.
957
958 To represent the VICI message data tree, the library converts the binary
959 encoding to Python data types. The _Session_ class takes and returns Python
960 objects for the exchanged message data:
961  * Sections get encoded as OrderedDict, containing other sections, or
962  * Key/Values, where the values are strings as dictionary values
963  * Lists get encoded as Python Lists with string values
964 Values that do not conform to Python dict or list get converted to strings using
965 str().
966
967 ## Connecting to the daemon ##
968
969 To create a connection to the daemon, a socket can be passed to the _Session_
970 constructor. If none is passed, a default Unix socket at _/var/run/charon.vici_
971 is used:
972
973         import vici
974         import socket
975
976         s = socket.socket(socket.AF_UNIX)
977         s.connect("/var/run/charon.vici")
978         v = vici.Session(s)
979
980 ## A simple client request ##
981
982 An example to print the daemon version information is as simple as:
983
984         ver = v.version()
985
986         print "{daemon} {version} ({sysname}, {release}, {machine})".format(**ver)
987
988 ## A request with response iteration ##
989
990 The _Session_ class returns an iterable Python generator for streamed events to
991 continuously stream objects to the caller. The following example lists all
992 loaded connections using the _list-conns_ command and implicitly the _list-conn_
993 event:
994
995         for conn in v.list_conns():
996                 for key in conn:
997                         print key
998
999 Please note that if the returned generator is not iterated completely, it must
1000 be closed using _close()_. This is implicitly done when breaking from a loop,
1001 but an explicit call may be required when directly iterating the generator with
1002 _next()_.
1003
1004 ## Sorting in dictionaries ##
1005
1006 In VICI, in some message trees the order of objects in dictionary matters. In
1007 contrast to ruby Hashes, Python dictionaries do not preserve order of added
1008 objects. It is therefore recommended to use OrderedDicts instead of the default
1009 dictionaries. Objects returned by the library use OrderedDicts.
1010
1011 ## API documentation ##
1012
1013 For more details about the Python egg refer to the comments in the Python source
1014 code.