ZEDEDA WiKi

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Using ZCLI ======

A practical guide to ZEDEDA CLI (ZCLI), the command-line way to manage ZEDEDA Cloud.

===== What ZCLI Is =====

  * ZCLI is one of three ways to talk to ZEDEDA Cloud. The other two are the GUI and the API.
  * It ships as a Docker container, not a native binary.
  * You need Docker Desktop running before you start it.

===== Starting ZCLI =====

<code>
docker run -it zededa/zcli:latest
</code>

First run pulls the image from ZEDEDA's registry, so it takes a moment. After that you're dropped into a ''zcli>'' prompt.

===== Logging In =====

Two ways to authenticate: username/password, or a session token.

==== Option 1: Username and Password ====

  - Run ''zcli configure''
  - Enter the server address (default is ''zedcontrol.zededa.net'')
  - Answer **n** to "Login with token?"
  - Enter your username and password
  - Run ''zcli login''

==== Option 2: Session Token ====

  - Log in to the ZEDEDA GUI
  - Open your user profile dropdown, top right, then **User Details**
  - Copy the session token from the Session Information section
  - Run ''zcli configure''
  - Enter the server address
  - Answer **y** to "Login with token?"
  - Paste the token
  - Run ''zcli login''

===== Reading the Command Syntax =====

  * ''<name>'' is a value you supply
  * ''[--title=<title>]'' is optional
  * ''[--clear-text=<true|false>]'' means pick one of the listed choices

If you leave out something required, ZCLI tells you plainly, e.g. ''Missing required option --dstype.''

===== Getting Help =====

  * ''zcli'' by itself lists every command group.
  * ''zcli <command> --help'' shows syntax for that command.
  * ''man zcli-<command>'' opens the full manual page (press **q** to exit).

^ Key ^ Action ^
| Space / Page Down | scroll down a page |
| b / Page Up | scroll up a page |
| j / Down Arrow | scroll down a line |
| k / Up Arrow | scroll up a line |
| / then text | search forward |

===== Command Groups You'll Actually Use =====

^ Command ^ What it manages ^
| edge-node | Create, update, activate, reboot, delete edge nodes |
| project | Resource groups that edge nodes and apps live in |
| network | Networking objects assigned to edge node adapters |
| network-instance | App-facing networking within an edge node |
| edge-app | Application manifests |
| edge-app-instance | Running app instances on edge nodes |
| datastore | Image storage locations |
| image | App images inside datastores |
| volume-instance | Storage volumes |
| events | Device events and user action logs |
| job | Long-running tasks across nodes/instances |
| user / role / auth-profile | Access control |

===== Typical Flow: Bringing Up an Edge Node =====

The GUI onboarding wizard bundles network and project setup for you. In ZCLI you do those pieces yourself, in order:

  - Create a project: ''zcli project create <name> ...''
  - Create a network: ''zcli network create'' (defines the subnet/DHCP mode the node's adapter will use)
  - Create the edge node itself:

<code>
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"