Class: PIF

Last published : Oct 01, 2026
A physical network interface note separate VLANs are represented as several PIFs
Related information
XenServer 9 Management API

Fields for class: PIF

Field Type Qualifier Description
bond_master_of Bond ref set RO/runtime Indicates this PIF represents the results of a bond
bond_slave_of Bond ref RO/runtime Indicates which bond this interface is part of
capabilities string set RO/runtime Additional capabilities on the interface.
currently_attached bool RO/runtime true if this interface is online
device string RO/constructor machine-readable name of the interface (for example, eth0)
disallow_unplug bool RO/runtime Prevent this PIF from being unplugged; set this to notify the management tool-stack that the PIF has a special use and should not be unplugged under any circumstances (for example, because you're running storage traffic over it)
DNS string RO/runtime Comma separated list of the IP addresses of the DNS servers to use
gateway string RO/runtime IP gateway
host host ref RO/constructor physical machine to which this pif is connected
igmp_snooping_status pif_igmp_status RO/runtime The IGMP snooping status of the corresponding network bridge
IP string RO/runtime IP address
ip_configuration_mode ip_configuration_mode RO/runtime Sets if and how this interface gets an IP address
IPv6 string set RO/runtime IPv6 address
ipv6_configuration_mode ipv6_configuration_mode RO/runtime Sets if and how this interface gets an IPv6 address
ipv6_gateway string RO/runtime IPv6 gateway
MAC string RO/constructor ethernet MAC address of physical interface
managed bool RO/constructor Indicates whether the interface is managed by xapi. If it is not, then xapi will not configure the interface, the commands PIF.plug/unplug/reconfigure_ip(v6) cannot be used, nor can the interface be bonded or have VLANs based on top through xapi.
management bool RO/runtime Indicates whether the control software is listening for connections on this interface
metrics PIF_metrics ref RO/runtime metrics associated with this PIF
MTU int RO/constructor MTU in octets
netmask string RO/runtime IP netmask
network network ref RO/constructor virtual network to which this pif is connected
other_config (string -> string) map RW Additional configuration
PCI PCI ref RO/runtime Link to underlying PCI device
physical bool RO/runtime true if this represents a physical network interface
primary_address_type primary_address_type RO/runtime Which protocol should define the primary address of this interface
properties (string -> string) map RO/runtime Additional configuration properties for the interface.
sriov_logical_PIF_of network_sriov ref set RO/runtime Indicates which network_sriov this interface is logical of
sriov_physical_PIF_of network_sriov ref set RO/runtime Indicates which network_sriov this interface is physical of
tunnel_access_PIF_of tunnel ref set RO/runtime Indicates to which tunnel this PIF gives access
tunnel_transport_PIF_of tunnel ref set RO/runtime Indicates to which tunnel this PIF provides transport
uuid string RO/runtime Unique identifier/object reference
VLAN int RO/constructor VLAN tag for all traffic passing through this interface
VLAN_master_of VLAN ref RO/runtime Indicates which VLAN this interface receives untagged traffic from
VLAN_slave_of VLAN ref set RO/runtime Indicates which VLANs this interface transmits tagged traffic to

RPCs associated with class: PIF

RPC name: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given PIF.
Signature:
void add_to_other_config (session ref session_ref, PIF ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
string key Key to add
string value Value to add
Minimum Role: pool-operator
Return Type: void

RPC name: createVLAN

This message is deprecated.
Overview:
Create a VLAN interface from an existing physical interface. This call is deprecated: use VLAN.create instead
Signature:
PIF ref create_VLAN (session ref session_ref, string device, network ref network, host ref host, int VLAN)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string device physical interface on which to create the VLAN interface
network ref network network to which this interface should be connected
host ref host physical machine to which this PIF is connected
int VLAN VLAN tag for the new interface
Minimum Role: pool-operator
Return Type: PIF ref
The reference of the created PIF object
Possible Error Codes: VLAN_TAG_INVALID

RPC name: dbforget

Overview:
Destroy a PIF database record.
Signature:
void db_forget (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self The ref of the PIF whose database record should be destroyed
Minimum Role: pool-operator
Return Type: void

RPC name: dbintroduce

Overview:
Create a new PIF record in the database only
Signature:
PIF ref db_introduce (session ref session_ref, string device, network ref network, host ref host, string MAC, int MTU, int VLAN, bool physical, ip_configuration_mode ip_configuration_mode, string IP, string netmask, string gateway, string DNS, Bond ref bond_slave_of, VLAN ref VLAN_master_of, bool management, (string -> string) map other_config, bool disallow_unplug, ipv6_configuration_mode ipv6_configuration_mode, string set IPv6, string ipv6_gateway, primary_address_type primary_address_type, bool managed, (string -> string) map properties)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string device
network ref network
host ref host
string MAC
int MTU
int VLAN
bool physical
ip_configuration_mode ip_configuration_mode
string IP
string netmask
string gateway
string DNS
Bond ref bond_slave_of
VLAN ref VLAN_master_of
bool management
(string -> string) map other_config
bool disallow_unplug
ipv6_configuration_mode ipv6_configuration_mode
string set IPv6
string ipv6_gateway
primary_address_type primary_address_type
bool managed
(string -> string) map properties
Minimum Role: pool-operator
Return Type: PIF ref
The ref of the newly created PIF record.

RPC name: destroy

This message is deprecated.
Overview:
Destroy the PIF object provided it is a VLAN interface. This call is deprecated: use VLAN.destroy or Bond.destroy instead
Signature:
void destroy (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self the PIF object to destroy
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: PIF_IS_PHYSICAL

RPC name: forget

Overview:
Destroy the PIF object matching a particular network interface
Signature:
void forget (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self The PIF object to destroy
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: PIF_TUNNEL_STILL_EXISTS, CLUSTERING_ENABLED

RPC name: getall

Overview:
Return a list of all the PIFs known to the system.
Signature:
PIF ref set get_all (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: PIF ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of PIF references to PIF records for all PIFs known to the system.
Signature:
(PIF ref -> PIF record) map get_all_records (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: (PIF ref -> PIF record) map
records of all objects

RPC name: getbondmasterof

Overview:
Get the bondmasterof field of the given PIF.
Signature:
Bond ref set get_bond_master_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: Bond ref set
value of the field

RPC name: getbondslaveof

Overview:
Get the bondslaveof field of the given PIF.
Signature:
Bond ref get_bond_slave_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: Bond ref
value of the field

RPC name: getbyuuid

Overview:
Get a reference to the PIF instance with the specified UUID.
Signature:
PIF ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: PIF ref
reference to the object

RPC name: getcapabilities

Overview:
Get the capabilities field of the given PIF.
Signature:
string set get_capabilities (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string set
value of the field

RPC name: getcurrentlyattached

Overview:
Get the currentlyattached field of the given PIF.
Signature:
bool get_currently_attached (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getdevice

Overview:
Get the device field of the given PIF.
Signature:
string get_device (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getdisallowunplug

Overview:
Get the disallowunplug field of the given PIF.
Signature:
bool get_disallow_unplug (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getDNS

Overview:
Get the DNS field of the given PIF.
Signature:
string get_DNS (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getgateway

Overview:
Get the gateway field of the given PIF.
Signature:
string get_gateway (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: gethost

Overview:
Get the host field of the given PIF.
Signature:
host ref get_host (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: host ref
value of the field

RPC name: getigmpsnoopingstatus

Overview:
Get the igmpsnoopingstatus field of the given PIF.
Signature:
pif_igmp_status get_igmp_snooping_status (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: pif_igmp_status
value of the field

RPC name: getIP

Overview:
Get the IP field of the given PIF.
Signature:
string get_IP (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getipconfigurationmode

Overview:
Get the ipconfigurationmode field of the given PIF.
Signature:
ip_configuration_mode get_ip_configuration_mode (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: ip_configuration_mode
value of the field

RPC name: getIPv6

Overview:
Get the IPv6 field of the given PIF.
Signature:
string set get_IPv6 (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string set
value of the field

RPC name: getipv6configurationmode

Overview:
Get the ipv6configurationmode field of the given PIF.
Signature:
ipv6_configuration_mode get_ipv6_configuration_mode (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: ipv6_configuration_mode
value of the field

RPC name: getipv6gateway

Overview:
Get the ipv6gateway field of the given PIF.
Signature:
string get_ipv6_gateway (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getMAC

Overview:
Get the MAC field of the given PIF.
Signature:
string get_MAC (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getmanaged

Overview:
Get the managed field of the given PIF.
Signature:
bool get_managed (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getmanagement

Overview:
Get the management field of the given PIF.
Signature:
bool get_management (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getmetrics

Overview:
Get the metrics field of the given PIF.
Signature:
PIF_metrics ref get_metrics (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: PIF_metrics ref
value of the field

RPC name: getMTU

Overview:
Get the MTU field of the given PIF.
Signature:
int get_MTU (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getnetmask

Overview:
Get the netmask field of the given PIF.
Signature:
string get_netmask (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getnetwork

Overview:
Get the network field of the given PIF.
Signature:
network ref get_network (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: network ref
value of the field

RPC name: getotherconfig

Overview:
Get the otherconfig field of the given PIF.
Signature:
(string -> string) map get_other_config (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getPCI

Overview:
Get the PCI field of the given PIF.
Signature:
PCI ref get_PCI (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: PCI ref
value of the field

RPC name: getphysical

Overview:
Get the physical field of the given PIF.
Signature:
bool get_physical (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getprimaryaddresstype

Overview:
Get the primaryaddresstype field of the given PIF.
Signature:
primary_address_type get_primary_address_type (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: primary_address_type
value of the field

RPC name: getproperties

Overview:
Get the properties field of the given PIF.
Signature:
(string -> string) map get_properties (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getrecord

Overview:
Get a record containing the current state of the given PIF.
Signature:
PIF record get_record (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: PIF record
all fields from the object

RPC name: getsriovlogicalPIFof

Overview:
Get the sriovlogicalPIFof field of the given PIF.
Signature:
network_sriov ref set get_sriov_logical_PIF_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: network_sriov ref set
value of the field

RPC name: getsriovphysicalPIFof

Overview:
Get the sriovphysicalPIFof field of the given PIF.
Signature:
network_sriov ref set get_sriov_physical_PIF_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: network_sriov ref set
value of the field

RPC name: gettunnelaccessPIFof

Overview:
Get the tunnelaccessPIFof field of the given PIF.
Signature:
tunnel ref set get_tunnel_access_PIF_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: tunnel ref set
value of the field

RPC name: gettunneltransportPIFof

Overview:
Get the tunneltransportPIFof field of the given PIF.
Signature:
tunnel ref set get_tunnel_transport_PIF_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: tunnel ref set
value of the field

RPC name: getuuid

Overview:
Get the uuid field of the given PIF.
Signature:
string get_uuid (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getVLAN

Overview:
Get the VLAN field of the given PIF.
Signature:
int get_VLAN (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getVLANmasterof

Overview:
Get the VLANmasterof field of the given PIF.
Signature:
VLAN ref get_VLAN_master_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: VLAN ref
value of the field

RPC name: getVLANslaveof

Overview:
Get the VLANslaveof field of the given PIF.
Signature:
VLAN ref set get_VLAN_slave_of (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
Minimum Role: read-only
Return Type: VLAN ref set
value of the field

RPC name: introduce

Overview:
Create a PIF object matching a particular network interface
Signature:
PIF ref introduce (session ref session_ref, host ref host, string MAC, string device, bool managed)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
host ref host The host on which the interface exists
string MAC The MAC address of the interface
string device The device name to use for the interface
bool managed Indicates whether the interface is managed by xapi (defaults to "true")
Minimum Role: pool-operator
Return Type: PIF ref
The reference of the created PIF object

RPC name: plug

Overview:
Attempt to bring up a physical interface
Signature:
void plug (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self the PIF object to plug
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: TRANSPORT_PIF_NOT_CONFIGURED

RPC name: reconfigureip

Overview:
Reconfigure the IP address settings for this interface
Signature:
void reconfigure_ip (session ref session_ref, PIF ref self, ip_configuration_mode mode, string IP, string netmask, string gateway, string DNS)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self the PIF object to reconfigure
ip_configuration_mode mode whether to use dynamic/static/no-assignment
string IP the new IP address
string netmask the new netmask
string gateway the new gateway
string DNS the new DNS settings
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: CLUSTERING_ENABLED

RPC name: reconfigureipv6

Overview:
Reconfigure the IPv6 address settings for this interface
Signature:
void reconfigure_ipv6 (session ref session_ref, PIF ref self, ipv6_configuration_mode mode, string IPv6, string gateway, string DNS)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self the PIF object to reconfigure
ipv6_configuration_mode mode whether to use dynamic/static/no-assignment
string IPv6 the new IPv6 address (in <addr>/<prefix length> format)
string gateway the new gateway
string DNS the new DNS settings
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: CLUSTERING_ENABLED

RPC name: removefromotherconfig

Overview:
Remove the given key and its corresponding value from the otherconfig field of the given PIF. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session ref session_ref, PIF ref self, string key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
string key Key to remove
Minimum Role: pool-operator
Return Type: void

RPC name: scan

Overview:
Scan for physical interfaces on a host and create PIF objects to represent them
Signature:
void scan (session ref session_ref, host ref host)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
host ref host The host on which to scan
Minimum Role: pool-operator
Return Type: void

RPC name: setdisallowunplug

Overview:
Set whether unplugging the PIF is allowed
Signature:
void set_disallow_unplug (session ref session_ref, PIF ref self, bool value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self Reference to the object
bool value New value to set
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: OTHER_OPERATION_IN_PROGRESS, CLUSTERING_ENABLED

RPC name: setotherconfig

Overview:
Set the otherconfig field of the given PIF.
Signature:
void set_other_config (session ref session_ref, PIF ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self reference to the object
(string -> string) map value New value to set
Minimum Role: pool-operator
Return Type: void

RPC name: setprimaryaddresstype

Overview:
Change the primary address type used by this PIF
Signature:
void set_primary_address_type (session ref session_ref, PIF ref self, primary_address_type primary_address_type)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self the PIF object to reconfigure
primary_address_type primary_address_type Whether to prefer IPv4 or IPv6 connections
Minimum Role: pool-operator
Return Type: void

RPC name: setproperty

Overview:
Set the value of a property of the PIF
Signature:
void set_property (session ref session_ref, PIF ref self, string name, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self The PIF
string name The property name
string value The property value
Minimum Role: pool-operator
Return Type: void

RPC name: unplug

Overview:
Attempt to bring down a physical interface
Signature:
void unplug (session ref session_ref, PIF ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
PIF ref self the PIF object to unplug
Minimum Role: pool-operator
Return Type: void
Possible Error Codes: HA_OPERATION_WOULD_BREAK_FAILOVER_PLAN, VIF_IN_USE, PIF_DOES_NOT_ALLOW_UNPLUG, PIF_HAS_FCOE_SR_IN_USE