Change Auditor 7.3 - PowerShell User Guide

Adding the PowerShell module Viewing available commands and help Installing Change Auditor coordinators and web clients Setting the master time zone Finding Change Auditor installations and coordinators Connecting to and disconnecting from Change Auditor installations and coordinators Importing and exporting configuration settings Managing client authentication options Gathering Change Auditor system information Deploying Change Auditor agents Managing auditing templates Working with searches

Copy-CASearch

Managing Active Directory Database auditing Working with Active Directory Database protection templates Managing Windows File System auditing Managing SQL Extended Events Auditing (Preview) Managing Fluid File System auditing Managing Azure Active Directory auditing Managing Office 365 auditing Managing Skype for Business auditing Configuring a Quest On Demand Audit integration Working with Active Directory protection templates Our brand, our vision. Together. Contacting Quest Technical support resources

Setting the master time zone

Starting with version 6.9, Change Auditor calculates the Next Run of the reports, and archive and purge jobs based on the master time zone. For new deployments, the master time zone is set to the time zone of the server where the first coordinator is being installed. During an upgrade, the master time zone is set to UTC. You can manually change the master time zone, using the set-CAScheduleMasterTimeZone and get-CAScheduleMasterTimeZone commands. We recommend that you set the master time zone to the time zone where most the users are located.


	NOTE: Because Daylight Saving Time changes on different dates worldwide, Change Auditor’s schedules follow the time change of that specific time zone.

•

Set-CAScheduleMasterTimeZone

•

Get-CAScheduleMasterTimeZone

Set-CAScheduleMasterTimeZone

Use this command to specify which time zone the coordinators should use to calculate Next Run of the reports and archive and purge jobs.

Table 4. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-TimeZoneID	The identifier of a system time zone.
-TimeZoneInfo	A TimeZoneInfo object.


	NOTE: The TimeZoneID and TimeZoneInfo parameters must be a system-recognized time zone obtained through a call to the PowerShell command "[System.TimeZoneInfo]::GetSystemTimezones()".

Example: Set the schedule master time zone with a time zone info object

$atlanticTime = [System.TimeZoneInfo]::GetSystemTimeZones() |? {$_.Id -eq "Atlantic Standard Time"}

Set-CAScheduleMasterTimeZone -Connection $connection -TimeZoneInfo $atlanticTime

Example: Set the schedule master time zone with a time zone identifier

Set-CAScheduleMasterTimeZone -Connection $connection -TimeZoneId "Eastern Standard Time"

Get-CAScheduleMasterTimeZone

Use this command to retrieve what time zone the coordinators should use to calculate Next Run of the reports and archive and purge jobs.

Table 5. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Retrieve the schedules master time zone

Get-CAScheduleMasterTimeZone -Connection $connection

Finding Change Auditor installations and coordinators

The following commands allow you to find the Change Auditor installations and coordinators available in your Active Directory environment. Once connected, you can run additional commands to manage the deployment.


	NOTE: The installations and coordinators that a search returns depends on your credentials and domain trusts.

•

Find-CAInstallations

•

Find-CACoordinators

•

Find-CASuitableCoordinator

Find-CAInstallations

Use this command to search Active Directory for all available Change Auditor installations. The default is the current computer’s forest, however, you can optionally specify a domain to search cross-forest for deployments.


	NOTE: This command runs in the context of the current user running PowerShell. The user must have permission to search Active Directory in the specified domain.

Example: Find all Change Auditor installations in DomainName.com

Find-CAInstallations –DomainName ‘DomainName.com’

Find-CACoordinators

Use this command to search Active Directory for all available coordinators. The default is the current computers forest, however, you can optionally specify a domain to search cross-forest for deployments. This search returns all the information required to connect to the coordinator including ports.


	NOTE: This command runs in the context of the current user running PowerShell. The user must have permission to search Active Directory in the specified domain.

Example: Find all available coordinators in DomainName.com

Find-CACoordinators -DomainName 'DomainName.com'

Find-CASuitableCoordinator

Use this command to search Active Directory for a coordinator to which a connection can be made. The default is the current computers forest; however, you can optionally specify a domain to search cross-forest for deployments.

If more than one Change Auditor installation is discovered, the call fails and the –InstallationName parameter is required.

Table 6. Available parameters


Parameter	Description
-Certificate (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies the thumbprint string copied from a certificate found in the certmgr.msc Certificate Manager for the current user in the Personal\Certificates folder. This certificate must be trusted, not expired, have a private key and at least the “Client Authentication” purpose. (“Proves your identity to a remote computer”).

Example: Find a coordinator in ‘DEFAULT’ installation that you have the credentials to connect to

Find-CASuitableCoordinator –InstallationName ‘DEFAULT’

Example: Find a coordinator in Domain that you have the credentials to connect to, when using certificate authentication

$creds = Get-Credential

$connection = Connect-CAClient -Credential $creds

Find-CASuitableCoordinator -Credential $creds -DomainName ‘DomainName.com'

Connecting to and disconnecting from Change Auditor installations and coordinators

•

Connect-CAClient

•

Disconnect-CAClient

Connect-CAClient

Most Change Auditor commands require a connection to a coordinator. This connection can be assigned to a variable and used for any command that requires it. This command searches for a suitable coordinator in a Change Auditor installation and creates a connection. Suitable coordinators are those to which you have access to and can be located by searching through Active Directory service connection points.

You can also connect to Change Auditor installations in untrusted domains or to a specific coordinator by specifying the -ComputerName and -Port parameters.

You can make multiple connections to different coordinators or deployments in the same script as long as the version of Change Auditor is the same.


	NOTE: Connections are closed when the PowerShell session is ended or disconnected.

Table 7. Available parameters


Parameter	Description
-Credential (Optional)	Windows credentials specifying the user to connect to the Change Auditor installation. All operations using this connection will be authorized as this user. When not specified, the current client running PowerShell is used. NOTE: Credentials are required when certificate authentication is being used.
-CoordinatorConnectionPoint	Specify to use a specific coordinator found from a previous call to Find-CACoordinators.
-SelectLocalCoordinator	Create a connection to the local coordinator.
-InstallationName (Optional)	The installation name to connect to. If an installation cannot be found with this name, no connection is made. If more than one Change Auditor installation exists in the current forest, this parameter is mandatory. Omitting it results in a connection failure due to ambiguity.
-DomainName (Optional)	The name of the domain where the Change Auditor installation exists.
-ComputerName	The computer to connect to.
-Port	The port to connect to.
-WaitForServiceReady (Optional)	The number of seconds to wait for the connected coordinator service to be ready. NOTE: If not specified, when the Change Auditor coordinator is not ready for connections due to an in-progress install or upgrade, an error is returned. The maximum is 144,000 seconds, or 10 hours.
-UseCertificateAuth (Optional)	This parameter specifies that the coordinator is expected to be configured for certificate authentication. This parameter does not require an input value. When specified, this parameter is $true.
-DisableCertificateCrlCheck (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies that Certificate Revocation List checking is disabled. This parameter does not require an input value. When specified, this parameter is $true.
-Certificate (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies the thumbprint string copied from a certificate found in the certmgr.msc Certificate Manager for the current user in the Personal\Certificates folder. This certificate must be trusted, not expired, have a private key and at least the “Client Authentication” purpose. (“Proves your identity to a remote computer”).

Table 8. Supported parameter sets that enable a connection
Example	Enter the following command:
Recommended: Connect to the installation “XYZ” in the local forest. NOTE: This allows for fault tolerance if you have numerous coordinators by selecting the best option in the domain.	Connect-CAClient –InstallationName ‘XYZ’ -DomainName 'DomainName.com'
Connect to the first suitable coordinator found in any installation in any trusted domain.	$connection = Connect-CAClient
Connect to a specific coordinator by computer name and port.	Connect-CAClient –ComputerName ‘ca-cord.DomainName.com’ –Port 52289
Connect to the first suitable coordinator in the domain “DomainName.com”.	Connect-CAClient –DomainName ‘DomainName.com’
Connect to the first suitable coordinator in the domain “DomainName.com” with an installation name “DEFAULT”.	Connect-CAClient –DomainName ‘DomainName.com’ –InstallationName ‘DEFAULT’
Connect to a coordinator found from Find-CACoordinators.	$coordinators = Find-CACoordinators –DomainName ‘DomainName.com’ $connection = Connect-CAClient –CoordinatorConnectionPoint $coordinators[0]
Connect to a specific coordinator by computer name and port, when using certificate authentication.	$creds = Get-Credential Connect-CAClient -Credential $creds -ComputerName ‘ca-coordinator.DomainName.com’ –Port 52289 -UseCertificateAuth

Disconnect-CAClient

Use this command to disconnect from Change Auditor. (This is the equivalent of closing the Change Auditor client.)

Example: Connect to a Change Auditor deployment, and then close the connection

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

# perform some actions

Disconnect-CAClient $connection

Importing and exporting configuration settings

•

Import-CAConfigurations

•

Export-CAConfigurations

Import-CAConfigurations

Use this command to import Change Auditor configuration settings.


	NOTE: All settings contained in the specified import file are imported by default when using this command except for Application User Interface and Coordinator configurations which can be included by using the provided optional parameters.

Table 9. Available parameters

Parameter

Description

-Connection

A connection obtained by using the Connect-CAClient command.

-ConfigurationSettings

An XML document (Xml.XmlDocument object) that contains the configuration settings to import.

-IncludeCoordinatorConfig (Optional)

Imports the coordinator configuration if present in the exported file.

NOTE:

•

This will overwrite existing settings, including SMTP Mail Server and Alert settings.

•

Scheduled task settings will not be applied when selected coordinators are missing.

-IncludeAppUserInterfaceConfig (Optional)

Imports the Application User Interface configuration.

NOTE: This will overwrite existing coordinator user role settings and assignments which may require a restart of the coordinator in order to regain access.

-Force (Optional)

Suppresses warning y/n prompts from the
-IncludeCoordinatorConfig and
-IncludeAppUserInterfaceConfig parameters.

Example: Importing configuration settings

$connection = Connect-CAClient -Credential $creds

[xml] $xmld = Get-Content 'C:\DataFolder\CAConfig.xml'

Import-CAConfigurations -Connection $connection -ConfigurationSettings $xmld

Export-CAConfigurations

Use this command to export Change Auditor configuration settings.


	NOTE: All settings that can be exported with the Windows client interface are included by default when exporting configuration settings using this command, including settings for Application User Interface and Coordinator configurations.

Table 10. Available parameters