Skip to main content
Skip table of contents

Performing API Operations Using PowerShell

Applies to PeerGFS v6.1.0 and later

Overview

You can access and manage the PeerGFS API using PowerShell, which provides a robust platform for automation and integration into existing workflows. This article explains how to run the PeerGFS PowerShell Toolkit, configure settings for automation, and use sample scripts to perform API operations. Whether you're creating custom scripts or automating routine tasks, these instructions will help you streamline your use of the PeerGFS API.

The PeerGFS PowerShell Toolkit is a set of specialized PowerShell commands and functions designed specifically for interacting with the PeerGFS system, leveraging PowerShell’s capabilities for automation. It is installed in the Peer Management Center directory, typically located in C:\Program Files\Peer Software\Peer Management Center\tools\powershell.

Initializing the PeerGFS PowerShell Toolkit

Each time you open PowerShell, you must initialize the PeerGFS PowerShell Toolkit to load the necessary module for interacting with the PeerGFS API. To simplify this, we’ve provided the ConfigurePeerGFSToolkit.ps1 script, which you can run to initialize the toolkit.

Follow these steps to initialize the PeerGFS PowerShell Toolkit and load the necessary module for the PeerGFS API

  1. Launch PowerShell on the PMC server and navigate to the following directory:
    <PMC Installation Directory>\tools\powershell.

  2. Run the following command in the PowerShell console to load the PowerShell module:

    POWERSHELL
    PS C:\Program Files\Peer Software\Peer Management Center\tools\powershell> .\ConfigurePeerGFSToolkit.ps1

    image-20250425-134104.png
  3. When you run the script, you will be prompted for user ID and password.

  4. After loading the PowerShell module, you can begin using the API.

Creating and Using a Configuration File for PowerShell Initialization

When you’re ready to create custom scripts and automate tasks, it’s important to remember that you must initialize the PowerShell Toolkit each time you run PowerShell. The ConfigurePeerGFSToolkit.ps1 script loads the necessary PowerShell module, but to avoid entering your user credentials manually every time, you can use a configuration file (an .ini file) with the script. The .ini file stores your user credentials and ensures they are automatically applied when initializing PowerShell for scripting.

Follow these steps to create a configuration file that eliminates the need for manual input of credentials and server details, and initializes PowerShell automatically when running custom scripts:

  1. Create the settings.ini file:

    • Save the file in a secure location, such as an administrator's home directory.

    • If the script will be run by multiple users, save the file in the same directory as the ConfigurePeerGFSToolkit.ps1 script.

  2. Edit the settings.ini file, replacing the example values with your actual PMC credentials and server details:

    CODE
    [General]
    username=admin
    password=password
    [Network]
    address=127.0.0.1
    port=8442
  3. Run the .\\ConfigurePeerGFSToolkit.ps1 script, passing the settings.ini file as the first parameter in the command. For example:

    CODE
    .\ConfigurePeerGFSToolkit.ps1 'C:\Users\Administrator\Documents\settings.ini'

    This step initializes the PowerShell Toolkit with the credentials and server information from the configuration file. After this, the script can be run again without requiring manual input of credentials or server details.

PowerShell Script Examples

This section demonstrates how to use the PeerGFS API from a PowerShell client. These examples can be adapted to suit your workflow.

  • Use the examples as starting points to customize operations within your workflow.

  • Replace placeholder commands or parameters with values specific to your environment as needed.

Initialize the Toolkit and Show Available Commands

Click here to expand...

To set up the environment and explore available commands in the PeerGFS Toolkit:

CODE
.\ConfigurePeerGFSToolkit.ps1
CODE
Get-Command -Module PeerGFSToolkit
image-20250425-134617.png

General Operations

Click here to expand...

The following PowerShell commands allow you to retrieve various operational data from your PeerGFS environment. You can use these commands to list Agents, jobs, files, quarantines, statistics, and more. You can format each operation's output for better readability by using tools like Format-Table or ConvertTo-Json.

List All Agents

CODE
$agents = Get-PeerGFSAgents
CODE
$agents.Agents | fl
image-20250429-024617.png

List All Jobs

CODE
$jobList = Get-PeerGFSJobs
CODE
$jobList.jobs | fl
image-20250425-151241.png

List All Open Files

CODE
$openFiles = Get-PeerGFSOpenFiles
CODE
$openFiles.openFiles | ft
image-20250428-071004.png

List All Quarantines

CODE
$quarantines = Get-PeerGFSConflicts -FileConflictTypes QUARANTINED
CODE
$quarantines.FileConflicts | ft
image-20250428-112719.png

List Watch Set Statistics

CODE
$watchSetStats = Get-PeerGFSWatchSetStats
CODE
$watchSetStats.watchSetStats | ft
image-20250428-103021.png

List Active Open and Pending Replication Statistics

CODE
$activeStats = Get-PeerGFSActiveStats
CODE
$activeStats.activeStats | ft
image-20250428-102945.png

List Queue Statistics

CODE
$queueStats = Get-PeerGFSQueueStats
CODE
$queueStats.fileQueueStats | ft
image-20250428-102905.png

List Completed Replication Work Statistics

CODE
$replStats = Get-PeerGFSReplicationStats
CODE
$replStats.replicationStats | ft
image-20250428-102841.png

List Scan Status and Statistics

CODE
$scanStatus = Get-PeerGFSScanStatus
CODE
$scanStatus.fileScanStatuses | ft
image-20250428-103130.png

List Error Job Alerts

CODE
$fatalJobAlerts = Get-PeerGFSFileJobAlerts -Severities ERROR
CODE
$fatalJobAlerts.alerts | ft
image-20250429-020839.png

List Fatal PMC Alerts

CODE
$fatalPmcAlerts = Get-PeerGFSPmcAlerts -Severities FATAL
CODE
$fatalPmcAlerts.alerts | ft

List Scheduled Task History

CODE
$scheduledTasks = Get-PeerGFSScheduledTasks
CODE
$scheduledTasks.scheduledTasks | ft

Create a Job

Click here to expand...

Creating a job is more complex than the other examples provided. For detailed guidance, refer to the following articles:

Creating a Job Using Scripting

Creating a Job Using PowerShell Scripting

These articles provide step-by-step instructions and additional context to successfully create a job.

Delete a Job

Click here to expand...

Before deleting a job, you need to first retrieve its status, and if the job is currently running, stop it. Deleting a job while it is still running could result in incomplete or corrupted operations. The following steps guide you through retrieving the job status, stopping a job if needed, and safely deleting the job.

Get the Job Status

To view the available jobs and their status, run the following commands:

CODE
.\ConfigurePeerGFSToolkit.ps1 'settings.ini'
CODE
$job = Get-PeerGFSJobs
CODE
$job.jobs | ft

This command will output a table showing job details, including the job ID, name, type, status, and participants. The following is an example of the output:

image-20250429-030916.png

To see the full status of the jobs, simply output the entire JSON:

CODE
$job.jobs
image-20250429-031223.png

Stop the Job

If the job is running, such as job 103 in this example you must stop it before deleting it. Stopping the job ensures a clean deletion and prevents issues with incomplete data removal.

To stop the job, run the following command:

CODE
Stop-PeerGFSJob -JobIds 103
image-20250429-031455.png

After stopping the job, check the job status again to confirm it has been halted:

CODE
$job = Get-PeerGFSJobs -jobIds 103
CODE
$job.jobs

The job status will return to Halted, as shown below:

image-20250429-031639.png

Delete the Job

Once the job is halted, you can delete it by running the following command:

CODE
Invoke-PeerGFSDeleteJob -jobId 103
image-20250429-031910.png

Delete a Cloud Backup Job

When deleting a Cloud Backup job, you must specify what data should be deleted—either only the database or all data associated with the job.

To delete only the database, run the following command:

CODE
Invoke-PeerGFSDeleteJob -jobId 103 -Options 'cleanup-database'

Alternatively, if you need to delete all data related to the job in the cloud, you can use:

CODE
Invoke-PeerGFSDeleteJob" -jobId 103 -Options 'cleanup-all'

If you don't specify an option, you'll see the following error message:

CODE
No operation is set. Please use 'cleanup-database' to clean up the database only, or 'cleanup-all' to delete all cloud data related to JOB_NAME.

Start and Stop a Job

Click here to expand...

Before starting or stopping a job, it’s important to first check its status. If the job is currently running, stopping it may be necessary to ensure proper execution. The following steps guide you through retrieving the job status, starting or stopping the job as needed, and ensuring that the operation is performed without issues.

Get Job Status

To retrieve the list of available jobs and their status, run the following commands:

CODE
.\ConfigurePeerGFSToolkit.ps1 'settings.ini'
CODE
$job = Get-PeerGFSJobs
CODE
$job.jobs | ft

This will output a table showing the job details, including the job ID, name, type, status, and participants. The following is an example of the output:

image-20250429-033809.png

To view the full status in JSON format, use:

CODE
$job.jobs

This will display detailed job information, including participants and their statuses, start times, and running durations.

Start a Job

Based on the output above, to start a job, use the following command, replacing 101 with the ID of the job you want to start:

CODE
Start-PeerGFSJob -JobID 101
image-20250429-035054.png

After the job has started, check the status again:

CODE
$job = Get-PeerGFSJobs -JobIds 101
CODE
$job.jobs

The job status will be updated to Running, as shown below:

image-20250429-035230.png

Stop a Job

Based on the output above, to stop a job, run the following command, replacing 101 with the ID of the job you wish to stop:

CODE
Stop-PeerGFSJob -JobID 101
image-20250429-035432.png

After stopping the job, check the status again to confirm it has been halted:

CODE
$job = Get-PeerGFSJobs -JobIds 101
CODE
$job.jobs

The job status will return to Halted, as shown below:

image-20250429-035551.png

Release Quarantines

Click here to expand...

When files are quarantined, you can often script simple solutions—such as prioritizing a specific Agent or always selecting the most recent file version. This can streamline conflict resolution.

Obtain Quarantined Files List

To retrieve a list of quarantined files, run the following commands:

CODE
$conflicts = Get-PeerGFSConflicts -FileConflictTypes QUARANTINED
CODE
$conflicts.FileConflicts

The output will show quarantined files along with related details, such as:

image-20250429-085036.png

In this case, the file TestQuarantine.txt has a conflict under job ID 101, which matches what is shown in Peer Management Center.

Clean Quarantined Files.png

Conflicts can also be retrieved by job ID. If no job ID is provided, a list of all conflicts will be displayed.

Clear File Conflicts

To resolve the conflicts, you can use the list of quarantined files retrieved earlier. For example, to resolve conflicts with the "Last Modified Wins" resolution, run the following command:

CODE
Clear-PeerGFSQuarantined -Action LAST_MODIFIED_WINS -FileConflictList $conflicts
image-20250429-085157.png

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.