Skip to main content

Module nbd

hexz_server

Module nbd 

Source
Expand description

Network Block Device (NBD) protocol server implementation.

This module implements the NBD protocol (version 3.0+, fixed newstyle negotiation) to expose Hexz snapshots as block devices over TCP. Clients can mount the snapshot using standard NBD client tools like nbd-client (Linux) or connect directly via the NBD protocol.

§Protocol Overview

The NBD protocol consists of three phases:

  1. Handshake: Server announces capabilities (flags) and magic values
  2. Option Negotiation: Client requests export info and flags
  3. Transmission: Client sends read/write/flush/trim commands

This implementation follows the “fixed newstyle” negotiation introduced in NBD 3.0, which is more robust than the legacy “oldstyle” protocol.

§Protocol Reference

§Security Considerations

  • Read-only mode: This implementation always exports snapshots as read-only to prevent accidental modification
  • No encryption: The NBD protocol does not include built-in encryption. For secure access over untrusted networks, use an SSH tunnel or VPN.
  • No authentication: NBD does not provide authentication. Access control must be implemented at the network level (firewall, localhost-only binding).

§Performance Characteristics

  • Throughput: Typically limited by snapshot decompression (~500-2000 MB/s) rather than network bandwidth for local connections
  • Latency: Read latency includes network RTT + decompression time (~1-5 ms total)
  • Concurrency: Each client connection is handled by a separate Tokio task

§Example Usage

// Server-side (in hexz-server)
let listener = TcpListener::bind("127.0.0.1:10809").await?;
// ... load snapshot into Arc<File> ...

loop {
    let (socket, _) = listener.accept().await?;
    let snap = snap.clone();
    tokio::spawn(async move {
        if let Err(e) = handle_client(socket, snap).await {
            eprintln!("NBD client error: {}", e);
        }
    });
}

§Client-Side Usage (Linux)

# Connect NBD client to server
sudo nbd-client localhost 10809 /dev/nbd0

# Mount the block device
sudo mount -o ro /dev/nbd0 /mnt/snapshot

# Disconnect when done
sudo nbd-client -d /dev/nbd0

Functions§

handle_client
Handle a single NBD client connection.