Appendices. SAS 9.4 Middle-Tier Administration Guide
Annonce
Annonce
Part 6
Appendices
Appendix 1
Configuring the SAS Environment File
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appendix 2
Administering Multicast Options
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
311
312
313
Appendix 1
Configuring the SAS Environment
File
About the SAS Environment File
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the SAS Environment File
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customizing the SAS Environment File
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the SAS Environment File
A SAS environment file defines the available set of SAS environments for SAS client applications, and is generated during the configuration of the SAS Web
Infrastructure Platform. The SAS Logon Manager includes a servlet that provides default information for the initial deployment. The sas-environment.xml file is automatically deployed on SAS Web Server at http:// hostname.example.com/sas/sas-environment.xml.
Your site might have requirements that application clients interact with separate development, test, and production environments. Or, you might choose to have separate SAS deployments to support distinct business units. In either scenario, when multiple environments are required, you can customize and deploy the
sas-environment.xml
file as needed.
Make sure that the file is available to SAS desktop clients. In environments that protect URLs with third-party products like IBM Tivoli Access Manager
WebSEAL or CA SiteMinder, do not protect the URL to the file. The SAS desktop clients that use the file are unable to respond to a prompt for credentials. In these environments, you can deploy the file from a different HTTP server. Update the SAS desktop clients with the new location if you change it.
Configuring the SAS Environment File
Customizing the SAS Environment File
The sas-environment.xml is located in the
SAS-configuration-directory
\Lev1\Web\WebServer\htdocs\sas
directory.
314
Appendix 1 / Configuring the SAS Environment File
Here is a sample sas-environment.xml file that is configured for two environments:
<?xml version="1.0" encoding="UTF-8">
<environments xmlns="http://www.sas.com/xml/schema/sas-environments-9.4"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.sas.com/xml/schema/sas-environments-9.4
http://www.sas.com/xml/schema/sas-environments-9.4/sas-environments-9.4.xsd"
version="2.0">
<environment name="Red" default="false">
<desc>test server Red for SAS Financial Management Studio</desc>
<service-registry>http://red.example.com:80/SASWIPClientAccess/ remote/ServiceRegistry</service-registry>
<service-registry interface-type="soap">http://red.example.com:
80/SASWIPSoapServices/services/ServiceRegistry</service-registry>
<service-registry interface-type="rest">http://red.example.com:
80/SASWIPClientAccess/rest</service-registry>
</environment>
<environment name="Blue" default="true">
<desc>test server Blue for SAS Financial Management Studio</desc>
<service-registry>http://blue.example.com:80/SASWIPClientAccess/ remote/ServiceRegistry</service-registry>
<service-registry interface-type="soap">http://blue.example.com:
80/SASWIPSoapServices/services/ServiceRegistry</service-registry>
<service-registry interface-type="rest">http://blue.example.com:
80/SASWIPClientAccess/rest</service-registry>
</environment>
</environment>
The service registry that is specified in the file enables desktop client applications to determine the location of required services on the middle tier. It also enables the applications to obtain a list of services available in the environment. Note that this sas-environment.xml file is used by SAS Web
Server, and the configuration in the file refers to the host name and port number of SAS Web Server.
If Transport Layer Security (TLS) is configured at your site, specify the https protocol and the TLS port number for the service registry.
If your site has multilingual users, you can configure the sas-environment.xml file to include localized descriptions. In the next example, the Blue environment is specified in German:
<environment name="Blue">
<desc>test2 Blue</desc>
<desc xml:lang="de">Blau</desc>
<service-registry>http://blue.example.com:80/SASWIPClientAccess
/remote/ServiceRegistry</service-registry>
<service-registry interface-type="soap">http://blue.example.com:
80/SASWIPSoapServices/services/ServiceRegistry</service-registry>
<service-registry interface-type="rest">http://blue.example.com:
80/SASWIPClientAccess/rest</service-registry>
</environment>
When the customized sas-environment.xml file is available for multiple environments, see to the documentation for your SAS application or solution for instructions about how to enable the availability of these environments for the users. If you change the location of the sas-environment.xml file, be aware that
SAS desktop applications such as SAS Enterprise Miner need to be updated
Configuring the SAS Environment File
315 with the new location. The SAS desktop applications that integrate with the middle tier use the
-Denv.definition.location
JVM option in INI files to identify the location of the sas-environment.xml file. Refer the documentation for the SAS desktop applications that you use. The
SASHome/sassw.config
file is also used to identify the location of the sas-environments.xml file. Update the
SASENVIRONMENTSURL=
value in the sassw.config file.
Element Description
The following list identifies and describes the elements that can be used in the sas-environment.xml file: environment has a name attribute that cannot contain space characters. This attribute is used internally by SAS software to identify each of the environments that are available in the deployment. This element has an attribute that is named default. This attribute is used to identify a default environment for client applications. If this attribute is set to true for more than one environment element, then the last environment in the file with the attribute set to true is set as the default environment. It is not necessary to set the attribute to false for all other environments.
desc used in the client applications to provide a menu of environment choices. As shown in the previous example, this field can provide a localized message when the xml:lang attribute is set.
service-registry contains the URL to the service registry for the environment. Use the protocol, host name, and port number of SAS Web Server. By default, SAS
Web Server is configured to provide access to SAS Web Infrastructure
Platform.
316
Appendix 1 / Configuring the SAS Environment File
317
Appendix 2
Administering Multicast Options
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How Much Multicast Network Traffic is Generated?
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applications That Use Multicast Communication
. . . . . . . . . . . . . . . . . . . . . . . . . . .
Multicast Options Configuration Files for SAS Remote Services
. . . . . . . . . . . .
Multicast Options Configuration Files for SAS Web Application Server
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring a Multicast Authentication Token
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding the Multicast Authentication Token
. . . . . . . . . . . . . . . . . . . . . . . . .
Reconfiguring to Use a Multicast Authentication Token
. . . . . . . . . . . . . . . . . . . . .
Configuring the JGroups Bind Address
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding the JGroups Bind Address
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting the Bind Address for SAS Remote Services
. . . . . . . . . . . . . . . . . . . . . . . .
Setting the Bind Address for SAS Web Application Server
. . . . . . . . . . . . . . . . . .
Overview of Multicasting
Note:
By default, multicasting is not used in the typical SAS deployment, and
SAS Remote Services is turned off. If you created a custom application that uses SAS Remote Services, you can use multicasting and enable SAS Remote
Services.
Multicast communication is no longer used to communicate among SAS 9.4 middle-tier applications in a single SAS deployment (the set of applications connected to the same SAS Metadata Server). However, you can still take advantage of this communication if you have developed custom applications by starting Remote Services. When installation is performed with the SAS
Deployment Wizard, the wizard generates a default multicast address that is based on IP address of the SAS Metadata Server. The combination of multicast address and multicast UDP port number must be different for each SAS deployment and also different from any other multicast applications at your site.
The multicast communication includes all the information that is needed to bootstrap a custom middle-tier application. Because this information includes the
SAS environment credentials (such as the sasadm account name and its password), time to live (TTL) and encryption options are provided to secure the multicast communication.
318
Appendix 2 / Administering Multicast Options
Multicast options are specified as JVM options. Multicast options provide the ability to tune and change the behavior of the multicast communication that occurs within the SAS deployment. The multicast address and UDP port number must match the values in the start-up script for SAS Web Application Server and the environment.properties file located in the
SAS-configuration-directory
\Lev1\Web\Applications\RemoteServices
directory.
Administering multicast options typically involves the following: n setting options such as the multicast address n n configuring security with a multicast authentication token configuring the bind address that is used for multicast communication
How Much Multicast Network Traffic is
Generated?
The amount of multicast network traffic that is generated by SAS applications is fairly small. The greatest amount of traffic is generated during application startup. When SAS Remote Services starts, the largest packet that it generates is
124 bytes. Once start-up is complete, the typical rate is less than 64 Kb per hour.
When the web application server starts, the largest packet is 256 bytes. Once start-up is complete, the typical rate for an entire SAS Enterprise Business
Intelligence Server deployment (including SAS Remote Services) is less than
128 Kb per hour.
Once the applications are generating multicast traffic, the amount of traffic is steady regardless of the load on the SAS Web applications.
Multicast Security
A multicast group communications protocol is used to communicate among middle-tier SAS applications in a single SAS deployment (the set of applications connected to the same SAS Metadata Server). During installation, the SAS
Deployment Wizard supplies you with a default multicast address and port number that it generates based on the machine's (metadata server) IP address.
The combination of multicast IP address and multicast UDP port should be different for each SAS deployment and also different from those used by other multicast applications at your site.
The IP address and multicast UDP port number for the multicast host must match the values in the start-up script for SAS Web Application Server and the environment.properties file.
The multicast group communication includes all information needed to bootstrap
SAS middle-tier applications. Because this includes sending the SAS environment credentials (such as the sasadm account name and its password), scoping and encryption options are provided in the SAS Deployment Wizard.
The defaults are most appropriate for deployments in the firewall, isolated data center environment. After installation, if you choose to modify the scoping or
Configuring Multicast Options
319 encryption options, you can do so by specifying the options for the
-
Dmulticast.security
parameter for the web application server.
For more information, see Appendix 2, “Administering Multicast Options,” on page 317
.
Configuring Multicast Options
Applications That Use Multicast Communication
Multicast options should be changed in a synchronous manner among the following applications: n n
SAS Remote Services
SAS Web Application Server
Multicast Options Configuration Files for SAS
Remote Services
You can make changes to the multicast options for the JVM that is used by SAS
Remote Services. Edit the appropriate files as needed.
On Windows, in directory
SAS-configuration-directory\Lev1\Web
\Applications\RemoteServices
, change the following files: n n
RemoteServices.bat
wrapper.conf
n environment.properties
On UNIX, edit the RemoteServices.sh and environment.properties files.
Multicast Options Configuration Files for SAS Web
Application Server
You can make changes to multicast options for SAS Web Application Server.
The options are specified as JVM options. For more information, see “Specifying
Key Multicast Properties
The following table shows some key multicast properties.
320
Appendix 2 / Administering Multicast Options
Table A2.1 Multicast Properties
Property
multicast.address
multicast.port
multicast_udp_ip_ttl multicast.security
multicast.config.file
Default Value
239.X.Y.Z
8561
1
Not applicable
Not applicable
Unit
Not applicable
Not applicable
Description
This value is provided by the SAS
Deployment Wizard prompting mechanism and defaults to 239.X.Y.Z.
Values for X, Y, and Z are the last three octets of the metadata server's IP address.
In an IPv6 environment, the value defaults to ff14::/16.
This value is provided by the SAS
Deployment Wizard prompting mechanism and represents the port on which UDP communication occurs.
Decimal. Specifies how far a multicast packet should be forwarded from a sending host.
0 is restricted to the same host.
1 is restricted to the same subnet.
32 is restricted to the same site.
64 is restricted to the same region.
128 is restricted to the same continent.
255 is unrestricted.
The IP multicast routing protocol uses the Time to Live (TTL) field of IP datagrams to decide how far a multicast packet should be forwarded from a sending host. The default TTL for multicast datagrams is 1, which results in multicast packets going only to other hosts in the local network.
If all SAS applications participating in the multicast (this includes Remote
Services, any Java applications in the middle tier, and BI Report Services) are on the same machine, the value should be 0.
If your site has a SAS middle-tier application that resides on a different subnet but uses the same metadata server within the same SAS deployment, increase the value for this property.
Not applicable By default (with no value), both encryption and authentication are enabled. Valid values are: n n
ENCRYPT: encrypt but do not require authentication
NONE: do not encrypt and do not require authentication
URL string (file://, http://, and so on)
By default, a JGroups configuration is provided. However, you can provide your own configuration by specifying the URL path to that configuration. This option enables you to specify a port range or change from IP multicast to the gossip router capabilities of
JGroups.
Configuring a Multicast Authentication Token
321
Configuring a Multicast Authentication
Token
Understanding the Multicast Authentication
Token
By default, the multicast communication is protected with encryption because it conveys credentials. This default setting for encryption uses a fixed encryption key that is built into the software and is common to all SAS middle-tier software.
This strategy prevents access to the multicast communication from unauthorized listeners. This setting might be sufficient for deployments where multicast communication is isolated from the user community with a firewall, a TTL option, or the deployment is in an isolated data center.
If your middle tier meets any of the following criteria, then you might want to set a multicast authentication token value: n n n n you have custom applications the middle-tier environment is not well isolated from end-user access the security procedures at your site require protection among administrative and operational staff in various roles you want more protection against eavesdroppers and unauthorized participants
For these deployments, set a multicast authentication token value that is known only to the appropriate personnel. A multicast authentication token is a password-like string that is needed to connect to the multicast group and create a site-specific encryption key. In a multi-tier configuration, the SAS Deployment
Wizard displays a prompt for a multicast authentication token on each tier that has an application participating in multicast communication. The same authentication token value must be specified for each tier in the same SAS deployment (each tier associated with the same metadata server).
The multicast authentication token has an interaction with the multicast.security property. By default, clients that want to join a multicast group to receive messages are required to provide an authentication token for the join request.
(This is true whether a custom token value is used or if the default token value that is built into the software is used.) If you determine this process is causing an impact on performance, or that it is unnecessary, you can disable the use of authentication tokens. If you set the multicast.security property to NONE, encryption and authentication are disabled. If you set the property to ENCRYPT, then encryption is enabled with no authentication of the join request.
322
Appendix 2 / Administering Multicast Options
Reconfiguring to Use a Multicast Authentication
Token
Generate a Token and Set the Token for SAS Remote
Services
1
Use SAS and the PWENCODE procedure to generate an encoded password to use as the multicast authentication token. Here is an example:
{SAS002}DA9A0A5C20629B7F34D2C88A165E5530.
2
Edit the
SAS-configuration-directory\Lev1\Web\Applications
\RemoteServices\RemoteServices.bat
file to add a -
DMULTICAST_AUTHENTICATION_TOKEN JVM option.
For Windows, add the option in the runasScripts section:
:runasScripts set MULTICAST_AUTHENTICATION_TOKEN=token
For UNIX, add the option to the
RemoteServices.sh
file after the
SERVERUSER variable:
SERVERUSER=sas
MULTICAST_AUTHENTICATION_TOKEN="token" export MULTICAST_AUTHENTICATION_TOKEN
3
For Windows, also add the JVM option to the
wrapper.conf
file. Add it to the end of the wrapper.java.additional.11 entry: wrapper.java.additional.11=-XX:+UseTLAB -XX:+UseConcMarkSweepGC
-XX:+DisableExplicitGC -Dsun.rmi.dgc.client.gcInterval=3600000
-Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.awt.headless=true -Xss256k
-XX:NewSize=16m -XX:MaxNewSize=16m -XX:PermSize=64m -XX:MaxPermSize=64m
-DMULTICAST_AUTHENTICATION_TOKEN=token
Note:
Do not use carriage returns or line feed characters when editing long lines.
4
Restart SAS Remote Services.
Setting the Token for the Report Output Generation Tool
1
Edit the
SAS-installation-directory\SASBIReportServices
\4.4\outputgen.ini
file.
2
Add a JavaArgs_nn entry that is similar to the following:
JavaArgs_13=-Dsas.app.launch.picklist=picklist;"help\primary.picklist"
JavaArgs_14=-DMULTICAST_AUTHENTICATION_TOKEN=token
Classpath=-cp "<VJRHOME>/eclipse/plugins/sas.launcher.jar"
Configuring the JGroups Bind Address
323
Configuring the JGroups Bind Address
Understanding the JGroups Bind Address
Some SAS middle-tier applications use JGroups to perform multicast communication between applications and to perform caching of application properties. The JGroups software binds to the IP address of first non-loopback network interface that it can detect on the machine. Many machines have multiple network interfaces (multihomed), and each network interface has its own IP address. In some cases, the web application server selects the value of
InetAddress.getLocalHost().getHostName()
as the bind address to use for multicast communication and SAS Remote Services selects a different IP address to bind to.
Multicast communication does not function correctly if the IP address selected by JGroups for SAS Remote Services does not match the IP address selected by the web application server. One indication of a mismatch is an error message that appears in the web application server log file. See the following example:
13:39:35,602 ERROR [ContextLoader] Context initialization failed org.springframework.beans.factory.BeanDefinitionStoreException: Invalid bean definition with name 'dashboardServices' defined in ServletContext resource
[/WEB-INF/spring-config/services-config.xml]: Could not resolve placeholder
'metadata.user'
ERROR [main] – ****************************************************************
ERROR [main] – Required entry, '/sas/properties/environment', not found in the cache.
ERROR [main] – Possible causes include: the RemoteServices VM is not started or
ERROR [main] – there is a multicast address/port mismatch; using
ERROR [main] – address=239.168.68.1 and port=8561.
ERROR [main] – ****************************************************************
Set the bind address for SAS Remote Services, the web application server, and the SAS BI Report Services Report Generation tool if the previous error message is seen.
Setting the Bind Address for SAS Remote
Services
1 For deployments on Windows, edit the
SAS-configuration-directory
\Lev1\Web\Applications\RemoteServices\wrapper.conf
file. Add a wrapper.java.additional.nn entry that is similar to the following: wrapper.java.additional.12=-Dlog4j.configuration="..." wrapper.java.additional.13=-Djgroups.bind_addr=ip-address
2
Edit the
SAS-configuration-directory\Lev1\Web\Applications
\RemoteServices\RemoteService.bat
file. Add the JVM option in the start2 section:
:start2
start "SAS Remote Services" "%JAVA_JRE_COMMAND%" ^
324
Appendix 2 / Administering Multicast Options
-classpath "%CLASSPATH%" ^
-Dsas.ext.config="C:\Program Files\SASHome\sas.java.ext.config" ^
-Djgroups.bind_addr=ip-address
3
Restart SAS Remote Services.
Setting the Bind Address for SAS Web Application
Server
Specify the following JVM option for the server:
-Djgroups.bind_addr=ip-address
The option is used when the server is restarted.
Download
Offentligt link opdateret
Det offentlige link til din chat er blevet opdateret. You may view and manage your chat links after registration here.
Dokument offentligt link
Annonce
