Skip to main content
Skip table of contents

Getting Started with Multi-Protocol for PeerGFS

Purpose of this Guide

Welcome to the Getting Started with Multi-Protocol for PeerGFS guide. This document introduces PeerGFS’s multi-protocol functionality, explaining how it enables synchronization and replication between storage devices hosting data using both SMB and NFS protocols. It covers key concepts, configuration steps, and best practices to help you set up and manage a multi-protocol environment effectively.

This guide assumes you are already familiar with installing and using PeerGFS. It focuses specifically on multi-protocol support and does not cover the broader capabilities of PeerGFS. If you need installation guidance, consult your Peer Software point of contact. For additional features and settings, refer to the PeerGFS User Guide.

The guide is structured to provide a clear, step-by-step approach to configuring PeerGFS for SMB and NFS integration:

  • Introducing Multi-Protocol with PeerGFS – Explains how PeerGFS replicates data using both SMB (Windows clients) and NFS (Linux clients).

  • Setting Up Access Permissions on Your Storage Device – Covers the required permissions for SMB and NFS to ensure proper connectivity.

  • Setting Up Storage Configurations – Guides you through configuring storage connectivity before creating a PeerGFS job.

  • Setting Up SMB Access for Linux Agents – Explains how to configure SMB access for Peer Agents running on Linux.

  • Setting Up a Multi-Protocol Job – Provides detailed steps for creating file synchronization and file replication jobs that use multi-protocol.

  • Understanding SMB and NFS Interactions – Highlights key differences between SMB and NFS, including file name case sensitivity and mixed permissions behavior.

  • Troubleshooting Common Issues – Offers solutions for common issues encountered when using PeerGFS in a multi-protocol environment.

Consult the PeerGFS Environmental Requirements and any appropriate storage prerequisites to verify that your environment meets the necessary requirements.


Introducing Multi-Protocol with PeerGFS

PeerGFS enables replication of data between NAS devices by monitoring SMB and NFS activity in real-time and triggering a Peer Agent to perform the replication. The multi-protocol functionality allows a single Peer Agent to receive notifications for both Windows and Linux client activity. By leveraging NFS for data transfers and a mix of NFS and SMB for permissions, PeerGFS ensures metadata integrity and provides a robust solution for managing data across heterogeneous environments.

image-20250219-080400.png

Multi-protocol support is beneficial in environments that require the ability to access and modify files from both Windows and Linux systems. Examples include:

  • Applications write data via NFS but end users use Windows clients to process the data generated by the applications.

  • Organizations have both Windows and Linux clients working with the same data.


Setting Up Access Permissions on Your Storage Device

This section focuses on ensuring that volumes and shares have the correct permissions for use with PeerGFS. While the guidelines are general, the same principles apply regardless of the storage vendor. Proper permissions are essential for configuring multi-protocol support in PeerGFS, and failure to follow the guidance below may result in errors during job validation.

Before configuring storage in PeerGFS, you must verify that your storage device has the correct permissions to allow Peer Agents can read and write data as needed for file replication and file synchronization jobs.

This section covers access permission setup for both SMB and NFS devices.

SMB Access: Setting Up SMB Permissions and Shares

Note: If Windows-style permissions do not need to be transferred, skip this section.

If you need to transfer Windows-style permissions, you must ensure that the Peer Agent has access to the SMB share(s). To set up access, follow the guidance in the following subsections—Granting SMB Share Permissions and Creating a Root SMB Admin Share—to ensure proper access configuration.

Granting SMB Share Permissions

When configuring an SMB share, grant the Peer Agent’s user account full read and write access, including permissions to modify file permissions and other metadata. For PowerScale storage devices, the account must have root-level access.

The example below shows a Dell PowerScale share named Share1, where the user peeruser has root-level access permissions. Although this example uses a local user, a domain user can be set if the storage device is part of a Windows domain.

SMB Share Access.png

Creating a Root SMB Admin Share

Creating a root SMB admin share is optional, but it can simplify access configuration. If you are using NetApp or Dell PowerScale, you may choose to have Peer Agents use an SMB admin share for writing Windows-style permissions. The key advantage is that a single share can be used to access data for all jobs, reducing configuration complexity.

For configuring this share, the options vary depending on the storage platform type:

  • NetApp: A predefined admin share called C$ is available and can be configured for use by Peer Agents.

  • Dell PowerScale: No admin share is available by default, so you must create one manually. Below is an example of how to create an admin share for Dell PowerScale.

Note: Using an SMB admin share may grant the Peer Agent access to more data than necessary.

The example below shows an admin share created for Dell PowerScale.

Root SMB Admin Share.png

NFS Access: Configuring NFS Permissions and Shares

When a Peer Agent connects to a NFS export, it mounts it as the root user. Since root squash is typically used to prevent the root user from having full access over NFS-mounted file systems, it’s important to configure it properly to allow the Peer Agent to function correctly. Here are your options:

  1. Disable root squash for these exports: This ensures that the root user on the client system (the Peer Agent in this case) has full access to the NFS export without being restricted by root squash.

  2. Map the root user to another user with full read/write access: If you don’t want to disable root squash entirely, you can map the root user to a different user (one with the necessary permissions) who has full read/write access to the NFS export. If root squash is still enabled and it maps the root user to an anonymous user, then that anonymous user must have full read/write access to the NFS export for proper functionality.

For more granular access control, NFS v4 Access Control Lists (ACLs) can be used, but ACLs are not available in earlier NFS versions.

The example below shows root mapping for Dell PowerScale.

NFS Access-1.png

Configuring Storage Platform Settings in PeerGFS

While the Create Job wizard allows you to configure storage platform settings during job creation, setting them up beforehand can streamline the process and reduce potential issues.

To configure storage platform settings in PeerGFS:

  1. Open Peer Management Center.

  2. Select Open Preferences from the Tools menu.

  3. Expand Storage Configuration in the navigation tree, and select Storage Platforms.

  4. Expand Storage Platforms.

    Storage Platforms.png
  5. Select the appropriate storage platform type.

  6. Provide the required values. For more information, see the Storage Platform topic under Preferences in the PeerGFS User Guide.

  7. Save the configuration.


Setting Up SMB Access for Linux Agents

Note: If Windows-style permissions do not need to be transferred, skip this section.

If a multi-protocol job requires transferring Windows-style permissions, the Peer Agent must connect to the SMB share using configured credentials.

To configure SMB access:

  1. Open Peer Management Center.

  2. Select Open Preferences from the Tools menu.

  3. Expand Storage Configuration in the navigation tree and select SMB Access Configuration.

    Set up SMB Access-1.png
  4. Click Create to add a new SMB access configuration.

    Set up SMB Access-2.png
  5. Fill in the required values:

    • Agent - Specifies the Agent that will use these credentials.

    • Description - A unique description for this configuration, specific to the selected Agent.

    • Domain Username - The username to be used. For non-domain users, this should be in the format host\username.

    • SMB Access Share - The share name for which the credentials are used. For admin shares, use ifs$ or c$.

    • Domain Password - The password associated with the domain username.

    • SMB Mount Options - For advanced users who need custom mount parameters. Use this option under the guidance of Peer Support.

  6. Click OK.

  7. Create other access configurations if needed:

    • If different shares require different credentials, you should create multiple entries per Agent, specifying the appropriate credentials for each share. This ensures that each SMB share is accessible with the correct permissions.

    • If a single credential set can access all shares, only one entry is required per Agent. This simplifies the setup but be sure to verify that the credentials have the necessary access for all intended shares.


Setting Up a Multi-Protocol Job

This section with guide you through setting up a multi-protocol job in PeerGFS.

PeerGFS supports multi-protocol file synchronization and file replication jobs. However, file collaboration jobs are not currently supported due to the way that file locking is handled with NFS.

Creating a File Synchronization Job

  1. Open Peer Management Center.

  2. In the Jobs view, right-click File Synchronization, and then select Create File Synchronization Job.

  3. Name the job, and then click OK.

  4. Select the Enable Multi-Protocol for NFS and SMB workloads checkbox to configure the job for multi-protocol environments.

    Create File Sync Job-1.png
  5. Click Add to configure the first participant:

    • Select the Management Agent.

      Create File Sync Job-2.png
    • Select the storage platform for this Agent.

      Create File Sync Job-3.png
    • Select or create the storage credentials.

      Create File Sync Job-4.png
    • Specify the NFS export path for this Agent, and then click Finish.

      Create File Sync Job-5.png
  6. Repeat Step 4 for additional participants.

  7. After adding all participants, click Next to continue configuring the job.

  8. Configure the permission settings as needed.

    • If you select Windows-style permissions, SMB access must be configured. If it has not been configured, you can do so during the validation process.

    • Mixed permissions is available for Dell PowerScale only. Contact Peer Software for more details.

      Create File Sync Job-6.png
  9. Click the Validate button to confirm the Peer Agent can access the required data.

  10. Click Finish to complete the job creation.

Creating a File Replication Job

  1. Open Peer Management Center.

  2. In the Jobs view, right-click File Replication, and then select Create File Replication Job.

  3. Name the job, and then click OK.

  4. Select the Enable Multi-Protocol for NFS and SMB workloads checkbox to configure the job for multi-protocol environments.

    Create File Rep Job-1.png
  5. Configure the Source Agent:

    • Select the Agent that will connect to the source data.

    • Select the storage platform for this Agent.

      Create File Rep Job-2.png
    • Select or create the storage credentials.

      Create File Rep Job-3.png
    • Specify the NFS export path for this Agent, and then click Finish to complete this participant setup.

      Create File Rep Job-4.png
  6. Configure the Destination Agent:

    • Select the Agent that will connect to the source data.

      Create File Rep Job-5.png
    • Specify the NFS export location and (if required) select the SMB access configuration.

      Create File Rep Job-6.png
    • Specify the Job Relative Path. Leave this blank if replicating to the root of the share.
      Job Relative Path refers to the subdirectory within the SMB share where data will be replicated.
      Take this example UNC path: \\fileserver1\MyShare1\Path\To\Data. It is made up of three parts:

      • The host – The server or system where the share resides (e.g., fileserver1).

      • The share – The specific shared folder on the file server (e.g., MyShare1).

      • The job relative path – The subdirectory within the share where data is or will be stored (e.g., Path\To\Data).

      So, the Job Relative Path field should contain just the last part of the UNC path, which is Path\To\Data in this example.

  7. Click Next to continue configuring the job.

  8. Configure the permission settings as needed.

    • If you select Windows-style permissions, SMB access must be configured. If it has not been configured, you can do so during the validation process.

    • Mixed permissions is available for Dell PowerScale only. Contact Peer Software for more details.

      Create File Rep Job-7.png
  9. Click the Validate button to confirm the Peer Agent can access the required data.

  10. Click Finish to complete the job creation.


Understanding SMB and NFS Interactions

When transferring data between NAS devices, the Peer Agent uses NFS to ensure filenames are preserved correctly, as NFS is case-sensitive while SMB is not. For file permissions and metadata, the Peer Agent uses an SMB connection to copy Windows-style permissions and an NFS connection to copy Linux-style permissions. The following details explain how this affects interactions between NFS and SMB.

  • File Name Differences Between SMB and NFS

    • NFS supports case-sensitive filenames, allowing files like report.txt and Report.txt to coexist as distinct files. In contrast, SMB is case-insensitive, meaning an attempt to create both files would result in an error, as SMB considers them identical.

    • SMB prohibits special characters (e.g., \ / : * ? < > |), but NFS allows them.

    • Storage vendor implementations may handle conflicts differently—avoid unsupported file names.

Note: PeerGFS uses NFS to transfer files and data, allowing files with case-sensitive names or special characters to be moved. However, the files may not behave or be displayed as expected when accessed through SMB. This could involve issues such as:

  • Filenames being altered or normalized (e.g., case differences may be ignored).

  • Special characters being stripped, replaced, or causing errors.

  • Files potentially not being visible or accessible in the way they were originally transferred via NFS due to SMB's limitations.

  • Mixing Linux and Windows Permissions

    • Peer Software defines mixed permissions as files having both Linux (NFS) and Windows (SMB) permissions simultaneously.

    • Dell PowerScale is the only storage vendor that fully supports this feature. Contact Peer Software for more details.

Note: If a storage platform does not support mixing Windows and Linux permissions, the outcome will depend on its configuration, and you may not achieve the results you want. Each storage manufacturer supported by Peer Software handles files created with NFS names unsupported by SMB differently. For this reason, it is highly recommended to avoid these scenarios.


Troubleshooting Common Issues

If issues arise during configuration or job execution, refer to the following troubleshooting tips:

Job Validation Issues

Issue

Possible Cause

Solution

SMB access share is not configured

No SMB access share configured for the given Agent

Create or select an SMB configuration in the storage platform settings

Permission denied when mounting CIFS share

Incorrect credentials

Update the SMB credentials in the SMB access configuration

Change user settings on the storage device

Failed to set ACLs on SMB path

Incorrect user permissions on the storage device

Ensure that the user has full read/write access on the storage device (root-level access required for PowerScale)

Job Execution Failures

Issue

Possible Cause

Solution

Warnings when trying to set Linux ACLs

Mismatch in NFS export settings

Ensure all storage devices allow the same NFS version (v3 or v4)

Failed to set ACLs on SMB path

Incorrect user permissions on storage device

Ensure that the user has full read/write access on the storage device (root-level access required for PowerScale)

Linux files created with root ownership

No root squash or mapping set on the storage device

Configure root squash or mapping on the storage device

JavaScript errors detected

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

If this problem persists, please contact our support.