SAS Federation Server Configuration Reference

Locale Support

At this time, SAS Federation Server supports the English, United States of America (en_US) locale. The following table outlines the character representations for output (display) format. There are no deviations from these formats:
Character Type
Format
Number
ddddd.fffffffff
Date
yyyy-mm-dd
Time
hh:mm:ss
Timestamp
yyyy-mm-dd hh:mm:ss[.ffffffff]
Note: Configure database drivers and clients to match this behavior to ensure that conversions are handled correctly.

Key Configuration Files

The following table lists the key configuration files for SAS Federation Server:
File or Script Name
Description
dfs_serv.xml,
dfs_serv_common.xml
These are the core configuration files for SAS Federation Server. They specify the system users, the location of the internal database, and other key configuration settings necessary for proper functionality of SAS Federation Server. These configuration files are located in the /etc directory of the Federation Server installation path. Detailed configuration information is presented in the Configuration Options.
dfs_entities.dtd
The dfs_entities.dtd file contains the values that were supplied during the install process. These values are referenced by other configuration files such as dfs_serv.xml and dfs_serv_common.xml files.
dfs_log.xml
This is the logging facility configuration file for SAS Federation Server. It specifies logging options for SAS Federation Server from information-only to debug and trace. This file is installed in the /etc directory of the installation path. For more information, see Server Logging Configuration..
dfs_log_SQL_Logging.xml 
This is the configuration file that is used to facilitate SQL Logging. This file is located in the /etc directory of the installation path. For additional information, seeSQL Logging.
dfs_pwencode.xml
This is the logging file used when running the tool to encrypt a password. The logs are located in the /var directory of the Federation Server installation path. See Utilities for SAS Federation Server for additional information about password encryption.

About the Server Configuration Files

SAS Federation Server uses the dfs_entities.dtd file to store values that are supplied during installation. These values are used by the other configuration files, dfs_serv_common.xml, dfs_serv.xml, dfs_log4sas.xml, and dfs_log_sql_logging.xml. For example, a port number supplied during installation is recorded in dfs_entities.dtd and the port number option in dfs_serv.xml points to the definition in the .dtd file:
dfs_serv.xml 
<Option name="Port">&cfg.port;</Option>
dfs_entities.dtd 
<!ENTITY cfg.Port "2171">

About Option Names and Option Sets

Overview

The dfs_serv_common.xml and dfs_serv.xml configuration files consist of a combination of option names and option sets that are explained below.

Option Names

Option names specify a name=value pair as configuration file options. They can stand alone in the configuration file or are contained within an option set. Here are the different types of option name configurations that appear in dfs_serv.xml:
This specifies a simple name=value pair as a configuration option: 
<Option name=”XXX”>yyy</Option>
Example:  <Option name="Port">21030</Option>
This represents a name=value pair where the value is a space-delimited string of values: 
<Option name=”XXX”>yyy zzz aaa</Option>
Example:  <Option name="AdminLoginManagementPolicy">ADD
REMOVE UPDATE</Option>

Option Sets

An option set consists of various options (option names). Option names that belong in an OptionSet will not be assessed correctly if they are placed outside of the OptionSet. For example, the SystemUsers option set requires at least one option name, Account, be defined in order to function properly: 
<SystemUsers>
    <Option name="Account">domain\uid1</Option>
    <Option name="Account">domain\uid2</Option>
</SystemUsers>

Child Option Sets

Here is an example of an option set within an option set which is called a child option set. The License option set shown in the following example contains two options to define: Provider and Location (where the license provider and the location of the license file is specified): 
<OptionSet name="License">
   <OptionSet
name="Primary">
      <Option name="Provider">SAS</Option>
      <Option name="Location">path_to_license_file</Option>
   </OptionSet>
</OptionSet>
For a complete list of configuration options for SAS Federation Server, refer to Configuration Options.

Required Configuration Options

Overview

The following configurations are required for SAS Federation Server operations.

Security Provider

The SecurityProvider option set provides information about the Federation Server security provider, including the threaded kernel extension name and other information specific to the security provider. Configuration of the extension and database options are required. 
<OptionSet name="SecurityProvider">
   <Option name="extension">extension_name</Option>
   <Option name="Database">database name</Option>
</OptionSet>

Authentication Server

The AuthenticationServer option set defines the location of the Authentication Server that serves as the back end for SAS Federation Server. The Authentication Server is required to authenticate SAS Federation Server users and store user information such as logins and group memberships.
The option, IOM_URI contains connection information for the Authentication Server and uses the following format: 
iom://<machine>:<port>;Bridge;CLSID=2D1BCDBF-F900-4CA9-85F6-95ECDBAF2122
<OptionSet name="AuthenticationServer">
   <OptionSet name="PrimaryServer">
       <Option name="URI">IOM-URI</Option>
   <OptionSet>
<OptionSet>

License

The License Option Set provides information about the type of licensing issued for SAS Federation Server. Within the Primary option set, specify the license provider and the path to the license file. 
OptionSet name="License">
   <OptionSet name="Primary">
      <Option name="Provider">SAS</Option>
      <Option name="Location">C:\Federation Server\server1\etc\license</Option>
   </OptionSet
The Primary option set is a required configuration for operation of SAS Federation Server. You cannot start the server without a valid license.

Configuration Options

Overview

The following sections reflect the options that are available in the system configuration files, dfs_serv.xml and dfs_serv_common.xml. A dfs_entities.dtd can exist in specific configurations. The dfs_entities.dtd file contains the values supplied during installation of SAS Federation Server. These values are referenced by the system configuration files.

AppendEnv OptionSet

Syntax
<OptionSet name="AppendEnv">
   <Option name="FIREBIRD">drive:\install_loc\firebird</Option>
</OptionSet>
Description
The AppendEnv option set locates the specified OS environment variable and appends the specified option to the environment variable’s current value. If the environment variable does not exist, it is created and set to the specified value. The AppendEnv option does not add a delimiter between the existing and appended environment variable values. Therefore, if a delimiter is needed, it should be included at the beginning of the specified value.
Tip
Each AppendEnv, PrependEnv and SetEnv option is processed entirely in the order in which they appear in the configuration file.

SetEnv OptionSet

Syntax
<OptionSet name="SetEnv">
   <Option name="FIREBIRD">[drive]:\install_dir\lib\fbembed</Option>
   <Option name="FIREBIRD_LOG">[drive]:\install_dir\var\log</Option>
   <Option name="FIREBIRD_TMP">[drive]:\FDS_Tmp</Option>
</OptionSet>
Description
This option set appears in dfs_serv_common.xml. The SetEnv option sets the OS environment variables to specific values. If the environment variable does not exist, it will be created and set to the option value. If the environment variable does exist, the value will be updated to the option value.
Set FIREBIRD_TMP as an environment option should the default database directory run out of space. Once the default directory has no available space, the engine switches to the directory specified in FIREBIRD_TMP.
Tip
Each AppendEnv, PrependEnv and SetEnv option is processed entirely in the order in which they appear in the configuration file.

Memory Size Option

Syntax
<Option name="MemSize">nnnnn [(K|k|M|m|T|t)[(B|b)]]</Option>,
Example
<Option name="MemSize">1G</Option>
Description
The MemSize system option specifies the total amount of memory available for each SAS Federation Server session. If a setting is not specified, all system memory is available for use by SAS Federation Server. However, SAS Federation Server will use only as much memory as it needs to complete a process. Setting a value that is too low will result in out-of-memory conditions.

Transactional Data Store Options

Syntax
<Option name="FIREBIRD">drive:\install_dir\lib\fbembed</Option>
<Option name="FIREBIRD_LOG">drive:\install_dir\var\log</Option>
Description
The FIREBIRD environment variable specifies the location of the Transactional Data Store installation files.
The FIREBIRD_LOG environment variable specifies the location of the log files for Transactional Data Store. The configuration file generated during installation sets the FIREBIRD_LOG option to the var\log directory of the installation path. If FIREBIRD_LOG is not set, the federation server will default to one of two locations:
  • TranPath: If the TranPath environment variable is set, FIREBIRD_LOG is set to the TranPath value.
  • ContentRoot: If TranPath is not set, FIREBIRD_LOG is set to the ContentRoot value as defined in the configuration file.

TranPath Option

Syntax
<Option name="TranPath">directory</Option>
Description
The TranPath option identifies the location in which to store the Federation Server Database files.
By default, the Federation Server Database files are stored in ContentRoot as defined in the configuration file. Federation Server Database system files cannot be stored on remote file systems. If ContentRoot is a network file system or share, use the TranPath option to redirect the Federation Server Database files to a local directory on the machine where SAS Federation Server is installed.
Rules and Dependencies
Here are the rules and dependencies for the TranPath option:
  • A relative directory specified in the ContentRoot tag is resolved against the server's working directory.
  • A relative directory specified in the TranPath tag is resolved against the directory specified in the ContentRoot tag, or the working directory of the server if none is specified.
  • If the TranPath option is omitted, it defaults to the directory specified in the ContentRoot tag, or the working directory of the server if none is specified.
  • The TranPath directory is used to resolve the server's system catalog database name specified in the provider-specific SecurityProvider or Database tag for the Transactional Data Store security provider (tkescfb) provider.

PrependEnv OptionSet

Syntax
<OptionSet name="PrependEnv">
   <Option name="FIREBIRD">drive:\install_loc\firebird</Option>
</OptionSet>
Description
This option appears in dfs_serv_common.xml. The PrependEnv option will find the indicated OS environment variable and prepend the option value to the OS environment variable value. If the environment variable does not exist, it will be created and set to the option value. The PrependEnv option will not add a delimiter of any sort between the existing and new environment variable value. If a semicolon (;) is needed, then the option value should include it at the end.
Tip
Each AppendEnv, PrependEnv and SetEnv option is processed entirely in the order in which they appear in the configuration file.

SystemUsers OptionSet

Syntax
<SystemUsers>
   <Option name="Account">domain\uid1</Option>
   <Option name="Account">domain\uid2</Option>
</SystemUsers>
Description
This option appears in dfs_serv_common.xml and defines the system user account(s) that are given all privileges to SAS Federation Server including all user and data objects. This privilege cannot be revoked or denied. When system users grant or deny privileges to others, the grantor is reflected in the system tables as the SYSTEM user ID. Each system user should be a domain-qualified user name.

SecurityProvider OptionSet

Syntax
<OptionSet name="SecurityProvider">
   <Option name="extension">extension_name</Option>
   <Option name="Database">database path</Option>
</OptionSet>
Description
This is a required configuration for SAS Federation Server. The security provider option set provides information about the server's security provider, including the threaded kernel extension name and other information specific to the security provider.

FunctionDispatchManager Option

Syntax
<Option name="FunctionDispatchManager">tktsfd</Option>
Description
This option appears in dfs_serv_common.xml. The Function Dispatch Manager tells FedSQL to load an extension that implements SQL functions, including row-level security. This option should always be set to tktsfd.

Database Option

Syntax
<Option name="Database">syscat.tdb</Option>
Description
Identifies the name of the database (syscat.tdb) to be used for the Transactional Data Store security provider (tkescfb).
The database name is appended to the TranPath value as defined elsewhere in the configuration file. The default TranPath value for Windows is Drive:\Program Files\SASHome\SasFederationServer\version\var, so by default, syscat.tdb will reside in that location. The default TranPath value for UNIX is <install_dir>/SASHome/SASFederationServer/version/var, so by default, syscat.tdb will reside in that location.
CAUTION:
The syscat database must reside on a local file system as indicated by the default installation paths above.
If the var directory is pointed to a remote file system such as a network file share or storage area network (SAN), the syscat database cannot be created, resulting in multiple application errors.

ContentRoot Option

Syntax
<Option name="ContentRoot">content_root_path</Option>
Description
This option, configured in dfs_serv_common.xml, defines the content root for SAS Federation Server. The content root is used to resolve all relative pathnames specified in SAS Federation Server configuration, such as a schema path. It is recommended that the value for ContentRoot be set to an absolute, fully qualified path.
Rules
If the ContentRoot option is not set, files will be written to the install directory.
  • Content root is absolute or relative to the install directory. 
  • TRACEFILEPATH is absolute or relative to content root.
  • TRACEFILE names are resolved against the TRACEFILEPATH path. Paths that do not match are rejected.
  • PRIMARYPATH paths in schema configuration options are absolute or relative to content root.
  • SCHEMA=(PRIMARYPATH) connection string options are resolved against PRIMARYPATH schema configuration path.

Port Option

Syntax
<Option name="Port">port_number</Option>
Description
Indicates the port on which SAS® Federation Server will start.

Authentication Server OptionSet

Syntax
<OptionSet name="AuthenticationServer">
   <OptionSet name="PrimaryServer">
       <Option name="URI">IOM-URI</Option>
   <OptionSet>
<OptionSet>
Description
A required configuration for SAS® Federation Server, this option defines the location of the Authentication Server that serves as the back end for the .
IOM_URI contains connection information for the Authentication Server and uses the following format:
iom://<machine>:<port>;Bridge;CLSID=2D1BCDBF-F900-4CA9-85F6-95ECDBAF2122
For example, IOM_URI can be used to connect to an Authentication Server that is running on port number 24140 and machine name myhost. The CLSID for an Authentication Server should always be 2D1BCDBF-F900-4CA9-85F6-95ECDBAF2122:
iom://yourserver.yourdomain.com:21030;Bridge;CLSID=2D1BCDBF-F900-4CA9-85F6-
95ECDBAF2122

License OptionSet

Syntax
<OptionSet name="License">
   <OptionSet name="Primary">
      <Option name="Provider">SAS</Option>
      <Option name="Location">path_to_license_file</Option>
   </OptionSet>
Description
This option set, configured in dfs_serv_common.xml, provides information about the type of licensing issued for the . The Primary option set is a required configuration. Within the Primary option set, specify the license provider and the path to the license file. The location option points to a setinit file.

ObjectServerParms Option

Syntax
<Option name="ObjectServerParms">object_server_parameters</Option>
Description
Identifies IOM object server parameters. Values for object_server_parameters include:
  • Clientencryptionlevel = (EVERYTHING | CREDENTIALS | NONE)—Specifies the client encryption level to use. Valid values include:
    • NONE—Nothing is encrypted.
    • CREDENTIALS— Login credentials are encrypted. Note: these are the login credentials used to authenticate to the SAS® Federation Server, and NOT logins used as outbound credentials to connect to third-party databases. It also does NOT include credentials passed in administration DDL, such as CREATE ACCOUNT REGISTRATION or CREATE USER.
    • EVERYTHING— All client/server communications are encrypted. Setting a value of EVERYTHING can affect server performance.

NetworkEncryptAlgorithm Option

Syntax
<Option name="NetworkEncryptAlgorithm">algorithm | 
("algorithm1", "algorithm2", ...)</Option>
Description
algorithm | ("algorithm1", "algorithm2", ... ) — Specifies the algorithm or algorithms that can be used for encrypting data that is transferred between a client and a server across a network. When you specify two or more encryption algorithms, use a space or a comma to separate them, and enclose the algorithms in parentheses. If more than one algorithm is specified, the client session negotiates the first specified algorithm with the server session. If the client session does not support that algorithm, the second algorithm is negotiated, and so on.
This is set with the CLIENTENCRYPTIONLEVEL OBJECTSERVERPARMS option. Possible values include: SASProprietary which is the default, and AES if implementing DFSecure.
For more information about Advanced Encryption Standard (AES), see the Authentication Server Administrator's Guide.

SelectStarExpansion Option

Syntax
<Option name="SelectStarExpansion">ALL</Option>
Description
This option modifies the behavior of the SELECT * expansion for table columns. The configuration options are ALL or VISIBLE. If set to ALL, the SAS® Federation Server attempts to expand SELECT * to all of the physical columns in the table and fails if the user does not have the SELECT privilege to one or more columns. If set at VISIBLE, which is the default value, SAS® Federation Server traverses the visible path, expanding the SELECT * privilege to those columns for which the user has the SELECT privilege.

Deadlock Protection Option

Syntax
<Option name="SystemDBCTimeOut">milliseconds</Option>
Description
A deadlock is sometimes caused by competing resources on the server resulting in perpetual wait time for the tasks to complete. This option controls the wait time in milliseconds before timing out a lock attempt that is causing the deadlock. If a connection cannot be acquired within the specified time limit, the request fails and the deadlock connection is aborted, allowing the remaining connection to run to completion. The default is <=0 which waits ‘forever’. This option is configured in dfs_serv_common.xml.
Copyright © SAS Institute Inc. All rights reserved.