GeoSync cmdlets
In this section:
About GeoSync
GeoSync setup is performed by cmdlets shipped with the personalization server. The cmdlets are automatically imported into a PowerShell session when Import-ApsInstancemodule is executed.
If the default Environment Manager install location is used, the cmdlets are here: C:\Program Files\AppSense\Environment Manager\Personaliztion Server\Support
The default date format of the SQL Configurer account must match the US date format (mm/dd/yyyy). Further details can be found in the GeoSync help topic, and in this article.
Use GeoSync with gMSA
GeoSync supports the use of a gMSA with the publisher and subscriber systems using the same gMSA for their database access. The geosync agent contacts the subscriber database directly using the gMSA identity.
The publisher and subscriber systems must be in the same Microsoft Entra ID forest.
To set up a subscriber with GeoSync cmdlets, specify the gMSA in the usual form (domain\account$). The cmdlets set this credential in the publisher database. When a synchronization starts, the agent checks that the synchronization is running under that gMSA.
Windows or SQL authentication remain functional on the subscriber regardless of whether the publisher uses a gMSA for its own database access.
GeoSync cmdlets
| Cmdlet | Description | Parameters |
|---|---|---|
| New-EMPSPublisher | Sets up the specified database as a publisher for GeoSync. This cmdlet operates in two modes - Live and Export. In Export mode, it exports a script which can be applied to a database to perform the operation. The script can requirementsbe tailored for advanced . |
Common parameters:
-PublisherServer -PublisherDatabase -DisplayName -Verbose -ConfigurerCredential -SecondaryReplicaServers -DatabaseMasterKeyPassword Live parameters: -ConfigurerCredential Export parameters: -ExportScript -ScriptFolder folder -Force |
| Remove-EMPSPublisher | Removes publisher functionality from a specified database. This cmdlet removes the publisher setup from a database, providing all subscribers have already been removed. If subscribers cannot be removed in the normal way, use the Reset-EMPSGeoSyncDatabase cmdlet. This cmdlet operates in live mode or export mode. |
Common parameters:
-PublisherServer -PublisherDatabase -Verbose -ConfigurerCredential PSCredential Live parameters: -ConfigurerCredential PSCredential Export parameters: -ExportScript -ScriptFolder folder -Force |
| Add-EMPSSubscriber | Adds a subscriber database to a publisher. In live mode both the publisher and subscriber must be accessible. In export mode three scripts are produced:
|
Common parameters:
-PublisherServer -PublisherDatabase -SubscriberServer -SubscriberDatabase -ServiceCredential PSCredential -DisplayName -Verbose Live parameters: -ConfigurerCredential PSCredential The configurer credentials must be the same for both the subscriber and publisher databases. Export parameters: -Force -PublisherDisplayName |
| Remove-EMPSSubscriber | Removes subscriber from publisher and cleans up subscriber. In live mode both the publisher and subscriber need to be accessible. In export mode two scripts are produced:
|
Common parameters:
-PublisherServer -PublisherDatabase -SubscriberServer -SubscriberDatabase -RemoveUsers -Verbose (optional) Live parameters: -ConfigurerCredential PSCredential The configurer credentials must be the same for both subscriber and publisher databases. Export parameters: -Force |
| Get-EMPSSubscribers | Returns list of subscribers for a publisher. This cmdlet writes a list of objects to the output pipeline with the string properties 'ServerInstance' and 'Database'. |
-PublisherServer
-PublisherDatabase -ConfigurerCredential PSCredential |
| Set-EMPSSubscriberCredential | Modifies the encrypted service account credential in the publisher for the specified subscriber. If -ExportScript is specified, Sql scripts are exported which can be used in sqlcmd or Sql Server Management Studio to perform the operations. Otherwise operations are performed directly on the specified database. |
Common Parameters
-PublisherServer <String> -PublisherDatabase <String> -ServiceCredential <PSCredential> -DisplayName <String> -ConfigurerCredential <PSCredential> Export -ExportScript <SwitchParameter> [-ScriptFolder <String>] -PublisherServer <String> -PublisherDatabase <String> -ServiceCredential <PSCredential> -DisplayName <String> [-Force <SwitchParameter>] [<CommonParameters>] |
| Reset-EMPSGeoSyncDatabase | Removes GeoSync setup from a single database where linked databases may not be available. Used to remove GeoSync information if subscribers or publisher are not available. This only runs in live mode. If -SubscriberDisplayName is specified, reference to that subscriber is removed from a publisher database. Otherwise removes all GeoSync objects from any database (publisher or subscriber). |
-Server
-Database -ConfigurerCredential -SubscriberDisplayName -Force |
| Start-EMPSBatchSync | Programmatically starts a batch sync from the specified publisher database to a specified subscriber database. Used to initiate a batch sync for any matching subscriber. This is the same as triggering a batch sync from the console. This command is asynchronous. It will return an object reflecting the status of the request but will not block until the sync has completed. |
-SubscriberDisplayName -ConfigOnly |
| Stop-EMPSBatchSync | Stops an executing batch sync. Used to stop a running batch sync for any matching subscriber. This is the same as canceling a batch sync from the console. This command is asynchronous. It will return an object reflecting the status of the request but will not block until the cancel has completed. |
-SubscriberDisplayName |
| Get-EMPSBatchSyncStatus | Retrieves the status of a sync. Used to return the sync status for any matching subscriber. This is the same status that is displayed in the console. It will return an object reflecting the status of the request. |
-SubscriberDisplayName |
Parameter Definitions
| Parameter | Description |
|---|---|
| -PublisherServer |
Server name for publisher server. For non-default instance use server\instance format. When setting up a publisher database that is part of an availability group, this parameter should point to the primary replica. |
| -PublisherDatabase | Name of publisher database. |
| -SubscriberServer | Server name for subscriber server. For non-default instance use server\instance format. |
| -SubscriberDatabase | Name of subscriber database. |
| -DisplayName | Optional display name refers to the publisher in subscriber databases and the subscriber in publisher databases. If omitted, it defaults to the leftmost component of the server name. If this does not result in a unique name when the subscriber is set up an error is displayed. |
| -Verbose | Verbose output displayed - optional. |
| -ConfigurerCredential PSCredential | Credential to use for configuration. If omitted, the current windows credential is used. If the username contains a backslash, the credential is treated as a windows credential. Otherwise it is treated as a SQL credential. |
|
-SecondaryReplicaServers |
A comma-separated list of the database servers where the secondary replica databases are hosted. |
|
-DatabaseMasterKeyPassword |
Allows you to specify the primary key password used to encrypt credentials. Without this parameter, the cmdlet will generate a random complex password. In some situations, the retention of the database primary key password is vital. See GeoSync.htm |
| -ServiceCredential PSCredential | Credential for service access on the subscriber (used for initial batch sync). This must be an existing service account on the subscriber. If the username has a backslash it is considered to be a windows credential, otherwise a SQL credential. |
| -ExportScript | Specifies export mode. |
| -ScriptFolder folder | Optionally specify a folder that the script is written to. This may be an absolute or relative path. If the folder doesn't exist it is created - provided that its parent folder exists. |
| -Force | If specified, an existing script of the same name will be overwritten. When a subscriber display name or pattern is specified, prevents the cmdlet from prompting for confirmation before each subscriber is removed. |
| -PublisherDisplayName | Optional display name of publisher for subscriber database. This should match the display name created at the publisher end. |
| -Server | Server name. For non-default instances, use server\instance format. |
| -Database | Database name. |
| -SubscriberDisplayName | If specified removes subscriber(s) matching the display name from a publisher. Name may include wildcards * and ?. If not specified all GeoSync setup is removed from the database (whether publisher or subscriber). |
| -ConfigOnly | Will initiate a configuration only sync. |
Start using PowerShell Cmdlets
PowerShell Cmdlets can be used to preview a selection of events, alerts or auditing data and then delete them if the database is growing too large.
-
Install and Configure the Personalization Server.
-
Run PowerShell as an Administrator.
-
On the PowerShell command prompt, use the Import-ApsInstanceModule cmdlet to select the ManagementServer instance to execute the cmdlets against.
Import-ApsInstanceModule -IsDefault -ProductName "Personalization Server"
Refer to the Server Configuration Portal Scripting Guide for further information.
Generate scripts to configure GeoSync
The GeoSync cmdlets can be used to generate SQL scripts for setting up and tearing down GeoSync. This is useful if the user does not have enough privileges to modify the respective databases. Instead the scripts can be passed to a database administrator to be executed.
Export mode is available by specifying the -ExportScript parameter with the cmdlets New-EMPSPublisher, Add-EMPSSubscriber, Remove-EMPSSubscriber, and Remove-EMPSPublisher. The other cmdlets do not have an export feature.
The cmdlets are loaded by executing Import-Apsinstancemodule. This may produce a warning if the user is not an administrator but it doesn’t affect the script generation.
New-EMPSPublisher
If -ExportScript is specified, -ConfigurerCredential is not used and additional parameters are available:
- -ScriptFolder specifies a folder where the script is written - if omitted a script is written to the current folder
- -Force tells the cmdlet to overwrite a script with the same name if it exists.
The script produced is named Publisher-<server>-<instance>-<database>.sql. This script can be run using sqlcmd against the publisher database. If SQL Server Management Studio is used, the query window used must be in sqlcmd mode.
Unlike running the cmdlet ‘live’, no checks are made to see if the database has already been set up.
Add-EMPSSubscriber
If -ExportScript is specified, -ConfigureCredential is not used and -ScriptFolder and -Force are available as for New-EMPSPublisher. The -ServiceCredential must be specified. Add-EMPSSubscriber produces three scripts:
- Subscriber-<server>-<instance>-<database>.sql - This script should be run first against the subscriber database to do the base setup. Server/instance/database refer to the subscriber
- Add-<server>-<instance>-<database>ToPublisher.sql - Run on the publisher server to add a reference to the subscriber.
- AddPublisherTo<server>-<instance>-<database>.sql - Run on the subscriber server to add a reference to the publisher.
Remove-EMPSSubscriber
Similar to Add-EMPSSubscriber in ExportScript mode, but -ServiceCredential is not required. Two scripts are produced:
- Remove-<server>-<instance>-<database>FromPublisher.sql - Run on the publisher server to remove the reference to the subscriber.
- RemoveSubscriber<server>-<instance>-<database>.sql - Run on the subscriber server to remove publisher reference and remove the base setup.
Remove-EMPSPublisher
As above, -ExportScript comes with -Force and -ScriptFolder and -ConfigurerCredential is not relevant. Produces a single script:
- RemovePublisher-<server>-<instance>-<database>FromPublisher.sql - Run on the publisher server to remove the publisher and revert the database to a standard personalization database.