Annotation of embedaddon/strongswan/src/libcharon/plugins/vici/README.md, revision 1.1.1.2

1.1       misho       1: # The Versatile IKE Control Interface (VICI) protocol #
                      2: 
                      3: The vici _[ˈvitʃi]_ plugin implements the server side of an IPC protocol to
                      4: configure, monitor and control the IKE daemon charon. It uses request/response
                      5: and event 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 hierarchical 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 represents 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:                ike = <IKE_SA configuration name to initiate or to find child under>
                    262:                timeout = <timeout in ms before returning>
                    263:                init-limits = <whether limits may prevent initiating the CHILD_SA>
                    264:                loglevel = <loglevel to issue "control-log" events for>
                    265:        } => {
                    266:                success = <yes or no>
                    267:                errmsg = <error string on failure or timeout>
                    268:        }
                    269: 
                    270: The default timeout of 0 waits indefinitely for a result, and a timeout value
                    271: of -1 returns a result immediately.
                    272: 
                    273: ### terminate() ###
                    274: 
                    275: Terminates an SA while streaming _control-log_ events.
                    276: 
                    277:        {
                    278:                child = <terminate a CHILD_SA by configuration name>
                    279:                ike = <terminate an IKE_SA by configuration name>
                    280:                child-id = <terminate a CHILD_SA by its reqid>
                    281:                ike-id = <terminate an IKE_SA by its unique id>
                    282:                force = <terminate IKE_SA without waiting for proper DELETE, if timeout
                    283:                                 is given, waits for a response until it is reached>
                    284:                timeout = <timeout in ms before returning, see below>
                    285:                loglevel = <loglevel to issue "control-log" events for>
                    286:        } => {
                    287:                success = <yes or no>
                    288:                matches = <number of matched SAs>
                    289:                terminated = <number of terminated SAs>
                    290:                errmsg = <error string on failure or timeout>
                    291:        }
                    292: 
                    293: The default timeout of 0 waits indefinitely for a result, and a timeout value
                    294: of -1 returns a result immediately.
                    295: 
                    296: ### rekey() ###
                    297: 
                    298: Initiate the rekeying of an SA.
                    299: 
                    300:        {
                    301:                child = <rekey a CHILD_SA by configuration name>
                    302:                ike = <rekey an IKE_SA by configuration name>
                    303:                child-id = <rekey a CHILD_SA by its reqid>
                    304:                ike-id = <rekey an IKE_SA by its unique id>
                    305:                reauth = <reauthenticate instead of rekey an IKEv2 SA>
                    306:        } => {
                    307:                success = <yes or no>
                    308:                matches = <number of matched SAs>
                    309:                errmsg = <error string on failure>
                    310:        }
                    311: 
                    312: ### redirect() ###
                    313: 
                    314: Redirect a client-initiated IKE_SA to another gateway.  Only for IKEv2 and if
                    315: supported by the peer.
                    316: 
                    317:        {
                    318:                ike = <redirect an IKE_SA by configuration name>
                    319:                ike-id = <redirect an IKE_SA by its unique id>
                    320:                peer-ip = <redirect an IKE_SA with matching peer IP, may also be a
                    321:                                   subnet in CIDR notation or an IP range>
                    322:                peer-id = <redirect an IKE_SA with matching peer identity, may contain
                    323:                                   wildcards>
                    324:        } => {
                    325:                success = <yes or no>
                    326:                matches = <number of matched SAs>
                    327:                errmsg = <error string on failure>
                    328:        }
                    329: 
                    330: ### install() ###
                    331: 
                    332: Install a trap, drop or bypass policy defined by a CHILD_SA config.
                    333: 
                    334:        {
                    335:                child = <CHILD_SA configuration name to install>
                    336:                ike = <optional IKE_SA configuration name to find child under>
                    337:        } => {
                    338:                success = <yes or no>
                    339:                errmsg = <error string on failure>
                    340:        }
                    341: 
                    342: ### uninstall() ###
                    343: 
                    344: Uninstall a trap, drop or bypass policy defined by a CHILD_SA config.
                    345: 
                    346:        {
                    347:                child = <CHILD_SA configuration name to install>
                    348:                ike = <optional IKE_SA configuration name to find child under,
                    349:                           if not given the first policy matching child is removed>
                    350:        } => {
                    351:                success = <yes or no>
                    352:                errmsg = <error string on failure>
                    353:        }
                    354: 
                    355: ### list-sas() ###
                    356: 
                    357: Lists currently active IKE_SAs and associated CHILD_SAs by streaming _list-sa_
                    358: events.
                    359: 
                    360:        {
                    361:                noblock = <use non-blocking mode if key is set>
                    362:                ike = <filter listed IKE_SAs by its name>
                    363:                ike-id = <filter listed IKE_SA by its unique id>
                    364:        } => {
                    365:                # completes after streaming list-sa events
                    366:        }
                    367: 
                    368: ### list-policies() ###
                    369: 
                    370: List currently installed trap, drop and bypass policies by streaming
                    371: _list-policy_ events.
                    372: 
                    373:        {
                    374:                drop = <set to yes to list drop policies>
                    375:                pass = <set to yes to list bypass policies>
                    376:                trap = <set to yes to list trap policies>
                    377:                child = <filter by CHILD_SA configuration name>
                    378:                ike = <filter by IKE_SA configuration name>
                    379:        } => {
                    380:                # completes after streaming list-sa events
                    381:        }
                    382: 
                    383: ### list-conns() ###
                    384: 
                    385: List currently loaded connections by streaming _list-conn_ events. This
                    386: call includes all connections known by the daemon, not only those loaded
                    387: over vici.
                    388: 
                    389:        {
                    390:                ike = <list connections matching a given configuration name only>
                    391:        } => {
                    392:                # completes after streaming list-conn events
                    393:        }
                    394: 
                    395: ### get-conns() ###
                    396: 
                    397: Return a list of connection names loaded exclusively over vici, not including
                    398: connections found in other backends.
                    399: 
                    400:        {} => {
                    401:                conns = [
                    402:                        <list of connection names>
                    403:                ]
                    404:        }
                    405: 
                    406: ### list-certs() ###
                    407: 
                    408: List currently loaded certificates by streaming _list-cert_ events. This
                    409: call includes all certificates known by the daemon, not only those loaded
                    410: over vici.
                    411: 
                    412:        {
                    413:                type = <certificate type to filter for, X509|X509_AC|X509_CRL|
                    414:                                                                                                OCSP_RESPONSE|PUBKEY  or ANY>
                    415:                flag = <X.509 certificate flag to filter for, NONE|CA|AA|OCSP or ANY>
                    416:                subject = <set to list only certificates having subject>
                    417:        } => {
                    418:                # completes after streaming list-cert events
                    419:        }
                    420: 
                    421: ### list-authorities() ###
                    422: 
                    423: List currently loaded certification authority information by streaming
                    424: _list-authority_ events.
                    425: 
                    426:        {
                    427:                name = <list certification authority of a given name>
                    428:        } => {
                    429:                # completes after streaming list-authority events
                    430:        }
                    431: 
                    432: ### get-authorities() ###
                    433: 
                    434: Return a list of currently loaded certification authority names.
                    435: 
                    436:        {} => {
                    437:                authorities = [
                    438:                        <list of certification authority names>
                    439:                ]
                    440:        }
                    441: 
                    442: ### load-conn() ###
                    443: 
                    444: Load a single connection definition into the daemon. An existing connection
                    445: with the same name gets updated or replaced.
                    446: 
                    447:        {
                    448:                <IKE_SA config name> = {
                    449:                        # IKE configuration parameters with authentication and CHILD_SA
                    450:                        # subsections. Refer to swanctl.conf(5) for details.
                    451:                }
                    452:        } => {
                    453:                success = <yes or no>
                    454:                errmsg = <error string on failure>
                    455:        }
                    456: 
                    457: ### unload-conn() ###
                    458: 
                    459: Unload a previously loaded connection definition by name.
                    460: 
                    461:        {
                    462:                name = <IKE_SA config name>
                    463:        } => {
                    464:                success = <yes or no>
                    465:                errmsg = <error string on failure>
                    466:        }
                    467: 
                    468: ### load-cert() ###
                    469: 
                    470: Load a certificate into the daemon.
                    471: 
                    472:        {
                    473:                type = <certificate type, X509|X509_AC|X509_CRL>
                    474:                flag = <X.509 certificate flag, NONE|CA|AA|OCSP>
                    475:                data = <PEM or DER encoded certificate data>
                    476:        } => {
                    477:                success = <yes or no>
                    478:                errmsg = <error string on failure>
                    479:        }
                    480: 
                    481: ### load-key() ###
                    482: 
                    483: Load a private key into the daemon.
                    484: 
                    485:        {
1.1.1.2 ! misho     486:                type = <private key type, rsa|ecdsa|ed25519|ed448|bliss|any>
1.1       misho     487:                data = <PEM or DER encoded key data>
                    488:        } => {
                    489:                success = <yes or no>
                    490:                errmsg = <error string on failure>
                    491:                id = <hex-encoded SHA-1 key identifier of the public key on success>
                    492:        }
                    493: 
                    494: ### unload-key() ###
                    495: 
                    496: Unload the private key with the given key identifier.
                    497: 
                    498:        {
                    499:                id = <hex-encoded SHA-1 key identifier of the private key to unload>
                    500:        } => {
                    501:                success = <yes or no>
                    502:                errmsg = <error string on failure>
                    503:        }
                    504: 
                    505: ### get-keys() ###
                    506: 
                    507: Return a list of identifiers of private keys loaded exclusively over vici, not
                    508: including keys found in other backends.
                    509: 
                    510:        {} => {
                    511:                keys = [
                    512:                        <list of hex-encoded SHA-1 key identifiers>
                    513:                ]
                    514:        }
                    515: 
                    516: ### load-token() ###
                    517: 
                    518: Load a private key located on a token into the daemon.  Such keys may be listed
                    519: and unloaded using the _get-keys_ and _unload-key_ commands, respectively (based
                    520: on the key identifier derived from the public key).
                    521: 
                    522:        {
                    523:                handle = <hex-encoded CKA_ID of the private key on token>
                    524:                slot = <optional slot number>
                    525:                module = <optional PKCS#11 module>
                    526:                pin = <optional PIN to access the key, has to be provided via other
                    527:                           means if not given>
                    528:        } => {
                    529:                success = <yes or no>
                    530:                errmsg = <error string on failure>
                    531:                id = <hex-encoded SHA-1 key identifier of the public key on success>
                    532:        }
                    533: 
                    534: ### load-shared() ###
                    535: 
                    536: Load a shared IKE PSK, EAP, XAuth or NTLM secret into the daemon.
                    537: 
                    538:        {
                    539:                id = <optional unique identifier of this shared key>
                    540:                type = <shared key type, IKE|EAP|XAUTH|NTLM>
                    541:                data = <raw shared key data>
                    542:                owners = [
                    543:                        <list of shared key owner identities>
                    544:                ]
                    545:        } => {
                    546:                success = <yes or no>
                    547:                errmsg = <error string on failure>
                    548:        }
                    549: 
                    550: ### unload-shared() ###
                    551: 
                    552: Unload a previously loaded shared IKE PSK, EAP, XAuth or NTLM secret by its
                    553: unique identifier.
                    554: 
                    555:        {
                    556:                id = <unique identifier of the shared key to unload>
                    557:        } => {
                    558:                success = <yes or no>
                    559:                errmsg = <error string on failure>
                    560:        }
                    561: 
                    562: ### get-shared() ###
                    563: 
                    564: Return a list of unique identifiers of shared keys loaded exclusively over vici,
                    565: not including keys found in other backends.
                    566: 
                    567:        {} => {
                    568:                keys = [
                    569:                        <list of unique identifiers>
                    570:                ]
                    571:        }
                    572: 
                    573: ### flush-certs() ###
                    574: 
                    575: Flushes the certificate cache. The optional type argument allows to flush
                    576: only certificates of a given type, e.g. all cached CRLs.
                    577: 
                    578:        {
                    579:                type = <certificate type to filter for, X509|X509_AC|X509_CRL|
                    580:                                                                                                OCSP_RESPONSE|PUBKEY or ANY>
                    581:        } => {
                    582:                success = <yes or no>
                    583:                errmsg = <error string on failure>
                    584:        }
                    585: 
                    586: ### clear-creds() ###
                    587: 
                    588: Clear all loaded certificate, private key and shared key credentials. This
                    589: affects only credentials loaded over vici, but additionally flushes the
                    590: credential cache.
                    591: 
                    592:        {} => {
                    593:                success = <yes or no>
                    594:                errmsg = <error string on failure>
                    595:        }
                    596: 
                    597: ### load-authority() ###
                    598: 
                    599: Load a single certification authority definition into the daemon. An existing
                    600: authority with the same name gets replaced.
                    601: 
                    602:        {
                    603:                <certification authority name> = {
                    604:                        # certification authority parameters
                    605:                        # refer to swanctl.conf(5) for details.
                    606:                }
                    607:        } => {
                    608:                success = <yes or no>
                    609:                errmsg = <error string on failure>
                    610:        }
                    611: 
                    612: ### unload-authority() ###
                    613: 
                    614: Unload a previously loaded certification authority definition by name.
                    615: 
                    616:        {
                    617:                name = <certification authority name>
                    618:        } => {
                    619:                success = <yes or no>
                    620:                errmsg = <error string on failure>
                    621:        }
                    622: 
                    623: ### load-pool() ###
                    624: 
                    625: Load an in-memory virtual IP and configuration attribute pool. Existing
                    626: pools with the same name get updated, if possible.
                    627: 
                    628:        {
                    629:                <pool name> = {
                    630:                        addrs = <subnet of virtual IP pool addresses>
                    631:                        <attribute type>* = [
                    632:                                # attribute type is one of address, dns, nbns, dhcp, netmask,
                    633:                                # server, subnet, split_include, split_exclude or a numerical
                    634:                                # attribute type identifier.
                    635:                                <list of attributes for type>
                    636:                        ]
                    637:                }
                    638:        } => {
                    639:                success = <yes or no>
                    640:                errmsg = <error string on failure>
                    641:        }
                    642: 
                    643: ### unload-pool() ###
                    644: 
                    645: Unload a previously loaded virtual IP and configuration attribute pool.
                    646: Unloading fails for pools with leases currently online.
                    647: 
                    648:        {
                    649:                name = <virtual IP address pool to delete>
                    650:        } => {
                    651:                success = <yes or no>
                    652:                errmsg = <error string on failure>
                    653:        }
                    654: 
                    655: ### get-pools() ###
                    656: 
                    657: List the currently loaded pools.
                    658: 
                    659:        {
                    660:                leases = <set to yes to include leases>
                    661:                name = <optional name of the pool to query>
                    662:        } => {
                    663:                <pool name>* = {
                    664:                        base = <virtual IP pool base address>
                    665:                        size = <total number of addresses in the pool>
                    666:                        online = <number of leases online>
                    667:                        offline = <number of leases offline>
                    668:                        leases = {
                    669:                                <zero-based index>* = {
                    670:                                        address = <IP address>
                    671:                                        identity = <assigned identity>
                    672:                                        status = <online|offline>
                    673:                                }
                    674:                        }
                    675:                }
                    676:        }
                    677: 
                    678: ### get-algorithms() ###
                    679: 
                    680: List currently loaded algorithms and their implementation.
                    681: 
                    682:        {} => {
                    683:                <algorithm type> = {
                    684:                        <algorithm> = <plugin providing the implementation>
                    685:                }
                    686:        }
                    687: 
                    688: ### get-counters() ###
                    689: 
                    690: List global or connection-specific counters for several IKE events.
                    691: 
                    692:        {
                    693:                name = <optional connection name, omit for global counters>
                    694:                all = <yes to get counters for all connections, name is ignored>
                    695:        } => {
                    696:                counters = {
                    697:                        <name|empty for global counters> = {
                    698:                                <pairs of counter name and 64-bit counter value>
                    699:                        }
                    700:                }
                    701:                success = <yes or no>
                    702:                errmsg = <error string on failure>
                    703:        }
                    704: 
                    705: ### reset-counters() ###
                    706: 
                    707: Reset global or connection-specific IKE event counters.
                    708: 
                    709:        {
                    710:                name = <optional connection name, omit for global counters>
                    711:                all = <yes to reset counters for all connections, name is ignored>
                    712:        } => {
                    713:                success = <yes or no>
                    714:                errmsg = <error string on failure>
                    715:        }
                    716: 
                    717: ## Server-issued events ##
                    718: 
                    719: Based on the packet layer, the vici plugin raises event messages using named
                    720: EVENT packets wrapping messages. The message contains event details.
                    721: 
                    722: ### log ###
                    723: 
                    724: The _log_ event is issued to registered clients for each debug log message.
                    725: This event is not associated with a command.
                    726: 
                    727:        {
                    728:                group = <subsystem identifier for debug message>
                    729:                level = <log level, 0-4>
                    730:                thread = <numerical thread identifier issuing the log message>
                    731:                ikesa-name = <name of IKE_SA, if log is associated with any>
                    732:                ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
                    733:                msg = <log message text>
                    734:        }
                    735: 
                    736: ### control-log ###
                    737: 
                    738: The _control-log_ event is issued for log events during active _initiate_ or
                    739: _terminate_ commands. It is issued only to clients currently having such
                    740: a command active.
                    741: 
                    742:        {
                    743:                group = <subsystem identifier for debug message>
                    744:                level = <log level, 0-4>
                    745:                ikesa-name = <name of IKE_SA, if log associated with any>
                    746:                ikesa-uniqued = <unique identifier of IKE_A, if log associated with any>
                    747:                msg = <log message text>
                    748:        }
                    749: 
                    750: ### list-sa ###
                    751: 
                    752: The _list-sa_ event is issued to stream IKE_SAs during an active _list-sas_
                    753: command.
                    754: 
                    755:        {
                    756:                <IKE_SA config name> = {
                    757:                        uniqueid = <IKE_SA unique identifier>
                    758:                        version = <IKE version, 1 or 2>
                    759:                        state = <IKE_SA state name>
                    760:                        local-host = <local IKE endpoint address>
                    761:                        local-port = <local IKE endpoint port>
                    762:                        local-id = <local IKE identity>
                    763:                        remote-host = <remote IKE endpoint address>
                    764:                        remote-port = <remote IKE endpoint port>
                    765:                        remote-id = <remote IKE identity>
                    766:                        remote-xauth-id = <remote XAuth identity, if XAuth-authenticated>
                    767:                        remote-eap-id = <remote EAP identity, if EAP-authenticated>
                    768:                        initiator = <yes, if initiator of IKE_SA>
                    769:                        initiator-spi = <hex encoded initiator SPI / cookie>
                    770:                        responder-spi = <hex encoded responder SPI / cookie>
                    771:                        nat-local = <yes, if local endpoint is behind a NAT>
                    772:                        nat-remote = <yes, if remote endpoint is behind a NAT>
                    773:                        nat-fake = <yes, if NAT situation has been faked as responder>
                    774:                        nat-any = <yes, if any endpoint is behind a NAT (also if faked)>
                    775:                        if-id-in = <hex encoded default inbound XFRM interface ID>
                    776:                        if-id-out = <hex encoded default outbound XFRM interface ID>
                    777:                        encr-alg = <IKE encryption algorithm string>
                    778:                        encr-keysize = <key size for encr-alg, if applicable>
                    779:                        integ-alg = <IKE integrity algorithm string>
                    780:                        integ-keysize = <key size for encr-alg, if applicable>
                    781:                        prf-alg = <IKE pseudo random function string>
                    782:                        dh-group = <IKE Diffie-Hellman group string>
                    783:                        established = <seconds the IKE_SA has been established>
                    784:                        rekey-time = <seconds before IKE_SA gets rekeyed>
                    785:                        reauth-time = <seconds before IKE_SA gets re-authenticated>
                    786:                        local-vips = [
                    787:                                <list of virtual IPs assigned by the remote peer, installed locally>
                    788:                        ]
                    789:                        remote-vips = [
                    790:                                <list of virtual IPs assigned to the remote peer>
                    791:                        ]
                    792:                        tasks-queued = [
                    793:                                <list of currently queued tasks for execution>
                    794:                        ]
                    795:                        tasks-active = [
                    796:                                <list of tasks currently initiating actively>
                    797:                        ]
                    798:                        tasks-passive = [
                    799:                                <list of tasks currently handling passively>
                    800:                        ]
                    801:                        child-sas = {
                    802:                                <unique child-sa-name>* = {
                    803:                                        name = <name of the CHILD_SA>
                    804:                                        uniqueid = <unique CHILD_SA identifier>
                    805:                                        reqid = <reqid of CHILD_SA>
                    806:                                        state = <state string of CHILD_SA>
                    807:                                        mode = <IPsec mode, tunnel|transport|beet>
                    808:                                        protocol = <IPsec protocol AH|ESP>
                    809:                                        encap = <yes if using UDP encapsulation>
                    810:                                        spi-in = <hex encoded inbound SPI>
                    811:                                        spi-out = <hex encoded outbound SPI>
                    812:                                        cpi-in = <hex encoded inbound CPI, if using compression>
                    813:                                        cpi-out = <hex encoded outbound CPI, if using compression>
                    814:                                        mark-in = <hex encoded inbound Netfilter mark value>
                    815:                                        mark-mask-in = <hex encoded inbound Netfilter mark mask>
                    816:                                        mark-out = <hex encoded outbound Netfilter mark value>
                    817:                                        mark-mask-out = <hex encoded outbound Netfilter mark mask>
                    818:                                        if-id-in = <hex encoded inbound XFRM interface ID>
                    819:                                        if-id-out = <hex encoded outbound XFRM interface ID>
                    820:                                        encr-alg = <ESP encryption algorithm name, if any>
                    821:                                        encr-keysize = <ESP encryption key size, if applicable>
                    822:                                        integ-alg = <ESP or AH integrity algorithm name, if any>
                    823:                                        integ-keysize = <ESP or AH integrity key size, if applicable>
                    824:                                        prf-alg = <CHILD_SA pseudo random function name>
                    825:                                        dh-group = <CHILD_SA PFS rekeying DH group name, if any>
                    826:                                        esn = <1 if using extended sequence numbers>
                    827:                                        bytes-in = <number of input bytes processed>
                    828:                                        packets-in = <number of input packets processed>
                    829:                                        use-in = <seconds since last inbound packet, if any>
                    830:                                        bytes-out = <number of output bytes processed>
                    831:                                        packets-out = <number of output packets processed>
                    832:                                        use-out = <seconds since last outbound packet, if any>
                    833:                                        rekey-time = <seconds before CHILD_SA gets rekeyed>
                    834:                                        life-time = <seconds before CHILD_SA expires>
                    835:                                        install-time = <seconds the CHILD_SA has been installed>
                    836:                                        local-ts = [
                    837:                                                <list of local traffic selectors>
                    838:                                        ]
                    839:                                        remote-ts = [
                    840:                                                <list of remote traffic selectors>
                    841:                                        ]
                    842:                                }
                    843:                        }
                    844:                }
                    845:        }
                    846: 
                    847: ### list-policy ###
                    848: 
                    849: The _list-policy_ event is issued to stream installed policies during an active
                    850: _list-policies_ command.
                    851: 
                    852:        {
                    853:                <ike-sa-config-name/child-sa-config-name> = {
                    854:                        child = <CHILD_SA configuration name>
                    855:                        ike = <IKE_SA configuration name or namespace, if available>
                    856:                        mode = <policy mode, tunnel|transport|pass|drop>
                    857:                        local-ts = [
                    858:                                <list of local traffic selectors>
                    859:                        ]
                    860:                        remote-ts = [
                    861:                                <list of remote traffic selectors>
                    862:                        ]
                    863:                }
                    864:        }
                    865: 
                    866: ### list-conn ###
                    867: 
                    868: The _list-conn_ event is issued to stream loaded connection during an active
                    869: _list-conns_ command.
                    870: 
                    871:        {
                    872:                <IKE_SA connection name> = {
                    873:                        local_addrs = [
                    874:                                <list of valid local IKE endpoint addresses>
                    875:                        ]
                    876:                        remote_addrs = [
                    877:                                <list of valid remote IKE endpoint addresses>
                    878:                        ]
                    879:                        version = <IKE version as string, IKEv1|IKEv2 or 0 for any>
                    880:                        reauth_time = <IKE_SA reauthentication interval in seconds>
                    881:                        rekey_time = <IKE_SA rekeying interval in seconds>
                    882: 
                    883:                        local*, remote* = { # multiple local and remote auth sections
                    884:                                class = <authentication type>
                    885:                                eap-type = <EAP type to authenticate if when using EAP>
                    886:                                eap-vendor = <EAP vendor for type, if any>
                    887:                                xauth = <xauth backend name>
                    888:                                revocation = <revocation policy>
                    889:                                id = <IKE identity>
                    890:                                aaa_id = <AAA authentication backend identity>
                    891:                                eap_id = <EAP identity for authentication>
                    892:                                xauth_id = <XAuth username for authentication>
                    893:                                groups = [
                    894:                                        <group membership required to use connection>
                    895:                                ]
                    896:                                certs = [
                    897:                                        <certificates allowed for authentication>
                    898:                                ]
                    899:                                cacerts = [
                    900:                                        <CA certificates allowed for authentication>
                    901:                                ]
                    902:                        }
                    903:                        children = {
                    904:                                <CHILD_SA config name>* = {
                    905:                                        mode = <IPsec mode>
                    906:                                        rekey_time = <CHILD_SA rekeying interval in seconds>
                    907:                                        rekey_bytes = <CHILD_SA rekeying interval in bytes>
                    908:                                        rekey_packets = <CHILD_SA rekeying interval in packets>
                    909:                                        local-ts = [
                    910:                                                <list of local traffic selectors>
                    911:                                        ]
                    912:                                        remote-ts = [
                    913:                                                <list of remote traffic selectors>
                    914:                                        ]
                    915:                                }
                    916:                        }
                    917:                }
                    918:        }
                    919: 
                    920: ### list-cert ###
                    921: 
                    922: The _list-cert_ event is issued to stream loaded certificates during an active
                    923: _list-certs_ command.
                    924: 
                    925:        {
                    926:                type = <certificate type, X509|X509_AC|X509_CRL|OCSP_RESPONSE|PUBKEY>
                    927:                flag = <X.509 certificate flag, NONE|CA|AA|OCSP>
                    928:                has_privkey = <set if a private key for the certificate is available>
                    929:                data = <ASN1 encoded certificate data>
                    930:                subject = <subject string if defined and certificate type is PUBKEY>
                    931:                not-before = <time string if defined and certificate type is PUBKEY>
                    932:                not-after  = <time string if defined and certificate type is PUBKEY>
                    933:        }
                    934: 
                    935: ### list-authority ###
                    936: 
                    937: The _list-authority_ event is issued to stream loaded certification authority
                    938: information during an active_list-authorities_ command.
                    939: 
                    940:        {
                    941:                <certification authority name> = {
                    942:                        cacert = <subject distinguished name of CA certificate>
                    943:                        crl_uris = [
                    944:                                <CRL URI (http, ldap or file)>
                    945:                        ]
                    946:                        ocsp_uris = [
                    947:                                <OCSP URI (http)>
                    948:                        ]
                    949:                        cert_uri_base = <base URI for download of hash-and-URL certificates>
                    950:                }
                    951:        }
                    952: 
                    953: ### ike-updown ###
                    954: 
                    955: The _ike-updown_ event is issued when an IKE_SA is established or terminated.
                    956: 
                    957:        {
                    958:                up = <set if up event>
                    959:                <IKE_SA config name> = {
                    960:                        <same data as in the list-sas event, but without child-sas section>
                    961:                }
                    962:        }
                    963: 
                    964: ### ike-rekey ###
                    965: 
                    966: The _ike-rekey_ event is issued when an IKE_SA is rekeyed.
                    967: 
                    968:        {
                    969:                <IKE_SA config name> = {
                    970:                        old = {
                    971:                                <same data as in the list-sas event, but without child-sas section>
                    972:                        }
                    973:                        new = {
                    974:                                <same data as in the list-sas event, but without child-sas section>
                    975:                        }
                    976:                }
                    977:        }
                    978: 
1.1.1.2 ! misho     979: ### ike-update ###
        !           980: 
        !           981: The _ike-update_ event is issued when the local or remote endpoint address of an
        !           982: IKE_SA is about to change (at least one address/port is different).
        !           983: 
        !           984:        {
        !           985:                local-host = <new/current local IKE endpoint address>
        !           986:                local-port = <new/current local IKE endpoint port>
        !           987:                remote-host = <new/current remote IKE endpoint address>
        !           988:                remote-port = <new/current remote IKE endpoint port>
        !           989:                <IKE_SA config name> = {
        !           990:                        <same data as in the list-sas event, but without child-sas section
        !           991:                         and listing the old addresses/ports>
        !           992:                }
        !           993:        }
        !           994: 
1.1       misho     995: ### child-updown ###
                    996: 
                    997: The _child-updown_ event is issued when a CHILD_SA is established or terminated.
                    998: 
                    999:        {
                   1000:                up = <set if up event>
                   1001:                <IKE_SA config name> = {
                   1002:                        <same data as in the list-sas event, but with only the affected
                   1003:                         CHILD_SA in the child-sas section>
                   1004:                }
                   1005:        }
                   1006: 
                   1007: ### child-rekey ###
                   1008: 
                   1009: The _child-rekey_ event is issued when a CHILD_SA is rekeyed.
                   1010: 
                   1011:        {
                   1012:                <IKE_SA config name> = {
                   1013:                        <same data as in the list-sas event, but with the child-sas section
                   1014:                         as follows>
                   1015:                        child-sas = {
                   1016:                                <child-sa-name> = {
                   1017:                                        old = {
                   1018:                                                <same data as in the list-sas event>
                   1019:                                        }
                   1020:                                        new = {
                   1021:                                                <same data as in the list-sas event>
                   1022:                                        }
                   1023:                                }
                   1024:                        }
                   1025:                }
                   1026:        }
                   1027: 
                   1028: # libvici C client library #
                   1029: 
                   1030: libvici is the reference implementation of a C client library implementing
                   1031: the vici protocol. It builds upon libstrongswan, but provides a stable API
                   1032: to implement client applications in the C programming language. libvici uses
                   1033: the libstrongswan thread pool to deliver event messages asynchronously.
                   1034: 
                   1035: ## Connecting to the daemon ##
                   1036: 
                   1037: This example shows how to connect to the daemon using the default URI, and
                   1038: then perform proper cleanup:
                   1039: 
                   1040:        #include <stdio.h>
                   1041:        #include <errno.h>
                   1042:        #include <string.h>
                   1043: 
                   1044:        #include <libvici.h>
                   1045: 
                   1046:        int main(int argc, char *argv[])
                   1047:        {
                   1048:                vici_conn_t *conn;
                   1049:                int ret = 0;
                   1050: 
                   1051:                vici_init();
                   1052:                conn = vici_connect(NULL);
                   1053:                if (conn)
                   1054:                {
                   1055:                        /* do stuff */
                   1056:                        vici_disconnect(conn);
                   1057:                }
                   1058:                else
                   1059:                {
                   1060:                        ret = errno;
                   1061:                        fprintf(stderr, "connecting failed: %s\n", strerror(errno));
                   1062:                }
                   1063:                vici_deinit();
                   1064:                return ret;
                   1065:        }
                   1066: 
                   1067: ## A simple client request ##
                   1068: 
                   1069: In the following example, a simple _version_ request is issued to the daemon
                   1070: and the result is printed:
                   1071: 
                   1072:        int get_version(vici_conn_t *conn)
                   1073:        {
                   1074:                vici_req_t *req;
                   1075:                vici_res_t *res;
                   1076:                int ret = 0;
                   1077: 
                   1078:                req = vici_begin("version");
                   1079:                res = vici_submit(req, conn);
                   1080:                if (res)
                   1081:                {
                   1082:                        printf("%s %s (%s, %s, %s)\n",
                   1083:                                vici_find_str(res, "", "daemon"),
                   1084:                                vici_find_str(res, "", "version"),
                   1085:                                vici_find_str(res, "", "sysname"),
                   1086:                                vici_find_str(res, "", "release"),
                   1087:                                vici_find_str(res, "", "machine"));
                   1088:                        vici_free_res(res);
                   1089:                }
                   1090:                else
                   1091:                {
                   1092:                        ret = errno;
                   1093:                        fprintf(stderr, "version request failed: %s\n", strerror(errno));
                   1094:                }
                   1095:                return ret;
                   1096:        }
                   1097: 
                   1098: ## A request with event streaming and callback parsing ##
                   1099: 
                   1100: In this more advanced example, the _list-conns_ command is used to stream
                   1101: loaded connections with the _list-conn_ event. The event message is parsed
                   1102: with a simple callback to print the connection name:
                   1103: 
                   1104:        int conn_cb(void *null, vici_res_t *res, char *name)
                   1105:        {
                   1106:                printf("%s\n", name);
                   1107:                return 0;
                   1108:        }
                   1109: 
                   1110:        void list_cb(void *null, char *name, vici_res_t *res)
                   1111:        {
                   1112:                if (vici_parse_cb(res, conn_cb, NULL, NULL, NULL) != 0)
                   1113:                {
                   1114:                        fprintf(stderr, "parsing failed: %s\n", strerror(errno));
                   1115:                }
                   1116:        }
                   1117: 
                   1118:        int list_conns(vici_conn_t *conn)
                   1119:        {
                   1120:                vici_req_t *req;
                   1121:                vici_res_t *res;
                   1122:                int ret = 0;
                   1123: 
                   1124:                if (vici_register(conn, "list-conn", list_cb, NULL) == 0)
                   1125:                {
                   1126:                        req = vici_begin("list-conns");
                   1127:                        res = vici_submit(req, conn);
                   1128:                        if (res)
                   1129:                        {
                   1130:                                vici_free_res(res);
                   1131:                        }
                   1132:                        else
                   1133:                        {
                   1134:                                ret = errno;
                   1135:                                fprintf(stderr, "request failed: %s\n", strerror(errno));
                   1136:                        }
                   1137:                        vici_register(conn, "list-conn", NULL, NULL);
                   1138:                }
                   1139:                else
                   1140:                {
                   1141:                        ret = errno;
                   1142:                        fprintf(stderr, "registration failed: %s\n", strerror(errno));
                   1143:                }
                   1144:                return ret;
                   1145:        }
                   1146: 
                   1147: ## API documentation ##
                   1148: 
                   1149: More information about the libvici API is available in the _libvici.h_ header
                   1150: file or the generated Doxygen documentation.
                   1151: 
                   1152: # vici ruby gem #
                   1153: 
                   1154: The _vici ruby gem_ is a pure ruby implementation of the VICI protocol to
                   1155: implement client applications. It is provided in the _ruby_ subdirectory, and
                   1156: gets built and installed if strongSwan has been _./configure_'d with
                   1157: _--enable-vici_ and _--enable-ruby-gems_.
                   1158: 
                   1159: The _Connection_ class from the _Vici_ module provides the high level interface,
                   1160: the underlying classes are usually not required to build ruby applications
                   1161: using VICI. The _Connection_ class provides methods for the supported VICI
                   1162: commands and an event listening mechanism.
                   1163: 
                   1164: To represent the VICI message data tree, the gem converts the binary encoding
                   1165: to ruby data types. The _Connection_ class takes and returns ruby objects for
                   1166: the exchanged message data:
                   1167:  * Sections get encoded as Hash, containing other sections as Hash, or
                   1168:  * Key/Values, where the values are Strings as Hash values
                   1169:  * Lists get encoded as Arrays with String values
                   1170: Non-String values that are not a Hash nor an Array get converted with .to_s
                   1171: during encoding.
                   1172: 
                   1173: ## Connecting to the daemon ##
                   1174: 
                   1175: To create a connection to the daemon, a socket can be passed to the
                   1176: _Connection_ constructor. If none is passed, a default Unix socket at
                   1177: _/var/run/charon.vici_ is used:
                   1178: 
                   1179:        require "vici"
                   1180:        require "socket"
                   1181: 
                   1182:        v = Vici::Connection.new(UNIXSocket.new("/var/run/charon.vici"))
                   1183: 
                   1184: ## A simple client request ##
                   1185: 
                   1186: An example to print the daemon version information is as simple as:
                   1187: 
                   1188:        x = v.version
                   1189:        puts "%s %s (%s, %s, %s)" % [
                   1190:                x["daemon"], x["version"], x["sysname"], x["release"], x["machine"]
                   1191:        ]
                   1192: 
                   1193: ## A request with closure invocation ##
                   1194: 
                   1195: The _Connection_ class takes care of event streaming by invoking a closure
                   1196: for each event. The following example lists all loaded connections using the
                   1197: _list-conns_ command and implicitly the _list-conn_ event:
                   1198: 
                   1199:        v.list_conns { |conn|
                   1200:                conn.each { |key, value|
                   1201:                        puts key
                   1202:                }
                   1203:        }
                   1204: 
                   1205: ## API documentation ##
                   1206: 
                   1207: For more details about the ruby gem refer to the comments in the gem source
                   1208: code or the generated documentation.
                   1209: 
                   1210: # vici Python egg #
                   1211: 
                   1212: The _vici Python egg_ is a pure Python implementation of the VICI protocol to
                   1213: implement client applications. It is provided in the _python_ subdirectory, and
                   1214: gets built and installed if strongSwan has been _./configure_'d with
                   1215: _--enable-vici_ and _--enable-python-eggs_.
                   1216: 
                   1217: The _vici_ module provides a _Session()_ constructor for a high level interface,
                   1218: the underlying classes are usually not required to build Python applications
                   1219: using VICI. The _Session_ class provides methods for the supported VICI
                   1220: commands.
                   1221: 
                   1222: To represent the VICI message data tree, the library converts the binary
                   1223: encoding to Python data types. The _Session_ class takes and returns Python
                   1224: objects for the exchanged message data:
                   1225:  * Sections get encoded as OrderedDict, containing other sections, or
                   1226:  * Key/Values, where the values are strings as dictionary values
                   1227:  * Lists get encoded as Python Lists with string values
                   1228: Values that do not conform to Python dict or list get converted to strings using
                   1229: str().
                   1230: 
                   1231: ## Connecting to the daemon ##
                   1232: 
                   1233: To create a connection to the daemon, a socket can be passed to the _Session_
                   1234: constructor. If none is passed, a default Unix socket at _/var/run/charon.vici_
                   1235: is used:
                   1236: 
                   1237:        import vici
                   1238:        import socket
                   1239: 
                   1240:        s = socket.socket(socket.AF_UNIX)
                   1241:        s.connect("/var/run/charon.vici")
                   1242:        v = vici.Session(s)
                   1243: 
                   1244: ## A simple client request ##
                   1245: 
                   1246: An example to print the daemon version information is as simple as:
                   1247: 
                   1248:        ver = v.version()
                   1249: 
                   1250:        print "{daemon} {version} ({sysname}, {release}, {machine})".format(**ver)
                   1251: 
                   1252: ## A request with response iteration ##
                   1253: 
                   1254: The _Session_ class returns an iterable Python generator for streamed events to
                   1255: continuously stream objects to the caller. The following example lists all
                   1256: loaded connections using the _list-conns_ command and implicitly the _list-conn_
                   1257: event:
                   1258: 
                   1259:        for conn in v.list_conns():
                   1260:                for key in conn:
                   1261:                        print key
                   1262: 
                   1263: Please note that if the returned generator is not iterated completely, it must
                   1264: be closed using _close()_. This is implicitly done when breaking from a loop,
                   1265: but an explicit call may be required when directly iterating the generator with
                   1266: _next()_.
                   1267: 
                   1268: ## Sorting in dictionaries ##
                   1269: 
                   1270: In VICI, in some message trees the order of objects in dictionary matters. In
                   1271: contrast to ruby Hashes, Python dictionaries do not preserve order of added
                   1272: objects. It is therefore recommended to use OrderedDicts instead of the default
                   1273: dictionaries. Objects returned by the library use OrderedDicts.
                   1274: 
                   1275: ## API documentation ##
                   1276: 
                   1277: For more details about the Python egg refer to the comments in the Python source
                   1278: code.
                   1279: 
                   1280: # Vici::Session Perl CPAN module #
                   1281: 
                   1282: The _Vici::Session Perl CPAN module_ is a pure Perl implementation of the VICI
                   1283: protocol to implement client applications. It is provided in the _perl_
                   1284: subdirectory, and gets built and installed if strongSwan has been
                   1285:  _./configure_'d with_--enable-vici_ and _--enable-perl-cpan_.
                   1286: 
                   1287: The _Vici::Session_ module provides a _new()_ constructor for a high level
                   1288: interface, the underlying _Vici::Packet_ and _Vici::Transport_ classes are
                   1289: usually not required to build Perl applications using VICI. The _Vici::Session_
                   1290: class provides methods for the supported VICI commands. The auxiliary
                   1291:  _Vici::Message_ class is used to encode configuration parameters sent to
                   1292: the daemon and decode data returned by the daemon.
                   1293: 
                   1294: ## Connecting to the daemon ##
                   1295: 
                   1296:        use IO::Socket::UNIX;
                   1297:        use Vici::Session;
                   1298:        use Vici::Message;
                   1299: 
                   1300:        my $socket = IO::Socket::UNIX->new(
                   1301:                        Type => SOCK_STREAM,
                   1302:                        Peer => '/var/run/charon.vici',
                   1303:        ) or die "Vici socket: $!";
                   1304: 
                   1305:        my $session = Vici::Session->new($socket);
                   1306: 
                   1307: ## A simple client request ##
                   1308: 
                   1309: An example to print the daemon version information is as simple as:
                   1310: 
                   1311:        my $version = $session->version()->hash();
                   1312: 
                   1313:        foreach my $key ('daemon', 'version', 'sysname', 'release', 'machine' ) {
                   1314:                print $version->{$key}, " ";
                   1315:        }
                   1316: 
                   1317: The _Vici::Session_ methods are explained in the perl/Vici-Session/README.pod
                   1318: document.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>