This is an old revision of the document!

ZCLI: SSH Access, Debug Knobs, and Volume Instances

SSH Into an Edge Node via ZCLI

SSH access to EVE-OS is off by default. You turn it on by pushing your public key to the node's debug.enable.ssh property through ZCLI. This was originally meant for EVE developer debugging, not production use, keep that in mind before leaving it on.

Step 1: Get Your Public Key

cat ~/.ssh/id_rsa.pub

If that's empty, generate one first:

ssh-keygen -b 2048 -t rsa

Step 2: Push the Key to the Edge Node

zcli edge-node update EDGE_NODE --config=debug.enable.ssh:"YOUR_PUBLIC_KEY"

Or pull the key straight from the file instead of pasting it:

zcli edge-node update EDGE_NODE --config="debug.enable.ssh:$(cat ~/.ssh/id_rsa.pub)"

Note: this survives until you clear it, but if you re-onboard or re-image the device, the key gets wiped and you'll need to push it again.

Step 3: Find the Node's IP

Pull it from zcli edge-node show EDGE_NODE –detail, or from the GUI's device status page.

Step 4: SSH In

ssh -i ~/.ssh/id_rsa root@<edge-node-ip>

Step 5: Disable SSH When You're Done

zcli edge-node update EDGE_NODE --config=debug.enable.ssh:""

An empty string clears every authorized key. Verify it actually cleared before you walk away from the box.

Alternative: Edge View Instead of SSH

ZEDEDA recommends Edge View over raw SSH for production environments. It adds policy control at the node/project/enterprise level, session time limits, and audit logs, things plain SSH doesn't give you. Worth using instead of SSH unless you specifically need a raw shell.

Debug and Troubleshooting Knobs

Same –config pattern used for SSH above:

zcli edge-node update EDGE_NODE --config="KEY:VALUE"

Changes sync on the node's next config check (default every 60 seconds, tunable via timer.config.interval).

Knob	Type	Default	What it does
debug.enable.ssh	SSH pubkey string	“”	Allows SSH when a key is set; empty disables it
debug.enable.usb	boolean	false	Allows USB devices (keyboards, etc.) on the node
debug.enable.vga	boolean	false	Allows VGA console output
debug.enable.console	boolean	false	Allows console access to EVE-OS; needs a reboot to turn back off
debug.enable.vnc.shim.vm	boolean	false	Allows VNC into the container app shim VM; needs a reboot to turn back off

A separate, unrelated command turns on raw metrics collection rather than a –config property:

zcli edge-node enable-debug-knob EDGE_NODE [--expiry=<expiry>]
zcli edge-node disable-debug-knob EDGE_NODE [--expiry=<expiry>]

That one is specifically for storing raw metrics on the device, don't confuse it with the debug.enable.* config properties above.

Storage-Related Knobs (Same --config Pattern)

Knob	Type	Default	What it does
storage.dom0.disk.minusage.percent	integer	20	Minimum percent of the persist partition reserved for the EVE-OS base system
storage.zfs.reserved.percent	integer	20	Minimum percent of the persist partition reserved for ZFS
storage.apps.ignore.disk.check	boolean	false	Lets edge containers create images larger than available disk space, can cause out-of-disk errors, use carefully
timer.gc.vdisk	seconds	3600	How often EVE-OS garbage collects unused container virtual disks
timer.defer.content.delete	seconds	0	Keeps deleted content trees around for reuse for this long; 0 deletes immediately

Mapping a Local Volume to an Edge Node

This is a different thing from the knobs above. A volume instance is persistent or scratch storage you attach to an app running on a specific edge node, not a debug switch.

Create It

zcli volume-instance create MY-VOL-INST --volume-type=CONTENT_TREE --project=MY-PROJECT \
  --edge-node=MY-EDGE-NODE --size=100 --access-mode=READWRITE

For an edge node cluster instead of a single node, swap –edge-node for –edge-node-cluster.

View It

zcli volume-instance show --edge-node=MY-EDGE-NODE

Update or Delete

zcli volume-instance update MY-VOL-INST --title=NEW-TITLE
zcli volume-instance delete MY-VOL-INST -f

Persistent vs. Perishable

Volume instances are created the same way regardless. What decides persistence is the Purge setting on the edge app that consumes the volume: leave Purge unchecked and the volume survives app updates and restarts. Check it, and the volume gets wiped on purge/update.

One catch: a persistent volume instance belongs to the specific edge node it was created on. Same behavior on multiple nodes means a separate volume instance per node, it doesn't automatically replicate.

Quick Reference: Which Tool for Which Job

Goal	Tool
Get a shell on the node	`zcli edge-node update … –config=debug.enable.ssh:…`
Turn on/off USB, VGA, console, VNC shim access	`zcli edge-node update … –config=debug.enable.X:…`
Turn on raw metrics storage	`zcli edge-node enable-debug-knob`
Give an app persistent or scratch disk space	`zcli volume-instance create`
Change storage allocation thresholds device-wide	`zcli edge-node update … –config=storage.X:…`

Source

ZEDEDA Help Center: “How to Enable and Disable SSH for Edge Nodes”
ZEDEDA Help Center: “Update Edge Node Configuration Properties”
ZEDEDA Help Center: “ZCLI: Create and Manage Volume Instances”
ZEDEDA Help Center: “Add Persistent Volume Instances”
ZEDEDA Help Center: “ZCLI: Create and Manage Edge Nodes”

ZEDEDA WiKi

Table of Contents