Zumero


ZSS Server: Installation


1. About

2021-03-18 11:06:38

This document explains how the ZSS Server components are installed.

2. Overview

ZSS Server is a module for Internet Information Services (IIS) 7.5 (or higher).

ZSS Server communicates with SQL Server using ODBC. It need not be on the same machine as SQL Server itself.

We provide an installer application which makes it easy to get started.

3. Files

ZSS Server is contained in four files:

zumero_server.dll The Zumero IIS Module
config_editor.exe The ZSS Server Configuration Utility
zumero_schema.xml IIS configuration schema
events.man Zumero IIS Module event manifest

4. Configuration

The IIS module needs four configuration parameters from its web.config file:

odbc_connection_string  
temp_directory  
license_key  
activation_key  

The easiest way to manipulate these configuration parameters is by using the ZSS Configuration Utility.

5. The Installer

The easiest way to install the Zumero server is to use the installer.

The installer will:

  • Install SQL Native Client if needed

  • Place the Zumero IIS Module, the ZSS Configuration Utility, and related files in "c:\Program Files\Zumero\ZSS Server"

  • Create the Zumero server's webroot in "c:\ProgramData\Zumero\ZSS Server\www"

  • Create the Zumero server's temp_directory at "c:\ProgramData\Zumero\ZSS Server\temp"

  • Create a website and an application pool in IIS, both named "zumero"

  • Bind the Zumero website to port 8080

After installation, the Zumero server will need the license key, activation key, and ODBC connection string configuration parameters to be set. These parameters can be set using the ZSS Configuration Utility which can be launched by clicking the "Configure Server" button on the last page of the installer.

6. Creating Additional Zumero Enabled IIS Sites

The ZSS Configuration Utility can be used to create additional IIS sites that have Zumero for SQL Server enabled.

To create a new Zumero enabled IIS site, launch the configuration tool and click the "Add Site" button. A wizard will guide you through setting up a new IIS site.

7. Database Configuration

In your ODBC connection string, you specify how ZSS Server will connect to and authenticate with SQL Server. Whether you are using SQL Server Authentication, Windows Authentication, or Azure Active Directory, it is important to be sure that ZSS Server can authenticate with SQL Server using credentials which are allowed to access your data.

For all ways of authenticating with SQL Server, the keywords for Server and Database are the same.

By default, Driver keyword has the value shown below:

Driver={SQL Server Native Client 11.0};

If you are authenticating to SQL Server using Azure Active Directory, the Driver keyword should be:

Driver={ODBC Driver 17 for SQL Server};

The Server keyword is used to configure the name of the host where SQL Server is running:

Server={server.ad.domain.com};

The Database keyword is used to configure the name of the SQL Server database you are using:

Database={database};

If you are using SQL Server Authentication, you need to specify the UID and PWD keywords:

UID={sql_server_user};
PWD={password};

... and ensure that the specified user has permission to access the database you specified with the Database keyword.

Alternatively, if you are using Windows Authentication, you need to specify the Trusted_Connection keyword:

Trusted_Connection={yes};

... and ensure that the effective user identity for the IIS Zumero AppPool has permission to access the database you specified with the Database keyword.

8. Securing Zumero for SQL Server

8.1. Enabling SSL

The default site created by the ZSS installer is not configured with SSL enabled. While this configuration is acceptable for development purposes, It is highly recommend that SSL is enabled when running ZSS in a production environment.

8.1.1. Obtain an SSL Certificate

First you will need to obtain an SSL certificate for the fully qualified domain name (FQDN) by which your Zumero server will be accessed. The certificate can be purchased from any number of online vendors (Symantec, GoDaddy, GeoTrust, etc…). Each of these providers has tutorials for requesting and importing an SSL certificate into IIS. You can also find a good walkthrough for obtaining an SSL certificate on the SSL Shopper [1] Website.

Once the certificate has been imported into IIS, proceed to the next step.

8.1.2. Enable SSL for the Zumero Site

To enable SSL on the site running zumero you will need to add an HTTPS binding.

  1. In IIS Manager, select your site from the "Connections" panel on the left hand side.

  2. Click on "Bindings…" in the "Actions" panel.

  3. In the "Site Bindings" window, click the "Add…" button to bring up the "Add Site Binding" window.

  4. In this window change the following settings:

    • Change Type to "https".

    • Set the hostname field to the FQDN you used in the Certificate Request.

    • Select the SSL certificate you imported earlier from the "SSL certificate" drop down.

    • Click Ok.

  5. (optional) In the "Site Bindings" window, remove the http binding on port 8080

  6. (optional) To force all connections to use SSL, select the SSL Settings feature in your site's configuration panel and check the "Require SSL" checkbox.

  7. Ensure that Windows firewall and any network firewalls are allowing incoming connections to port 443 on your server.

8.2. Preventing Brute Force Attacks

Zumero for SQL Server does not provide built in mechanisms for preventing brute force authentication attacks. It is highly recommended that ZSS servers in production environments have some sort of exterior mechanism in place to prevent against these kinds of attacks. Below are instructions on enabling an IIS feature to help prevent these kinds of attacks. Alternatively, third party security devices exist that can be used to rate limit or block hosts that attempt to use brute force methods.

8.2.1. IIS Dynamic IP restrictions

IIS versions 7 and newer have an optional feature that can be enabled to help mitigate these kinds of attacks. Below are instructions for installing this feature and where to find its configuration pages. More information on the configuration of this feature can be found online. [2]

  1. Install the following Windows feature:

    • (Windows 7/8) "Internet Information Services" > "World Wide Web Services" > "Security" > "IP Security"

    • (Server 2008 R2, 2012, and 2012 R2) "Web Server (IIS)" > "Web Server" > "Security" > "IP and Domain Restrictions"

  2. Open IIS Manager and select your site from the "Connections" panel on the lest hand side. Alternatively you can configure this at the server level.

  3. Open "IP Address and Domain Restrictions" from the center pane.

  4. The "Edit Dynamic Restriction Settings..." link in the "Actions" panel is where the dynamic filtering is configured.

  5. The "Edit Feature Settings..." link in the "Actions" panel contains further configuration parameters.

9. Troubleshooting

9.1. Look for error messages in Event Viewer

If something is going wrong, the Zumero server should log an error message which you can view using Event Viewer.

9.2. Verify that the Zumero web site is running

Using a web browser to browse to your zumero server (http://<servername>:<port>) will bring up a page displaying the version of the Zumero IIS Module installed.

9.3. Look at Zumero's log table

Zumero keeps its own log in a SQL table. The table is called "log", and it is located in the zumero schema of your SQL Server database.

9.4. Look at Zumero's audit table

Whenever Zumero resolves a conflict between two changes of the data, it adds a row to an audit table. The table is called "audit", and it is located in the zumero schema of your SQL Server database.

10. Preparing your SQL Server data for Zumero Sync

See the documentation for "ZSS Manager".



[1] This walk through is for IIS 7, but it is still valid for IIS 8 and 8.5.