Crate openvpn_mgmt_codec 

openvpn-mgmt-codec

A Rust tokio_util::codec for the OpenVPN management interface protocol. It gives you fully typed, escape-aware command encoding and stateful response decoding so you can talk to an OpenVPN daemon over TCP or a Unix socket without hand-rolling string parsing.

Features

• Type-safe commands – every management-interface command is a variant of OvpnCommand; the compiler prevents malformed protocol strings.
• Stateful decoder – tracks which command was sent so it can disambiguate single-line replies, multi-line blocks, and real-time notifications (even when they arrive interleaved).
• Automatic escaping – backslashes and double-quotes are escaped following the OpenVPN config-file lexer rules.
• Full protocol coverage – 44 commands including auth, signals, client management, PKCS#11, external keys, proxy/remote overrides, and a Raw escape hatch for anything new.

Quick start

Add the crate to your project:

[dependencies]
openvpn-mgmt-codec = "0.3"
tokio = { version = "1", features = ["full"] }
tokio-util = { version = "0.7", features = ["codec"] }

Then wrap a TCP stream with the codec:

use tokio::net::TcpStream;
use tokio_util::codec::Framed;
use futures::{SinkExt, StreamExt};
use openvpn_mgmt_codec::{OvpnCodec, OvpnCommand, OvpnMessage, StatusFormat};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let stream = TcpStream::connect("127.0.0.1:7505").await?;
    let mut framed = Framed::new(stream, OvpnCodec::new());

    // ask for status
    framed.send(OvpnCommand::Status(StatusFormat::V3)).await?;

    // read responses
    while let Some(msg) = framed.next().await {
        match msg? {
            OvpnMessage::Success(text)     => println!("OK: {text}"),
            OvpnMessage::Error(text)       => eprintln!("ERR: {text}"),
            OvpnMessage::MultiLine(lines)  => {
                for line in &lines {
                    println!("  {line}");
                }
            }
            OvpnMessage::Notification(n)   => println!("event: {n:?}"),
            other                          => println!("{other:?}"),
        }
    }

    Ok(())
}

How it works

OvpnCodec implements Encoder<OvpnCommand> and Decoder (Item = OvpnMessage).

Direction	Type	Description
Encode	OvpnCommand	One of 44 command variants – serialised to the wire format with proper escaping and multi-line framing.
Decode	OvpnMessage	Success, Error, SingleValue, MultiLine, Notification, Info, or Unrecognized.

Real-time notifications (>STATE:, >BYTECOUNT:, >CLIENT:, etc.) are emitted as OvpnMessage::Notification and can arrive at any time, including in the middle of a multi-line response block. The codec handles this transparently.

Re-exports

pub use auth::AuthRetryMode;

pub use auth::AuthType;

pub use client_event::ClientEvent;

pub use codec::AccumulationLimit;

pub use codec::EncodeError;

pub use codec::EncoderMode;

pub use codec::OvpnCodec;

pub use command::OvpnCommand;

pub use kill_target::KillTarget;

pub use log_level::LogLevel;

pub use message::Notification;

pub use message::OvpnMessage;

pub use message::PasswordNotification;

pub use need_ok::NeedOkResponse;

pub use openvpn_state::OpenVpnState;

pub use proxy_action::ProxyAction;

pub use redacted::Redacted;

pub use remote_action::RemoteAction;

pub use signal::Signal;

pub use status_format::StatusFormat;

pub use stream_mode::StreamMode;

pub use transport_protocol::TransportProtocol;

pub use unrecognized::UnrecognizedKind;

pub use version_info::VersionInfo;

Modules

auth

Authentication credential types and retry strategies.

client_event

Client notification event types (CONNECT, REAUTH, etc.).

codec

The OvpnCodec encoder/decoder implementation.

command

Typed management-interface commands (OvpnCommand).

kill_target

Client kill-target addressing.

log_level

Log severity levels (Info, Debug, Warning, etc.).

message

Decoded messages and real-time notifications.

need_ok

Responses to >NEED-OK: prompts.

openvpn_state

OpenVPN connection states (CONNECTING, CONNECTED, etc.).

parsed_response

Typed parsers for SUCCESS: payloads and multi-line responses. Typed parsers for SUCCESS: payloads and multi-line responses.

proxy_action

Proxy configuration for >PROXY: responses.

redacted

A wrapper type that masks sensitive values in debug/display output. A wrapper type that masks sensitive values in Debug and [Display] output to prevent accidental exposure in logs.

remote_action

Remote-override actions for >REMOTE: responses.

signal

Daemon signals (HUP, TERM, USR1, USR2).

status_format

Status output format versions (V1/V2/V3).

stream

Stream adapter categorizing messages as responses or notifications. Helpers for categorizing OvpnMessages into responses and notifications.

stream_mode

Stream mode selectors (on/off/all/recent).

transport_protocol

Transport protocol (UDP, TCP) for remote/proxy notifications.

unrecognized

Error classification for unrecognized protocol lines.

version_info

Parsed version information from the version command.