How to Use nydusctl for Managing Nydus Resources: Complete CLI and API Guide

nydusctl is a lightweight command-line interface that communicates with the nydusd daemon over Unix-domain sockets to query daemon status, modify runtime configuration, collect performance metrics, and manage filesystem mount operations.

nydusctl serves as the primary management interface for the Nydus container image acceleration framework in the dragonflyoss/nydus repository. This Rust-based CLI translates user-friendly sub-commands into HTTP-like API calls against the daemon's REST interface, providing direct access to nydusd internals without requiring custom HTTP clients. Whether debugging performance issues or automating container workflows, understanding how to use nydusctl effectively is essential for production Nydus deployments.

Architecture and Core Components

The nydusctl binary consists of three primary Rust modules that handle argument parsing, API communication, and command execution.

CLI Entry Point and Command Dispatch

In src/bin/nydusctl/main.rs, the application uses Clap to parse global flags and sub-commands. The dispatcher instantiates command structs from commands.rs based on user input, handling the --sock and --raw global options before executing the requested operation.

The HTTP Client Layer

The src/bin/nydusctl/client.rs module implements NydusdClient, a thin wrapper around hyper that constructs Unix-socket URIs targeting /api/* endpoints. All commands use NydusdClient::new(sock_path) to establish communication channels, supporting GET, PUT, POST, and DELETE operations via hyperlocal::Uri::new.

Command Implementations

Concrete business logic resides in src/bin/nydusctl/commands.rs, which implements:

• CommandDaemon – Daemon status and information queries
• CommandBackend – Storage backend metrics collection
• CommandCache – Cache performance statistics
• CommandFsStats – Filesystem-level metrics
• CommandMount – Filesystem mounting operations
• CommandUmount – Filesystem unmounting operations

Essential nydusctl Commands and Usage Patterns

The general invocation pattern requires specifying the daemon socket and optionally requesting raw JSON output:

nydusctl --sock <socket_path> [--raw] <subcommand> [options]

Connecting to the Daemon (--sock)

The --sock (or -S) parameter specifies the Unix-domain socket path where nydusd listens for API requests. While defaults vary by installation, system-wide daemons typically use /var/run/nydusd.sock. This path is passed to NydusdClient::new() in client.rs to establish the connection.

Querying Daemon State with info

The info sub-command queries the v1/daemon endpoint to retrieve version information, current state, and lists of mounted instances. Implemented in CommandDaemon within commands.rs, this command requires no additional arguments:

nydusctl -S /var/run/nydusd.sock info

Runtime Configuration with set

Use the set sub-command to adjust daemon parameters at runtime without restarting. Currently, this supports modifying the log-level through the CommandDaemon implementation:

nydusctl -S /var/run/nydusd.sock set log-level debug

Valid log levels include trace, debug, info, warn, and error.

Monitoring Performance with metrics

The metrics sub-command retrieves runtime statistics through three distinct categories implemented in separate command structs:

• backend (CommandBackend) – Storage backend latency and throughput metrics
• cache (CommandCache) – Prefetch statistics and cache hit rates
• fsstats (CommandFsStats) – Filesystem operation counters

For backend metrics, use the --interval (or -I) flag to enable periodic polling:

# Single query

nydusctl -S /var/run/nydusd.sock metrics cache

# Periodic backend monitoring every 5 seconds

nydusctl -S /var/run/nydusd.sock metrics backend -I 5

Managing Filesystems with mount and umount

The mount sub-command creates new Nydus filesystem instances by posting configuration to the daemon API:

nydusctl -S /var/run/nydusd.sock mount \
    --source registry:docker.io/library/busybox:latest \
    --config /etc/nydus/rafs.json \
    --mountpoint /mnt/rafs \
    --type rafs

Key parameters include:

• --source (or -s) – Backend source URI (e.g., registry:, oss:)
• --config (or -c) – JSON configuration file path for the backend
• --mountpoint (or -m) – Target directory for the mount
• --type (or -t) – Filesystem type: rafs (Registry Accelerated File System) or passthrough_fs

To remove a filesystem, use umount with the mountpoint:

nydusctl -S /var/run/nydusd.sock umount --mountpoint /mnt/rafs

Practical Workflow Examples

A typical management session combines multiple nydusctl operations to verify daemon health, adjust logging, monitor performance, and manage workloads:

# Verify daemon responsiveness

nydusctl -S /var/run/nydusd.sock info

# Enable verbose logging for debugging

nydusctl -S /var/run/nydusd.sock set log-level trace

# Monitor cache performance during workload

nydusctl -S /var/run/nydusd.sock metrics cache

# Mount a production image

nydusctl -S /var/run/nydusd.sock mount \
    -s registry:myimage:latest \
    -c /etc/nydus/rafs-config.json \
    -m /mnt/nydus \
    -t rafs

# Poll backend bandwidth every 3 seconds

nydusctl -S /var/run/nydusd.sock metrics backend -I 3

# Cleanup after workload completion

nydusctl -S /var/run/nydusd.sock umount -m /mnt/nydus

Programmatic Integration with NydusdClient

For automation beyond shell scripts, import nydusctl as a library to interact with the daemon directly from Rust:

use nydusctl::client::NydusdClient;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize client with socket path
    let client = NydusdClient::new("/var/run/nydusd.sock");
    
    // Query daemon information via v1/daemon endpoint
    let info = client.get("v1/daemon").await?;
    println!("Daemon state: {}", info["state"]);
    
    Ok(())
}

This approach leverages the same client.rs implementation used by the CLI, ensuring consistent API behavior.

Shell Script Automation

Integrate nydusctl into bash workflows for health checks and conditional logic:

#!/usr/bin/env bash
SOCK="/var/run/nydusd.sock"

# Enable debug logging

nydusctl -S "$SOCK" set log-level debug

# Wait for daemon to reach Running state

while true; do
    STATE=$(nydusctl -S "$SOCK" info --raw | grep -o '"state":"[^"]*"' | cut -d'"' -f4)
    if [[ "$STATE" == "Running" ]]; then
        break
    fi
    sleep 1
done
echo "Nydusd is ready for mount operations"

Summary

• nydusctl communicates with nydusd via Unix-domain sockets specified by --sock, defaulting to paths like /var/run/nydusd.sock.
• Five primary sub-commands manage the daemon lifecycle: info (status), set (configuration), metrics (monitoring), mount (filesystem creation), and umount (filesystem removal).
• Raw JSON output is available via the --raw flag, while default output provides human-readable tables formatted in commands.rs.
• Three metrics categories (backend, cache, fsstats) expose performance data, with backend metrics supporting interval-based polling via -I.
• Programmatic access is possible through the NydusdClient struct in src/bin/nydusctl/client.rs, which handles HTTP-like requests over Unix sockets using hyper.

Frequently Asked Questions

What socket path does nydusctl use by default?

While nydusctl requires explicit socket paths via --sock or -S, system-wide nydusd installations typically create /var/run/nydusd.sock. Containerized deployments may use alternative paths like /nydus/api.sock depending on volume mounts. Always verify the socket path matches your nydusd startup configuration.

How do I view raw JSON output instead of formatted tables?

Append the --raw flag to any command to display the unprocessed JSON response from the daemon API. This bypasses the formatting logic in commands.rs and outputs the exact serde_json::Value returned by endpoints like v1/daemon or the metrics API.

Can nydusctl manage multiple daemon instances simultaneously?

Yes, by specifying different socket paths with --sock for each command invocation. Each nydusctl execution creates an independent NydusdClient connection, allowing you to query or configure multiple nydusd processes running on different sockets from the same host.

What metrics categories are available in nydusctl?

The metrics sub-command accepts three category arguments implemented in commands.rs: backend (storage I/O latency and bandwidth), cache (prefetch statistics and hit ratios), and fsstats (filesystem operation counters). Only the backend category supports the --interval flag for continuous polling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}