< Back
Connect-PrtgServer
Post
NAME Connect-PrtgServer
SYNOPSIS
Initializes a new instance of a PrtgClient. This cmdlet must be called at least once before attempting to use any
other cmdlets.
SYNTAX
Connect-PrtgServer [-Server] <string> [-Credential] <PSCredential> [-Force <SwitchParameter>] [-IgnoreSSL
<SwitchParameter>] [-LogLevel {None | Trace | Request | Response | All}] [-PassHash <SwitchParameter>] [-PassThru
<SwitchParameter>] [-Progress <SwitchParameter>] [-RetryCount <int>] [-RetryDelay <int>] [<CommonParameters>]
DESCRIPTION
The Connect-PrtgServer cmdlet establishes a new connection to a PRTG Server. As PRTG uses a stateless REST API,
Connect-PrtgServer initializes a PrtgClient which stores the settings that will be used when generating each
request.
PRTG supports two authentication methods: username/password and username/passhash. A PassHash is a numeric
password generated by PRTG that can be used in place of your regular password. When your PrtgClient is
initialized, if you have specified a password PrtgAPI will automatically retrieve your account's PassHash for use
in all future requests.
By default when PRTG times out while processing a request PrtgAPI will throw an exception. This can be quite
problematic when attempting to batch process a large number of items with PrtgAPI in PowerShell. You can request
PrtgAPI automatically attempt to retry failed requests by specifying the -RetryCount and -RetryDelay parameters.
If -RetryCount is greater than 0, PrtgAPI will send a warning to the pipeline indicating a failure has occurred,
as well as the number of retries remaining before PrtgAPI gives up. Each request invocation uses a separate retry
count.
If a protocol is not specified, PrtgAPI will connect with HTTPS. If your PRTG Server is HTTP only, this will cause
an exception. For HTTP only servers, prefix your URL with http://
When Connect-PrtgServer is run from outside of a script or the PowerShell ISE, PrtgAPI will display PowerShell
progress when piping between PrtgAPI cmdlets or when piping from variables containing PrtgAPI objects. This
default setting can be overridden by specifying a value to the -Progress parameter, or by using the
Enable-PrtgProgress and Disable-PrtgProgress cmdlets.
Attempting to invoke Connect-PrtgServer after a PrtgClient has already been initialized for the current session
will generate an exception. To override the existing PrtgClient, specify the -Force parameter to
Connect-PrtgServer, or invalidate the PrtgClient by calling Disconnect-PrtgServer. The current PrtgClient can be
retrieved via the Get-PrtgClient cmdlet. This cmdlet can also be used to detect whether a connection is active. If
you wish to retrieve the PrtgClient immediately upon connecting to PRTG, this can be achieved by specifying the
-PassThru parameter to Connect-PrtgServer.
For information on viewing and editing the session's PrtgClient settings see Get-Help Get-PrtgClient.
PARAMETERS
-Server <string>
Specifies the PRTG Server requests will be made against.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
Specifies the username and password to authenticate with. If PassHash is specified, the password will be
treated as a PassHash instead.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Force <SwitchParameter>
Forces a PrtgClient to be replaced if one already exists.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-PassHash <SwitchParameter>
Specifies that the Credential's password contains a PassHash instead of a Password.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-RetryCount <int>
The number of times to retry a request that times out while communicating with PRTG.
Required? false
Position? named
Default value 1
Accept pipeline input? false
Accept wildcard characters? false
-RetryDelay <int>
The base delay (in seconds) between retrying a timed out request. Each successive failure of a given request
will wait an additional multiple of this value.
Required? false
Position? named
Default value 3
Accept pipeline input? false
Accept wildcard characters? false
-LogLevel <LogLevel[]>
The type of events to log when -Verbose is specified.
Possible values: None, Trace, Request, Response, All
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Progress <SwitchParameter>
Enable or disable PowerShell Progress when piping between cmdlets. By default, if Connect-PrtgServer is being
called from within a script or the PowerShell ISE this value is false. Otherwise, true.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-PassThru <SwitchParameter>
Specifies whether to return the PrtgClient that was passed to this cmdlet, allowing the object to be further
piped into additional cmdlets.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-IgnoreSSL <SwitchParameter>
Whether to ignore SSL certificate errors encountered when communicating with your Server. In Windows
PowerShell affects all requests for the life of your process.
Required? false
Position? named
Default value False
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
System.Management.Automation.PSCredential
Specifies the username and password to authenticate with. If PassHash is specified, the password will be
treated as a PassHash instead.
OUTPUTS
---------- EXAMPLE 1 ----------
C:\\> Connect-PrtgServer prtg.example.com
Connect to a PRTG Server. You will receive a login prompt requesting you enter your credentials.
---------- EXAMPLE 2 ----------
C:\\> Connect-PrtgServer prtg.example.com (New-Credential prtgadmin prtgadmin)
Connect to a PRTG Server specifying your credentials as part of the command. The New-Credential cmdlet can be used
when developing scripts to avoid a login prompt.
---------- EXAMPLE 3 ----------
C:\\> Connect-PrtgServer prtg.example2.com -Force
Connect to a PRTG Server, overriding the session's existing PrtgClient (if applicable)
---------- EXAMPLE 4 ----------
C:\\> Connect-PrtgServer http://prtg.example.com
Connect to a PRTG Server using HTTP. http:// must be specified for servers that do not accept HTTPS.
---------- EXAMPLE 5 ----------
if(!(Get-PrtgClient))
{
Connect-PrtgServer prtg.example.com
}
Connect to a PRTG Server only if an existing connection is not active.
---------- EXAMPLE 6 ----------
C:\\> $client = Connect-PrtgServer prtg.example.com -PassThru
Connect to a PRTG Server, storing the PrtgClient for later use.
---------- EXAMPLE 7 ----------
C:\\> Connect-PrtgServer prtg.example.com -RetryCount 3 -RetryDelay 5
Connect to a PRTG Server, indicating that any requests that fail during the use of the PrtgClient should be
attempted at most 3 times, with a delay of 5 seconds between each attempt.
RELATED LINKS
Online version: https://github.com/lordmilko/PrtgAPI/wi ... powershell
Get-PrtgClient
Set-PrtgClient
Disconnect-PrtgServer
Enable-PrtgProgress
Disable-PrtgProgress
Install-GoPrtgServer
Connect-GoPrtgServer
SYNOPSIS
Initializes a new instance of a PrtgClient. This cmdlet must be called at least once before attempting to use any
other cmdlets.
SYNTAX
Connect-PrtgServer [-Server] <string> [-Credential] <PSCredential> [-Force <SwitchParameter>] [-IgnoreSSL
<SwitchParameter>] [-LogLevel {None | Trace | Request | Response | All}] [-PassHash <SwitchParameter>] [-PassThru
<SwitchParameter>] [-Progress <SwitchParameter>] [-RetryCount <int>] [-RetryDelay <int>] [<CommonParameters>]
DESCRIPTION
The Connect-PrtgServer cmdlet establishes a new connection to a PRTG Server. As PRTG uses a stateless REST API,
Connect-PrtgServer initializes a PrtgClient which stores the settings that will be used when generating each
request.
PRTG supports two authentication methods: username/password and username/passhash. A PassHash is a numeric
password generated by PRTG that can be used in place of your regular password. When your PrtgClient is
initialized, if you have specified a password PrtgAPI will automatically retrieve your account's PassHash for use
in all future requests.
By default when PRTG times out while processing a request PrtgAPI will throw an exception. This can be quite
problematic when attempting to batch process a large number of items with PrtgAPI in PowerShell. You can request
PrtgAPI automatically attempt to retry failed requests by specifying the -RetryCount and -RetryDelay parameters.
If -RetryCount is greater than 0, PrtgAPI will send a warning to the pipeline indicating a failure has occurred,
as well as the number of retries remaining before PrtgAPI gives up. Each request invocation uses a separate retry
count.
If a protocol is not specified, PrtgAPI will connect with HTTPS. If your PRTG Server is HTTP only, this will cause
an exception. For HTTP only servers, prefix your URL with http://
When Connect-PrtgServer is run from outside of a script or the PowerShell ISE, PrtgAPI will display PowerShell
progress when piping between PrtgAPI cmdlets or when piping from variables containing PrtgAPI objects. This
default setting can be overridden by specifying a value to the -Progress parameter, or by using the
Enable-PrtgProgress and Disable-PrtgProgress cmdlets.
Attempting to invoke Connect-PrtgServer after a PrtgClient has already been initialized for the current session
will generate an exception. To override the existing PrtgClient, specify the -Force parameter to
Connect-PrtgServer, or invalidate the PrtgClient by calling Disconnect-PrtgServer. The current PrtgClient can be
retrieved via the Get-PrtgClient cmdlet. This cmdlet can also be used to detect whether a connection is active. If
you wish to retrieve the PrtgClient immediately upon connecting to PRTG, this can be achieved by specifying the
-PassThru parameter to Connect-PrtgServer.
For information on viewing and editing the session's PrtgClient settings see Get-Help Get-PrtgClient.
PARAMETERS
-Server <string>
Specifies the PRTG Server requests will be made against.
Required? true
Position? 0
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Credential <PSCredential>
Specifies the username and password to authenticate with. If PassHash is specified, the password will be
treated as a PassHash instead.
Required? true
Position? 1
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? false
-Force <SwitchParameter>
Forces a PrtgClient to be replaced if one already exists.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-PassHash <SwitchParameter>
Specifies that the Credential's password contains a PassHash instead of a Password.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-RetryCount <int>
The number of times to retry a request that times out while communicating with PRTG.
Required? false
Position? named
Default value 1
Accept pipeline input? false
Accept wildcard characters? false
-RetryDelay <int>
The base delay (in seconds) between retrying a timed out request. Each successive failure of a given request
will wait an additional multiple of this value.
Required? false
Position? named
Default value 3
Accept pipeline input? false
Accept wildcard characters? false
-LogLevel <LogLevel[]>
The type of events to log when -Verbose is specified.
Possible values: None, Trace, Request, Response, All
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Progress <SwitchParameter>
Enable or disable PowerShell Progress when piping between cmdlets. By default, if Connect-PrtgServer is being
called from within a script or the PowerShell ISE this value is false. Otherwise, true.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-PassThru <SwitchParameter>
Specifies whether to return the PrtgClient that was passed to this cmdlet, allowing the object to be further
piped into additional cmdlets.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-IgnoreSSL <SwitchParameter>
Whether to ignore SSL certificate errors encountered when communicating with your Server. In Windows
PowerShell affects all requests for the life of your process.
Required? false
Position? named
Default value False
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
System.Management.Automation.PSCredential
Specifies the username and password to authenticate with. If PassHash is specified, the password will be
treated as a PassHash instead.
OUTPUTS
---------- EXAMPLE 1 ----------
C:\\> Connect-PrtgServer prtg.example.com
Connect to a PRTG Server. You will receive a login prompt requesting you enter your credentials.
---------- EXAMPLE 2 ----------
C:\\> Connect-PrtgServer prtg.example.com (New-Credential prtgadmin prtgadmin)
Connect to a PRTG Server specifying your credentials as part of the command. The New-Credential cmdlet can be used
when developing scripts to avoid a login prompt.
---------- EXAMPLE 3 ----------
C:\\> Connect-PrtgServer prtg.example2.com -Force
Connect to a PRTG Server, overriding the session's existing PrtgClient (if applicable)
---------- EXAMPLE 4 ----------
C:\\> Connect-PrtgServer http://prtg.example.com
Connect to a PRTG Server using HTTP. http:// must be specified for servers that do not accept HTTPS.
---------- EXAMPLE 5 ----------
if(!(Get-PrtgClient))
{
Connect-PrtgServer prtg.example.com
}
Connect to a PRTG Server only if an existing connection is not active.
---------- EXAMPLE 6 ----------
C:\\> $client = Connect-PrtgServer prtg.example.com -PassThru
Connect to a PRTG Server, storing the PrtgClient for later use.
---------- EXAMPLE 7 ----------
C:\\> Connect-PrtgServer prtg.example.com -RetryCount 3 -RetryDelay 5
Connect to a PRTG Server, indicating that any requests that fail during the use of the PrtgClient should be
attempted at most 3 times, with a delay of 5 seconds between each attempt.
RELATED LINKS
Online version: https://github.com/lordmilko/PrtgAPI/wi ... powershell
Get-PrtgClient
Set-PrtgClient
Disconnect-PrtgServer
Enable-PrtgProgress
Disable-PrtgProgress
Install-GoPrtgServer
Connect-GoPrtgServer