Differences

This shows you the differences between two versions of the page.

--- zededa:zcli-how-to [2026/08/20 15:05] – created mc
+++ zededa:zcli-how-to [2026/08/20 15:11] (current) – mc
@@ Line 86: / Line 86: @@
 <code>
-zcli edge-node create MY_EDGE_NODE --project=MY_PROJECT
+zcli edge-node create MY_EDGE_NODE --project=MY_PROJECT --model=SYS-E100-9APP \
+  --network=eth0:management:MY_STATIC_NET:192.168.1.100:adapterLabel1
+</code>
+  - View it: ''zcli edge-node show MY_EDGE_NODE''
+  - Update it later: ''zcli edge-node update MY_EDGE_NODE --title=NEW_TITLE''
+===== Adapter-Specific Interface Config =====
+For anything beyond a single static IP, ZCLI uses a JSON template workflow instead of a giant flag list.
+  - Copy the templates: ''zcli edge-node copy-adapter-config-template''
+    * Drops ''adapter-net-config.json'' (the one you edit) plus ''.jsonc'' and ''.md'' reference copies, to ''/root/zcli/adapter-net-config-templates'' by default
+  - Edit the json file (vi works fine in the container: **i** to insert, **Esc** to stop, **:wq** to save)
+  - Use it when creating or updating a node:
+<code>
+zcli edge-node create MY_EDGE_NODE --project=MY_PROJECT --model=Advantech-2012 \
+  --adapter-network-config=adapter-net-config-templates/adapter-net-config.json
+</code>
+  - Pull an existing node's config back out for editing: ''zcli edge-node export-adapter-config MY_EDGE_NODE''
+===== Day 2 Operations =====
+^ Task ^ Command ^
+| Reboot | ''zcli edge-node reboot -f MY_EDGE_NODE'' |
+| Graceful shutdown prep | ''zcli edge-node prepare-poweroff MY_EDGE_NODE -f'' |
+| Deactivate (stops app instances) | ''zcli edge-node deactivate MY_EDGE_NODE'' |
+| Reactivate | ''zcli edge-node activate MY_EDGE_NODE'' |
+| Update EVE-OS image | ''zcli edge-node eveimage-update MY_EDGE_NODE -f'' |
+| Remove an old EVE-OS image | ''zcli edge-node eveimage-remove MY_EDGE_NODE --image=<image>'' |
+| Pull current config to a file | ''zcli edge-node get-config MY_EDGE_NODE'' |
+| Force a config regen from cloud | ''zcli edge-node gen-config MY_EDGE_NODE'' |
+| Pull TPM PCR values | ''zcli edge-node get-pcr MY_EDGE_NODE'' |
+| Delete | ''zcli edge-node delete MY_EDGE_NODE -f'' |
+''-f'' skips the confirmation prompt. Leave it off if you want the safety check.
+===== Output Format =====
+Default output is human-readable text. Force JSON for scripting with the global flag:
+<code>
+zcli -o json edge-node show MY_EDGE_NODE
+</code>
+===== 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 ====
+<code>
+cat ~/.ssh/id_rsa.pub
+</code>
+If that's empty, generate one first:
+<code>
+ssh-keygen -b 2048 -t rsa
+</code>
+==== Step 2: Push the Key to the Edge Node ====
+<code>
+zcli edge-node update EDGE_NODE --config=debug.enable.ssh:"YOUR_PUBLIC_KEY"
+</code>
+Or pull the key straight from the file instead of pasting it:
+<code>
+zcli edge-node update EDGE_NODE --config="debug.enable.ssh:$(cat ~/.ssh/id_rsa.pub)"
+</code>
+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 ====
+<code>
+ssh -i ~/.ssh/id_rsa root@<edge-node-ip>
+</code>
+==== Step 5: Disable SSH When You're Done ====
+<code>
+zcli edge-node update EDGE_NODE --config=debug.enable.ssh:""
+</code>
+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:
+<code>
+zcli edge-node update EDGE_NODE --config="KEY:VALUE"
+</code>
+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:
+<code>
+zcli edge-node enable-debug-knob EDGE_NODE [--expiry=<expiry>]
+zcli edge-node disable-debug-knob EDGE_NODE [--expiry=<expiry>]
+</code>
+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 ====
+<code>
+zcli volume-instance create MY-VOL-INST --volume-type=CONTENT_TREE --project=MY-PROJECT \
+  --edge-node=MY-EDGE-NODE --size=100 --access-mode=READWRITE
+</code>
+For an edge node cluster instead of a single node, swap ''--edge-node'' for ''--edge-node-cluster''.
+==== View It ====
+<code>
+zcli volume-instance show --edge-node=MY-EDGE-NODE
+</code>
+==== Update or Delete ====
+<code>
+zcli volume-instance update MY-VOL-INST --title=NEW-TITLE
+zcli volume-instance delete MY-VOL-INST -f
+</code>
+==== 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:...'' |
+===== Gotchas =====
+  * Most successful commands print nothing. Silence means it worked, only failures produce output.
+  * TLS verification is on by default. ''--no-verify'' / ''-k'' turns it off, only use this if you know why you need to.
+  * The GUI onboarding wizard does more behind the scenes (network + project wiring) than ''zcli edge-node create'' alone. If a node created via ZCLI looks half-configured, check whether you also need the ''zcli network'' and ''zcli project'' steps first.
+  * ''debug.enable.ssh'' and volume instances solve different problems. SSH knobs get you a shell on the node itself. Volume instances give an app storage. Don't reach for one when you mean the other.
+===== Source =====
+  * ZEDEDA Help Center: "ZEDEDA CLI Overview"
+  * ZEDEDA Help Center: "ZCLI: Create and Manage Edge Nodes"
+  * 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"