Installing the SANsymphony Storage Plugin for Proxmox

Explore this Page

Overview

The SANsymphony Storage Plugin for Proxmox connects Proxmox Virtual Environment (VE) with the SANsymphony storage system. This section explains how to install the plugin and helps you choose the method that works best for your setup.

  • Perform the following steps on each Proxmox node in the PVE cluster.
  • Installing the SANsymphony Storage Plugin for Proxmox using the APT repository or DPKG package methods updates several host-level configurations on the Proxmox VE node as part of the installation process. These configuration updates are applied immediately after the plugin installation completes and are required for correct operation with SANsymphony storage. For more information, refer to Configuration Updates Performed After Plugin Installation.

Installing the SANsymphony Storage Plugin for Proxmox via APT Repository (Recommended)

This installation method uses the APT repository to install the SANsymphony Storage Plugin for Proxmox on your Proxmox VE system. It simplifies the installation process.

This method ensures automatic updates and integrates the plugin into the Proxmox package management system, making future updates and management much easier.

Procedure:

  1. Download the PGP/GPG Public key: Before configuring the APT repository, you need to download the PGP/GPG public key used to sign the repository packages. This ensures the integrity and authenticity of the packages that will be installed on your system.
      Open a terminal on your Proxmox VE server and run the following command to download the key directly into the /usr/share/keyrings directory:
      Copy
      Command
      wget -P /usr/share/keyrings https://github.com/DataCoreSoftware/Scripts/releases/download/SSY_PVE_Plugin/ssy-pgp-key.public
      This command saves the ssy-pgp-key.public file in the /usr/share/keyrings directory. The key will be used later to verify the authenticity of the SANsymphony plugin packages.
  2. Configure the APT Repository: Once the public key is downloaded, the next step is to configure the APT repository that will provide access to the SANsymphony Storage Plugin for Proxmox package.
      Add the DataCore repository to your Proxmox VE system:
      Copy
      Command
      echo "deb [signed-by=/usr/share/keyrings/ssy-pgp-key.public] https://datacoresoftware.github.io/Scripts/ssy-apt-repo stable main" | tee /etc/apt/sources.list.d/ssy.list
      Next, update APT and install the new ssy-plugin package.
      Copy
      Command
      apt update
      apt install ssy-plugin

Installing the SANsymphony Storage Plugin for Proxmox via DPKG

The DPKG method requires you to manually download the .deb package and install it using the dpkg command on your Proxmox server. Unlike the APT method, this approach gives you more control but does not automatically handle dependencies.

Procedure:

  1. Download the DataCore Plugin Package: Run the following command on your Proxmox server to download the .deb package: 
      Copy
      Command
      wget https://github.com/DataCoreSoftware/Scripts/releases/download/SSY_PVE_Plugin/SANsymphony-plugin_1.0.2_amd64.deb
      This command downloads the SANsymphony-plugin_1.0.2_amd64.deb file from the specified URL.
  2.  Install the Package Using DPKG:
    1. Once the .deb package is downloaded, the next step is to install it on your Proxmox server.
    2. Run the following command:
      3. Copy
      Command
      dpkg -i SANsymphony-plugin_1.0.2_amd64.deb
      The dpkg -i command installs the specified .deb package on your system. Once the installation starts, dpkg will unpack and install the files required for the plugin.

    3. When installing the SANsymphony Storage Plugin for Proxmox using the DPKG, existing iSCSI and Multipath configuration files are automatically backed up to "/var/backups/SANsymphony-Plugin-Backup", allowing you to restore the previous configuration if needed.

  3. After the SANsymphony plugin is installed, you can run the following command to check if the SANsymphony Storage Plugin for Proxmox has been installed:
      Copy
      Command
      dpkg -l | grep ssy-plugin

Before installation, ensure the multipath-tools and jq packages are installed on the Proxmox server.

Manual Installation of SANsymphony Storage Plugin for Proxmox

This method involves manually setting up the directory for the SANsymphony Storage Plugin for Proxmox and copying the necessary plugin files to the correct location on your Proxmox server.

Procedure:

  1. Navigate to the Proxmox Storage plugin directory.
      Copy
      Command
      cd /usr/share/perl5/PVE/Storage/
  2. Create the required directory (if it does not exist):
      Copy
      Command
      mkdir -p /usr/share/perl5/PVE/Storage/Custom
  3. Download the SANsymphonyPlugin.pm file from DataCore Software Proxmox Repository. Ensure the file name is exactly SANsymphonyPlugin.pm.
  4. If you already have the SANsymphonyPlugin.pm file, simply copy it into the newly created directory using this command:
      Copy
      Command
      cp /path/to/SANsymphonyPlugin.pm /usr/share/perl5/PVE/Storage/Custom/
  5. Download the ssy-plugin, ssy-multipath, and ssy-configure-iscsid files from the DataCore Software Proxmox Repository.
  6. Copy the files and place them in the user bin directory:
      Copy
      Command
      cp /path/to/ssy-plugin /usr/bin
      cp /path/to/ssy-multipath /usr/bin
      cp /path/to/ssy-configure-iscsid /usr/bin
  7. Add execute permissions to the files so they can be run from any directory:
      Copy
      Command
      chmod +x /usr/bin/ssy-plugin
      chmod +x /usr/bin/ssy-multipath
      chmod +x /usr/bin/ssy-configure-iscsid
  8. Add DataCore Udev rules. Refer to SCSI Disk Timeout for more information.
  9. Configure iSCSI Settings. Refer to the iSCSI Settings section in the Proxmox Configuration Guide.
  10. Configure iSCSI Multipath. Follow the steps in the SCSI Multipath section of the documentation.
  11. Install jq Debian package:
      Copy
      Command
      apt install jq

If you encounter any issues or errors during the setup or operation, refer to the Troubleshooting section for assistance.

Configuration Updates Performed After Plugin Installation

When the SANsymphony Storage Plugin for Proxmox is installed using any of the supported methods (APT repository or DPKG package), the installer updates several host-level configurations immediately after the installation completes.

These updates are required for proper operation of SANsymphony storage with Proxmox VE and are applied as soon as the plugin is installed, without requiring manual configuration. The following sections describe the configuration changes that are applied during installation.

iSCSI Settings

On Proxmox VE nodes, the iSCSI service does not start automatically by default after a system reboot. During installation of the SANsymphony Storage Plugin for Proxmox, the installer updates the iSCSI configuration to ensure reliable connectivity to SANsymphony storage.

  • Configures the iSCSI initiator to start automatically by updating the /etc/iscsi/iscsid.conf file:
      Copy
      Command
      node.startup = manual 
      node.leading_login = No

  • Updates the session replacement timeout from the default value of node.session.timeo.replacement_timeout (120 seconds) to the recommended value of 15 seconds.

      Copy
      Command
      node.session.timeo.replacement_timeout = 15

  • Increases the initial login retry count to the recommended value of node.session.initial_login_retry_max (64) to handle scenarios where a port reinitialization prevents automatic login.

      Copy
      Command
      node.session.initial_login_retry_max = 64
      These changes are applied automatically by the plugin immediately after installation and do not require manual configuration.
  • A backup of the original iscsid.conf file is stored at the following location:
      Copy
      Command
      /var/backups/SANsymphony-Plugin-Backup/iscsid.conf
      For more information, refer to the iSCSI Settings section in the Proxmox Configuration Guide.

iSCSI Multipath Configuration

To ensure high availability and proper path management for SANsymphony virtual disks, the plugin installation updates the multipath configuration on the Proxmox VE node immediately after installation. Refer to iSCSI Multipath for more information.

As part of the installation, the plugin creates or updates the multipath configuration file at the following location:

    Copy
    Command
    /etc/multipath.conf

If the multipath.conf file already exists, a backup of the original file is created at the following location:

    Copy
    Command
    /var/backups/SANsymphony-Plugin-Backup/multipath.conf

The configuration applied includes DataCore-recommended defaults and device-specific settings equivalent to the following:

    Copy
    Command
    defaults {
        user_friendly_names    yes
        polling_interval       60
        find_multipaths        "smart"
    }

    blacklist {
        devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*"
        devnode "^hd[a-z]"
    }

    devices {
        device {
            vendor               "DataCore"
            product              "Virtual Disk"
            path_checker          tur
            prio                  alua
            failback              10
            no_path_retry         fail
            dev_loss_tmo          60
            fast_io_fail_tmo      5
            rr_min_io_rq          100
            path_grouping_policy  group_by_prio
        }
    }

Multipath Service Restart

After applying the multipath configuration, the installer restarts the multipath service, so the changes take effect immediately:

    Copy
    Command
    multipath -r

Custom udev Rule for DataCore Disks

During installation, the plugin adds a custom udev rule to ensure appropriate SCSI timeout handling for SANsymphony virtual disks.

The following file is created or updated as part of the installation:

    Copy
    Command
    /etc/udev/rules.d/99-datacore.rules

With the following rule:

    Copy
    Command
    SUBSYSTEM=="block", ACTION=="add", ATTRS{vendor}=="DataCore", ATTRS{model}=="Virtual Disk    ", RUN+="/bin/sh -c 'echo 80 > /sys/block/%k/device/timeout' "

The udev rules are reloaded automatically by the SANsymphony Storage Plugin for Proxmox so the changes take effect immediately.

    Copy
    Command
    udevadm control --reload-rules
    udevadm trigger --subsystem-match=block

Post-Installation Proxmox Service Updates

During installation of the SANsymphony Storage Plugin for Proxmox, several Proxmox Virtual Environment (PVE) services are reloaded or restarted to ensure that plugin configurations are correctly applied and available immediately. The installer attempts to reload services first and performs a restart only when required, ensuring zero or minimal disruption during installation.

The following Proxmox services may be reloaded or restarted as part of the post-installation process:

  • pvedaemon.service – Proxmox VE API daemon
  • pveproxy.service – Proxmox VE web interface proxy
  • pvestatd.service – Proxmox VE status update daemon
  • pvescheduler.service – Proxmox VE task scheduler
  • pve-ha-lrm.service – Proxmox VE HA local resource manager

The service reload and restart operations are safe and include fallback handling to ensure the installation continues even if a service is not currently running.

Learn More