Search

Windows

Version 22.0.8473

Windows

The Windows version of CData Arc includes a stand-alone embedded web server and can also be hosted in IIS. This section describes various options for hosting the application in Windows.

If you do not have experience with IIS, the embedded server is recommended. The embedded server is automatically deployed at installation and provides a simple interface for server-level administration tasks such as configuring logging, running the application as a service, and enabling SSL/TLS.

Using the Embedded Server

This section shows how to configure the stand-alone, embedded Web server, including how to host SSL/TLS connections and configure the Cloud Gateway, a reverse SSH tunnel.

When hosted in the stand-alone server, the application can be run as a Windows service:

  1. Right-click the CData Arc icon in the taskbar and click Server Options.
  2. Select the Run as a Windows Service option.
  3. Save your changes.

Host SSL/TLS Connections (Embedded Server)

You can require TLS as well as offer services in plaintext. This section shows how to host SSL/TLS connections in the stand-alone server included with the Windows edition of the application. To deploy SSL/TLS for the Java edition, refer to the documentation for the Java servlet you are using to host the application.

  1. Right-click the icon for the application in the Windows system tray and click Server Options.
  2. On the Web Server tab, select Enable TLS and select a port that you want to listen on for TLS connections.
  3. Click the button next to the TLS Server Certificate box to select a private key certificate. The certificate with private key must be installed to the Local Computer certificate store. If there are no certificates available that match that criteria, click Create New Certificate to create a simple certificate for this purpose.

The server will restart and begin serving TLS requests after you save your changes.

Manage Personal Certificates

If you would like to manage the certificates that are available in the certificate selection dialog, they are located in the Personal certificate store for the local computer. To add a certificate to the Windows store:

  1. Launch Microsoft Management Console by entering mmc from the Run menu.
  2. Click File > Add/Remove Snap-In.

  3. Select Certificates from the Available Snap-Ins table and click Add.

  4. Select Computer Account > Local Computer.
  5. After adding the snap-in, click Certificates (Local Computer) > Personal > Certificates to display the available certificates. The certificates for which a private key is available have a small key icon superimposed over the certificate icon.
  6. To import a certificate from the local disk into this store, click Action > All Tasks > Import. After completing the import wizard, the certificates are available in the application certificate selection dialog.

Cloud Gateway

The Cloud Gateway feature of Arc provides a simple way to expose the application to the Internet without the need for firewall changes. As long as a publicly accessible SSH server is available, Arc may be accessed via a port on the publicly accessible SSH server by leveraging an SSH Reverse Tunnel.

To leverage this functionality, right-click the application icon in the system tray and select Server Options. Navigate to the Cloud Gateway tab, as shown below, and enter the following information:

  • Host indicates the SSH server that Arc connects to.
  • Port indicates the port on which the SSH host is listening for connections. Most SSH servers listen on port 22, which is the default value.
  • Authentication Type indicates the type of authentication to use. Password, Public Key, Multi-Factor, and Keyboard Interactive are supported.
  • User indicates the username Arc uses to authenticate to the SSH server.
  • Password indicates the password used to authenticate, if required, by the Authentication Type used.
  • Certificate indicates the certificate Arc uses to authenticate to the SSH server during Public Key Authentication.
  • Server Fingerprint indicates the SSH host key fingerprint of the SSH server. This value is read-only and purely informational.
  • Forwarding Port indicates the port that the publicly available SSH server listens on for connections to forward to Arc.

In addition, it may be necessary to change the configuration of your SSH Server to allow port forwarding. Default SSH server configuration may not always enable port forwarding to non-localhost addresses. For example, if connecting to an OpenSSH server, the GatewayPorts property must be set to yes or clientspecified in the SSH server configuration file.

After you enter this information, click Test Connection to test the connection to the SSH server to verify the validity of the information provided. If successful, once the application is restarted, Arc is accessible via the Forwarding Port on the SSH host. For example, if the SSH server my.ssh.host was specified, with a Forwarding Port of 8401, entering https://my.ssh.host:8401 in a browser would cause the communication to be forwarded to the local machine where Arc is running, allowing public access despite it not being directly accessible.

Windows Authentication

By default, the embedded web server uses ASP.NET’s forms-based authentication, wherein a username/password combination must be entered into a webform (i.e. a login portal) to grant access to the administration console. Arc also supports Windows/Active Directory authentication to grant application access to specific Windows users or security groups.

To enable Windows authentication, simply open the embedded web server configuration UI (right-click the Arc icon in the system tray and select Server Options) and toggle the Authentication Type field under the ‘Web Server’ tab.

By default, access is granted to the current Windows user managing the web server. To configure the users and groups permitted to access the application, add new users within the Users tab of the Settings page in the application.

Users must be added within the application using DOMAIN\Username syntax. Users must be added individually, as an entire group cannot be granted access to the application at this time.

Using IIS

These instructions cover several versions of IIS and Windows. If you run into difficulties following one of these guides, see the last section, Troubleshooting. If your version is not covered in this tutorial or if you have other questions, contact our support team for further assistance.

IIS 8, 8.5, and 10

Create a New Web Application

Note: This example uses the default website.

To host the application on your website:

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application.
  3. In the Add Application dialog that is displayed, enter the following information:
Alias The name for the application; for example, “arc”.
Application Pool The application pool associated with the application. This tutorial uses “DefaultAppPool”.
Physical Path The path to the www directory, in the directory where the application was installed. The default location for this directory is C:\Program Files\CData\Arc\www.

Configure Directory Permissions

The application must have full access to the Arc application directory for full functionality.

In ArcESB 2021 and earlier, the application directory and the installation directory were the same—by default, C:\Program Files\ArcESB\. If you upgraded from a previous version of Arc to Arc 2022, this is likely still your application directory.

In Arc 2021, the application directory was split from the install directory. The installation directory is now C:\Program Files\CData\CData Arc. The application directory is now C:\ProgramData\CData\Arc\.

The application directory contains the following folders:

  • connectors
  • data
  • db
  • locks
  • logs
  • schemas
  • workspaces

The install directory contains:

  • Program executables (CData.Arc.exe, .exe) and configuration files
  • the www folder and subfolders
  • the www_services folder and subfolders

To set permissions, locate the application directory for your Arc installation and follow these steps:

  1. Right-click the folder and click Properties. On the Security tab, click Edit > Add.
  2. In the Enter the object names to select box, enter the following, substituting the name of the application pool: IIS AppPool\\[your-application-pool]. For example, IIS AppPool\\DefaultAppPool.

  3. Ensure that the application pool has the following permissions:

    • Read
    • Write
    • Modify
    • Read & Execute
    • List Folder Contents

Note: You can also use the command line to allow access to the application pool. For example:

icacls "www" /grant "IIS APPPOOL\\DefaultAppPool":(OI)(M)

Configure Server Permissions

If you are using sftpserver or ftpserver, you must ensure that the application pool has the correct permissions set to the root directory that you have configured for that server. If you created the root directory as a child of the application directory path, then setting permissions on the parent application directory and its subfolders should be sufficient.

Prevent Application Processes from Unloading

IIS can shut down a web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool’s resource use is too high. This may halt background tasks from occurring in your application. Ensure that the application stays running by modifying the following settings:

  1. Enable the optional Application Initialization feature.

    In Windows Server 2012 R2 and Windows Server 2016, open Server Manager and click Dashboard > Quick Start > Add Roles and Features. The Add Roles and Features wizard opens. In the Server Roles step, click Web Server (IIS) > Web Server > Application Development > Application Initialization.

    In Windows 8 and Windows 10, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > Application Initialization.

  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the workspace, right-click the application pool and click Advanced Settings.

  4. In the General settings, set Start Mode to AlwaysRunning.

  5. In the Process Model settings, set the Idle Timeout property to 0.

    If you are using IIS 8, ensure that the Start Automatically property in the General settings is set to True.

  6. In the CPU section, set the LimitInterval property to 0.
  7. In the Recycling section, set the Regular Time Interval property to 0.
  8. In the Generate Recycle Event Log Entry node, under the Recycling section, set Regular Time Interval to False.

Configure ASP.NET App Pool Recycling

IIS recycles regularly so that it can clean up the ASP.NET app pool processes. You can instead schedule recycling during off-peak hours by navigating to the Recycling section, and setting Specific Time to True and enter the times to recycle in the format hh:mm:ss.

Preloading Applications

IIS’s preloading feature improves performance by allowing the application to run prior to a user connecting. To enable this feature, right-click the web application associated with Arc in the Connections pane and select Manage Application > Advanced Settings. In the PreloadEnabled menu, select True.

When PreloadEnabled is set to True, IIS simulates a user request to the default page of the website or virtual directory so that the application initializes.

Confirm Settings

To open the application, navigate to http://localhost/arc. If you are getting any errors, see Troubleshooting.

IIS 7 and 7.5

Create a New Web Application

To host the application on your website.

Note: This example uses the default website.

  1. In the IIS Manager, expand the node for your server in the Connections panel.
  2. Expand the Sites node, right-click your website, and click Add Application.
  3. In the Add Application dialog that is displayed, enter the following information:
Alias The name for the application; for example, “arc”.
Application Pool The application pool associated with the application. This tutorial uses “DefaultAppPool”.
Physical Path The path to the www directory, in the directory where the application was installed. The default location for this directory is C:\Program Files\Arc\www.

Configure Permission

See Configure Permissions for IIS 8, 8.5, and 10 above. The information is applicable across IIS versions.

Prevent Application Processes from Unloading

IIS can shut down a web application for several reasons, including when an idle timeout is exceeded, or when it deems the application pool’s resource use is too high. This may halt background tasks from occurring.

This version of IIS does not have configuration settings to always keep the Web application running. To ensure that the application pool is always running so that background tasks will occur, you need to configure a script to issue an HTTP request to the application periodically.

In IIS 7.5, you can ensure that the application stays running by modifying the following settings:

  1. Install the Application Initialization Extension for IIS 7.5. You can download it at http://www.iis.net/download/ApplicationInitialization.
  2. In the IIS Manager, click Application Pools in the Connections panel.
  3. In the workspace, right-click the application pool and click Advanced Settings.
  4. In the General settings, ensure that Start Automatically is set to True.
  5. In the Process Model settings, set the Idle Timeout property to 0.
  6. In the CPU section, set the LimitInterval property to 0.
  7. In the Recycling section, set the Regular Time Interval property to 0.
  8. In the Generate Recycle Event Log Entry node, under the Recycling section, set Regular Time Interval to False.
  9. Modify the settings for the application pool entry in the ApplicationHost.config file, located in C:\Windows\System32\inetsrv\config\. Add startMode=”AlwaysRunning” and autoStart=”True” to the appropriate entry. For example:
<applicationPools>
<add name="DefaultAppPool" managedRuntimeVersion="v4.0" startMode="AlwaysRunning" autoStart="true"/>
</applicationPools>

Configuring ASP.NET App Pool Recycling

IIS recycles regularly so that it can clean up the ASP.NET app pool processes. You can instead schedule recycling during off-peak hours by navigating to the Recycling section, and setting Specific Time to True and enter the times to recycle in the format hh:mm:ss.

Preloading Applications

IIS’s preloading feature improves performance by allowing the application to run prior to a user connecting. To enable this feature, edit the ApplicationHost.config file (C:\Windows\System32\inetsrv\config\ApplicationHost.config) and add the preloadEnabled attribute to the <application> element associated with the application. The application node is a child element of the sites node, as shown in the following example:

<sites>
  <site name="Default Web Site" id="1">
  <application path="/arc" applicationPool="DefaultAppPool"  preloadEnabled="true">
  ...

When PreloadEnabled is set to true, IIS simulates a user request to the default page of the website or virtual directory so that the application initializes.

Confirm Settings

To open the application, navigate to http://localhost/arc. If you are getting any errors, see Troubleshooting.

Host SSL/TLS Connections (IIS)

SSL/TLS can be used to protect the confidentiality of your business-critical and mission-critical communications with trading partners. The following steps assume you already have a certificate you can use to enable SSL/TLS on your server.

  1. In IIS Manager, click your website’s node from the Connections pane.
  2. Click Bindings on the Actions pane.
  3. Click Add and select HTTPS.
  4. Choose the server certificate.
  5. If you want to require SSL/TLS, double-click the SSL/TLS Settings icon in the workspace with your website’s node still selected. Select Require SSL/TLS and click Apply in the Actions pane.

Troubleshooting

The sections below provide resolutions for several common errors.

The application stops responding some time after I log out.

IIS is possibly unloading your application after it times out from inactivity. By default, IIS terminates the worker process assigned to the application after 20 minutes of inactivity. The section “Prevent Application Processes from Unloading”, in the steps to set up your version of IIS, explains how to override this feature.

In IIS 7.5, 8, and 8.5, you can ensure the application stays running by modifying the configuration settings in the IIS Manager.

Versions of IIS before IIS 7.5 do not have configuration settings to always keep the web application running. To ensure that the application pool is always running so that background tasks occur, you need to configure a script to issue an HTTP request to the application periodically.

Visiting http://localhost/application results in a “Page Cannot Be Displayed” error (an HTTP 404 error).

This can happen if ASP.NET is not enabled. To confirm if ASP.NET is enabled, go to http://localhost/arc/favicon.ico. If this page loads successfully, then ASP.NET is not enabled.

If you are running IIS7 or higher, select Control Panel > Programs (or Programs and Features) > Turn Windows Features On or Off > Internet Information Services > World Wide Web Services > Application Development Features. Select the check box next to ASP.NET.

If you are using Windows Server 2003 open the Internet Information Services Manager, expand the local computer node, and click Web Service Extensions > ASP.NET > Allow. You may also need to follow the steps below.

If you are running IIS 6 or earlier open the Windows command prompt, navigate to the .NET Framework version installation, such as C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727, and issue the aspnet_regiis -i</b> command. You may have to change Framework to Framework64 if you are using a 64-bit processor. The output should resemble the following:

C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727>aspnet\_regiis -i
  Start installing ASP.NET (2.0.50727).
  ...
  Finished installing ASP.NET (2.0.50727).

Restart IIS by issuing the iisreset command. The output should resemble the following:

  C:\\WINDOWS\\Microsoft.NET\\Framework\\v2.0.50727>iisreset

  Attempting stop...
  Internet services successfully stopped
  Attempting start...
  Internet services successfully restarted

The section is locked at a parent level. Locking is either by default (overrideModeDefault=”Deny”), or set explicitly by a location tag with overrideMode=”Deny” or the legacy allowOverride=”false”.

This error can occur if ASP.NET is not installed.

IIS 8 and 8.5

First, determine the version of the ASP.NET CLR that is used by your application pool. You will need to install the version of ASP.NET that ships the same ASP.NET CLR. For example, ASP.NET 4.5 uses CLR version 4.0. You can find the CLR version in the IIS Manager by clicking Application Pools in the Connections panel. The .NET CLR Version property is displayed in the list of application pools.

In Windows Server 2012, open Server Manager and click Dashboard > Quick Start > Add roles and features. The Add Roles and Features wizard opens. Click Web Server (IIS) > Web Server > Application Development and select the appropriate version of ASP.NET.

In Windows 8, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > Application Development and select the appropriate version of ASP.NET.

IIS 7 and 7.5

In Windows 7, open the Control Panel and click Programs and Features > Turn Windows Features On or Off. Click Internet Information Services > World Wide Web Services > Application Development Features > ASP.NET.

In Windows Server 2008, open Server Manager and click Add Role Services. Select Web Server > Application Development > ASP.NET.

Managing Users

Upon first starting, Arc will prompt for the creation of a user with username/password credentials. After this first user is created, users can be added, deleted, and managed via the Settings page of the application, under the Users tab.

More information about user management and roles can be found in the User Roles section.

Configuring the Application Directory

The Arc application directory contains all of the data used by the application: configuration data, application data, logging data, certificates, etc. Typically, the application directory defaults to the following location:

C:\ProgramData\CData\Arc

The application directory can be set to be a different folder, which is useful in a variety of scenarios:

  • Clustering multiple instances of Arc
  • Using a shared network drive for application data
  • Embed Arc within other systems accessing the same folders

Changing the application directory will move the application’s data files, but it will not move other application resources like .exe’s, .jar’s, etc.

Web.Config

To set a custom application directory, open the Web.Config file in the www folder of the installation directory. At the bottom of the file, inside the <appSettings> tags, locate this value:

<add key="AppDirectory" value="C:\ProgramData\CData\Arc" />

Replace the text inside the quotation marks after value with your desired application directory. This can be any local or network path for which the application has read and write permissions.

Configuring the Application Database

The Arc Application Database stores several tables of application data, including:

  • Transaction Log (metadata for each transaction processed by the application)
  • Application Log (application-level errors and events)
  • Access Log (requests to the application’s web endpoint)
  • Audit Log (user-made changes to the Arc configuration)

By default, Arc uses a SQLite database in the Installation Directory as the Application Database, but this can be configured to use an enterprise database like SQL Server, PostgreSQL, or MySQL.

The Application Database is configured in the Web.Config file in the www folder of the Installation Directory. This file contains a commented-out AppDb block that that describes the following connectionStrings tag. The connection string and provider name for the target database should be set within the ‘AppDb’ key.

Setting the Connection Strings

The sections below provide example connection strings for various server configurations in the Web.Config file. You can set these values in plaintext, or you can generate an encrypted connection string to use for the connectionString value.

SQL Server

<connectionStrings>
   <add name="AppDb" connectionString="server=localhost;database=sqlserver;user=MyUserName;password=MyPassword;" providerName="System.Data.CData.SQL" />
</connectionStrings>

MySQL

<connectionStrings>
   <add name="AppDb" connectionString="server=localhost;database=appdb;user=MyUserName;password=MyPassword;" providerName="System.Data.CData.MySQL" />
</connectionStrings>

PostgreSQL

<connectionStrings>
   <add name="AppDb" connectionString="server=localhost;port=5432;database=postgres;user=postgres;password=MySecretPassword;" providerName="System.Data.CData.PostgreSQL" />
</connectionStrings>

Generating an Encrypted Database Connection String

Arc provides the ability to generate an encrypted connection string for your application database connection. You can use this encrypted connection string to specify the application database without storing your login credentials in plaintext in the Arc configuration files. To generate an encrypted connection string, issue the following command in the installation directory where CData.Arc.exe is located, substituting your connection information for the example string at the end:

CData.Arc.exe -EncryptConnectionString server=serverName;database=databaseName;user=userName;password=passwordSample;

After you issue the command, the command window prints the encrypted string. For example:

ENCRYPTEDA:XuUY73BQHKdzWn52z6AqLvZ7uG6jlwkcsQL8yGM8sQ2Znfm1HwG6BpH+LP92mGBBCQX2/IWMal2V5a1AujfltOwResXjAijDzxJ7JmvgUt4=

You can then use this encrypted string in place of the plaintext value for connectionString as shown above.

Setting Login Lockouts

Arc will automatically lock out users who enter incorrect passwords too many times in order to prevent brute force attacks. By default, a user who enters 6 incorrect passwords within 5 minutes will be locked out for 30 minutes when the 7th try fails.

These settings can be modified by editing the Web.Config file within the www folder of the Installation Directory. There are 3 settings relevant to lockouts:

  • LockoutFailedAttempts - the number of incorrect passwords that will trigger a lockout (set this to 0 to disable lockouts)
  • LockoutMinutes - the duration of the lockout (default 30 minutes)
  • LockoutTimeCheckPeriod - the period after which the number of failed attempts is reset to 0 (default 5 minutes)

Each of these settings can be set under the <appSettings> tag in the Web.Config file like the following:

<appSettings>
     <add key="LockoutFailedAttempts" value="0"/>
</appSettings>