Receive-XenHostBackup

Last published : Nov 12, 2026
Downloads data from the server using the 'get\_host\_backup' HTTP interface.
Related information
File transfer cmdlets

Syntax

Receive-XenHostBackup -XenHost <string> -Path <string>
    [-DataCopiedDelegate <HTTP.DataCopiedDelegate>] [-CancellingDelegate <HTTP.FuncBool>]
    [-TimeoutMs <int>] [-Proxy <IWebProxy>]
    [-CertificateValidationCallback <RemoteCertificateValidationCallback>]
    [-NoWarnNewCertificates] [-NoWarnCertificates] [-TaskRef <string>] [-BestEffort]
    [-SessionOpaqueRef <string>] [<CommonParameters>]

Description

This cmdlet wraps the 'get\_host\_backup' HTTP interface of the server. Downloads data from the server over HTTP(S).

Parameters

-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

-CancellingDelegate

A delegate polled during the transfer; returning true cancels it.
Attribute Value
Type HTTP.FuncBool
Required False
Position Named
Accepts pipeline input False

-CertificateValidationCallback

A callback used to validate the server's TLS certificate.
Attribute Value
Type RemoteCertificateValidationCallback
Required False
Position Named
Accepts pipeline input False

-DataCopiedDelegate

A delegate called with the number of bytes copied so far.
Attribute Value
Type HTTP.DataCopiedDelegate
Required False
Position Named
Accepts pipeline input False

-NoWarnCertificates

If set, no warning is issued for certificate validation failures.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-NoWarnNewCertificates

If set, no warning is issued when the server presents a certificate that has not been seen before.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Path

The path of the local file to read from or write to.
Attribute Value
Type string
Required True
Position Named
Accepts pipeline input False

-Proxy

The web proxy to use for the request.
Attribute Value
Type IWebProxy
Required False
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

-TaskRef

The opaque reference of a task to track the transfer with.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-TimeoutMs

The timeout of the HTTP request, in milliseconds.
Attribute Value
Type int
Required False
Position Named
Accepts pipeline input False

-XenHost

The address of the server to transfer data with.
Attribute Value
Type string
Required True
Position Named
Accepts pipeline input False

Inputs

  • None

Outputs

  • void

Examples

Example 1: Download a file from the server

PS> Receive-XenHostBackup -XenHost "myserver" -Path "C:\download.dat"
Downloads from the server into the local file.

Example 2: Set a timeout for the transfer

PS> Receive-XenHostBackup -XenHost "myserver" -Path "C:\download.dat" -TimeoutMs 600000
Gives the transfer ten minutes. The timeout covers the HTTP request, not the API call that set it up.

Example 3: Use an existing session

PS> Receive-XenHostBackup -XenHost "myserver" -Path "C:\download.dat" -SessionOpaqueRef $session.opaque_ref
Runs against a session already opened with Connect-XenServer rather than the default one, which is how a script drives more than one server at a time.