Performing API Operations Using Bash

Applies to PeerGFS v6.1.0 and later

Overview

You can access and manage the PeerGFS API using Bash, which offers a flexible option for automation and integration into Unix-based workflows. This article explains how to use the provided Bash scripts, configure settings for convenience, and run examples to perform API operations. Whether you're customizing scripts or automating frequent tasks, these instructions will help you streamlinee your use of the PeerGFS API.

Running the Predefined Bash Script for API Operations

The predefined Bash script, PeerGFS-cli.sh, simplifies common API operations by providing a ready-to-use interface for interacting with the PeerGFS API. The script eliminates the need to manually construct cURL commands, making it easier to automate tasks and ensure consistent execution across environments. The predefined Bash script is located in the installation directory <PMC Installation Directory>\\tools\\bash, for both Windows and Linux deployments.

For PMC deployments on Windows, copy the bash folder (with contents) to a Linux or macOS system. Ensure the script has executable permissions and is in Unix line-ending format:

Commands:

CODE

sudo chmod u+x PeerGFS-cli.sh

CODE

sudo dos2unix ./PeerGFS-cli.sh

The PeerGFS-cli.sh script provides a user-friendly interface for running API operations using cURL. You can also use cURL directly in custom scripts. To generate the correct syntax for cURL commands, you can use the API web interface.

Set Up Environment Variables

No configuration is required to run the PeerGFS-cli.sh script or cURL. However, for convenience, the examples in this section use environment variables. Set up environment variables for easier script access by creating a script such as PeerGFS-API-Setup.sh. To set these variables in your environment, copy the script below, fill in the relevant parameters, then make it executable and run it in the same terminal session before executing the examples.

CODE

#! /bin/bash
export address=10.10.12.11
export port=8442
export username=admin
export password=password

To apply the environment variables to an existing session, use the . or source command:

Commands:

CODE

. ./PeerGFS-API-Setup.sh
echo $address

or

CODE

source ./PeerGFS-API-Setup.sh
echo $address

Bash Script Examples

This section illustrates how to use the PeerGFS-cli.sh script to interact with the API from Bash. These examples can be customized to fit your workflow. To execute them:

Run the configuration script described earlier.
Copy and paste the provided commands into your terminal.

Show Available Commands

Click here to expand...

To view the available commands and get help on usage, run the following command:

CODE

./PeerGFS-cli.sh --help

General Operations

Click here to expand...

The following 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 the output of each operation for better readability by piping the response into python -m json.tool:

List All Agents

CODE

agents=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getAgents`

CODE

echo $agents | python -m json.tool

List All Jobs

CODE

jobs=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getJobs`

CODE

echo $jobs | python -m json.tool

List All Open Files

CODE

files=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getOpenFiles`

CODE

echo $files | python -m json.tool

List All Quarantines

CODE

quarantines=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getConflicts fileConflictTypes=QUARANTINED`

CODE

echo $quarantines | python -m json.tool

List Watch Set Statistics

CODE

watchSetStats=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getWatchSetStats`

CODE

echo $watchSetStats | python -m json.tool

List Active Open and Pending Replication Statistics

CODE

activeStats=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getActiveStats`

CODE

echo $activeStats | python -m json.tool

List Queue Statistics

CODE

queueStats=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getQueueStats`

CODE

echo $queueStats | python -m json.tool

List Completed Replication Work Statistics

CODE

replStats=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getReplicationStats`

CODE

echo $replStats | python -m json.tool

List Scan Status and Statistics

CODE

scanStatus=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getScanStatus`

CODE

echo $scanStatus | python -m json.tool

List Error Job Alerts

CODE

errorJobAlerts=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getFileJobAlerts severities=ERROR`

CODE

echo $errorJobAlerts | python -m json.tool

List Fatal PMC Alerts

CODE

fatalPmcAlerts=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getPmcAlerts severities=FATAL`

CODE

echo $fatalPmcAlerts | python -m json.tool

List Scheduled Task History

CODE

scheduledTasks=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getScheduledTasks`

CODE

echo $scheduledTasks | python -m json.tool

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 Bash 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 manage their status (such as stopping or starting), run the following command:

CODE

jobs=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getJobs`

You can format the output for better readability by piping the response into python -m json.tool:

CODE

echo $jobs | python -m json.tool

The output will display a list of jobs, including details such as the job ID, name, type, status, and participants. The following is an example of the JSON output:

Stop the Job

If the job is running, such as job 104 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 commands:

CODE

export jobID=104

CODE

./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" stopJob jobIds=$jobID

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

CODE

jobs=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getJobs jobIds=$jobID`

CODE

echo $jobs | python -m json.tool

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

Delete the Job

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

CODE

./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" deleteJob jobIds=$jobID

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

./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" deleteJob jobIds=$jobID options=cleanup-database

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

CODE

./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" deleteJob jobIds=$jobID 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.

These steps assume that the environment variable jobID is already set to the desired job ID.

Get Job Status

To retrieve the status of the job you want to stop or start, run the following command:

CODE

jobs=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getJobs jobIds=$jobID`

To view the full status of the job, output the entire JSON with:

CODE

echo $jobs | python -m json.tool

This command 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:

Start a Job

Based on the output above, to start a job, use the following command:

CODE

./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" startJob jobIds=$jobID

After the job has started, check the status again:

CODE

jobs=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getJobs jobIds=$jobID`

CODE

echo $jobs | python -m json.tool

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

Stopping a Job

To stop the job, run the following command:

CODE

./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" stopJob jobIds=$jobID

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

CODE

jobs=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getJobs jobIds=$jobID`

CODE

echo $jobs | python -m json.tool

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

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 command:

CODE

conflicts=`./PeerGFS-cli.sh --insecure --host "https://$address:$port" -u "$username:$password" getConflicts`

CODE

echo $conflicts | python -m json.tool

The output will display a list of quarantined files, such as:

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

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

Resolve Quarantines

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

CODE

echo $conflicts | ./PeerGFS-cli.sh -k "https://$address:$port" -u "$username:$password" releaseQuarantined action=LAST_MODIFIED_WINS -

Notes for macOS users

Click here to expand...

macOS includes an older version of Bash (version 3.2.57) by default, which does not meet the minimum requirement of Bash 4.3 needed to run the PeerGFS Bash scripts. Even on newer macOS versions (such as 14.6), this outdated version of Bash may cause the scripts to fail.

You can check your current Bash version with the following command:

CODE

user@MacBook-Pro ~ % bash --version

If the version displayed is 3.2.57 or lower, you will encounter an error when running the PeerGFS Bash script:

CODE

user@MacBook-Pro ~ % ./bash/PeerGFS-cli.sh
Sorry - your Bash version is 3.2.57(1)-release
You need at least Bash 4.3 to run this script.

If you're using an older version, you you have two options:

Install a newer version of Bash using a package manager like Homebrew:
CODE
```
brew install bash
```
Use zsh, which is the default shell in newer macOS versions, as an alternative to Bash. PeerGFS scripts should work with zsh as an alternative to Bash.

Overview

Running the Predefined Bash Script for API Operations

Set Up Environment Variables

Bash Script Examples

Show Available Commands

General Operations

List All Agents

List All Jobs

List All Open Files

List All Quarantines

List Watch Set Statistics

List Active Open and Pending Replication Statistics

List Queue Statistics

List Completed Replication Work Statistics

List Scan Status and Statistics

List Error Job Alerts

List Fatal PMC Alerts

List Scheduled Task History

Create a Job

Delete a Job

Get the Job Status

Stop the Job

Delete the Job

Delete a Cloud Backup Job

Start and Stop a Job

Get Job Status

Start a Job

Stopping a Job

Release Quarantines

Obtain Quarantined Files List

Resolve Quarantines

Notes for macOS users

Related articles