New-XenVIF

Last published : Nov 12, 2026
Creates a new VIF object.
Related information
VIF cmdlets

Syntax

New-XenVIF -HashTable <hashtable> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>]
    [-WhatIf] [-Confirm] [-Async] [<CommonParameters>]
New-XenVIF -Record <VIF> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf]
    [-Confirm] [-Async] [<CommonParameters>]
New-XenVIF [-PassThru] [-Device <string>] [-Network <XenRef[Network]>] [-VM <XenRef[VM]>]
    [-MAC <string>] [-MTU <long>] [-OtherConfig <hashtable>] [-CurrentlyAttached <bool>]
    [-QosAlgorithmType <string>] [-QosAlgorithmParams <hashtable>]
    [-LockingMode {network_default | locked | unlocked | disabled | unknown}]
    [-Ipv4Allowed <string[]>] [-Ipv6Allowed <string[]>] [-Trunks <long[]>] [-BestEffort]
    [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async] [<CommonParameters>]

Description

Creates a new VIF object.
VIF: A virtual network interface.

Parameters

-Async

If set, the operation runs asynchronously and returns a Task object that can be used to track its progress.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-BestEffort

If set, the cmdlet continues processing further objects instead of throwing a terminating error when an operation fails for one object.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Confirm

Prompts for confirmation before running the cmdlet.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases cf

-CurrentlyAttached

is the device currently attached (erased on reboot)
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Device

order in which VIF backends are created by xapi. Guaranteed to be an unsigned decimal integer.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-HashTable

A hashtable of field names to values, from which to create the VIF.
Attribute Value
Type hashtable
Required True
Position Named
Accepts pipeline input False

-Ipv4Allowed

A list of IPv4 addresses which can be used to filter traffic passing through this VIF
Attribute Value
Type string[]
Required False
Position Named
Accepts pipeline input False

-Ipv6Allowed

A list of IPv6 addresses which can be used to filter traffic passing through this VIF
Attribute Value
Type string[]
Required False
Position Named
Accepts pipeline input False

-LockingMode

current locking mode of the VIF
Attribute Value
Type vif_locking_mode
Required False
Position Named
Accepts pipeline input False
Accepted values network_default, locked, unlocked, disabled, unknown

-MAC

ethernet MAC address of virtual interface, as exposed to guest
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-MTU

MTU in octets
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-Network

virtual network to which this vif is connected
Attribute Value
Type XenRef[Network]
Required False
Position Named
Accepts pipeline input False

-OtherConfig

additional configuration
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-PassThru

If set, the cmdlet returns the affected object. By default the cmdlet does not generate any output.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-QosAlgorithmParams

parameters for chosen QoS algorithm
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-QosAlgorithmType

QoS algorithm to use
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Record

An existing VIF record whose fields are used to create the new object.
Attribute Value
Type VIF
Required True
Position Named
Accepts pipeline input False

-SessionOpaqueRef

The session object on which to run the cmdlet. This overrides the default session and lets you target a specific open XenServer connection.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Trunks

the 802.1Q VLANs that this port trunks (if available) ; if it is empty, then the port trunks all VLANs.
Attribute Value
Type long[]
Required False
Position Named
Accepts pipeline input False

-VM

virtual machine to which this vif is connected
Attribute Value
Type XenRef[VM]
Required False
Position Named
Accepts pipeline input False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases wi

Inputs

  • None

Outputs

  • VIF
  • Task
  • void

Examples

Example 1: Create a VIF from a table of fields

PS> New-XenVIF -HashTable @{ name_label = "Demo VIF" } -PassThru
The keys are the API's field names, so this form reads the same for every class whatever fields it happens to have. -PassThru returns the new VIF.

Example 2: Attach a VM to a network

PS> $vm = Get-XenVM -Name "web-01"
PS> $network = Get-XenNetwork -Name "storage"
PS> New-XenVIF -VM $vm -Network $network -Device "1" -PassThru
A VIF is the attachment between a VM and a network. -Device is the slot number as the guest sees it and has to be free; leaving the MAC unset lets the server generate one.

Example 3: Create a VIF from parameters

PS> New-XenVIF -Device "new value" -PassThru
The same thing with one parameter per field, which is the form that tab-completes. Get-Help New-XenVIF -Full lists them all.
  • VIF cmdlets
  • Class: VIF
  • Using the XenServer PowerShell module