Project

General

Profile

vici Plugin

Purpose

The vici [ˈvitʃi] plugin provides VICI, the Versatile IKE Configuration Interface. As its name indicates, it provides an interface for external applications to not only configure, but also to control and monitor the IKE daemon charon.

strongSwan is often used to provide IKE service functionality in a tailored system for specific needs. Developers of such systems often have a need to automate configuration and control of the IKE daemon. For this purpose, external components require to interact with the strongSwan infrastructure without human intervention.

The existing starter, ipsec.conf and stroke interfaces have never been designed to get automated. Scripting these tools is difficult, returning information cumbersome. While libcharon and libstrongswan are reusable, extendable and have have very powerful plugin APIs, writing and maintaining strongSwan code is non-trivial.

VICI is an attempt to improve the situation for system integrators by providing a stable IPC interface, allowing external tools to query, configure and control the IKE daemon.

The most prominent user of the VICI interface is swanctl, a command line application to configure and control charon. It is the driving force to develop, extend and maintain the VICI interface, and currently provides almost all functionality to run strongSwan installations without the need for ipsec.conf and friends.

The plugin is enabled by default but may be disabled by adding

--disable-vici
to the ./configure options.

The plugin has been introduced in strongSwan 5.2.0, it is enabled by default since 5.4.0.

Configuration

The plugin is configured using the following strongswan.conf options:

Key Default Description
charon.plugins.vici.socket unix:///var/run/charon.vici URI the plugin listens for client connections

On Windows, the default URL is tcp://127.0.0.1:4502.

Protocol details

The VICI protocol runs over a reliable transport protocol. As the protocol itself currently does not provide any security or authentication properties, it is recommended to run it over a UNIX socket with appropriate permissions.

A low-level VICI protocol description is available in the README.md in the vici plugin sources folder. A higher level protocol description (commands, events) will follow.

Writing clients

For the client side, any programming language may be used to communicate to the daemon using the vici protocol. Currently strongSwan comes with VICI client libraries for C, Perl, Python and Ruby. The available operations and some simple examples using the libvici C interface, the Python Egg, Perl CPAN module and Ruby gem and can be found in README.md.

libvici C bindings

libvici provides a stable low-level C API to exchange messages using the VICI protocol. While it depends on libstrongswan, it uses a stable, coding-style neutral API and should work for many applications.

The libvici API is documented in the source:src/libcharon/plugins/vici/libvici.h header.

davici C library

The davici project provides an alternative C client implementation of the VICI protocol. In contrast to libvici, it does not build upon the libstrongswan library, is designed for asynchronous operation and is LGPLv2+ licensed. It is usually a more suitable choice when integrating VICI client functionality into an application.

Ruby gem

With 5.2.1 a Ruby gem has been added to allow Ruby applications to control and monitor the IKE daemon.

Python egg

Starting with 5.3.0, strongSwan ships a Python egg for the very same purpose. It may also be installed via PyPI.

Perl CPAN module

Starting with 5.4.0, strongSwan contains a Perl CPAN module as a client-side wrapper around the VICI protocol.