Skip to content

Commit 339d5a0

Browse files
AngryProgrammerInsideAngryProgrammerInside
committed
More documentation and picture updates
Update to Custom Service to handle nulls
1 parent 1c4c9c3 commit 339d5a0

1 file changed

Lines changed: 50 additions & 41 deletions

File tree

‎ReadMe.md‎

Lines changed: 50 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ These tools are provided as-is, in the best of faith, by those Partners and Comm
5454
* Functioning N-Central AMP scripts that support 2 methods for updating the configuration file used for installation
5555
* Direct update of Customer ID/Registration Token and other values from N-Central Custom Property (CP) injected via N-Central API See: [How to N-Central API Automation](https://github.com/AngryProgrammerInside/NC-API-Documentation) for examples
5656
* Automatic update of Customer ID/Registration token from values pulled from local Agent/Maintenance XML along with provided JWT (see above documentation)
57+
* Functioning N-Central AMP script to update/renew expired/expiring tokens
5758
* Legacy Support: If you still have old values within your GPO, you can use a flag within the LaunchInstaller.bat to ignore provided parameters and rely upon the configuration file
5859
* Custom installation method data
5960
* Through additional modules you can use your own source for CustomerID/Registration Token enumeration
@@ -174,33 +175,32 @@ The **Deployment Package** is suitable by itself for all deployments, and contai
174175
* **InstallAgent.ps1** - **Agent Setup Script,** the main/wrapper script, which contains most pre-defined constants and structures for execution
175176
* **LaunchInstaller.bat** - **Agent Setup Launcher,** the launcher script, which is called On-Demand (click-to-run) or by Group Policy (calling the Launcher by either method **requires an N-Central Customer/Site ID number as a Parameter for any new Agent installations**)
176177
* **PartnerConfig.xml** - **Partner Configuration,** which is used to dictate most variable options to the **Agent Setup Script**
177-
* **AMP Config Updater** folder
178-
* **Refresh Agent from JWT-API.amp** - **AMP wrapper**, for below ps1 file that uses local agent information and a JWT token to automatically populate a PartnerConfig.xml
179-
* **Refresh Agent Token from JWT-API.ps1** - **PS Code** for populating PartnerConfig
180-
* **Refresh Agent Token from CP.amp** - **AMP wrapper**, for below ps1 file that populates the PartnerConfig from your N-Central Customer Property
181-
* **Refresh Agent Token from CP.ps1** - **PS Code** for populating PartnerConfig from CP
178+
* **AMPs** folder
179+
* **Refresh Agent Token.amp** - AMP wrapper for below token refresh/update PS1 file
180+
* **Refresh Agent Token.ps1** - Core code for refreshing/updating tokens inside of N-Central without human interaction
181+
* **Update PartnerConfig from JWT-API.amp** - **AMP wrapper**, for below ps1 file that uses local agent information and a JWT token to automatically populate a PartnerConfig.xml
182+
* **Update PartnerConfig from JWT-API.ps1** - **PS Code** for populating PartnerConfig
183+
* **Update PartnerConfig from CP.amp** - **AMP wrapper**, for below ps1 file that populates the PartnerConfig from your N-Central Customer Property
184+
* **Update PartnerConfig from CP.ps1** - **PS Code** for populating PartnerConfig from CP
182185
* **Custom Library** folder
183186
* **CustomOverrideExample.psm1** - Example function overrides for extended Azure telemetry capability
184187
* **GetCustomInstallMethodExamples.psm1** - Example function to override or change your install method data. This function is called by default at the approriate time just prior to validation checks
185188
* **LibReadme.md** - Brief instruction on usage of above files
186-
* **Custom Service Package** folder
187-
* **CustomService.ps1** Core logic for the custom service AMP file
188-
* **Agent Installer v6.amp** Wrapper for the CustomService to upload into N-Central
189+
189190

190191
<sup>1</sup> Download Instructions for these items are included at the designated location in order to reduce overall package size, as they are already freely available on the web
191192

192193
## AMP-Based Custom Service Package
193194

194195
The **Custom Service Package** is an optional download available with the **Deployment Package,** which integrates with N-Central to collect and monitor information about the most recent run of the **Deployment Package.**
195196

196-
***ATTENTION - The Custom Service Package is no longer compatible with Deployment Package 5.0.0 and above***
197-
198197
The **Custom Service Package** contains the following items:
199198

200-
* **CustomService** Folder - Not required for any other Packages
201-
* **InstallAgent status.amp** - Automation Policy run by the Custom Service
202-
* **InstallAgent status - Tim Wiser.amp** - Automation Policy run by the Custom Service, for **Deployment Packages** still using Tim's Registry key (4.01 and Below)
203-
* **Agent Installer Script Status.xml** - Custom Service Configuration file
199+
* **Custom Service Package** Folder - Not required for any other Packages
200+
* **Agent Installer v6.amp** - Automation Policy run by the Custom Service
201+
* **Custom Service.ps1** - Core logic of the above AMP file
202+
* **Agent Installer.xml** - The custom service file that you can import into N-Central
203+
204204

205205
## Custom PowerShell modules
206206
The default InstallAgent-Core.psm1 module provides the default behaviors, and now includes AzNableProxy token lookup by default.
@@ -285,17 +285,13 @@ Open **PartnerConfig.xml** to begin. This **Partner Configuration** is your one-
285285
| | *NETVersion* | 4.5.2 | Yes | User-Friendly Version of .NET Framework to install on Typical systems - for verification/logging purposes |
286286
| | *NETFileVersion* | 4.5.51209.34209 | Yes | Windows Version of the .NET Framework Installer to use on Typical systems, which should match the **File Version** property when you right-click **Properties > Details.** |
287287
| | *SOAgentFileName* | WindowsAgentSetup.exe | Yes | Name of the Agent Installer supplied in the Typical *InstallFolder* - change this each time you upgrade your N-Central Server, and **be sure to use the System-Level Agent Installer** |
288-
| | *SOAgentVersion* | 12.0.1.118 | Yes | User-Friendly (N-Central) Version of the Agent to install on Typical systems - for verification/logging purposes |
289-
| | *SOAgentFileVersion* | 12.0.10118.0 | Yes | Windows Version of the Agent Installer to use on Typical systems, which should match the **File Version** property when you right-click **Properties > Details.** |
288+
| | *SOAgentVersion* | 2020.1.5.425 | Yes | User-Friendly (N-Central) Version of the Agent to install on Typical systems - for verification/logging purposes |
289+
| | *SOAgentFileVersion* | 2020.1.50425.0 | Yes | Windows Version of the Agent Installer to use on Typical systems, which should match the **File Version** property when you right-click **Properties > Details.** |
290290
| | *CustomerId* | null | No | The Customer ID value as found under **Administration > Customers**, typically populated via a provided AMP|
291291
| | *RegistrationToken* | null | No | The Registration Token value as found under **Actions > Download Agent/Probe > Get Registration Token**, typically populated via a provided AMP|
292292
| | *AzNableProxyUri* | null | No | The URI of the AzNableProxy function as found under the function app overview but without the leading https:// , ie. mytokenproxy.azurewebsite.net. Typically updated via a provided AMP.|
293293
| | *AzNableAuthCode* | null | No | The AuthCode of the AzNableProxy function as found under the **Functions > GET function > Function Keys**. Typically updated via a provided AMP.|
294294

295-
296-
297-
298-
299295
Once you've made your adjustments, in most cases, you should be able to utilize the Configuration Values for your all your clients, but you may elect to customize them for specific environments. For example, you may wish to increase the *PingTolerance* for a Customer/Site where you know there is significant latency, and therefore Agents may have trouble reliably communicating with the N-Central Server.
300296

301297
A small amount of customization can also be made in the **Agent Launcher Script** (LaunchInstaller.bat):
@@ -416,17 +412,11 @@ Congratulations! Your **Group Policy Deployment** is ready for action!
416412

417413

418414
## OPTIONAL
419-
## 1a - Setup the N-Central Custom Service (Version 4.xx)
420-
<span style="color:red">
421-
***ATTENTION - The Custom Service Package is no longer compatible with Deployment Package 5.0.0 and above***</span>
422-
<span style="color:red">
423-
Another option for viewing results of the **Deployment Package** is to **Monitor the Registry updates it makes to the Device with N-Central.** You can setup the **Custom Service Package** to do exactly that! The current Version of the **Custom Service** is called **Agent Installer Script Status** in N-Central, and is compatible with the following:</span>
424-
425-
* **InstallAgent Deployment Package 4.xx**
426-
* **N-Central 9.5 SP1 and Above**
427-
<span style="color:red">
428-
For setup and configuration help, consult the appropriate SolarWinds MSP N-Central Documentation for **Importing a Custom Service.**</span>
415+
## 1a - Setup the N-Central Custom Service (Version 6.xx)
429416

417+
* **InstallAgent Deployment Package 6.xx**
418+
* **N-Able N-central 2020.1 HF5 and Above**
419+
For setup and configuration help, consult the appropriate SolarWinds MSP N-Central Documentation for **Importing a Custom Service.**
430420

431421
## 2 - Review Deployment Package Results
432422

@@ -530,22 +520,41 @@ Lastly in our example, the Agent Service Configuration has been compromised once
530520

531521
### N-Central Custom Service
532522

533-
***ATTENTION - The Custom Service Package is no longer compatible with Deployment Package 5.0.0 and above***
534-
535523
If you have setup the **Custom Service Package,** you can also review the results of the most recent run of the **Deployment Package** directly in N-Central!
536524

537-
A sample of output from the **Custom Service** in N-Central can be seen below:
525+
A sample of output from the **Custom Service** in N-Central can be seen below for a service in a healthy state:
538526

539527
![](media/readme-image0.png)
540528

541-
| Parameter | Thresholds | Description |
542-
| --------- | ---------- | ----------- |
543-
| *Date/Time of Last Execution* | None | Timestamp of most recent **Agent Setup Script** run |
544-
| *Path to Installer Files* | None | Location of the *NetworkFolder* |
545-
| *Script Version* | Warning on Outdated Version | Detected Version of the **Agent Setup Script** |
546-
| *Last Successful Completion* | None | Timestamp of last Successful result (Code 10) |
547-
| *Last Result Code* | Warning on Codes 1 thru 9, Failed on Code 0 | Exit Code returned by the most recent **Agent Setup Script** run |
548-
| *Last Execution Mode* | Warning on Interactive Mode | Execution Mode used by the most recent **Agent Setup Script** run |
529+
| Parameter |Type | Null value| Thresholds | Description |
530+
| --------- | --------- | --------- | ---------- | ----------- |
531+
| *Script Action*| String | - | **Not** Graceful Exit | The last action take by the Agent Installer |
532+
| *Script Exit Code* | Number | 404 | **Not** 0 | Exit code of the Agent Installer script |
533+
| *Script Version* | Number | 404 | Warning on Outdated Version | Detected Version of the **Agent Setup Script** |
534+
| *Script Result* | String | - | **Not** Script Completed Successfully | The last action take by the Agent Installer |
535+
| *Script Last Ran* | DateTime | 1/1/1900 | Default timedate threshold | Timestamp of last run |
536+
| *Script Mode* | String | - | None | Displays if GPO or On-Demand |
537+
| *Script Sequence* | String | - | The last point/function being called | Execution Mode used by the most recent **Agent Setup Script** run |
538+
| *Agent Last Diagnosed* | DateTime | 1/1/1900 | Default timedate threshold | Displays when the Diagnosis function last ran, typically this is each run |
539+
| *Agent Last Installed* | DateTime | 1/1/1900 | Default timedate threshold | Displays when the Agent called the Install function to deploy the package
540+
541+
<br>
542+
543+
When deploying the custom service package to a service template, it is recommmended to disable threshold monitoring of *Agent Last Diagnosed* and *Agent Last Installed* as the values may not always be available. It is optional to have a threshold on the *Script Last Ran* depending how often you reboot and how often you expect machines to run the Agent Installer script.
544+
545+
Some further examples of output you may encounter from the service:
546+
547+
| **Old version of script warning**|
548+
| -- |
549+
|![Old Version of script](media/readme-image9.png)|
550+
551+
| **Script has never run/registry values missing** |
552+
| -- |
553+
| ![No registry values](media/readme-image10.png) |
554+
555+
| **Agent upgrade failed** |
556+
| -- |
557+
| ![Agent upgrade failed](media/readme-image11.png) |
549558

550559

551560
# Testing and Troubleshooting

0 commit comments

Comments
 (0)