Virtual HSM
Home
  • Virtual HSM
  • Documentation
    • What is Virtual HSM?
    • Use Case: Attested Secret Provisioning in the Cloud
    • Setup
      • Install
      • vHSM Server Configuration
        • Parameters
        • vHSM Telemetry Parameters
      • vHSM Agent
        • Agent Configuration
      • vHSM Proxy
        • Proxy Configuration
    • Get Started
      • Start the Vault server
      • MariaDB root admin password provisioning on Azure DCXas_v5 VM
    • Supported Cloud Configurations
  • Tutorials
    • Deploying the vhsm Container on an EC2 Instance
    • CLI quickstart
    • vHSM Agent quickstart
    • vHSM Proxy quickstart
    • Passing vHSM secrets using ConfigMaps
    • Provisioning MariaDB Password on Azure DCXas_v5 VM
    • Registering a buckypaper plugin
    • Monitoring vHSM with Grafana
  • Integration with Utimaco SecurityServer
    • Integrate enclaive vHSM with Utimaco HSM
  • API
    • Auth
    • Default
    • Secrets
    • System
    • Identity
    • Models
  • vHSM CLI
    • Server and Infrastructure Management
      • vhsm server
      • vhsm proxy
      • vhsm monitor
      • vhsm status
      • vhsm agent
    • Secret Management
      • vhsm read
      • vhsm write
      • vhsm delete
      • vhsm list
      • vhsm secrets
        • vhsm secrets enable
        • vhsm secrets disable
        • vhsm secrets list
        • vhsm secrets move
        • vhsm secrets tune
      • vhsm unwrap
    • Configuration and Management
      • vhsm plugin
        • vhsm plugin info
        • vhsm plugin deregister
        • vhsm plugin list
        • vhsm plugin register
        • vhsm plugin reload
        • vhsm plugin reload-status
      • vhsm namespace
      • vhsm operator
      • vhsm print
      • vhsm path-help
      • vhsm lease
    • Auditing and Debugging
      • vhsm audit
      • vhsm debug
    • Attestation
    • Security and Encryption
      • vhsm pki
        • vhsm pki health-check
        • vhsm pki issue
        • vhsm pki list-intermediates
        • vhsm pki reissue
        • vhsm pki verify-sign
      • vhsm transit
      • vhsm ssh
      • vhsm transform
    • Authentication and Authorization
      • vhsm login
      • vhsm auth
      • vhsm token
      • vhsm policy
    • Storage and Data Mangement
      • vhsm kv
      • vhsm patch
    • vhsm version
      • vhsm version-history
  • Troubleshooting
    • CA Validity Period
    • CRL Validity Period
    • Root Certificate Issued Non-CA Leaves
    • Role Allows Implicit Localhost Issuance
    • Role Allows Glob-Based Wildcard Issuance
    • Performance Impact
    • Accessibility of Audit Information
    • Allow If-Modified-Since Requests
    • Auto-Tidy Disabled
    • Tidy Hasn't Run
    • Too Many Certificates
    • Enable ACME Issuance
    • ACME Response Headers Configuration
  • Resources
    • Community
    • GitHub
    • Youtube
    • CCx101 wiki
Powered by GitBook
On this page
  • Permissions
  • Examples
  • Output
  • Command Options
  • Capture Targets
  • Output Layout

Was this helpful?

  1. vHSM CLI
  2. Auditing and Debugging

vhsm debug

Learn to debug vHSM server by starting a process that collects and probes information for a specific duration.

The debug command starts a process that monitors a vHSM server, collecting and probing information for a specified duration. This helps operators retrieve and share consistent diagnostic information about the server state.

Note: The command honors the same authentication variables as the base command, including the token stored from a previous login or the environment variables VAULT_TOKEN and VAULT_ADDR. The permissions granted by the token determine the extent of information collected.

If the command is interrupted, the collected data is persisted to an output directory.


Permissions

The ability to fetch debug data depends on the provided token. Some targets, such as server-status, query unauthenticated endpoints, while others require ACL permissions.

Required Policy for Full Debugging

path "auth/token/lookup-self" {
  capabilities = ["read"]
}

path "sys/pprof/*" {
  capabilities = ["read"]
}

path "sys/config/state/sanitized" {
  capabilities = ["read"]
}

path "sys/monitor" {
  capabilities = ["read"]
}

path "sys/host-info" {
  capabilities = ["read"]
}

path "sys/in-flight-req" {
  capabilities = ["read"]
}

Examples

Start debug with default settings:

vhsm debug

Run debug for 1 minute, with custom intervals and no compression:

vhsm debug -duration=1m -interval=10s -metrics-interval=5s -compress=false

Capture only specific targets:

vhsm debug -target=host -target=metrics

Output

Finished capturing information, bundling files...
Success! Bundle written to: vault-debug-2025-03-04T08-28-46Z.tar.gz

Command Options

Flag

Type

Default Value

Description

-compress

bool

true

Toggles compression of the output package.

-duration

int or string

2m

Duration for which the command runs.

-interval

int or string

30s

Interval for collecting profiling data and server state.

-log-format

string

standard

Log format for log target (standard or json).

-metrics-interval

int or string

10s

Interval for collecting metrics data.

-output

string

Auto-generated filename

Specifies output path for the debug package.

-target

string

all targets

Specifies targets to capture (can be used multiple times).

Capture Targets

The -target flag can be used multiple times to specify which information to capture. By default, all available targets are collected.

Target
Description

config

Sanitized version of the configuration state.

host

Information about the server instance, including CPU, memory, and disk.

metrics

Telemetry information.

pprof

Runtime profiling data, including heap, CPU, goroutine, and trace profiling.

replication-status

Replication status.

server-status

Health and seal status.

Note:

  • The config, host, metrics, and pprof targets are only queried on active and performance standby nodes.

  • The host target is unavailable on OpenBSD due to system library limitations.

Output Layout

The collected data is stored in a structured directory format. Profiling data is captured at each interval in separate files, while other targets store data as JSON arrays.

Example Directory Structure

vault-debug-2025-03-04T21-44-49Z/
├── 2025-03-04T21-44-49Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── 2025-03-04T21-45-19Z
│   ├── goroutine.prof
│   ├── heap.prof
│   ├── profile.prof
│   └── trace.out
├── config.json
├── host_info.json
├── index.json
├── metrics.json
├── replication_status.json
├── server_status.json
Previousvhsm auditNextAttestation

Last updated 2 months ago

Was this helpful?