< Back
Connect-NsxServer
Post
NAME Connect-NsxServer
SYNOPSIS
Connects to the specified NSX server and constructs a connection object.
SYNTAX
Connect-NsxServer [-Server] <String> [-Port <Int32>] [-Credential <PSCredential>] [-Username <String>] [-Password
<String>] [-ValidateCertificate] [-Protocol <String>] [-UriPrefix <String>] [-DefaultConnection <Boolean>]
[-VIDefaultConnection <Boolean>] [-DisableVIAutoConnect] [-VIUserName <String>] [-VIPassword <String>]
[-VICredential <PSCredential>] [-DebugLogging] [-DebugLogFile <String>] [-ViWarningAction <String>]
[<CommonParameters>]
Connect-NsxServer -NsxServer <String> [-Port <Int32>] [-Credential <PSCredential>] [-Username <String>] [-Password
<String>] [-ValidateCertificate] [-Protocol <String>] [-UriPrefix <String>] [-DefaultConnection <Boolean>]
[-VIDefaultConnection <Boolean>] [-DisableVIAutoConnect] [-VIUserName <String>] [-VIPassword <String>]
[-VICredential <PSCredential>] [-DebugLogging] [-DebugLogFile <String>] [-ViWarningAction <String>]
[<CommonParameters>]
Connect-NsxServer -vCenterServer <String> [-NsxServerHint <String>] [-Port <Int32>] [-Credential <PSCredential>]
[-Username <String>] [-Password <String>] [-ValidateCertificate] [-Protocol <String>] [-UriPrefix <String>]
[-DefaultConnection <Boolean>] [-VIDefaultConnection <Boolean>] [-DebugLogging] [-DebugLogFile <String>]
[-ViWarningAction <String>] [<CommonParameters>]
DESCRIPTION
The Connect-NsxServer cmdlet returns a connection object that contains
the necessary information for PowerNSX cmdlets to locate and authenticate
to NSX server in order to perform REST API calls.
Because the underlying REST protocol is not connection oriented, the
'Connection' concept relates to just validating endpoint details and
credentials and storing details relevant to the NSX manager endpoint.
NOTE:
Previous releases of PowerNSX required the user to specify the NSX manager
endpoint directly and required the use of an NSX manager local account
with super_user privileges.
This behaviour as a default is now DEPRECATED and will be removed in a
future release (the ability to connect directly to NSX using the admin
account will not be removed, but will no longer be the default behaviour)
The preferred method for most PowerNSX use is now to use the -vCenterServer
parameter to specify the vCenter server that NSX is connected to, along with
appropriate SSO credentials to authenticate to NSX. This will become the
default behaviour in a future version (ie. will not require a -vCenterServer
parameter name and will replace the current default behaviour of assuming
the first argument specified without a parameter to be the desired NSX
server endpoint.)
Full support for all NSX roles is now available in NSX. (cmdlets that
attempt API operations not supported by the users role will throw
appropriate not authorised errors from the API.)
Minimum required rights are vCenter Inventory ReadOnly and NSX Auditor role.
PARAMETERS
-Server <String>
NSX Manager address or FQDN. Deprecated. Use -vCenterServer with SSO credentials as preferred method, or
-NsxServer with appliance admin user if required.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NsxServer <String>
NSX Manager address or FQDN. Recommended method is to use -vCenterServer with SSO credentials. Use this for
cmdlets requiring local appliance credentials(Appliance Management and Central CLI).
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-vCenterServer <String>
vCenter Server address or FQDN (not NSX Manager!). Used to determine NSX Server endpoint and authenticate
using SSO credentials. Recommended method.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NsxServerHint <String>
NSX Manager address used to override that registered in vCenter. Used for scenarios where NSX manager is
behind a NAT device.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Port <Int32>
TCP Port to connect to on -Server
Required? false
Position? named
Default value 443
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
PSCredential object containing NSX API authentication credentials
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Username <String>
Username used to authenticate to NSX API
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Password <String>
Password used to authenticate to NSX API
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ValidateCertificate [<SwitchParameter>]
Validates the certificate presented by NSX Manager for HTTPS connections. Defaults to False
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Protocol <String>
NSX API transport protocol - HTTPS / HTTP . Defaults to HTTPS
Required? false
Position? named
Default value https
Accept pipeline input? false
Accept wildcard characters? false
-UriPrefix <String>
NSX API URI prefix. Supports reverse proxy in between client and NSX doing URI rewrites so that uri is
prepended with $UriPrefix
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-DefaultConnection <Boolean>
If True, the $DefaultNsxConnection global variable is created and populated with connection details.
All PowerNSX commands that use the NSX API will utilise this connection unless they are called with the
-connection parameter.
Defaults to True
Required? false
Position? named
Default value True
Accept pipeline input? false
Accept wildcard characters? false
-VIDefaultConnection <Boolean>
If False, and a PowerCLI connection needs to be established to the registered vCenter, the Connect-ViServer
call made by PowerNSX will specify the -NotDefault switch (see Get-Help Connect-ViServer)
Defaults to True
Required? false
Position? named
Default value True
Accept pipeline input? false
Accept wildcard characters? false
-DisableVIAutoConnect [<SwitchParameter>]
If True, and the PowerNSX connection attempt is successful, an automatic PowerCLI connection to the registered
vCenter server is not attempted. Defaults to False.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-VIUserName <String>
UserName used in PowerCLI connection to registered vCenter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-VIPassword <String>
Password used in PowerCLI connection to registered vCenter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-VICredential <PSCredential>
PSCredential object containing credentials used in PowerCLI connection to registered vCenter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-DebugLogging [<SwitchParameter>]
Enable DebugLogging of all API calls to $DebugLogFile. Can be enabled on esisting connections with
$connection.DebugLogging = $true. Defaults to False.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-DebugLogFile <String>
If DebugLogging is enabled, specifies the file to which output is written. Defaults to
$Env:temp\\PowerNSXLog-<user>@<server>-<datetime>.log
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ViWarningAction <String>
Supresses warning output from PowerCLI connection attempts (typically invalid Certificate warnings)
Required? false
Position? named
Default value Continue
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local
Connect to vCenter server vcenter.corp.local to determine the NSX server IP
and return an appropriate connection object. SSO Credentials will
be prompted for and will be used for both vCenter and NSX authentication.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local -credential $cred
Connect to vCenter server vcenter.corp.local using the SSO credentials in $cred
to determine the NSX server IP and return an appropriate connection object.
The credentials specified in -credential are used for both vCenter connection
(if not already established) AND SSO authentication to NSX server.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local -username me@vsphere.local -password secret
Connect to vCenter server vcenter.corp.local using the SSO credentials in
-username and -password to determine the NSX server IP and return an
appropriate connection object.
The credentials specified in -credential are used for both vCenter connection
(if not already established) AND SSO authentication to NSX server.
-------------------------- EXAMPLE 4 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local -credential $cred -VIDefaultConnection:$false
Connect to vCenter server vcenter.corp.local using the SSO credentials in
-username and -password to determine the NSX server IP and return an
appropriate connection object. The PowerCLi connection stored in the returned
connection object is NOT stored in $DefaultViServer.
-------------------------- EXAMPLE 5 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1!
Connects to the nsxserver 'nsxserver' with the specified credentials. If a
registered vCenter server is configured in NSX manager, you are prompted to
establish a PowerCLI session to that vCenter along with required
authentication details.
-------------------------- EXAMPLE 6 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1! -DisableViAutoConnect
Connects to the nsxserver 'nsxserver' with the specified credentials and
supresses the prompt to establish a PowerCLI connection with the registered
vCenter.
-------------------------- EXAMPLE 7 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1! -ViUserName
administrator@vsphere.local -ViPassword VMware1!
Connects to the nsxserver 'nsxserver' with the specified credentials and
automatically establishes a PowerCLI connection with the registered
vCenter using the credentials specified.
-------------------------- EXAMPLE 8 --------------------------
PS C:\\>$MyConnection = Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1!
-DefaultConnection:$false
Get-NsxTransportZone 'TransportZone1' -connection $MyConnection
Connects to the nsxserver 'nsxserver' with the specified credentials and
then uses the returned connection object in a subsequent call to
Get-NsxTransportZone. The $DefaultNsxConnection parameter is not populated
Note: Any PowerNSX cmdlets will fail if the -connection parameters is not
specified and the $DefaultNsxConnection variable is not populated.
Note: Pipline operations involving multiple PowerNSX commands that interact
with the NSX API (not all) require that all cmdlets specify the -connection
parameter (not just the fist one.)
-------------------------- EXAMPLE 9 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1! -ViUserName
administrator@vsphere.local -ViPassword VMware1! -UriPRefix /other
Automatically prepends /other to the URI used to access the NSX REST API for
all PowerNSX cmdlets using the associated connection. UriPrefix is intended
to allow for a reverse proxy that is doing URL rewriting in front of NSX.
Connects to the nsxserver 'nsxserver' with the specified credentials and
automatically establishes a PowerCLI connection with the registered
vCenter using the credentials specified.
RELATED LINKS
SYNOPSIS
Connects to the specified NSX server and constructs a connection object.
SYNTAX
Connect-NsxServer [-Server] <String> [-Port <Int32>] [-Credential <PSCredential>] [-Username <String>] [-Password
<String>] [-ValidateCertificate] [-Protocol <String>] [-UriPrefix <String>] [-DefaultConnection <Boolean>]
[-VIDefaultConnection <Boolean>] [-DisableVIAutoConnect] [-VIUserName <String>] [-VIPassword <String>]
[-VICredential <PSCredential>] [-DebugLogging] [-DebugLogFile <String>] [-ViWarningAction <String>]
[<CommonParameters>]
Connect-NsxServer -NsxServer <String> [-Port <Int32>] [-Credential <PSCredential>] [-Username <String>] [-Password
<String>] [-ValidateCertificate] [-Protocol <String>] [-UriPrefix <String>] [-DefaultConnection <Boolean>]
[-VIDefaultConnection <Boolean>] [-DisableVIAutoConnect] [-VIUserName <String>] [-VIPassword <String>]
[-VICredential <PSCredential>] [-DebugLogging] [-DebugLogFile <String>] [-ViWarningAction <String>]
[<CommonParameters>]
Connect-NsxServer -vCenterServer <String> [-NsxServerHint <String>] [-Port <Int32>] [-Credential <PSCredential>]
[-Username <String>] [-Password <String>] [-ValidateCertificate] [-Protocol <String>] [-UriPrefix <String>]
[-DefaultConnection <Boolean>] [-VIDefaultConnection <Boolean>] [-DebugLogging] [-DebugLogFile <String>]
[-ViWarningAction <String>] [<CommonParameters>]
DESCRIPTION
The Connect-NsxServer cmdlet returns a connection object that contains
the necessary information for PowerNSX cmdlets to locate and authenticate
to NSX server in order to perform REST API calls.
Because the underlying REST protocol is not connection oriented, the
'Connection' concept relates to just validating endpoint details and
credentials and storing details relevant to the NSX manager endpoint.
NOTE:
Previous releases of PowerNSX required the user to specify the NSX manager
endpoint directly and required the use of an NSX manager local account
with super_user privileges.
This behaviour as a default is now DEPRECATED and will be removed in a
future release (the ability to connect directly to NSX using the admin
account will not be removed, but will no longer be the default behaviour)
The preferred method for most PowerNSX use is now to use the -vCenterServer
parameter to specify the vCenter server that NSX is connected to, along with
appropriate SSO credentials to authenticate to NSX. This will become the
default behaviour in a future version (ie. will not require a -vCenterServer
parameter name and will replace the current default behaviour of assuming
the first argument specified without a parameter to be the desired NSX
server endpoint.)
Full support for all NSX roles is now available in NSX. (cmdlets that
attempt API operations not supported by the users role will throw
appropriate not authorised errors from the API.)
Minimum required rights are vCenter Inventory ReadOnly and NSX Auditor role.
PARAMETERS
-Server <String>
NSX Manager address or FQDN. Deprecated. Use -vCenterServer with SSO credentials as preferred method, or
-NsxServer with appliance admin user if required.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NsxServer <String>
NSX Manager address or FQDN. Recommended method is to use -vCenterServer with SSO credentials. Use this for
cmdlets requiring local appliance credentials(Appliance Management and Central CLI).
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-vCenterServer <String>
vCenter Server address or FQDN (not NSX Manager!). Used to determine NSX Server endpoint and authenticate
using SSO credentials. Recommended method.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-NsxServerHint <String>
NSX Manager address used to override that registered in vCenter. Used for scenarios where NSX manager is
behind a NAT device.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Port <Int32>
TCP Port to connect to on -Server
Required? false
Position? named
Default value 443
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
PSCredential object containing NSX API authentication credentials
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Username <String>
Username used to authenticate to NSX API
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Password <String>
Password used to authenticate to NSX API
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ValidateCertificate [<SwitchParameter>]
Validates the certificate presented by NSX Manager for HTTPS connections. Defaults to False
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Protocol <String>
NSX API transport protocol - HTTPS / HTTP . Defaults to HTTPS
Required? false
Position? named
Default value https
Accept pipeline input? false
Accept wildcard characters? false
-UriPrefix <String>
NSX API URI prefix. Supports reverse proxy in between client and NSX doing URI rewrites so that uri is
prepended with $UriPrefix
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-DefaultConnection <Boolean>
If True, the $DefaultNsxConnection global variable is created and populated with connection details.
All PowerNSX commands that use the NSX API will utilise this connection unless they are called with the
-connection parameter.
Defaults to True
Required? false
Position? named
Default value True
Accept pipeline input? false
Accept wildcard characters? false
-VIDefaultConnection <Boolean>
If False, and a PowerCLI connection needs to be established to the registered vCenter, the Connect-ViServer
call made by PowerNSX will specify the -NotDefault switch (see Get-Help Connect-ViServer)
Defaults to True
Required? false
Position? named
Default value True
Accept pipeline input? false
Accept wildcard characters? false
-DisableVIAutoConnect [<SwitchParameter>]
If True, and the PowerNSX connection attempt is successful, an automatic PowerCLI connection to the registered
vCenter server is not attempted. Defaults to False.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-VIUserName <String>
UserName used in PowerCLI connection to registered vCenter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-VIPassword <String>
Password used in PowerCLI connection to registered vCenter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-VICredential <PSCredential>
PSCredential object containing credentials used in PowerCLI connection to registered vCenter.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-DebugLogging [<SwitchParameter>]
Enable DebugLogging of all API calls to $DebugLogFile. Can be enabled on esisting connections with
$connection.DebugLogging = $true. Defaults to False.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-DebugLogFile <String>
If DebugLogging is enabled, specifies the file to which output is written. Defaults to
$Env:temp\\PowerNSXLog-<user>@<server>-<datetime>.log
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ViWarningAction <String>
Supresses warning output from PowerCLI connection attempts (typically invalid Certificate warnings)
Required? false
Position? named
Default value Continue
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local
Connect to vCenter server vcenter.corp.local to determine the NSX server IP
and return an appropriate connection object. SSO Credentials will
be prompted for and will be used for both vCenter and NSX authentication.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local -credential $cred
Connect to vCenter server vcenter.corp.local using the SSO credentials in $cred
to determine the NSX server IP and return an appropriate connection object.
The credentials specified in -credential are used for both vCenter connection
(if not already established) AND SSO authentication to NSX server.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local -username me@vsphere.local -password secret
Connect to vCenter server vcenter.corp.local using the SSO credentials in
-username and -password to determine the NSX server IP and return an
appropriate connection object.
The credentials specified in -credential are used for both vCenter connection
(if not already established) AND SSO authentication to NSX server.
-------------------------- EXAMPLE 4 --------------------------
PS C:\\>Connect-NsxServer -vCenterServer vcenter.corp.local -credential $cred -VIDefaultConnection:$false
Connect to vCenter server vcenter.corp.local using the SSO credentials in
-username and -password to determine the NSX server IP and return an
appropriate connection object. The PowerCLi connection stored in the returned
connection object is NOT stored in $DefaultViServer.
-------------------------- EXAMPLE 5 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1!
Connects to the nsxserver 'nsxserver' with the specified credentials. If a
registered vCenter server is configured in NSX manager, you are prompted to
establish a PowerCLI session to that vCenter along with required
authentication details.
-------------------------- EXAMPLE 6 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1! -DisableViAutoConnect
Connects to the nsxserver 'nsxserver' with the specified credentials and
supresses the prompt to establish a PowerCLI connection with the registered
vCenter.
-------------------------- EXAMPLE 7 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1! -ViUserName
administrator@vsphere.local -ViPassword VMware1!
Connects to the nsxserver 'nsxserver' with the specified credentials and
automatically establishes a PowerCLI connection with the registered
vCenter using the credentials specified.
-------------------------- EXAMPLE 8 --------------------------
PS C:\\>$MyConnection = Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1!
-DefaultConnection:$false
Get-NsxTransportZone 'TransportZone1' -connection $MyConnection
Connects to the nsxserver 'nsxserver' with the specified credentials and
then uses the returned connection object in a subsequent call to
Get-NsxTransportZone. The $DefaultNsxConnection parameter is not populated
Note: Any PowerNSX cmdlets will fail if the -connection parameters is not
specified and the $DefaultNsxConnection variable is not populated.
Note: Pipline operations involving multiple PowerNSX commands that interact
with the NSX API (not all) require that all cmdlets specify the -connection
parameter (not just the fist one.)
-------------------------- EXAMPLE 9 --------------------------
PS C:\\>Connect-NsxServer -NsxServer nsxserver -username admin -Password VMware1! -ViUserName
administrator@vsphere.local -ViPassword VMware1! -UriPRefix /other
Automatically prepends /other to the URI used to access the NSX REST API for
all PowerNSX cmdlets using the associated connection. UriPrefix is intended
to allow for a reverse proxy that is doing URL rewriting in front of NSX.
Connects to the nsxserver 'nsxserver' with the specified credentials and
automatically establishes a PowerCLI connection with the registered
vCenter using the credentials specified.
RELATED LINKS