New-XenBond

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

Syntax

New-XenBond -HashTable <hashtable> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>]
    [-WhatIf] [-Confirm] [-Async] [<CommonParameters>]
New-XenBond -Record <Bond> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>]
    [-WhatIf] [-Confirm] [-Async] [<CommonParameters>]
New-XenBond [-PassThru] [-Network <XenRef[Network]>] [-Members <List[XenRef[PIF]]>]
    [-MAC <string>] [-Mode {balance_slb | active_backup | lacp | unknown}]
    [-Properties <hashtable>] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf]
    [-Confirm] [-Async] [<CommonParameters>]

Description

Creates a new Bond object.
Bond.create: Create an interface bond.
Bond: A Network bond that combines physical network interfaces, also known as link aggregation.

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

-HashTable

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

-MAC

The MAC address to use on the bond itself. If this parameter is the empty string then the bond will inherit its MAC address from the primary member.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Members

PIFs to add to this bond
Attribute Value
Type List[XenRef[PIF]]
Required False
Position Named
Accepts pipeline input False

-Mode

Bonding mode to use for the new bond
Attribute Value
Type bond_mode
Required False
Position Named
Accepts pipeline input False
Accepted values balance_slb, active_backup, lacp, unknown

-Network

Network to add the bonded PIF to
Attribute Value
Type XenRef[Network]
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

-Properties

Additional configuration parameters specific to the bond mode
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-Record

An existing Bond record whose fields are used to create the new object.
Attribute Value
Type Bond
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

-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

  • Bond
  • Task
  • void

Examples

Example 1: Create a Bond

PS> $network = Get-XenNetwork | Select-Object -First 1
PS> $pif = Get-XenPIF | Select-Object -First 1
PS> New-XenBond -Network $network -Members $pif -MAC "value" -Mode balance_slb -Properties @{ "key" = "value" } -PassThru
New-XenBond takes the arguments of the create call rather than a record of fields, and needs all of them. -PassThru returns the new Bond.

Example 2: Create a Bond and wait for the task

PS> $network = Get-XenNetwork | Select-Object -First 1
PS> $pif = Get-XenPIF | Select-Object -First 1
PS> New-XenBond -Network $network -Members $pif -MAC "value" -Mode balance_slb -Properties @{ "key" = "value" } -Async -PassThru |
    Wait-XenTask -ShowProgress
-Async hands the work to the server and returns the Task that represents it, which pipes into Wait-XenTask.

Example 3: See what would be created

PS> $network = Get-XenNetwork | Select-Object -First 1
PS> $pif = Get-XenPIF | Select-Object -First 1
PS> New-XenBond -Network $network -Members $pif -MAC "value" -Mode balance_slb -Properties @{ "key" = "value" } -WhatIf
Reports what would be created without creating it. Every cmdlet that changes the server takes -WhatIf and -Confirm.
  • Bond cmdlets
  • Class: Bond
  • Using the XenServer PowerShell module