> ## Documentation Index > Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL. > Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other. > Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking. > Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify. # Manage Virtual Networks > Use ZCLI to create, view, update, and delete the Local and Switch virtual networks that application instances use on an edge node. Use the ZEDEDA CLI (ZCLI) to manage virtual networks from the command line. A virtual network gives application instances on an edge node their connectivity, either as a Local routed subnet with its own DHCP server or as a Switch bridge onto a physical port. The CLI name for a virtual network is `network-instance`, so this article covers `zcli network-instance` commands with syntax and examples for each operation. If you want to manage the node networks that define connectivity for the physical ports of an edge node, see [Manage Networks](https://zededa.mintlify.site/zcli-reference/networks.md) instead. ## Before You Start * ZCLI is installed and authenticated against your enterprise. See [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md). * You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md). * The edge node or node cluster that hosts the virtual network is onboarded. List nodes with `zcli edge-node show` and clusters with `zcli edge-node-cluster show`. * For GUI-based virtual network management, see [Virtual Networks Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks.md), [Create a Virtual Network](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks/create-a-virtual-network.md), [Manage a Virtual Network](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks/manage-a-virtual-network.md), and [Virtual Network Details](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks/virtual-network-details.md). ## Manage Virtual Networks ### Create a virtual network Create a virtual network on a single edge node (`--edge-node`) or on a node cluster (`--edge-node-cluster`). You must pass exactly one of the two. The `--kind` and `--ip-type` flags are required. The name must be unique and cannot be changed after creation. If you omit `--title`, ZCLI uses the name as the title. ```text theme={"dark"} zcli network-instance create [--title=title] (--edge-node= | --edge-node-cluster=) [--default] [--port=port] --kind=[switch|local|cloud] --ip-type=[v4|v6] [--subnet=] [--gateway=] [--domain=] [--ntp=] [--ntp-servers=...] [--nameserver=...] [--dhcp-range=] [--static-dns=...] [--config=] [--tags=...] [--mtu=] [--static-routes=] ``` The `--kind` flag selects the virtual network type. The console offers the following two types. ZCLI also accepts `--kind=cloud`, which the console does not offer; if you pass `--config` with this kind, you must also pass `--port`. | Kind | Console name | Description | | - | - | - | | `local` | **Local** | An isolated routed subnet on the node. EVE-OS (Edge Virtualization Engine) runs a DHCP server for the application instances on the network and routes their traffic through the port you select. Accepts the IP options (`--subnet`, `--gateway`, `--dhcp-range`, `--nameserver`, `--ntp-servers`, `--domain`, `--static-dns`) and `--static-routes`. | | `switch` | **Switch** | A Layer 2 bridge between the application instances and a physical port. Application instances obtain IP addresses from the external network, so a Switch virtual network has no IP settings. Do not pass IP options for this kind. ZCLI does not reject them: it still validates `--subnet` and `--gateway`, sends `--static-dns` and `--static-routes`, and if you pass `--dhcp-range` it sends an IP block with the subnet, gateway, domain, and DNS values. | The `--port` flag sets the node port the virtual network uses. It accepts a physical port name (for example `eth0`), a VLAN sub-interface logical label, an adapter label that groups several ports for multi-path routing, or one of the following predefined labels. Omit `--port` to create an air-gapped virtual network with no external connectivity (**None** in the console). | Value | Console name | Description | | - | - | - | | `uplink` | **Uplink** | All management ports on the node. | | `freeuplink` | **Freeuplink** | All zero-cost management ports on the node. | The following flags are the ones you are most likely to need. For the full list, run `zcli network-instance --help`. | Flag | Description | | - | - | | `--edge-node=` | Name of the edge node that hosts the virtual network. | | `--edge-node-cluster=` | Name of the node cluster that hosts the virtual network. The configuration copies to every node in the cluster. | | `--ip-type=[v4\|v6]` | IP address family: `v4` or `v6`. | | `--default` | Mark the virtual network as the default for the edge node, so that new application instances on the node attach to it automatically. The console does not offer this option for cluster deployments. | | `--subnet=` | Subnet in CIDR notation, for example `192.168.10.0/24`. Required if you pass `--gateway`. | | `--gateway=` | IP address of the default gateway for the virtual network. | | `--dhcp-range=` | Range of addresses to assign to application instances, in the format `start-end`, for example `192.168.10.100-192.168.10.200`. | | `--nameserver=` | Host name or IP address of a DNS server. Repeat the option to add more than one. | | `--ntp-servers=` | IP address or FQDN of an NTP server. Repeat the option to add more than one. The older `--ntp` flag is deprecated; use `--ntp-servers` instead. | | `--domain=` | Domain name for the virtual network. | | `--static-dns=` | Hostname-to-IP mapping in the format `hostname:ip-list`, where `ip-list` is a comma-separated list, for example `myweb.local:192.168.10.10,10.0.0.1`. Repeat the option to add more than one entry. | | `--static-routes=` | Path to a JSON file that lists static routes. Each route has a `prefix` in CIDR notation, an optional `gateway`, and an `outputPort` (a port name or adapter label). | | `--mtu=` | Maximum transmission unit in bytes. The minimum is 1280. If omitted, EVE-OS uses 1500 for air-gapped networks or the lowest MTU among the associated ports. | | `--tags=` | User-defined tag in the format `key:value`, for example `role:management`. Repeat the option to add more than one. Note that this command separates key and value with a colon, not an equals sign. | | `--config=` | Path to a JSON file with an opaque configuration (the help text calls it an "oconfig file"). ZCLI reads the file and sends its contents to Edge Infrastructure Services unchanged. Used with `--kind=cloud`. | Example (Local virtual network with DHCP on a single node): ```text theme={"dark"} zcli network-instance create MY_LOCAL_NET --edge-node=MY_NODE --kind=local --ip-type=v4 --port=uplink ``` Example (Local virtual network with static IP settings and a DHCP range): ```text theme={"dark"} zcli network-instance create MY_LOCAL_STATIC_NET --edge-node=MY_NODE --kind=local --ip-type=v4 --port=uplink --subnet=192.168.10.0/24 --gateway=192.168.10.1 --dhcp-range=192.168.10.100-192.168.10.200 --nameserver=192.168.10.1 --ntp-servers=pool.ntp.org --domain=example.local ``` Example (Switch virtual network bound to a specific port): ```text theme={"dark"} zcli network-instance create MY_SWITCH_NET --edge-node=MY_NODE --kind=switch --ip-type=v4 --port=eth1 ``` Example (Local virtual network on a node cluster): ```text theme={"dark"} zcli network-instance create MY_CLUSTER_NET --edge-node-cluster=MY_CLUSTER --kind=local --ip-type=v4 --port=uplink ``` Example (Local virtual network with tags and static routes from a file): ```text theme={"dark"} zcli network-instance create MY_ROUTED_NET --edge-node=MY_NODE --kind=local --ip-type=v4 --port=uplink --tags=role:management --static-routes=./my-static-routes.json ``` ### View a virtual network Query a single virtual network by name or UUID, or list the virtual networks in your enterprise. Add `--detail` to a single-network query to show the full configuration and runtime status, including the bridge, IP mappings, and static routes. When listing, filter with `--project` to show the virtual networks in one project, `--edge-node` or `--edge-node-cluster` to show those on one node or cluster, `--name-pattern` to match a substring of the name, `--state` to match a run state, or `--tags` to match a tag. Use `--summary` to print counts by kind and address type instead of the full list. Add `--raw` to a single-network query to print the raw status and metrics JSON that the edge node reports for the virtual network instead of the formatted output. If the node has not reported any, ZCLI prints `No metrics or status in response.` ```text theme={"dark"} zcli network-instance show [[[ | --uuid=] [--detail] [--raw]] | [[--edge-node= | --edge-node-cluster=] [--name-pattern=] [--summary] [--page-size=] [--project=] [--state=] [--tags=]]] ``` Example (list all virtual networks): ```text theme={"dark"} zcli network-instance show ``` Example (list the virtual networks in a project): ```text theme={"dark"} zcli network-instance show --project=MY_PROJECT ``` Example (list the virtual networks on one edge node): ```text theme={"dark"} zcli network-instance show --edge-node=MY_NODE ``` Example (list activated virtual networks whose name contains a substring): ```text theme={"dark"} zcli network-instance show --state=Activated --name-pattern=LOCAL ``` Example (show one virtual network in detail): ```text theme={"dark"} zcli network-instance show MY_LOCAL_STATIC_NET --detail ``` Example response: ```text theme={"dark"} Network Instance Name: MY_LOCAL_STATIC_NET Network Instance ID: 8c1f2a7e-5b3d-4e9a-9f0c-2d6b7a1e4c55 Network Instance Title: MY_LOCAL_STATIC_NET Network Instance Description: Tags: Edge Node: MY_NODE Kind: LOCAL IP-Type: V4 Port: uplink DHCP: Configured MTU: 1500 Reported MTU: 1500 Subnet: 192.168.10.0/24 Gateway: 192.168.10.1 Domain: example.local DHCP Address Range: 192.168.10.100-192.168.10.200 State: ACTIVATED BridgeName: bn1 BridgeNum: 1 BridgeIPAddress: 192.168.10.1 UpTimeStamp: 2025-03-30T05:50:39Z Nameservers ------------- 192.168.10.1 Version: 1 Created at: Sun Mar 30 2025 05:50:39 AM Created By: user@zededa.com Last Updated at: Sun Mar 30 2025 05:50:39 AM Last Updated By: user@zededa.com ``` The `--page-size` flag changes how many records each API call returns while ZCLI builds the full list. It does not change the output; it only reduces the chance of a timeout on large enterprises. ### Update a virtual network Change the title, port, IP settings, DNS and NTP servers, static routes, MTU, tags, or default flag of an existing virtual network. You cannot change the name, kind, IP type, or hosting node after creation; to change those, create a new virtual network. If you pass `--subnet` or `--gateway` on its own, ZCLI validates the new value against the other value already stored on the virtual network. If you run the command with no options, ZCLI reports `Nothing to update`. ```text theme={"dark"} zcli network-instance update [--default] [--port=port] [--title=title] [--subnet=] [--gateway=] [--domain=] [--ntp=] [--ntp-servers=...] [--nameserver=...] [--dhcp-range=] [--static-dns=...] [--config=] [--tags=...] [--mtu=] [--static-routes=] ``` Example (change the title and port): ```text theme={"dark"} zcli network-instance update MY_LOCAL_NET --title=MY_NEW_TITLE --port=eth0 ``` Example (set NTP servers): ```text theme={"dark"} zcli network-instance update MY_LOCAL_NET --ntp-servers=time1.example.com --ntp-servers=time2.example.com ``` Example (replace the static routes from a file): ```text theme={"dark"} zcli network-instance update MY_LOCAL_NET --static-routes=./my-static-routes.json ``` ### Delete a virtual network Delete a virtual network you no longer need. Without the `-f` flag, ZCLI asks you to confirm the deletion. ```text theme={"dark"} zcli network-instance delete [-f] ``` Example: ```text theme={"dark"} zcli network-instance delete MY_LOCAL_NET ``` Example response: ```text theme={"dark"} Delete network_instance MY_LOCAL_NET? [Y/N]: Y ``` The `-f` flag deletes the virtual network without a confirmation prompt. ## Next Steps > [card] [Virtual Networks Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks.md) > > How Local and Switch virtual networks, IP options, VLANs, and routing fit together. > [card] [Create a Virtual Network](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks/create-a-virtual-network.md) > > Create a Local or Switch virtual network in the Edge Intelligence Platform Console. > [card] [Manage a Virtual Network](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-networks/manage-a-virtual-network.md) > > GUI-based virtual network management. > [card] [Overview](https://zededa.mintlify.site/zcli-reference/overview.md) > > All ZCLI command procedures, organized by resource type.