Menu ⌃

CLI — Network

CLI v1.3.0 manages VPCs and subnets, reserved public IPs, firewall rules, L4 load balancers, security groups and per-VM internet access. Concepts are in the dashboard guides: VPCs, public IPs and firewall rules.

How these commands take input

Most networking commands send one API request, read as JSON from --file PATH or --file - (stdin). Field names match the API reference. Flags such as --project, --name, --vm, --vpc and --datacenter fill the matching fields when the file leaves them out. Unknown fields are rejected.

VPCs and subnets

A default VPC is created with your first VM. Create your own to choose address ranges and keep environments apart:

metalhost vpc create --file - <<'EOF'
{ "project_name": "projects/my-app", "display_name": "staging" }
EOF

metalhost vpc subnet create --vpc projects/my-app/vpcs/VPC_ID --file - <<'EOF'
{ "display_name": "app", "ipv4_range": "10.20.0.0/24" }
EOF

# Enable the subnet in a datacenter, then publish a network VMs can join.
metalhost vpc subnet attach --datacenter datacenters/us-dal-1 --wait --file - <<'EOF'
{ "subnet_name": "projects/my-app/vpcs/VPC_ID/subnets/SUBNET_ID" }
EOF
metalhost network create --project projects/my-app --region datacenters/us-dal-1 \
  --subnet projects/my-app/vpcs/VPC_ID/subnets/SUBNET_ID
CommandWhat it does
vpc list | get | create | update | deleteVPC definitions. Update changes the display name only.
vpc subnet list | get | create | update | deleteSubnets. Ranges and DNS resolvers are fixed at creation.
vpc subnet attachEnable a subnet in a datacenter.
vpc detach-datacenterRemove a VPC's unused subnets from one datacenter.
network list | create --subnetNetworks that VMs join.

Subnets take an RFC 1918 range that does not overlap another subnet in the same VPC, and optionally up to three custom_dns_ipv4 resolvers. Delete subnets before their VPC; anything still connected must be removed first.

Each project includes three networks by default, and the default VPC uses one. Beyond that, network create --subnet fails with QUOTA_EXCEEDED until you raise the network.network.count quota with metalhost quota request.

Reserved public IPs

A reserved IPv4 belongs to your project until you release it. Attach it to a private IPv4 on any VM in the same datacenter, detach it, and attach it elsewhere without restarting either VM.

metalhost public-ip reserve --project projects/my-app --file - <<'EOF'
{ "display_name": "web" }
EOF

# Attach: name the VM's private IPv4 and the reservation's current generation.
metalhost public-ip get --name projects/my-app/public-ips/IP_ID -o json   # read "generation"
metalhost public-ip attach --name projects/my-app/public-ips/IP_ID \
  --vm projects/my-app/virtual-machines/web-01 --wait --file - <<'EOF'
{ "private_ipv4": "10.20.0.5", "expected_generation": 1 }
EOF

public-ip detach takes the binding's ID and generation from the get output (binding.id, binding.generation). If you detach a VM's default outbound address while it has others, name the replacement with replacement_default_public_ip_name. public-ip release is permanent: billing stops and the address may go to another customer.

You can also attach a reservation when creating a VM:

metalhost vm create ... --public-ip projects/my-app/public-ips/IP_ID --public-ip-generation 1
metalhost vm create ... --assign-public-ipv4   # allocate a new address
metalhost vm create ... --private-only         # no public IPv4

Firewall rules

New VMs start with no inbound rules, so nothing reaches them from the internet until you add one, including SSH:

metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
  --port 22/tcp --source 203.0.113.7/32 --display-name "ssh from office"

metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
  --port 443/tcp --source 0.0.0.0/0 --ip-family both --display-name https

# Deny wins ties; lower priorities are evaluated first.
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
  --action deny --priority 10 --port 443/tcp --source 198.51.100.0/24

# Outbound rule: restrict what the VM may reach.
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
  --direction egress --port 443/tcp --destination 0.0.0.0/0 --ip-family ipv4

# Forward public port 2222 on an attached address to port 22 on the VM.
metalhost firewall create --vm projects/my-app/virtual-machines/web-01 \
  --forward-public-ip projects/my-app/public-ips/IP_ID --port 2222:22/tcp
CommandWhat it does
firewall list --vm NAMEList a VM's rules.
firewall createAdd a rule. Flags: --direction, --action, --priority, --ip-family, --port, --source, --destination, --forward-public-ip.
firewall delete NAMEDelete a rule.

Load balancers

A regional L4 TCP load balancer puts one public IPv4 in front of VM interfaces on a network. Backends are interface IDs from vm network interfaces. Clients' source IPs reach the backends unchanged.

metalhost vm network interfaces --file - <<'EOF'
{ "project_name": "projects/my-app", "target_vm": "projects/my-app/virtual-machines/web-01" }
EOF

metalhost load-balancer create --project projects/my-app --wait --file - <<'EOF'
{
  "network_name": "projects/my-app/networks/NETWORK_ID",
  "display_name": "web",
  "listeners": [{
    "port": 443, "backend_port": 443, "protocol": "TCP",
    "health_check": { "port": 443, "interval_seconds": 10, "timeout_milliseconds": 2000,
                      "healthy_threshold": 2, "unhealthy_threshold": 3 }
  }],
  "backend_interface_ids": ["IFACE_ID_1", "IFACE_ID_2"],
  "drain_timeout_seconds": 30
}
EOF

load-balancer get shows per-backend health. update replaces listeners and backends and needs the current expected_generation; so does delete.

Security groups

Security groups filter traffic between VMs on the private network. Membership changes need no restart.

metalhost security-group create --project projects/my-app --file - <<'EOF'
{
  "display_name": "db",
  "rules": [{ "direction": "ingress", "protocol": "tcp", "port": 5432,
              "security_group": "projects/my-app/security-groups/APP_GROUP_ID" }]
}
EOF

metalhost security-group add-vm --file - <<'EOF'
{ "security_group": "projects/my-app/security-groups/DB_GROUP_ID",
  "vm": "projects/my-app/virtual-machines/db-01" }
EOF

Rules take action (allow or deny), priority (1–1000), ip_family and an optional client source-port range. See Security groups for how rules combine.

VM internet access and addresses

metalhost vm network internet-policy get --vm projects/my-app/virtual-machines/web-01

# Both settings are required; pass the current generation from "get".
metalhost vm network internet-policy set --vm projects/my-app/virtual-machines/web-01 --wait --file - <<'EOF'
{ "project_name": "projects/my-app", "allow_outbound_internet": false,
  "allow_ipv6_internet": true, "expected_generation": 3 }
EOF
CommandWhat it does
vm network interfacesInterfaces, addresses and the default outbound IPv4.
vm network internet-policy get | setAllow outbound internet; allow IPv6 internet access.
vm network alias add | removeExtra private IPv4 addresses on an interface.
vm network set-default-public-ipChoose which attached public IPv4 new outbound connections use.

What's next