tritonctl networking commands

The seven tenant networking command families of tritonctl: vpc, subnet, nat-gateway, floating-ip, route-table, route, and firewall-rule. Each family has list, show, create, and delete. vpc, subnet, and firewall-rule add update. floating-ip adds attach and detach.

tritonctl external-ip and tritonctl load-balancer also manage project networking objects. This page does not cover them; see the command index.

For the global flags, output formats, and confirmation prompt that apply to every command below, see the tritonctl command index.

Common behavior

Every list answers to ls, and every delete to rm. floating-ip answers to ip, and firewall-rule to fwrule.

Every resource argument and every parent flag (--vpc, --route-table, --nic, --instance, --target-nat-gateway) takes a name, a UUID, or a UUID prefix. The resolution order is in Resource references. A full UUID is read directly. A name or a prefix is looked up by listing the project, so it needs a project from --project or the stored configuration. The one exception is a NAT gateway named in route create, which is looked up in the VPC of the route table. Without a project, a lookup that needs one fails before any request:

finding a vpc by name needs a project; pass --project, or set one with `tritonctl configure --project`

vpc list, vpc create, floating-ip list, and floating-ip create always need a project. Each sends tenant= and project= selectors. tritonctl reads the tenant from GET /v1/me and caches it. Without a project, these commands fail before any request:

<DOING> needs a project; pass --project, or set one with `tritonctl configure --project`

<DOING> is listing vpcs, creating a vpc, listing floating IPs, or creating a floating IP.

The server scopes every other networking listing by its parent: subnets, NAT gateways, route tables, and firewall rules by vpc=, and routes by route_table=. When you omit --vpc on subnet list, nat-gateway list, or route-table list, tritonctl lists the VPCs of the project and sends one listing per VPC. When you omit --route-table on route list, it lists every route table of those VPCs and sends one listing per table. Both walks need a project.

List endpoints are paged with limit (default 50, capped at 500) and page_token, and answer with an items array and a next_page cursor. tritonctl requests 500 rows per page and follows next_page to the end. The firewall rule listing is not paged; one request per VPC returns every rule. A walk across parents that collects more than 5,000 rows stops with:

the <WHAT> walk stopped after 5000 rows; name the parent to narrow it

list prints a table. The tables sort by name, except floating-ip list, which sorts by address, and firewall-rule list, described in its section. -l swaps the default columns for the wider set listed under each family. show, create, update, attach, and detach print the server record as key value lines. A nested object with eight keys or fewer prints one line per key, named <PARENT>.<KEY>, for example target.kind. -j or --format prints the raw record instead. See Output formats.

Every delete prints a one-line plan and asks for confirmation before it sends the request. It takes -n, -y, and --keep-going, described in Confirmation.

Enum-valued fields render through their wire form. AddressFamily renders as v4 or v6. RouteTarget is internally tagged on kind, so the TARGET column of tritonctl route list renders a JSON object:

{"kind":"blackhole"}

{"kind":"nat_gateway","nat_gateway_id":"11111111-1111-4111-8111-111111111111"}

Resource names are validated at the storage layer before the row is written: 1 to 63 bytes, no / or \, no ASCII control bytes, and no leading or trailing whitespace. A name that breaks a rule returns 409 Conflict.

vpc

A VPC is the tenant's isolated overlay network. It carries a server-assigned Geneve VNI and one or two CIDR blocks.

vpc subcommands

Command	Request	Description
tritonctl vpc list	GET /v1/vpcs?tenant=&project=	List the VPCs of the project.
tritonctl vpc show <VPC>	GET /v1/vpcs/{vpc}	Show one VPC.
tritonctl vpc create	POST /v1/vpcs?tenant=&project=	Create a VPC in the project.
tritonctl vpc update <VPC>	PATCH /v1/vpcs/{vpc}	Rename a VPC or change its description.
tritonctl vpc delete <VPC>	DELETE /v1/vpcs/{vpc}	Delete a VPC.

vpc options

Subcommand	Flag	Value	Required	Behavior
list, create	--project	Project	Yes	Global flag, or the stored project.
create	--name	String	Yes	VPC name. Unique within the project.
create	--description	String	No	Free-text description. Empty when omitted.
create	--ipv4-block	CIDR	One of the two	IPv4 CIDR for the overlay, for example 10.0.0.0/16.
create	--ipv6-block	CIDR	One of the two	IPv6 CIDR for the overlay.
update	--name	String	One of the two	New name.
update	--description	String	One of the two	New description.

update with neither flag fails in the CLI with pass --name or --description.

vpc output

list renders the columns SHORTID, NAME, VNI, and AGE. -l renders ID, NAME, DESCRIPTION, VNI, MAIN_ROUTE_TABLE, and CREATED_AT.

The delete plan line is delete vpc <NAME> (<SHORTID>).

vpc constraints

• A create with neither --ipv4-block nor --ipv6-block returns 400 with vpc must specify ipv4_block, ipv6_block, or both.
• Both blocks must be private address space. An IPv4 block outside 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and 100.64.0.0/10 returns 400 with ipv4_block <BLOCK> must be private space: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10. An IPv6 block outside fd00::/8 returns 400 with ipv6_block <BLOCK> must be unique local space inside fd00::/8.
• The VNI is assigned by the server from the non-reserved VNI range and is unique rack-wide.
• Creating a VPC also creates a route table named main in the same transaction, with a description of Main route table for VPC <VPC_NAME>. New subnets inherit that route table.
• update changes the name and the description only. The blocks and the VNI cannot change. A name already used in the project returns 409 Conflict.
• A project outside the caller's tenant resolves as 404 Not Found.
• Delete returns 409 Conflict while any subnet remains in the VPC, while any non-main route table remains, and while the main route table still holds routes. NAT gateways in the VPC are deleted with it, unless one is mid-change, which returns 409 Conflict. Deleting the VPC deletes its main route table.

subnet

A subnet carves a CIDR out of its parent VPC. An instance NIC attaches to one subnet at create time.

subnet subcommands

Command	Request	Description
tritonctl subnet list	GET /v1/subnets?vpc=	List the subnets of one VPC, or of every VPC in the project.
tritonctl subnet show <SUBNET>	GET /v1/subnets/{subnet_id}	Show one subnet.
tritonctl subnet create --vpc <VPC>	POST /v1/subnets?vpc=	Create a subnet inside a VPC.
tritonctl subnet update <SUBNET>	PATCH /v1/subnets/{subnet_id}	Rename a subnet, change its description, or turn its SSH relay on or off.
tritonctl subnet delete <SUBNET>	DELETE /v1/subnets/{subnet_id}	Delete a subnet.

subnet options

Subcommand	Flag	Value	Required	Behavior
list	--vpc	VPC	No	Only the subnets of this VPC.
create	--vpc	VPC	Yes	Parent VPC. The server resolves the tenant and project from it.
create	--name	String	Yes	Subnet name. Unique within the VPC.
create	--description	String	No	Free-text description. Empty when omitted.
create	--ipv4-block	CIDR	One of the two	IPv4 CIDR, contained in the VPC's IPv4 block.
create	--ipv6-block	CIDR	One of the two	IPv6 CIDR, contained in the VPC's IPv6 block.
create	--no-ssh-relay	Flag	No	Create the subnet with SSH access through the platform relay off. The relay is on by default.
update	--name	String	One of the three	New name.
update	--description	String	One of the three	New description.
update	--ssh-relay	on, off	One of the three	Turn SSH access through the platform relay on or off.

update with none of the three flags fails in the CLI with pass --name, --description, or --ssh-relay.

subnet output

list renders the columns SHORTID, NAME, VPC, KIND, VLAN, SSH, and AGE. -l renders ID, NAME, VPC, KIND, VLAN, SSH, ROUTE_TABLE, NIC_TAG, and CREATED_AT. The SSH cell is on or off, and - for an external subnet.

The delete plan line is delete subnet <NAME> (<SHORTID>).

subnet constraints

• A create with neither --ipv4-block nor --ipv6-block returns 400 with subnet must specify ipv4_block, ipv6_block, or both.
• Each block must be contained in the parent VPC's block of the same family. A block whose family the VPC does not plan for returns 409 Conflict, as does a block that is not contained in the parent block.
• A block that overlaps an existing subnet block in the same VPC, in either family, returns 409 Conflict naming the peer subnet.
• A subnet created through this command is always an internal overlay subnet. Its kind is internal, and it carries no NIC tag and no VLAN id. External subnets come from the operator surface.
• The new subnet is associated with the VPC's main route table. The API moves a subnet to another route table in the same VPC with PUT /v1/subnets/{subnet_id}/route-table. tritonctl has no command for it.
• With the SSH relay on, the subnet takes one of the tenant's relay slots. When none is free, create, and an update that turns the relay on, return 403 QuotaExceeded. Turning the relay off is recorded at once, and the platform tears the relay down afterward.
• update cannot change the blocks. A name already used in the VPC returns 409 Conflict.
• A VPC that is not visible to the caller's tenant resolves as 404 Not Found.
• Delete returns 409 Conflict while instances or sandboxes still hold NICs on the subnet. It also returns 409 Conflict while the subnet holds a NAT gateway zone that other subnets use for egress, with this subnet holds the NAT gateway that gives internet egress to <COUNT> other subnet(s) in the VPC; turn off their internet egress first.
• A successful delete answers 202 Accepted with the subnet record and runs the subnet-delete saga. Reads of the subnet answer 404 Not Found once the saga finishes.

nat-gateway

A NAT gateway is the project-owned egress point of a VPC. It reserves one public IPv4 address at create time.

nat-gateway subcommands

Command	Request	Description
tritonctl nat-gateway list	GET /v1/nat-gateways?vpc=	List the NAT gateways of one VPC, or of every VPC in the project.
tritonctl nat-gateway show <NAT_GATEWAY>	GET /v1/nat-gateways/{nat_gateway_id}	Show one NAT gateway.
tritonctl nat-gateway create --vpc <VPC>	POST /v1/nat-gateways?vpc=	Create a NAT gateway on a VPC.
tritonctl nat-gateway delete <NAT_GATEWAY>	DELETE /v1/nat-gateways/{nat_gateway_id}	Delete a NAT gateway.

nat-gateway options

Subcommand	Flag	Value	Required	Behavior
list	--vpc	VPC	No	Only the gateways of this VPC.
create	--vpc	VPC	Yes	Parent VPC. The server resolves the tenant and project from it.
create	--name	String	Yes	Gateway name. Unique within the VPC.
create	--description	String	No	Defaults to the empty string.
create	--family	v4, v6	No	Address family of the public side. Defaults to v4.

nat-gateway output

list renders the columns SHORTID, NAME, VPC, PUBLIC_ADDRESS, and AGE. -l renders ID, NAME, VPC, PUBLIC_ADDRESS, FAMILY, CREATED_AT, and UPDATED_AT.

The delete plan line is delete nat gateway <NAME> (<SHORTID>) <PUBLIC_ADDRESS>.

nat-gateway constraints

• NAT gateways serve IPv4 only. --family v6 returns 409 Conflict with conflict: NAT gateways serve IPv4 only.
• Create runs the nat-gateway-create saga, then starts the nat-gateway-ensure saga, which builds the gateway zone. tritonctl names no subnet, so the zone goes in the VPC's lowest-named subnet. The audit record carries the saga id as operation_id.
• The public address comes from the address pool the operator assigns to NAT gateways. When none is assigned, create returns 409 Conflict with conflict: no public address range is configured for nat_gateway: set network.nat_egress_pool. An exhausted pool returns 409 PoolExhausted.
• A project at its NAT gateway limit returns 409 Conflict with conflict: project <PROJECT_UUID> is at its NAT gateway limit (<LIMIT>).
• A name that already exists in the VPC returns 409 Conflict.
• Delete returns 409 Conflict while any route still targets the gateway, with nat gateway is still referenced by routes, and while the gateway zone is being built or torn down, with nat gateway is busy; retry shortly.
• A successful delete answers 202 Accepted with the gateway record. It runs the nat-gateway-teardown saga when a zone is bound, and the nat-gateway-delete saga otherwise. Reads answer 404 Not Found once the platform has released the gateway.

floating-ip

A floating IP is a tenant-managed external address. It persists across attach and detach cycles and across instance deletes.

floating-ip subcommands

Command	Request	Description
tritonctl floating-ip list	GET /v1/floating-ips?tenant=&project=	List the floating IPs of the project.
tritonctl floating-ip show <FIP>	GET /v1/floating-ips/{floating_ip_id}	Show one floating IP.
tritonctl floating-ip create	POST /v1/floating-ips?tenant=&project=	Allocate a floating IP in the project.
tritonctl floating-ip delete <FIP>	DELETE /v1/floating-ips/{floating_ip_id}	Delete a floating IP.
tritonctl floating-ip attach <FIP> --nic <NIC>	POST /v1/tenants/{tenant_id}/projects/{project_id}/floating-ips/{floating_ip_id}/attach	Bind the address to a NIC.
tritonctl floating-ip detach <FIP>	POST /v1/tenants/{tenant_id}/projects/{project_id}/floating-ips/{floating_ip_id}/detach	Release the address from its NIC.

<FIP> also accepts the floating IP's address. <NIC> also accepts the NIC's MAC address.

floating-ip options

Subcommand	Flag	Value	Required	Behavior
list, create	--project	Project	Yes	Global flag, or the stored project.
create	--name	String	Yes	Floating IP name. Unique within the project.
create	--description	String	No	Free-text description.
create	--family	v4, v6	No	Address family to allocate from. Defaults to v4.
attach	--nic	NIC	Yes	Target NIC.
attach	--instance	Instance	No	The NIC's instance. Needed unless --nic is a full UUID.

Finding a NIC by name, MAC, or UUID prefix without --instance fails in the CLI with:

finding a nic by name needs its instance; pass --instance, or the nic's uuid

floating-ip output

list renders the columns SHORTID, NAME, ADDRESS, ATTACHED, and AGE, sorted by address. The ATTACHED cell is the short id of the bound NIC, and - when the address is not bound. -l renders ID, NAME, ADDRESS, ATTACHED, HOSTED_CN, CREATED_AT, and UPDATED_AT.

The delete plan line is delete floating ip <NAME> (<SHORTID>) <ADDRESS>.

floating-ip constraints

• The API accepts three mutually exclusive allocation sources, family, network_id, and pool_id. tritonctl always sends family and has no flag for the other two.
• With family, the address comes from the address pool the operator assigns to floating IPs. When none is assigned, create returns 409 Conflict with conflict: no public address range is configured for floating_ip: set network.floating_ip_pool. An exhausted pool returns 409 PoolExhausted.
• Create runs the floating-ip-allocate saga, attach runs floating-ip-attach, and detach runs floating-ip-detach.
• attach reads the NIC and the floating IP first, and detach reads the floating IP first. The floating IP record supplies the tenant and project path parameters of the project-scoped route.
• attach captures the current binding before it starts, so the saga can restore it on failure. Attaching an already-bound address moves it. The target NIC must be in the floating IP's tenant and project; a mismatch resolves as 404 Not Found.
• detach on an address that is not bound returns the current record.
• Delete returns 409 Conflict while the address is attached, with floating ip <FIP_UUID> is currently attached; detach first. A successful delete releases the address back to the pool, where a later create can hand it to a different project.

route-table

A route table holds the routes applied to the subnets associated with it. Each VPC has one table named main, created with the VPC.

route-table subcommands

Command	Request	Description
tritonctl route-table list	GET /v1/route-tables?vpc=	List the route tables of one VPC, or of every VPC in the project.
tritonctl route-table show <ROUTE_TABLE>	GET /v1/route-tables/{route_table_id}	Show one route table.
tritonctl route-table create --vpc <VPC>	POST /v1/route-tables?vpc=	Create a non-main route table inside a VPC.
tritonctl route-table delete <ROUTE_TABLE>	DELETE /v1/route-tables/{route_table_id}	Delete a route table.

route-table options

Subcommand	Flag	Value	Required	Behavior
list	--vpc	VPC	No	Only the tables of this VPC.
create	--vpc	VPC	Yes	Parent VPC. The server resolves the tenant and project from it.
create	--name	String	Yes	Route table name. Unique within the VPC.
create	--description	String	No	Defaults to the empty string.

route-table output

list renders the columns SHORTID, NAME, VPC, MAIN, and AGE. The MAIN cell is yes or no. -l renders ID, NAME, VPC, MAIN, DESCRIPTION, and CREATED_AT.

The delete plan line is delete route table <NAME> (<SHORTID>).

route-table constraints

• A table created through this command is never the main table. Its is_main field is false.
• The name main is taken by the table the VPC created, so a create that reuses it returns 409 Conflict.
• A subnet uses a non-main table only after the API moves it there with PUT /v1/subnets/{subnet_id}/route-table. tritonctl has no command for it.
• Deleting the main table returns 409 Conflict. Delete the VPC instead.
• Delete returns 409 Conflict while the table still holds routes, and again while any subnet is still associated with it.

route

A route sends traffic for one destination CIDR to one target. Routes live in a route table.

route subcommands

Command	Request	Description
tritonctl route list	GET /v1/routes?route_table=	List the routes of one route table, or of every route table in the project.
tritonctl route show <ROUTE>	GET /v1/routes/{route_id}	Show one route.
tritonctl route create --route-table <ROUTE_TABLE>	POST /v1/routes?route_table=	Create a route in a route table.
tritonctl route delete <ROUTE>	DELETE /v1/routes/{route_id}	Delete a route.

route options

Subcommand	Flag	Value	Required	Behavior
list	--route-table	Route table	No	Only the routes of this table.
create	--route-table	Route table	Yes	Parent route table. The server resolves the tenant, project, and VPC from it.
create	--name	String	Yes	Route name.
create	--description	String	No	Defaults to the empty string.
create	--destination	CIDR	Yes	Destination prefix.
create	--target-nat-gateway	NAT gateway	One target	Send matching traffic to a NAT gateway. A name or prefix is looked up in the route table's VPC.
create	--target-blackhole	Flag	One target	Drop matching traffic.
create	--target-reject	Flag	One target	Drop matching traffic. The dataplane sends no ICMP response.
create	--target-virtual-gateway	Flag	One target	Send matching traffic to the VPC virtual gateway.

Any count of --target-* flags other than one fails in the CLI before any request:

pass exactly one of --target-nat-gateway, --target-blackhole, --target-reject, --target-virtual-gateway (<COUNT> given)

route output

list renders the columns SHORTID, NAME, ROUTE_TABLE, DESTINATION, TARGET, and AGE. -l renders ID, NAME, VPC, ROUTE_TABLE, DESTINATION, TARGET, and CREATED_AT. The TARGET cell holds the tagged JSON object described in Common behavior. show prints the target as target.kind and, for a NAT gateway target, target.nat_gateway_id.

The delete plan line is delete route <NAME> (<SHORTID>) to <DESTINATION>.

route constraints

• The floating-IP route target is rejected on this surface with 400 and floating ip route targets are system-installed only in v1. The system installs that target itself.
• A NAT gateway target outside the caller's tenant and project resolves as 404 Not Found. A NAT gateway in another VPC returns 400 with nat gateway <NAT_GATEWAY_UUID> is not in vpc <VPC_UUID>.
• The destination is canonicalized to its network address before it is stored.
• A destination whose address family the parent VPC does not plan for returns 409 Conflict, and so does a destination that already exists in the same route table.

firewall-rule

A firewall rule permits or denies traffic on a VPC by direction, protocol, CIDR, and port range. Inbound traffic that no rule allows is dropped. A new VPC gets the rules default-allow-intra-vpc, and default-allow-intra-vpc-v6 when it has an IPv6 block. Each new overlay subnet adds platform-access-<SUBNET_UUID>, plus a -v6 twin when the subnet has an IPv6 relay address. See Networking concepts.

Aliases: fwrule. list also answers to ls, and delete to rm.

firewall-rule subcommands

Command	Request	Description
tritonctl firewall-rule list	GET /v1/firewall-rules?vpc=	List the rules of one VPC, or of every VPC in the project when --vpc is omitted.
tritonctl firewall-rule show <RULE>	GET /v1/firewall-rules/{firewall_rule_id}	Show one rule.
tritonctl firewall-rule create --vpc <VPC>	POST /v1/firewall-rules?vpc=	Create a rule on a VPC.
tritonctl firewall-rule update <RULE>	PATCH /v1/firewall-rules/{firewall_rule_id}	Change a rule. Only the flags given change.
tritonctl firewall-rule delete <RULE>	DELETE /v1/firewall-rules/{firewall_rule_id}	Delete a rule.

<RULE> and <VPC> take a name, a UUID, or a UUID prefix. Given a full UUID, show, update, and delete read the rule directly. Given a name or a prefix, they search the rules of every VPC in the project.

firewall-rule options

Subcommand	Flag	Value	Required	Behavior
list	--vpc	VPC	No	Only the rules of this VPC.
create	--vpc	VPC	Yes	Parent VPC.
create, update	--name	String	Yes on create	Rule name. Unique within the VPC.
create, update	--description	String	No	Defaults to the empty string on create.
create, update	--action	allow, deny	Yes on create
create, update	--direction	inbound, outbound	Yes on create
create, update	--protocol	any, tcp, udp, icmp4, icmp6	No	Defaults to any on create.
create, update	--priority	Integer, 0 to 1000	Yes on create	Higher numbers evaluate first. At equal priority, inbound allow beats inbound deny, and outbound deny beats outbound allow.
create, update	--source-cidr	CIDR	No	Omitted on create means any source.
create, update	--destination-cidr	CIDR	No	Omitted on create means any destination.
create, update	--source-ports	LOW-HIGH or a single port	No	Requires --protocol tcp or udp.
create, update	--destination-ports	LOW-HIGH or a single port	No	Requires --protocol tcp or udp.
update	--enable	Flag	No	Turn the rule on. Conflicts with --disable.
update	--disable	Flag	No	Turn the rule off without deleting it. A disabled rule stays listed and has no effect.
delete	-n, --dry-run	Flag	No	Print the change and exit.
delete	-y, --yes	Flag	No	Skip the confirmation prompt. Required when no terminal is available to ask on.

Values for --action, --direction, and --protocol are matched exactly, with no aliases. create always sends the rule enabled. update with no flag to change fails in the CLI with pass at least one flag to change.

firewall-rule output

list renders the columns SHORTID, NAME, VPC, PRIORITY, DIRECTION, ACTION, PROTOCOL, SOURCE, and DESTINATION, sorted by VPC and then priority. -l replaces SHORTID with the full ID and adds CREATED_AT.

show, create, and update print the rule record, including enabled. list has no enabled column, so use show to tell a disabled rule from an enabled one.

delete prints the change it will make and asks for confirmation before it sends the request.

firewall-rule constraints

• A priority from 1001 to 29999 returns 409 Conflict with firewall rule priority <PRIORITY> is above the maximum of 1000.
• A priority of 30000 or more returns 400 BadRequest, because that range is reserved for platform rules.
• A port range is parsed as LOW-HIGH, or as a single port that becomes both bounds. A non-integer bound, or a range whose low bound exceeds the high bound, fails in the CLI before any request.
• The CLI sends no ICMP type or code. The API field exists and the server rejects it on a non-ICMP protocol, but no flag sets it.
• The API also accepts sources and destinations target lists (any, all instances, an IP address, a subnet, an instance, or a tag). No CLI flag sets them.
• Ports on a protocol other than tcp or udp return 409 Conflict with firewall rule sets ports on a protocol that has none. --protocol defaults to any, so a rule with ports needs --protocol tcp or --protocol udp.
• A rule name that already exists in the VPC returns 409 Conflict.

See also

• tritonctl command index
• tritonctl instance reference
• Networking concepts
• Create an instance