1 /* 2 * libvirt-network.h 3 * Summary: APIs for management of networks 4 * Description: Provides APIs for the management of networks 5 * 6 * Copyright (C) 2006-2014 Red Hat, Inc. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see 20 * <http://www.gnu.org/licenses/>. 21 */ 22 23 #ifndef LIBVIRT_NETWORK_H 24 # define LIBVIRT_NETWORK_H 25 26 # ifndef __VIR_LIBVIRT_H_INCLUDES__ 27 # error "Don't include this file directly, only use libvirt/libvirt.h" 28 # endif 29 30 typedef enum { 31 VIR_NETWORK_XML_INACTIVE = (1 << 0), /* dump inactive network information */ 32 } virNetworkXMLFlags; 33 34 /** 35 * virNetwork: 36 * 37 * a virNetwork is a private structure representing a virtual network. 38 */ 39 typedef struct _virNetwork virNetwork; 40 41 /** 42 * virNetworkPtr: 43 * 44 * a virNetworkPtr is pointer to a virNetwork private structure, this is the 45 * type used to reference a virtual network in the API. 46 */ 47 typedef virNetwork *virNetworkPtr; 48 49 /** 50 * virNetworkPort: 51 * 52 * a virNetworkPort is a private structure representing a virtual network 53 * port 54 */ 55 typedef struct _virNetworkPort virNetworkPort; 56 57 /** 58 * virNetworkPortPtr: 59 * 60 * a virNetworkPortPtr is pointer to a virNetworkPort private structure, 61 * this is the type used to reference a virtual network port in the API. 62 */ 63 typedef virNetworkPort *virNetworkPortPtr; 64 65 /* 66 * Get connection from network. 67 */ 68 virConnectPtr virNetworkGetConnect (virNetworkPtr network); 69 70 /* 71 * List active networks 72 */ 73 int virConnectNumOfNetworks (virConnectPtr conn); 74 int virConnectListNetworks (virConnectPtr conn, 75 char **const names, 76 int maxnames); 77 78 /* 79 * List inactive networks 80 */ 81 int virConnectNumOfDefinedNetworks (virConnectPtr conn); 82 int virConnectListDefinedNetworks (virConnectPtr conn, 83 char **const names, 84 int maxnames); 85 /* 86 * virConnectListAllNetworks: 87 * 88 * Flags used to filter the returned networks. Flags in each group 89 * are exclusive attributes of a network. 90 */ 91 typedef enum { 92 VIR_CONNECT_LIST_NETWORKS_INACTIVE = 1 << 0, 93 VIR_CONNECT_LIST_NETWORKS_ACTIVE = 1 << 1, 94 95 VIR_CONNECT_LIST_NETWORKS_PERSISTENT = 1 << 2, 96 VIR_CONNECT_LIST_NETWORKS_TRANSIENT = 1 << 3, 97 98 VIR_CONNECT_LIST_NETWORKS_AUTOSTART = 1 << 4, 99 VIR_CONNECT_LIST_NETWORKS_NO_AUTOSTART = 1 << 5, 100 } virConnectListAllNetworksFlags; 101 102 int virConnectListAllNetworks (virConnectPtr conn, 103 virNetworkPtr **nets, 104 unsigned int flags); 105 106 /* 107 * Lookup network by name or uuid 108 */ 109 virNetworkPtr virNetworkLookupByName (virConnectPtr conn, 110 const char *name); 111 virNetworkPtr virNetworkLookupByUUID (virConnectPtr conn, 112 const unsigned char *uuid); 113 virNetworkPtr virNetworkLookupByUUIDString (virConnectPtr conn, 114 const char *uuid); 115 116 typedef enum { 117 VIR_NETWORK_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ 118 } virNetworkCreateFlags; 119 120 /* 121 * Create active transient network 122 */ 123 virNetworkPtr virNetworkCreateXML (virConnectPtr conn, 124 const char *xmlDesc); 125 virNetworkPtr virNetworkCreateXMLFlags(virConnectPtr conn, 126 const char *xmlDesc, 127 unsigned int flags); 128 129 typedef enum { 130 VIR_NETWORK_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ 131 } virNetworkDefineFlags; 132 133 /* 134 * Define inactive persistent network 135 */ 136 virNetworkPtr virNetworkDefineXML (virConnectPtr conn, 137 const char *xmlDesc); 138 virNetworkPtr virNetworkDefineXMLFlags(virConnectPtr conn, 139 const char *xmlDesc, 140 unsigned int flags); 141 142 /* 143 * Delete persistent network 144 */ 145 int virNetworkUndefine (virNetworkPtr network); 146 147 /** 148 * virNetworkUpdateCommand: 149 * 150 * describes which type of update to perform on a <network> 151 * definition. 152 * 153 */ 154 typedef enum { 155 VIR_NETWORK_UPDATE_COMMAND_NONE = 0, /* (invalid) */ 156 VIR_NETWORK_UPDATE_COMMAND_MODIFY = 1, /* modify an existing element */ 157 VIR_NETWORK_UPDATE_COMMAND_DELETE = 2, /* delete an existing element */ 158 VIR_NETWORK_UPDATE_COMMAND_ADD_LAST = 3, /* add an element at end of list */ 159 VIR_NETWORK_UPDATE_COMMAND_ADD_FIRST = 4, /* add an element at start of list */ 160 # ifdef VIR_ENUM_SENTINELS 161 VIR_NETWORK_UPDATE_COMMAND_LAST 162 # endif 163 } virNetworkUpdateCommand; 164 165 /** 166 * virNetworkUpdateSection: 167 * 168 * describes which section of a <network> definition the provided 169 * xml should be applied to. 170 * 171 */ 172 typedef enum { 173 VIR_NETWORK_SECTION_NONE = 0, /* (invalid) */ 174 VIR_NETWORK_SECTION_BRIDGE = 1, /* <bridge> */ 175 VIR_NETWORK_SECTION_DOMAIN = 2, /* <domain> */ 176 VIR_NETWORK_SECTION_IP = 3, /* <ip> */ 177 VIR_NETWORK_SECTION_IP_DHCP_HOST = 4, /* <ip>/<dhcp>/<host> */ 178 VIR_NETWORK_SECTION_IP_DHCP_RANGE = 5, /* <ip>/<dhcp>/<range> */ 179 VIR_NETWORK_SECTION_FORWARD = 6, /* <forward> */ 180 VIR_NETWORK_SECTION_FORWARD_INTERFACE = 7, /* <forward>/<interface> */ 181 VIR_NETWORK_SECTION_FORWARD_PF = 8, /* <forward>/<pf> */ 182 VIR_NETWORK_SECTION_PORTGROUP = 9, /* <portgroup> */ 183 VIR_NETWORK_SECTION_DNS_HOST = 10, /* <dns>/<host> */ 184 VIR_NETWORK_SECTION_DNS_TXT = 11, /* <dns>/<txt> */ 185 VIR_NETWORK_SECTION_DNS_SRV = 12, /* <dns>/<srv> */ 186 # ifdef VIR_ENUM_SENTINELS 187 VIR_NETWORK_SECTION_LAST 188 # endif 189 } virNetworkUpdateSection; 190 191 /** 192 * virNetworkUpdateFlags: 193 * 194 * Flags to control options for virNetworkUpdate() 195 */ 196 typedef enum { 197 VIR_NETWORK_UPDATE_AFFECT_CURRENT = 0, /* affect live if network is active, 198 config if it's not active */ 199 VIR_NETWORK_UPDATE_AFFECT_LIVE = 1 << 0, /* affect live state of network only */ 200 VIR_NETWORK_UPDATE_AFFECT_CONFIG = 1 << 1, /* affect persistent config only */ 201 } virNetworkUpdateFlags; 202 203 /* 204 * Update an existing network definition 205 */ 206 int virNetworkUpdate(virNetworkPtr network, 207 unsigned int command, /* virNetworkUpdateCommand */ 208 unsigned int section, /* virNetworkUpdateSection */ 209 int parentIndex, 210 const char *xml, 211 unsigned int flags); 212 213 /* 214 * Activate persistent network 215 */ 216 int virNetworkCreate (virNetworkPtr network); 217 218 /* 219 * Network destroy/free 220 */ 221 int virNetworkDestroy (virNetworkPtr network); 222 int virNetworkRef (virNetworkPtr network); 223 int virNetworkFree (virNetworkPtr network); 224 225 /* 226 * Network information 227 */ 228 const char* virNetworkGetName (virNetworkPtr network); 229 int virNetworkGetUUID (virNetworkPtr network, 230 unsigned char *uuid); 231 int virNetworkGetUUIDString (virNetworkPtr network, 232 char *buf); 233 char * virNetworkGetXMLDesc (virNetworkPtr network, 234 unsigned int flags); 235 char * virNetworkGetBridgeName (virNetworkPtr network); 236 237 int virNetworkGetAutostart (virNetworkPtr network, 238 int *autostart); 239 int virNetworkSetAutostart (virNetworkPtr network, 240 int autostart); 241 242 int virNetworkIsActive(virNetworkPtr net); 243 int virNetworkIsPersistent(virNetworkPtr net); 244 245 /** 246 * virNetworkEventLifecycleType: 247 * 248 * a virNetworkEventLifecycleType is emitted during network lifecycle events 249 */ 250 typedef enum { 251 VIR_NETWORK_EVENT_DEFINED = 0, 252 VIR_NETWORK_EVENT_UNDEFINED = 1, 253 VIR_NETWORK_EVENT_STARTED = 2, 254 VIR_NETWORK_EVENT_STOPPED = 3, 255 256 # ifdef VIR_ENUM_SENTINELS 257 VIR_NETWORK_EVENT_LAST 258 # endif 259 } virNetworkEventLifecycleType; 260 261 /** 262 * virConnectNetworkEventLifecycleCallback: 263 * @conn: connection object 264 * @net: network on which the event occurred 265 * @event: The specific virNetworkEventLifeCycleType which occurred 266 * @detail: contains some details on the reason of the event. 267 * It will be 0 for the while. 268 * @opaque: application specified data 269 * 270 * This callback occurs when the network is started or stopped. 271 * 272 * The callback signature to use when registering for an event of type 273 * VIR_NETWORK_EVENT_ID_LIFECYCLE with virConnectNetworkEventRegisterAny() 274 */ 275 typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn, 276 virNetworkPtr net, 277 int event, 278 int detail, 279 void *opaque); 280 281 /** 282 * VIR_NETWORK_EVENT_CALLBACK: 283 * 284 * Used to cast the event specific callback into the generic one 285 * for use for virConnectNetworkEventRegisterAny() 286 */ 287 # define VIR_NETWORK_EVENT_CALLBACK(cb) ((virConnectNetworkEventGenericCallback)(cb)) 288 289 /** 290 * virNetworkEventID: 291 * 292 * An enumeration of supported eventId parameters for 293 * virConnectNetworkEventRegisterAny(). Each event id determines which 294 * signature of callback function will be used. 295 */ 296 typedef enum { 297 VIR_NETWORK_EVENT_ID_LIFECYCLE = 0, /* virConnectNetworkEventLifecycleCallback */ 298 299 # ifdef VIR_ENUM_SENTINELS 300 VIR_NETWORK_EVENT_ID_LAST 301 /* 302 * NB: this enum value will increase over time as new events are 303 * added to the libvirt API. It reflects the last event ID supported 304 * by this version of the libvirt API. 305 */ 306 # endif 307 } virNetworkEventID; 308 309 typedef enum { 310 VIR_IP_ADDR_TYPE_IPV4, 311 VIR_IP_ADDR_TYPE_IPV6, 312 313 # ifdef VIR_ENUM_SENTINELS 314 VIR_IP_ADDR_TYPE_LAST 315 # endif 316 } virIPAddrType; 317 318 typedef struct _virNetworkDHCPLease virNetworkDHCPLease; 319 typedef virNetworkDHCPLease *virNetworkDHCPLeasePtr; 320 struct _virNetworkDHCPLease { 321 char *iface; /* Network interface name */ 322 long long expirytime; /* Seconds since epoch */ 323 int type; /* virIPAddrType */ 324 char *mac; /* MAC address */ 325 char *iaid; /* IAID */ 326 char *ipaddr; /* IP address */ 327 unsigned int prefix; /* IP address prefix */ 328 char *hostname; /* Hostname */ 329 char *clientid; /* Client ID or DUID */ 330 }; 331 332 void virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease); 333 334 int virNetworkGetDHCPLeases(virNetworkPtr network, 335 const char *mac, 336 virNetworkDHCPLeasePtr **leases, 337 unsigned int flags); 338 339 /** 340 * virConnectNetworkEventGenericCallback: 341 * @conn: the connection pointer 342 * @net: the network pointer 343 * @opaque: application specified data 344 * 345 * A generic network event callback handler, for use with 346 * virConnectNetworkEventRegisterAny(). Specific events usually 347 * have a customization with extra parameters, often with @opaque being 348 * passed in a different parameter position; use VIR_NETWORK_EVENT_CALLBACK() 349 * when registering an appropriate handler. 350 */ 351 typedef void (*virConnectNetworkEventGenericCallback)(virConnectPtr conn, 352 virNetworkPtr net, 353 void *opaque); 354 355 /* Use VIR_NETWORK_EVENT_CALLBACK() to cast the 'cb' parameter */ 356 int virConnectNetworkEventRegisterAny(virConnectPtr conn, 357 virNetworkPtr net, /* Optional, to filter */ 358 int eventID, 359 virConnectNetworkEventGenericCallback cb, 360 void *opaque, 361 virFreeCallback freecb); 362 363 int virConnectNetworkEventDeregisterAny(virConnectPtr conn, 364 int callbackID); 365 366 367 virNetworkPortPtr 368 virNetworkPortLookupByUUID(virNetworkPtr net, 369 const unsigned char *uuid); 370 371 virNetworkPortPtr 372 virNetworkPortLookupByUUIDString(virNetworkPtr net, 373 const char *uuidstr); 374 375 typedef enum { 376 VIR_NETWORK_PORT_CREATE_RECLAIM = (1 << 0), /* reclaim existing used resources */ 377 VIR_NETWORK_PORT_CREATE_VALIDATE = (1 << 1), /* Validate the XML document against schema */ 378 } virNetworkPortCreateFlags; 379 380 virNetworkPortPtr 381 virNetworkPortCreateXML(virNetworkPtr net, 382 const char *xmldesc, 383 unsigned int flags); 384 385 virNetworkPtr 386 virNetworkPortGetNetwork(virNetworkPortPtr port); 387 388 char * 389 virNetworkPortGetXMLDesc(virNetworkPortPtr port, 390 unsigned int flags); 391 392 int 393 virNetworkPortGetUUID(virNetworkPortPtr port, 394 unsigned char *uuid); 395 int 396 virNetworkPortGetUUIDString(virNetworkPortPtr port, 397 char *buf); 398 399 /* Management of interface parameters */ 400 401 /** 402 * VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE: 403 * 404 * Macro represents the inbound average of NIC bandwidth, as a uint. 405 */ 406 # define VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE "inbound.average" 407 408 /** 409 * VIR_NETWORK_PORT_BANDWIDTH_IN_PEAK: 410 * 411 * Macro represents the inbound peak of NIC bandwidth, as a uint. 412 */ 413 # define VIR_NETWORK_PORT_BANDWIDTH_IN_PEAK "inbound.peak" 414 415 /** 416 * VIR_NETWORK_PORT_BANDWIDTH_IN_BURST: 417 * 418 * Macro represents the inbound burst of NIC bandwidth, as a uint. 419 */ 420 # define VIR_NETWORK_PORT_BANDWIDTH_IN_BURST "inbound.burst" 421 422 /** 423 * VIR_NETWORK_PORT_BANDWIDTH_IN_FLOOR: 424 * 425 * Macro represents the inbound floor of NIC bandwidth, as a uint. 426 */ 427 # define VIR_NETWORK_PORT_BANDWIDTH_IN_FLOOR "inbound.floor" 428 429 /** 430 * VIR_NETWORK_PORT_BANDWIDTH_OUT_AVERAGE: 431 * 432 * Macro represents the outbound average of NIC bandwidth, as a uint. 433 */ 434 # define VIR_NETWORK_PORT_BANDWIDTH_OUT_AVERAGE "outbound.average" 435 436 /** 437 * VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK: 438 * 439 * Macro represents the outbound peak of NIC bandwidth, as a uint. 440 */ 441 # define VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK "outbound.peak" 442 443 /** 444 * VIR_NETWORK_PORT_BANDWIDTH_OUT_BURST: 445 * 446 * Macro represents the outbound burst of NIC bandwidth, as a uint. 447 */ 448 # define VIR_NETWORK_PORT_BANDWIDTH_OUT_BURST "outbound.burst" 449 450 int 451 virNetworkPortSetParameters(virNetworkPortPtr port, 452 virTypedParameterPtr params, 453 int nparams, 454 unsigned int flags); 455 int 456 virNetworkPortGetParameters(virNetworkPortPtr port, 457 virTypedParameterPtr *params, 458 int *nparams, 459 unsigned int flags); 460 461 int 462 virNetworkPortDelete(virNetworkPortPtr port, 463 unsigned int flags); 464 465 int 466 virNetworkListAllPorts(virNetworkPtr network, 467 virNetworkPortPtr **ports, 468 unsigned int flags); 469 470 int 471 virNetworkPortFree(virNetworkPortPtr port); 472 473 int 474 virNetworkPortRef(virNetworkPortPtr port); 475 476 #endif /* LIBVIRT_NETWORK_H */ 477