Update src/integrations.datto.ps1
This commit is contained in:
@@ -1,3 +1,161 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Installs the Datto RMM agent and/or performs Datto RMM site operations using API or webhook-provided credentials.
|
||||
|
||||
.DESCRIPTION
|
||||
Install-DattoRMM can obtain Datto RMM API credentials either directly (ApiUrl/ApiKey/ApiSecretKey) or via a webhook
|
||||
(-UseWebhook). It then acquires an OAuth token and can:
|
||||
- Fetch sites (-FetchSites), optionally saving the list to CSV/JSON (-SaveSitesList, -OutputFile)
|
||||
- Pull a site's variables and write them to the registry (-PushSiteVars, -SiteUID, -SiteName)
|
||||
- Download and launch the RMM agent installer for a site (-InstallRMM, -SiteUID, -SiteName)
|
||||
- Download and save a copy of the installer (-SaveCopy, -SiteUID)
|
||||
|
||||
.PARAMETER UseWebhook
|
||||
If specified, retrieves API credentials from the webhook endpoint specified by -WebhookUrl.
|
||||
If not specified, -ApiUrl/-ApiKey/-ApiSecretKey must be provided.
|
||||
|
||||
.PARAMETER WebhookPassword
|
||||
Optional shared secret sent as the SAMYPW header when calling the webhook.
|
||||
If null, it is treated as a blank string (intended for allowlisted IP flows).
|
||||
|
||||
.PARAMETER WebhookUrl
|
||||
Webhook endpoint to retrieve Datto RMM API credentials. Defaults to $Global:DattoWebhookUrl.
|
||||
|
||||
.PARAMETER ApiUrl
|
||||
Base URL of the Datto RMM instance (for example, https://rmm.example.com).
|
||||
Required when -UseWebhook is not specified.
|
||||
|
||||
.PARAMETER ApiKey
|
||||
Datto RMM API key (used as the OAuth username in the token request).
|
||||
Required when -UseWebhook is not specified.
|
||||
|
||||
.PARAMETER ApiSecretKey
|
||||
Datto RMM API secret key (used as the OAuth password in the token request).
|
||||
Required when -UseWebhook is not specified.
|
||||
|
||||
.PARAMETER FetchSites
|
||||
If specified, fetches the full site list from the Datto RMM API and returns objects with Name and UID.
|
||||
|
||||
.PARAMETER SaveSitesList
|
||||
If specified, saves the fetched site list to disk. Requires -FetchSites.
|
||||
The output format is determined by -OutputFile extension:
|
||||
- .csv (default): CSV output
|
||||
- .json: JSON output
|
||||
|
||||
.PARAMETER OutputFile
|
||||
Filename to write when using -SaveSitesList. Defaults to 'datto_sites.csv'.
|
||||
The file is written to the current user's Desktop.
|
||||
|
||||
.PARAMETER PushSiteVars
|
||||
If specified, fetches variables for the specified site and writes them to the registry at:
|
||||
HKLM:\Software\SVS\Deployment
|
||||
Requires -SiteUID. -SiteName is used for logging.
|
||||
|
||||
.PARAMETER InstallRMM
|
||||
If specified, downloads the Datto RMM agent installer for -SiteUID to %TEMP%\AgentInstall.exe and launches it.
|
||||
Requires -SiteUID. -SiteName is used for logging. Respects ShouldProcess/Confirm.
|
||||
|
||||
.PARAMETER SaveCopy
|
||||
If specified, downloads the Datto RMM agent installer for -SiteUID and saves it to:
|
||||
C:\Temp\AgentInstall.exe
|
||||
Requires -SiteUID.
|
||||
|
||||
.PARAMETER SiteUID
|
||||
Datto RMM Site UID used for site-scoped operations such as variable fetch, agent download/install, and save-copy.
|
||||
|
||||
.PARAMETER SiteName
|
||||
Friendly site name used for logging/output messages for site-scoped operations. Not required by the API calls.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites
|
||||
|
||||
Fetches the full site list from the Datto RMM API and returns objects containing Name and UID.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList
|
||||
|
||||
Fetches the site list and saves it as a CSV named "datto_sites.csv" on the current user's Desktop (default -OutputFile),
|
||||
then returns the site list.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList -OutputFile "sites.csv"
|
||||
|
||||
Fetches the site list and saves it as "sites.csv" on the Desktop.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList -OutputFile "sites.json"
|
||||
|
||||
Fetches the site list and saves it as JSON ("sites.json") on the Desktop.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -WebhookPassword "SuperSecret" -FetchSites -SaveSitesList
|
||||
|
||||
Uses the webhook endpoint to retrieve API credentials, then fetches sites and saves "datto_sites.csv" to the Desktop.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -UseWebhook -WebhookUrl "https://internal.example.com/datto-creds" -FetchSites
|
||||
|
||||
Uses the webhook endpoint to retrieve API credentials, then fetches and returns the site list.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -FetchSites -SaveSitesList -OutputFile "customer_sites.csv"
|
||||
|
||||
Same as the other webhook fetch, but writes the CSV as "customer_sites.csv" on the Desktop.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -PushSiteVars -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ"
|
||||
|
||||
Fetches variables for the specified site and writes each variable name/value into:
|
||||
HKLM:\Software\SVS\Deployment
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -PushSiteVars -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ"
|
||||
|
||||
Uses webhook-sourced credentials, then fetches and writes site variables to the registry.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ"
|
||||
|
||||
Downloads the agent installer for the specified SiteUID to %TEMP%\AgentInstall.exe and launches it.
|
||||
Because SupportsShouldProcess is enabled, this may prompt unless -Confirm:$false is used.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" -Confirm:$false
|
||||
|
||||
Installs the agent without prompting for confirmation.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" -Confirm:$false
|
||||
|
||||
Uses webhook credentials, downloads the installer, and launches it without confirmation.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -SaveCopy -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab"
|
||||
|
||||
Downloads the agent installer and saves a copy to:
|
||||
C:\Temp\AgentInstall.exe
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -SaveCopy -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab"
|
||||
|
||||
Uses webhook credentials, then downloads and saves the installer copy to C:\Temp\AgentInstall.exe.
|
||||
|
||||
.EXAMPLE
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET"
|
||||
|
||||
If no action switch is specified (-FetchSites, -PushSiteVars, -InstallRMM, or -SaveCopy),
|
||||
the function logs a warning indicating that no action was selected.
|
||||
|
||||
.EXAMPLE
|
||||
# Get the site list, then pick a site and install using its UID
|
||||
$sites = Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites
|
||||
$site = $sites | Where-Object Name -like "*Toronto*" | Select-Object -First 1
|
||||
Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID $site.UID -SiteName $site.Name -Confirm:$false
|
||||
|
||||
Demonstrates a common flow: fetch sites, select one, then install the agent for that site.
|
||||
#>
|
||||
|
||||
|
||||
function Install-DattoRMM {
|
||||
[CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium')]
|
||||
param (
|
||||
|
||||
Reference in New Issue
Block a user