Skip to main content

serve_nbd

hexz_server

Function serve_nbd 

Source 
pub async fn serve_nbd(snap: Arc<File>, port: u16) -> Result<()>
Expand description

Exposes a File over NBD (Network Block Device) protocol.

Starts a TCP listener on 127.0.0.1:<port> that implements the NBD protocol, allowing Linux clients to mount the Hexz snapshot as a local block device using standard tools like nbd-client.

This function runs indefinitely, accepting connections in a loop. Each client connection is handled in a separate Tokio task, allowing concurrent clients.

§Arguments

  • snap: The Hexz snapshot file to expose. Must be wrapped in Arc for sharing across multiple client connections.
  • port: TCP port to bind to on the loopback interface (e.g., 10809).

§Returns

This function never returns under normal operation (it runs forever). It only returns Err if:

  • The TCP listener fails to bind (port already in use, permission denied)
  • An unrecoverable I/O error occurs on the listener socket

Individual client errors (malformed requests, disconnects) are logged but do not stop the server.

§Errors

  • std::io::Error: If binding to the socket fails or the listener encounters a fatal error.

§Examples

use std::sync::Arc;
use hexz_core::File;
use hexz_core::store::local::FileBackend;
use hexz_core::algo::compression::lz4::Lz4Compressor;
use hexz_server::serve_nbd;

let backend = Arc::new(FileBackend::new("vm_snapshot.hxz".as_ref())?);
let compressor = Box::new(Lz4Compressor::new());
let snap = File::new(backend, compressor, None)?;

// Start NBD server (runs forever)
serve_nbd(snap, 10809).await?;

§Client-Side Usage (Linux)

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

# Mount the block device (read-only, automatically detected filesystem)
sudo mount -o ro /dev/nbd0 /mnt/snapshot

# Browse files normally
ls -la /mnt/snapshot
sudo cat /mnt/snapshot/var/log/syslog

# Unmount and disconnect
sudo umount /mnt/snapshot
sudo nbd-client -d /dev/nbd0

§Security Considerations

§No Encryption

The NBD protocol transmits data in plaintext. For localhost connections this is acceptable, but for remote access consider:

  • SSH tunnel: ssh -L 10809:localhost:10809 user@server
  • VPN: WireGuard, OpenVPN, etc.
  • TLS wrapper: stunnel or similar

§No Authentication

Any process with network access to the port can connect. The default loopback binding mitigates this, but if exposing to the network, use firewall rules or SSH key authentication.

§Read-Only Enforcement

The NBD server always exports snapshots as read-only (NBD flag NBD_FLAG_READ_ONLY). Write attempts return EPERM (operation not permitted). However, a malicious NBD client could theoretically attempt to crash the server via protocol abuse.

§Performance Notes

  • Concurrency: Each client spawns a separate Tokio task. With 100 concurrent clients, memory overhead is ~10 MB (100 KB per task).
  • Throughput: Typically 500-1000 MB/s for sequential reads, limited by decompression rather than NBD protocol overhead.
  • Latency: ~2-10 ms per read, including TCP round-trip and decompression.

§Panics

This function does not panic under normal operation. Client errors are logged and handled gracefully.