Skip to content

Installing SQL Agent on Linux

Server Selection

The SQL Agent application can be installed on Linux or Windows. For best performance and throughput, the ideal and recommended solution is to install it on the same system that hosts the SQL Server database.

Preparing to Install

The agent runs as a systemd service. Default values are used for the user account name, user group and profile name to be used, but can be customized. For more information, refer to Preparing to Install on Linux.

Installation

Installing SQL Agent on a Linux system involves downloading and running an RPM installer. The installation can be downloaded from the Synergex Resource Center.

The name of the installation file will be as shown below, where n.n.n.n is the version number of the product you've downloaded:

Linux SQL Agent Installer
sip-sql-agent-n.n.n-n.el9.x86_64.rpm

The installation is started using the package manager and requires root privileges, like this:

Install SQL Agent
sudo dnf install sip-sql-agent-n.n.n-n.el9.x86_64.rpm

The product will be installed into the directory /usr/lib/synergex/sip/sql-agent.

Configuration

By default, the ISAM Agent runs on TCP/IP port 2127 and needs two essential configuration values to operate:

  • The URL (including port) of the Configuration Server, if in use.
  • The name of the profile to load.

The default values are

  • Configuration Server URL: https://localhost:5120
  • Profile name: 'default'

If you need to change these values, please refer to the information below.

Changing the Service Port Number

Changing the Configuration Server URL

When the agent starts, it attempts to determine the URL of a Configuration Server in the following ways:

  • Checks for a command-line parameter --config-server followed by the URL and port of the config server.
  • Checks for an environment variable SIP_CONFIG_SERVER that specifies the URL and port of the config server.
  • Checks /usr/lib/synergex/sip/isam-agent/appsettings.json for a ConfigurationServerUrl property that specifies the URL and port of the config server.

Changing the Profile Name

When the agent starts it attempts to determine the profile name in the following ways:

  • Checks for a command-line parameter --config-profile followed by the name of the profile to use.
  • Checks for an environment variable SIP_CONFIG_PROFILE that specifies the name of the profile to use.
  • Checks /usr/lib/synergex/sip/isam-agent/appsettings.json for a ProfileName property that specifies the name of the profile to use.

SQL Server 2022 Time Processing

When implementing SQL Replication using the SQL Agent, part of the preparation and deployment involves the generation of custom code that is used to interact with the SQL Server tables. This custom code understands the fields and data types used in your application and is responsible for transposing that information to appropriate SQL Server column date types.

In SQL Server 2022, the PolyBase environment did not correctly process time fields (HH:MM and HH:MM:SS) when processing data from parquet data sources, and we had to work around the problem in the generated SQL code. Microsoft corrected the issue in SQL Server 2025, but this was a breaking change that we once again had to code our way around.

By default, the SQL Agent environment is configured with the assumption that SQL Server 2025 (or later) will be used. If SQL Server 2022 is being used, and the application data files contain time fields in replicated files, you must set the Sql2022TimeProcessing property in the Database section of the master configuration file (MasterConfig.json) before starting the SQL Agent application.

Service Management

The SQL Agent runs as a standard Linux systemd service and can be controlled using the systemctl utility. Some examples of common systemctl commands are as follows:

Show status
  sudo systemctl status sip-sql-agent
Restart service
  sudo systemctl restart sip-sql-agent
Stop service
  sudo systemctl stop sip-sql-agent
Disable service
  sudo systemctl disable sip-sql-agent
Enable service
  sudo systemctl enable sip-sql-agent

Upgrades

To upgrade the SQL Agent to a new version:

  • Review the release notes for the new version so you're aware of any prerequisite tasks or tasks that must be completed after the upgrade.
  • Download the installer for the new version and copy it to the target system.
  • Make sure you still have the installer for the version you are currently running, in case you need to revert to that version for any reason.
  • Perform any prerequisite tasks as defined in the release notes.
  • When you're ready to perform the upgrade, stop the service and verify that it stopped.
  • Execute the installer for the new version. You don't need to remove the old version; the installer for the new version will perform an in-place upgrade.
  • Perform any post-upgrade tasks as defined in the release notes.
  • Restart the service and verify that it started.
Upgrade SQL Agent
  sudo systemctl stop sip-sql-agent
  sudo systemctl status sip-sql-agent
  sudo dnf install sip-sql-agent-n.n.n-n.el10.x86_64.rpm
  sudo systemctl start sip-sql-agent
  sudo systemctl status sip-sql-agent

Removal

To remove the SQL Agent from a Linux system:

  • Stop the service and verify that it stopped.
  • Remove the product using the package manager.
Stop the Agent before removing
  sudo systemctl stop sip-sql-agent
  sudo systemctl status sip-sql-agent
  sudo dnf remove sip-sql-agent