The networks API from Incus — 5 operation(s) for networks.
swagger: '2.0'
info:
contact:
email: lxc-devel@lists.linuxcontainers.org
name: Incus upstream
url: https://github.com/lxc/incus
description: 'This is the REST API used by all Incus clients.
Internal endpoints aren''t included in this documentation.
The Incus API is available over both a local unix+http and remote https API.
Authentication for local users relies on group membership and access to the unix socket.
For remote users, the default authentication method is TLS client
certificates.'
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
title: Incus external REST certificates networks API
version: '1.0'
tags:
- name: networks
paths:
/1.0/networks:
get:
description: Returns a list of networks (URLs).
operationId: networks_get
parameters:
- description: Project name
example: default
in: query
name: project
type: string
- description: Retrieve networks from all projects
example: true
in: query
name: all-projects
type: boolean
- description: Collection filter
example: default
in: query
name: filter
type: string
produces:
- application/json
responses:
'200':
description: API endpoints
schema:
description: Sync response
properties:
metadata:
description: List of endpoints
example: "[\n \"/1.0/networks/mybr0\",\n \"/1.0/networks/mybr1\"\n]"
items:
type: string
type: array
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get the networks
tags:
- networks
post:
consumes:
- application/json
description: 'Creates a new network.
When clustered, most network types require individual POST for each cluster member prior to a global POST.'
operationId: networks_post
parameters:
- description: Project name
example: default
in: query
name: project
type: string
- description: Cluster member name
example: server01
in: query
name: target
type: string
- description: Network
in: body
name: network
required: true
schema:
$ref: '#/definitions/NetworksPost'
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Add a network
tags:
- networks
/1.0/networks/{name}:
delete:
description: Removes the network.
operationId: network_delete
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Delete the network
tags:
- networks
get:
description: Gets a specific network.
operationId: network_get
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
- description: Cluster member name
example: server01
in: query
name: target
type: string
produces:
- application/json
responses:
'200':
description: Network
schema:
description: Sync response
properties:
metadata:
$ref: '#/definitions/Network'
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get the network
tags:
- networks
patch:
consumes:
- application/json
description: Updates a subset of the network configuration.
operationId: network_patch
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
- description: Cluster member name
example: server01
in: query
name: target
type: string
- description: Network configuration
in: body
name: network
required: true
schema:
$ref: '#/definitions/NetworkPut'
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'412':
$ref: '#/responses/PreconditionFailed'
'500':
$ref: '#/responses/InternalServerError'
summary: Partially update the network
tags:
- networks
post:
consumes:
- application/json
description: Renames an existing network.
operationId: network_post
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
- description: Network rename request
in: body
name: network
required: true
schema:
$ref: '#/definitions/NetworkPost'
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Rename the network
tags:
- networks
put:
consumes:
- application/json
description: Updates the entire network configuration.
operationId: network_put
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
- description: Cluster member name
example: server01
in: query
name: target
type: string
- description: Network configuration
in: body
name: network
required: true
schema:
$ref: '#/definitions/NetworkPut'
produces:
- application/json
responses:
'200':
$ref: '#/responses/EmptySyncResponse'
'400':
$ref: '#/responses/BadRequest'
'403':
$ref: '#/responses/Forbidden'
'412':
$ref: '#/responses/PreconditionFailed'
'500':
$ref: '#/responses/InternalServerError'
summary: Update the network
tags:
- networks
/1.0/networks/{name}/leases:
get:
description: Returns a list of DHCP leases for the network.
operationId: networks_leases_get
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
- description: Cluster member name
example: server01
in: query
name: target
type: string
produces:
- application/json
responses:
'200':
description: API endpoints
schema:
description: Sync response
properties:
metadata:
description: List of DHCP leases
items:
$ref: '#/definitions/NetworkLease'
type: array
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get the DHCP leases
tags:
- networks
/1.0/networks/{name}/state:
get:
description: Returns the current network state information.
operationId: networks_state_get
parameters:
- description: Network name
in: path
name: name
required: true
type: string
- description: Project name
example: default
in: query
name: project
type: string
- description: Cluster member name
example: server01
in: query
name: target
type: string
produces:
- application/json
responses:
'200':
description: API endpoints
schema:
description: Sync response
properties:
metadata:
$ref: '#/definitions/NetworkState'
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get the network state
tags:
- networks
/1.0/networks?recursion=1:
get:
description: Returns a list of networks (structs).
operationId: networks_get_recursion1
parameters:
- description: Project name
example: default
in: query
name: project
type: string
- description: Retrieve networks from all projects
example: true
in: query
name: all-projects
type: boolean
- description: Collection filter
example: default
in: query
name: filter
type: string
produces:
- application/json
responses:
'200':
description: API endpoints
schema:
description: Sync response
properties:
metadata:
description: List of networks
items:
$ref: '#/definitions/Network'
type: array
status:
description: Status description
example: Success
type: string
status_code:
description: Status code
example: 200
type: integer
type:
description: Response type
example: sync
type: string
type: object
'403':
$ref: '#/responses/Forbidden'
'500':
$ref: '#/responses/InternalServerError'
summary: Get the networks
tags:
- networks
definitions:
NetworkPost:
description: NetworkPost represents the fields required to rename a network
properties:
name:
description: The new name for the network
example: mybr1
type: string
x-go-name: Name
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkStateBond:
description: NetworkStateBond represents bond specific state
properties:
down_delay:
description: Delay on link down (ms)
example: 0
format: uint64
type: integer
x-go-name: DownDelay
lower_devices:
description: List of devices that are part of the bond
example:
- eth0
- eth1
items:
type: string
type: array
x-go-name: LowerDevices
mii_frequency:
description: How often to check for link state (ms)
example: 100
format: uint64
type: integer
x-go-name: MIIFrequency
mii_state:
description: Bond link state
example: up
type: string
x-go-name: MIIState
mode:
description: Bonding mode
example: 802.3ad
type: string
x-go-name: Mode
transmit_policy:
description: Transmit balancing policy
example: layer3+4
type: string
x-go-name: TransmitPolicy
up_delay:
description: Delay on link up (ms)
example: 0
format: uint64
type: integer
x-go-name: UpDelay
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkStateVLAN:
description: NetworkStateVLAN represents VLAN specific state
properties:
lower_device:
description: Parent device
example: eth0
type: string
x-go-name: LowerDevice
vid:
description: VLAN ID
example: 100
format: uint64
type: integer
x-go-name: VID
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkState:
description: NetworkState represents the network state
properties:
addresses:
description: List of addresses
items:
$ref: '#/definitions/NetworkStateAddress'
type: array
x-go-name: Addresses
bond:
$ref: '#/definitions/NetworkStateBond'
bridge:
$ref: '#/definitions/NetworkStateBridge'
counters:
$ref: '#/definitions/NetworkStateCounters'
hwaddr:
description: MAC address
example: 10:66:6a:5a:83:57
type: string
x-go-name: Hwaddr
mtu:
description: MTU
example: 1500
format: int64
type: integer
x-go-name: Mtu
ovn:
$ref: '#/definitions/NetworkStateOVN'
state:
description: Link state
example: up
type: string
x-go-name: State
type:
description: Interface type
example: broadcast
type: string
x-go-name: Type
vlan:
$ref: '#/definitions/NetworkStateVLAN'
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkPut:
description: NetworkPut represents the modifiable fields of a network
properties:
config:
description: Network configuration map (refer to doc/networks.md)
example:
ipv4.address: 10.0.0.1/24
ipv4.nat: 'true'
ipv6.address: none
type: object
x-go-name: Config
description:
description: Description of the profile
example: My new bridge
type: string
x-go-name: Description
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkStateBridge:
description: NetworkStateBridge represents bridge specific state
properties:
forward_delay:
description: Delay on port join (ms)
example: 1500
format: uint64
type: integer
x-go-name: ForwardDelay
id:
description: Bridge ID
example: 8000.0a0f7c6edbd9
type: string
x-go-name: ID
stp:
description: Whether STP is enabled
example: false
type: boolean
x-go-name: STP
upper_devices:
description: List of devices that are in the bridge
example:
- eth0
- eth1
items:
type: string
type: array
x-go-name: UpperDevices
vlan_default:
description: Default VLAN ID
example: 1
format: uint64
type: integer
x-go-name: VLANDefault
vlan_filtering:
description: Whether VLAN filtering is enabled
example: false
type: boolean
x-go-name: VLANFiltering
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkStateOVN:
description: NetworkStateOVN represents OVN specific state
properties:
chassis:
description: OVN network chassis name
example: server01
type: string
x-go-name: Chassis
logical_router:
description: OVN logical router name
example: incus-net1-lr
type: string
x-go-name: LogicalRouter
logical_switch:
description: OVN logical switch name
example: incus-net1-ls-int
type: string
x-go-name: LogicalSwitch
uplink_ipv4:
description: OVN network uplink ipv4 address
example: 10.0.0.1
type: string
x-go-name: UplinkIPv4
uplink_ipv6:
description: OVN network uplink ipv6 address
example: 2001:0000:130F:0000:0000:09C0:876A:130B.
type: string
x-go-name: UplinkIPv6
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkStateCounters:
description: NetworkStateCounters represents packet counters
properties:
bytes_received:
description: Number of bytes received
example: 250542118
format: int64
type: integer
x-go-name: BytesReceived
bytes_sent:
description: Number of bytes sent
example: 17524040140
format: int64
type: integer
x-go-name: BytesSent
packets_received:
description: Number of packets received
example: 1182515
format: int64
type: integer
x-go-name: PacketsReceived
packets_sent:
description: Number of packets sent
example: 1567934
format: int64
type: integer
x-go-name: PacketsSent
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
Network:
description: Network represents a network
properties:
config:
description: Network configuration map (refer to doc/networks.md)
example:
ipv4.address: 10.0.0.1/24
ipv4.nat: 'true'
ipv6.address: none
type: object
x-go-name: Config
description:
description: Description of the profile
example: My new bridge
type: string
x-go-name: Description
locations:
description: Cluster members on which the network has been defined
example:
- server01
- server02
- server03
items:
type: string
readOnly: true
type: array
x-go-name: Locations
managed:
description: Whether this is a managed network
example: true
readOnly: true
type: boolean
x-go-name: Managed
name:
description: The network name
example: mybr0
readOnly: true
type: string
x-go-name: Name
project:
description: Project name
example: project1
type: string
x-go-name: Project
status:
description: The state of the network (for managed network in clusters)
example: Created
readOnly: true
type: string
x-go-name: Status
type:
description: The network type
example: bridge
readOnly: true
type: string
x-go-name: Type
used_by:
description: List of URLs of objects using this profile
example:
- /1.0/profiles/default
- /1.0/instances/c1
items:
type: string
readOnly: true
type: array
x-go-name: UsedBy
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkStateAddress:
description: NetworkStateAddress represents a network address
properties:
address:
description: IP address
example: 10.0.0.1
type: string
x-go-name: Address
family:
description: Address family
example: inet
type: string
x-go-name: Family
netmask:
description: IP netmask (CIDR)
example: '24'
type: string
x-go-name: Netmask
scope:
description: Address scope
example: global
type: string
x-go-name: Scope
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworksPost:
description: NetworksPost represents the fields of a new network
properties:
config:
description: Network configuration map (refer to doc/networks.md)
example:
ipv4.address: 10.0.0.1/24
ipv4.nat: 'true'
ipv6.address: none
type: object
x-go-name: Config
description:
description: Description of the profile
example: My new bridge
type: string
x-go-name: Description
name:
description: The name of the new network
example: mybr1
type: string
x-go-name: Name
type:
description: The network type (refer to doc/networks.md)
example: bridge
type: string
x-go-name: Type
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
NetworkLease:
description: NetworkLease represents a DHCP lease
properties:
address:
description: The IP address
example: 10.0.0.98
type: string
x-go-name: Address
hostname:
description: The hostname associated with the record
example: c1
type: string
x-go-name: Hostname
hwaddr:
description: The MAC address
example: 10:66:6a:2c:89:d9
type: string
x-go-name: Hwaddr
location:
description: What cluster member this record was found on
example: server01
type: string
x-go-name: Location
type:
description: The type of record (static or dynamic)
example: dynamic
type: string
x-go-name: Type
type: object
x-go-package: github.com/lxc/incus/v7/shared/api
responses:
Forbidden:
description: Forbidden
schema:
properties:
error:
example: not authorized
type: string
x-go-name: Error
error_code:
example: 403
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
BadRequest:
description: Bad Request
schema:
properties:
error:
example: bad request
type: string
x-go-name: Error
error_code:
example: 400
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
PreconditionFailed:
description: Precondition Failed
schema:
properties:
error:
example: precondition failed
type: string
x-go-name: Error
error_code:
example: 412
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object
EmptySyncResponse:
description: Empty sync response
schema:
properties:
status:
example: Success
type: string
x-go-name: Status
status_code:
example: 200
format: int64
type: integer
x-go-name: StatusCode
type:
example: sync
type: string
x-go-name: Type
type: object
InternalServerError:
description: Internal Server Error
schema:
properties:
error:
example: internal server error
type: string
x-go-name: Error
error_code:
example: 500
format: int64
type: integer
x-go-name: ErrorCode
type:
example: error
type: string
x-go-name: Type
type: object