Connect-XenServer

Last published : Nov 12, 2026
Connects to a XenServer host or pool.
Related information
Connection and session cmdlets

Syntax

Connect-XenServer [-Url] <string[]> [[-UserName] <string>] [[-Password] <string>]
    [-Creds <PSCredential>] [-OpaqueRef <string[]>] [-Originator <string>]
    [-UserAgent <string>] [-PassThru] [-NoWarnNewCertificates] [-NoWarnCertificates]
    [-SetDefaultSession] [-Force] [<CommonParameters>]
Connect-XenServer [-Server] <string[]> [[-UserName] <string>] [[-Password] <string>]
    [-Port <int>] [-Creds <PSCredential>] [-OpaqueRef <string[]>] [-Originator <string>]
    [-UserAgent <string>] [-PassThru] [-NoWarnNewCertificates] [-NoWarnCertificates]
    [-SetDefaultSession] [-Force] [<CommonParameters>]

Description

Opens a session with a XenServer host and adds it to the set of connections the other cmdlets can use.
Every other cmdlet needs a session. Use -SetDefaultSession so the rest of the module picks this connection up implicitly; otherwise pass the session to each cmdlet with -SessionOpaqueRef.
Only the pool coordinator accepts logins. Connecting to any other member of a pool fails with HOST\_IS\_SLAVE, and the coordinator's address is the second element of the error's ErrorDescription, so a script that may be pointed at any host in a pool has to catch that and connect again. The last example does this.

Parameters

-Creds

The credentials to log in with, as returned by Get-Credential. Use this in preference to -UserName and -Password, which put the password in the command line and so into the session history.
Attribute Value
Type PSCredential
Required False
Position Named
Accepts pipeline input True (ByValue, ByPropertyName)
Aliases cred

-Force

If set, the cmdlet connects without prompting for confirmation.
Attribute Value
Type SwitchParameter
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

-OpaqueRef

The reference of a session that is already open on the server, to adopt instead of logging in again.
Attribute Value
Type string[]
Required False
Position Named
Accepts pipeline input False

-Originator

The name this client reports to the server, which appears in the server's logs and audit trail.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PassThru

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

-Password

The password to log in with.
Attribute Value
Type string
Required False
Position 2
Accepts pipeline input False
Aliases pwd

-Port

The port to connect on. Defaults to 443.
Attribute Value
Type int
Required False
Position Named
Accepts pipeline input False

-Server

The address of the server to connect to, as an alternative to -Url. More than one may be given.
Attribute Value
Type string[]
Required True
Position 0
Accepts pipeline input False
Aliases svr

-SetDefaultSession

If set, this session becomes the one the other cmdlets use when none is given explicitly.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Url

The URL of the server to connect to, for example https://myserver. More than one may be given, and a session is opened for each.
Attribute Value
Type string[]
Required True
Position 0
Accepts pipeline input False

-UserAgent

The user agent to send with requests to the server.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-UserName

The user to log in as.
Attribute Value
Type string
Required False
Position 1
Accepts pipeline input False
Aliases user

Inputs

  • PSCredential

Outputs

  • Session

Examples

Example 1: Connect and make it the default session

PS> $creds = Get-Credential
PS> Connect-XenServer -Url https://myserver -Creds $creds -SetDefaultSession
Opens a session and makes it the one every other cmdlet uses, so nothing else has to name it. Get-Credential prompts without echoing, which keeps the password out of the command line and out of the session history.

Example 2: Connect as a domain user

PS> $creds = Get-Credential MYDOMAIN\alice
PS> Connect-XenServer -Url https://myserver -Creds $creds -SetDefaultSession
Prefer an Active Directory account to the local root account. root is the pool's superuser and bypasses role-based access control, so what it does is neither restricted nor attributable to a person; a domain account gets the roles it has been granted and appears as itself in the audit log. Either MYDOMAIN\\alice or alice@mydomain.com is accepted.

Example 3: Connect from a script

PS> $secret = Read-Host -AsSecureString "Password"
PS> $creds = New-Object System.Management.Automation.PSCredential("MYDOMAIN\alice", $secret)
PS> Connect-XenServer -Url https://myserver -Creds $creds -SetDefaultSession
Where a script cannot prompt, build the credential itself. -UserName and -Password are accepted too, but they put the password in the command line.

Example 4: Keep the session to pass explicitly

PS> $creds = Get-Credential
PS> $session = Connect-XenServer -Url https://myserver -Creds $creds -PassThru
PS> Get-XenVM -SessionOpaqueRef $session.opaque_ref
-PassThru returns the session. Naming it on each cmdlet is how to work with more than one server at a time.

Example 5: Connect to several servers at once

PS> $creds = Get-Credential
PS> Connect-XenServer -Url https://server1, https://server2 -Creds $creds
A session is opened for each, and Get-XenSession lists them.

Example 6: Connect without being asked about the certificate

PS> $creds = Get-Credential MYDOMAIN\alice
PS> Connect-XenServer -Url https://myserver -Creds $creds -NoWarnCertificates -NoWarnNewCertificates -SetDefaultSession
A server presenting a certificate this client has not seen before, or one that does not validate, prompts for confirmation - which stalls an unattended script. These two switches answer the prompts instead. They suppress the warning rather than fix the cause, so a script that always sets them will not notice the day the certificate really is wrong.

Example 7: Connect to a pool without knowing which host is the coordinator

PS> $creds = Get-Credential MYDOMAIN\alice
PS> try {
      Connect-XenServer -Url https://myserver -Creds $creds -SetDefaultSession -PassThru
  }
  catch {
      $desc = $_.Exception.ErrorDescription
      if ($desc[0] -ne "HOST_IS_SLAVE") { throw }
      # $desc[1] is the coordinator's address
      Connect-XenServer -Url "https://$($desc[1])" -Creds $creds -SetDefaultSession -PassThru
  }
A pool member refuses the login rather than forwarding it, so a script given the address of whichever host answers has to retry against the coordinator itself. ErrorDescription\[0\] is the error code and ErrorDescription\[1\] is the coordinator's address. Re-throwing anything else matters: without that test this swallows a wrong password as readily as a wrong host. Nothing here is specific to certificates - add the switches from the previous example only if the prompts are also in the way.