libxl2tp - xl2tpd Client API Library

A C library providing an API for controlling xl2tpd L2TP tunnels.

Read this in other languages: English, 中文.

Overview

libxl2tp is a client library that provides a simple C API for managing xl2tpd L2TP connections. It allows applications to programmatically control L2TP tunnels without needing to directly interact with xl2tpd configuration files or control interfaces.

Features

• Simple C API for L2TP tunnel management
• Support for LAC (L2TP Access Concentrator) and LNS (L2TP Network Server) modes
• Complete tunnel lifecycle management (create, connect, disconnect, delete)
• Service status query and health checking
• Flexible configuration options
• Comprehensive error handling and status feedback
• Support for both static and shared library builds
• Symbol visibility control for stable ABI

Building

Prerequisites

• C compiler (GCC, Clang)
• CMake 3.10 or later, or Autotools
• xl2tpd daemon (runtime dependency)

Using CMake

# Create build directory
mkdir build && cd build

# Basic configuration
cmake ..

# Configure with options
cmake -DBUILD_TESTS=ON -DENABLE_DEBUG=ON -DBUILD_SHARED_LIBS=ON ..

# Build
make

# Run tests (if enabled)
make test

# Install
sudo make install

Using Autotools

# Generate configure script
./autogen.sh

# Configure
./configure --enable-tests --enable-debug

# Build
make

# Run tests
make check

# Install
sudo make install

Build Options

CMake Options

• BUILD_SHARED_LIBS: Build shared library (default: ON)
• ENABLE_STATIC: Build static library (default: OFF)
• BUILD_TESTS: Build test programs (default: OFF)
• ENABLE_DEBUG: Enable debug output (default: OFF)

Autotools Options

• --enable-shared: Build shared library (default: yes)
• --enable-static: Build static library (default: yes)
• --enable-tests: Build test programs (default: no)
• --enable-debug: Enable debug output (default: no)

API Usage

Basic Example

#include <libxl2tp.h>
#include <stdio.h>

int main() {
    l2tp_config_t config = {
        .interface = "test0",
        .server = "192.168.1.1", 
        .username = "user",
        .password = "password"
    };
    
    char result[1024];
    int ret;
    
    // Start xl2tpd service
    ret = xl2tpd_start();
    if (ret != XL2TPD_SUCCESS) {
        printf("Failed to start service: %s\n", xl2tpd_strerror(ret));
        return 1;
    }
    
    // Add LAC tunnel
    ret = xl2tpd_add_lac_full(&config, result, sizeof(result));
    if (ret != XL2TPD_SUCCESS) {
        printf("Failed to add tunnel: %s\n", xl2tpd_strerror(ret));
        return 1;
    }
    
    // Connect tunnel
    ret = xl2tpd_connect_lac_config(&config, result, sizeof(result));
    if (ret != XL2TPD_SUCCESS) {
        printf("Failed to connect: %s\n", xl2tpd_strerror(ret));
        return 1;
    }
    
    printf("Connected successfully!\n");
    
    // Query status
    ret = xl2tpd_status_lac(config.interface, result, sizeof(result));
    if (ret == XL2TPD_SUCCESS) {
        printf("Tunnel status: %s\n", result);
    }
    
    return 0;
}

Compilation

# Using pkg-config
gcc -o myapp myapp.c $(pkg-config --cflags --libs libxl2tp)

# Manual linking
gcc -o myapp myapp.c -lxl2tp

API Reference

Service Management

• xl2tpd_start() - Start xl2tpd service
• xl2tpd_stop() - Stop xl2tpd service
• xl2tpd_check_available() - Check service availability

LAC Tunnel Management

• xl2tpd_add_lac_full() - Add and configure LAC tunnel
• xl2tpd_connect_lac_config() - Connect LAC tunnel
• xl2tpd_disconnect_lac() - Disconnect LAC tunnel
• xl2tpd_status_lac() - Query LAC status
• xl2tpd_remove_lac() - Remove LAC tunnel

LNS Tunnel Management

• xl2tpd_add_lns() - Add LNS tunnel
• xl2tpd_status_lns() - Query LNS status
• xl2tpd_remove_lns() - Remove LNS tunnel

Configuration and Utilities

• l2tp_config_t - L2TP configuration structure
• xl2tpd_strerror() - Get error description
• xl2tpd_set_log_level() - Set log level

Error Codes

• XL2TPD_SUCCESS - Success
• XL2TPD_ERROR_INVALID_PARAM - Invalid parameter
• XL2TPD_ERROR_SERVICE_NOT_RUNNING - Service not running
• XL2TPD_ERROR_PIPE - Pipe communication error
• XL2TPD_ERROR_TIMEOUT - Operation timeout
• See libxl2tp.h for more error codes

Testing

The project includes a comprehensive test program:

# Build with tests enabled
cmake -DBUILD_TESTS=ON ..
make

# Run tests
make test

# Or run directly
./test_libxl2tp

The test program test_libxl2tp provides an interactive menu to test all API functions.

Configuration Example

l2tp_config_t config = {
    // Basic configuration
    .interface = "vpn0",
    .server = "vpn.example.com",
    .username = "myuser",
    .password = "mypass",
    
    // Advanced configuration
    .mtu = 1460,
    .keepalive_enabled = 1,
    .keepalive_interval = 30,
    .redial_enabled = 1,
    .redial_timeout = 30,
    .max_redials = 5,
    
    // Network configuration
    .local_ip = "192.168.1.100",
    .remote_ip = "192.168.1.1",
    
    // Authentication configuration
    .require_chap = 1,
    .ppp_dynamic_auth = 1
};

Dependencies

Runtime Dependencies

• xl2tpd daemon
• Standard C library
• PPP daemon (pppd)

Build Dependencies

• CMake 3.10+ or Autotools
• C compiler (C99 support)
• pkg-config (recommended)

Platform Support

• Linux (primary platform)
• Unix-like systems

Project Structure

xl2tp_api/
├── libxl2tp.h          # Main header file
├── libxl2tp.c          # Main implementation
├── libxl2tp.map        # Symbol export control
├── test/
│   └── test_libxl2tp.c # Test program
├── CMakeLists.txt      # CMake build file
├── Makefile.am         # Autotools build file
├── configure.ac        # Autotools configuration
└── README.md           # This document

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Support

For bug reports and feature requests, please use the GitHub issue tracker.

Changelog

Version 1.0.0

• Initial release
• Complete L2TP tunnel management API
• Support for LAC and LNS modes
• CMake and Autotools build systems
• Interactive test program
• Comprehensive error handling and status feedback