Installation Steps

This section explains the steps needed to install and configure ScaleOut StateServer during a typical installation. You should install ScaleOut StateServer on every server that potentially could join the distributed store, including systems that may be used as spares in case a server fails. A server that runs ScaleOut StateServer is called a host. The installation procedure is as follows:

Product Installation

Download soss_setup32.msi or soss_setup64.msi from ScaleOut Software’s Web site (www.scaleoutsoftware.com).

Note

The SOSS installers require that the .NET 3.5 framework be installed on the target system.
To install the 32-bit version of ScaleOut StateServer, run soss_setup32.msi on the first server in your farm. To install the x64 version, run soss_setup64.msi. The installer will start the console at the end of the installation process so that you can configure the host’s parameters.

Note

You optionally can perform an unattended installation by following the instructions in this section’s Unattended Installation sub-topic.

Note

The installer automatically installs and starts the StateServer service when the StateServer Service installation type is selected. (Please see the Components section for details on installing optional components.) The service is configured to automatically start when the system boots. You can change this behavior using the Windows Service Control Manager.
Edit the configuration parameters in the soss_params.txt file, which was created with default parameters in the install directory. In most cases, you only have to enter your license key and select the network interface that you want the StateServer service to use when communicating with other hosts.

Note

You can edit these parameters using the management console (soss_console.exe), by using the command-line control program (soss.exe), or (not recommended) by editing the parameters file with a text editor. You should use the management tools whenever possible because this enables changes to global parameters to automatically propagate to all other hosts in the store. If you make changes manually with a text editor, they will not be propagated and could be overwritten by other hosts; you also need to restart the StateServer service for manual changes to take effect.
Run the Management Console, which is automatically started by the install program, to check the configuration of all parameters. The console connects to the local StateServer service, which has already been started by the install program. You should review the local host’s configuration settings and select the correct network interface for the service’s communications with other hosts. (If you have only one network interface, the service automatically selects the first available network interface and sets the net_interface parameter.)

Note

Be sure to configure the server’s firewall to ensure that the configured management and server ports are not blocked.

Note

Be sure to select a network interface to which Windows Network Load Balancing (NLB) is not bound. (See Requirements and Limitations.)
Activate the StateServer service using the management console or from the command line using soss.exe (see Command-line Control Programs). If this is the first server to be activated, a new store will be created. Otherwise, the service will automatically discover the store and join it to take on a portion of the storage workload.
Repeat this installation process on additional servers in the farm. You should install ScaleOut StateServer on all hosts that make access requests to the store, since access requests are always directed to a host’s local service.

Note

Be sure that all hosts use the same multicast IP address (mcast_ip parameter) and port (mgt_port parameter). Otherwise, the hosts will not discover each other.

Session State Provider Installation

Tip

The steps discussed in this section only apply to the original ASP.NET session provider that ships with the ScaleOut Product Suite installer. ScaleOut also offers newer session providers that are available as NuGet packages:

These newer libraries do not require an installation of the ScaleOut Product Suite and are configured through standard .NET config files. See the documentation in the NuGet package links above for details.

The ScaleOut Product Suite Installer installs an ASP.NET session state provider, but your application will not use the provider until your web.config file is configured to use it. If you are running ASP.NET and you want ScaleOut StateServer to transparently save and retrieve ASP.NET session-state objects, please take the following additional steps:

Edit your application’s web.config file to add ScaleOut StateServer’s session state provider, as follows:
```
<sessionState mode="Custom" customProvider="SossStoreProvider" cookieless="UseCookies" >
  <providers>
    <add name="SossStoreProvider"
         type="Soss.Web.SossStoreProvider, soss_storeprovider, Version=5.0.0.0, Culture=neutral, PublicKeyToken=a1ec0b86f746a476" />
  </providers>
</sessionState>
```
Note

Avoid inserting carriage return/line feed characters inside of values assigned to XML attributes (such as the long string assigned to the type attribute in the example above). Otherwise, the attribute may not be correctly parsed, which can lead to .NET Framework errors in locating ScaleOut StateServer’s dll files.

The version of the soss_storeprovider assembly that you specify in the type attribute above will depend on the version of the .NET Framework that your application targets:

Targeted Framework

soss_storeprovider Version

.NET 2.0 - 3.5

2.0.0.0

.NET 4.0 - 4.6.1

5.0.0.0

.NET 4.6.2 - 4.7.1

6.1.0.0

.NET 4.7.2 and higher

6.2.0.0
Edit the .NET Framework’s machine.config file to ensure that the machineKey's settings are identical for all hosts. Note that this requires setting a value for both validationKey and decryptionKey. This ensures that ASP.NET will be able to validate ASP.NET Forms Authentication cookies and View State content across all the web servers in your farm.
Ensure that your application objects to be stored are defined as serializable.
Ensure that the application path in the IIS metabase is the same for every Web server in the farm, as described in Requirements and Limitations.

The ScaleOut installation folder contains a sample ASP.NET Web site in the sub-folder \DOTNET4.0\SessionTest. This application lets you verify that your SOSS installation is working correctly. Please see the file SessionTest_readme.txt in this folder for more information.

Tip

The session provider has several parameters that can be used to configure its behavior. See the ASP.NET Session Provider Configuration Parameters topic for more information.

Encrypted Session State Provider

To encrypt session data at rest in the ScaleOut service, the ScaleOut Product Suite Installer installs an encrypted ASP.NET session state provider. This provider uses AES to encrypt session data in your ASP.NET client application before storing it in the ScaleOut service.

Your application will not use this encrypted provider unless your web.config file is configured to use it. If you are running ASP.NET and you want ScaleOut StateServer to transparently save and retrieve encrypted ASP.NET session-state objects, please take the following additional steps:

Edit your application’s web.config file to add ScaleOut StateServer’s encrypted session state provider, as follows:

<sessionState mode="Custom" customProvider="SossStoreCryptoProvider" cookieless="UseCookies" >
  <providers>
    <add name="SossStoreCryptoProvider"
         type="Soss.Web.SossEncryptedStoreProvider, soss_storeprovider, Version=6.2.0.0, Culture=neutral, PublicKeyToken=a1ec0b86f746a476" />
  </providers>
</sessionState>

Edit your application’s web.config file to add the encrypted session provider’s config section handler:

<configSections>
  <section name="sossEncryptedSessions" type="Soss.Web.SossEncryptedStoreProviderSection, soss_storeprovider, Version=6.2.0.0, Culture=neutral, PublicKeyToken=a1ec0b86f746a476" />
</configSections>

Edit your application’s web.config file to add the password and salt used for encryption:
```
<sossEncryptedSessions password="My secret password"
                           salt="16141146641420173986" />
```
Important

The supplied password and salt must be set to the same values across all the web servers in your farm.

The value of the password attribute is run through PBKDF2 to derive a 256-bit AES encryption key. The salt value is an 8-byte value (expressed as a 64-bit unsigned integer) used to initialize the cryptographic hash algorithm that derives the key from the supplied password.

Note

Any 64-bit integer can be used here as the cryptographic salt. Valid numbers fall in the range of 0 to 18446744073709551615 (inclusive).
Optional, but recommended: Use .NET’s Protected Configuration feature to encrypt the <sossEncryptedSessions/> section. See the Protecting .NET Framework Configuration Sections topic in this User Guide for best practices when using Proctected Configuration in a web farm.
Edit the .NET Framework’s machine.config file to ensure that the machineKey's settings are identical for all hosts. Note that this requires setting a value for both validationKey and decryptionKey. This ensures that ASP.NET will be able to validate ASP.NET Forms Authentication cookies and View State content across all the web servers in your farm.
Ensure that your application objects to be stored are defined as serializable.
Ensure that the application path in the IIS metabase is the same for every Web server in the farm, as described in Requirements and Limitations.

Output Cache Provider Installation

ScaleOut’s ASP.NET Output Cache Provider is installed by default with the product’s .NET API libraries, but your application will not use the provider until your web.config file is configured to use it. If you are running ASP.NET 4.0 (or higher) and you want ScaleOut StateServer to store output cache data, modify your application’s web.config file to add ScaleOut StateServer’s output cache provider. For example:

<caching>
  <outputCache defaultProvider="SossOutputCacheProvider">
    <providers>
      <add name="SossOutputCacheProvider"
           type="Soss.Web.SossOutputCacheProvider, soss_storeprovider, Version=5.0.0.0, Culture=neutral, PublicKeyToken=a1ec0b86f746a476"
           throwOnError="false"
           sossAccessTimeoutMilliseconds="250" />
    </providers>
  </outputCache>
</caching>

The output cache provider has a number of configuration parameters that can be used to adjust its behavior. See the ASP.NET Output Cache Provider Configuration Parameters topic for more information.

Unattended Installation

You optionally can install ScaleOut StateServer from the command line “quiet mode” with no user interaction by running the Windows utility program msiexec.exe from the command line with the /quiet switch. To install the 32-bit version of ScaleOut StateServer, run the following command:

msiexec.exe /i soss_setup32.msi /quiet

To install the x64 version of ScaleOut StateServer, run the following command:

msiexec.exe /i soss_setup64.msi /quiet

Note

When running an unattended installation on Windows Server 2008 or Windows Vista with UAC enabled, you must run the setup using the Administrator account. (It is not sufficient for your user to be part of the Administrators group if UAC is enabled.)

After installation, a pre-configured soss_params.txt file should be copied over the unconfigured one in the StateServer installation directory on each host. Restart the ScaleOut StateServer service (“soss.exe restart”) for the new host configuration settings to take effect.

There are two approaches to specifying which product features are installed. You can either use the standard INSTALLLEVEL property to select an installation type, or you can specify the individual features that you’d like installed using the ADDLOCAL property. If you do not specify an INSTALLLEVEL or an ADDLOCAL property (see below) then a full server installation will be performed. Note that the INSTALLTYPE property that was used in earlier versions of the installer (prior to version 5.0) is no longer available.

Specifying an INSTALLLEVEL from the command line is equivalent to clicking one of the setup type buttons in the installer’s wizard UI (i.e., the “SOSS Full Install” and “Remote Client” buttons). For example, to install the remote client components you would run the following command:

msiexec.exe /i soss_setup64.msi /quiet INSTALLLEVEL=500

The INSTALLLEVEL values supported by the setup are defined as follows:

500	Remote client installation.
1000	Full server installation, including all features. (Default)

Individual features can be selected for installation from the command line using the ADDLOCAL property, where each feature is separated by a comma (and no spaces). This is equivalent to going into the installer’s wizard UI and clicking the Custom setup type button to select the desired features from a list. For example, to install just the management tools and the Java libraries, you would run the following command:

msiexec.exe /i soss_setup64.msi /quiet ADDLOCAL=ManagementTools,JavaLibs

The following feature identifiers are supported for the ADDLOCAL property:

Feature ID	Description
Server	The ScaleOut StateServer service. Do not include this feature if you want a remote client installation.
Samples	Samples for .NET, Java, and C development.
ManagementTools	(Recommended.) Graphical and command line tools for managing the ScaleOut server and remote client configuration.
DotNet20Libs	Libraries to support .NET 2.0 client applications.
DotNet35Libs	Libraries to support .NET 3.5 client applications.
DotNet40Libs	Libraries to support .NET 4.0 client applications.
JavaLibs	Libraries to support Java client applications.
NativeLibs	Headers and libs for building native C/C++ client applications.
SossSvcRest	HTTP REST API service and documentation for building HTTP-enabled client applications.

To set the directory that the product will be installed in, use the APPLICATIONFOLDER property. So, for example, to perform a 32-bit remote client installation to the non-default “e:\SOSS” directory, you would run:

msiexec.exe /i soss_setup32.msi /quiet INSTALLLEVEL=500 APPLICATIONFOLDER="e:\SOSS"

Many additional properties are defined by Windows Installer. Consult the Microsoft Developer Network for a full list at http://msdn.microsoft.com/en-us/library/aa370905%28VS.85%29.aspx.

ASP.NET Core Distributed Cache Library

ScaleOut provides an implementation of the ASP.NET Core IDistributedCache interface for caching and session state management in ASP.NET Core web applications. Unlike ScaleOut’s provider for traditional ASP.NET applications, this ASP.NET Core provider does not require an installation of the ScaleOut Product Suite and is configured through standard .NET config files. See the provider’s documentation site for details.

Targeted Framework	soss_storeprovider Version
.NET 2.0 - 3.5	2.0.0.0
.NET 4.0 - 4.6.1	5.0.0.0
.NET 4.6.2 - 4.7.1	6.1.0.0
.NET 4.7.2 and higher	6.2.0.0