Windows

Version 20.0.7580


Windows


The Windows version of ArcESB 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.

Embedded Server

This section shows how to configure the stand-alone, embedded Web server, including how to Host TLS/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 Arc icon in the taskbar and click Server Options.
  2. Select the Run as a Windows Service option.
  3. Save your changes.

Host TLS/SSL/TLS Connections (Embedded Server)

You can require TLS as well as offer services in plaintext. This section shows how to host TLS/SSL/TLS connections in the stand-alone server included with the Windows edition of the application. To deploy TLS/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.

Server Dialog

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.

    Add Snap-In

  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:

Cloud Gateway

  • 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, first enable the ‘Users’ tab in the embedded web server UI:

  • Open the ArcESB.xml file located in the root of the installation directory
  • Add a new element (or modify the existing element) called ShowAuthentication and set its value to ‘true’:
    • <ShowAuthentication>true</ShowAuthentication>
  • Exit the embedded server UI (using the ‘Exit’ button in the toolbar rather than the ‘X’ in the top right of the window) and re-launch the application

Once these steps are completed, the embedded web server UI will include a ‘Users’ tab that defines the users and groups that can authenticate to the Arc administration console. To add new users or groups, click the Add... button to the right.

Configuration in 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, “arcesb”.
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\ArcESB\www.

Configure Permissions

The application must be able to access several folders within the installation directory. Some folders only need to be included if specific features of the application are used (e.g. hosting an SFTP server). All installations will need to grant permissions to the following folders:

  • data: Stores configuration data, certificates, logfiles, and the data files processed by the application
  • www: Stores the web resources that governs the specific site within IIS

Installations may also need to grant permissions to the following folders:

  • sftpserver - Only if the SFTP Server is enabled and running
  • ftpserver - Only if the FTP Server is enabled and running
  • oftpserver - Only if the OFTP Server is enabled and running
  • the www folder and data folder, located in the installation directory. Allow access to the application pool associated with the application:
  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: IIS AppPool\your-application-pool. For example, enter 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)

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/arcesb. 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, “arcesb”.
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\ArcESB\www.

Configure Permission

The application must be able to access the www folder and data folder, located in the installation directory. Allow access to the application pool identity associated with the application:

  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: IIS AppPool\your-application-pool. For example, IIS AppPool\DefaultAppPool.
  3. Ensure that the application pool has the following permissions:

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

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)

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="/arcesb" 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/arcesb. If you are getting any errors, see Troubleshooting.

Host TLS/SSL/TLS Connections (IIS)

TLS/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 TLS/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 TLS/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/arcesb/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.

User Management

Arc uses the standard ASP.NET approach for managing the set of users who are permitted to access the administration console. Note that this section does not apply when using Windows/AD authentication with the embedded web server.

Regardless of whether Arc is hosted via the embedded web server or IIS, the list of users and associated permissions is held in a Web.Config file found within the ‘www’ folder of the installation directory. To inspect or edit the authorized users, find the following XML structure within this file:

<configuration>
  <system.web>
    <authentication>
      <forms>
        <credentials>

Each user element contained within the credentials element defines a username and password to grant access to the administration console. Access is granted on an all-or-nothing basis; all listed users have full read/write/modify/delete permissions when logged in to the application.

Find and Configure the Application Directory

Arc’s Application Directory holds all of the data used by the application: configuration data, application data, logging data, certificates, etc. Typically, the Application Directory is the same as the Installation Directory, which defaults to the following location:

C:\Program Files\ArcESB

The Application Directory can be configured to be a different folder from the Installation Directory, 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 will not move other application resources like .exe’s, .jar’s, etc.

Web.Config

The Application Directory is configured in the Web.Config file within the ‘www’ folder of the Installation Directory.

This file contains a commented-out AppDirectory block that that describes the following appSettings tag. The path to the desired Application Directory should be set as the ‘AppDirectory’ key with appSettings.

The Application Directory can be set to any local or network path for which the application has read and write permissions.

Configure the Application Database

Arc’s 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)

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 MySQL or SQL Server.

Web.Config

The Application Database is configured in the Web.Config file within 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.