Spawner Invocation Options

Overview of Spawner Invocation Options

The object spawner controls the execution of the workspace server and the stored process server through an IOM bridge connection. Spawner invocation options consist of options that are specific to the spawner and several SAS system options that you can use to run and configure the object spawner from the command line. On Windows and UNIX, when you install and configure SAS servers with the SAS Deployment Wizard, a spawner batch or script file is created by default in the object spawner configuration directory (ObjectSpawner.bat or objectspawner.sh).
For more information about the various object spawner configuration files and their purpose, see Configuration Files for SAS Object Spawners and SAS/CONNECT Spawners in SAS Intelligence Platform: System Administration Guide.
On z/OS, the spawner is run as a started task. If you want to create a SAS start-up command, see the section, Configuring and Starting the Object Spawner on z/OS.
Note: On z/OS and UNIX, to set the object spawner temp directory, update the TKOPT_ENV_UTILLOC environment variable with the new path. For more information, TKMVSENV File in SAS Companion for z/OS or your UNIX documentation.
The object spawner executable resides by default in:
  • Windows:
    install-dir\SASFoundation\9.3\objspawn.exe
  • UNIX:
    install-dir/SASFoundation/9.3/utilities/bin/objspawn
The spawner must be refreshed through the SAS Management Console in order to reflect configuration updates. The SAS Management Console provides an interface to refresh the spawner with configuration changes. For more information, see Using SAS Management Console to Operate SAS Servers in SAS Intelligence Platform: System Administration Guide. If your spawner is configured as a Windows service, then you must redefine the service to change the invocation options. For more information, see Update a Windows Object Spawner Service.
Spawner invocation options can be logically grouped into these categories:
  • general options
  • metadata connection options
  • service options

General Options

Overview of General Options

Use the following general options for identifying which object spawner to invoke and for setting spawner options such as security and logging:

Syntax Description

-dnsmatch DNSalias
specifies a DNS alias that will be accepted by the object spawner as a match for the local machine name.
In addition, the spawner replaces the dnsMatch value with the local machine name in its list of servers. This option is necessary if your network configuration resolves a single DNS alias to multiple machines that run SAS object spawners. For example, you configure SAS servers and spawners on two different machines: n1.my.org and n2.my.org. The DNS alias srv.my.org resolves to both of these machines, so clients can send a request to the alias and one of the two spawners will receive it. To support this configuration, specify -dnsMatch srv.my.org in the spawner start-up command on each machine.
-dnsname | -dns name
specifies which IP stack is used for communication between the spawner and the servers that the spawner launches. This option can be abbreviated as -dns.
-hostknownby DNSalias
specifies a DNS alias that will be accepted by the object spawner as a match for the local machine name.
-sasspawnercn | -ssc name
specifies the name (used in the SAS Management Console configuration) of the spawner object to use for this spawner invocation configuration. If you do not specify -sasspawnercn, the object spawner uses the first spawner definition (on the metadata server) with the same machine name as the current host.
Note: If none of the spawner definitions contain a host name of the current host, you must specify the -sasspawnercn option to designate which spawner definition to use. If you specify a spawner name that contains embedded blank spaces, then you must enclose the name in quotation marks (" "). This option can be abbreviated as -ssc.
-lbaddtocluster | -lbadd logicalLoadbalancedServerName </serverName>
specifies a logical, load-balanced server to which the object spawner should add itself. -lbaddtocluster enables you to add a new host to an existing load balancing peer object without requiring a peer refresh. This feature is required for cloud computing and software as a service models.
serverName is optional and is the name of the server to add the load-balanced server information to. When you omit serverName, the Object Spawner updates the first server definition associated with the logical load-balanced server.
-lbaddtocluster must be used in conjunction with the -sasSpawnercn (-ssc) option.
For example: 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe
-ssc "SASApp - Spawner"
-lbadd "SASApp - Logical Workspace Server" /compute.server.01.example.com
When using -lbaddtocluster, note the following:
  • The Object Spawner definition must already be associated with at least one server definition in the logical server that you specify.
  • The Object Spawner can add only itself to one cluster at a time. If you need to update multiple clusters, use the SAS Management Console.
  • Any error encountered during an -lbaddtocluster spawned update of metadata causes the Object Spawner to shut down.
  • Any error encountered after an -lbaddtocluster spawned update of metadata does not cause SAS to rollback or reset the metadata. The metadata changes made persist.
-allowxcmd
enables host commands and PIPE commands for all servers that are started by the spawner. You can use the SAS Management Console to enable host and PIPE commands on a server-by-server basis (Server Propertiesthen selectOptionsthen selectAdvanced Optionsthen selectLaunch Properties). By default, the spawner starts all servers with the -NOXCMD SAS system option. When you specify -allowxcmd, the spawner no longer specifies -NOXCMD when launching server sessions.
CAUTION:
When you specify -allowxcmd, clients can use host commands to perform potentially harmful operations such as file deletion.
-authproviderdomain | -authpd hostuser:domain
associates a domain with the host authentication provider, because the spawner starts either a SAS Workspace Server or SAS Stored Process Server. Workspace and stored process servers authenticate only against the host. For example: -authp hostuser:mydomain
-encryptfips
causes the spawner to run in Federal Information Processing Standards (FIPS) compliance mode that is provided by SAS/SECURE software in its implementation of the FIPS 140–2 specification. The object spawner checks each server and the object spawner's operator port to ensure that AES is used as the encryption algorithm. If the object spawner's operator connection is not using AES, the object spawner terminates. SAS marks any servers that are not using AES as invalid. If the spawner finds no valid servers, it terminates.
If the object spawner's operator port is not compliant, the following error message is written to the log:
The object spawner is running in FIPS compliance mode, 
therefore the only encryption algorithm that is supported for the 
Operator connection for <Spawner Name=""> (<Spawner ID="">) is AES.
If a server is not compliant, the warning message output is:
The object spawner is running in FIPS compliance mode, 
therefore the only encryption algorithm that is supported for %s (%s) 
is AES.  This server definition will not be included.
For more information, see FIPS 140-2 Standards Compliance in Encryption in SAS.
-conversationport | -cp port
specifies which port is used for communication between the spawner and the servers that the spawner launches. This option can be abbreviated as -cp.
-logconfigloc filename
sets the log options for the spawner in a log configuration file. For example: -logconfigloc "C:\SAS\Config\Lev1\ObjectSpawner\logconfig.xml"The file is an XML file that uses specific options. For more information, see Using the SAS Logging Facility in the SAS Intelligence Platform in SAS Logging: Configuration and Programming Reference.
Unless a path is specified, the spawner looks for the log config file in the current directory.
-generic
causes the spawner to use generic placeholders in data that it writes to its log. For example, user names are output as <user identity>, host names as <IP address>, connection and process IDs as –1 or <child process>, configuration paths as <configuration file path>, and so on.
-sspi
identifies support for the Security Support Provider Interface for single sign-on connections to the object spawner.
For more information, see SSPI System Option.
-secpackage "package-name" | "negotiate"
specifies the security package that the spawner should use to authenticate incoming client connections. (Use with -sspi.)
The "package-name" value specifies the security package that the spawner should use to authenticate incoming client connections. Enclose the security package name within double quotation marks (").
The default value is "negotiate". This value enables the spawner to present a set of valid security packages (through SECPACKAGELIST), which the server uses to find a match with an incoming client connection. If the client specifies a security package in the list, then the server attempts to authenticate the client the matched security package. Enclose negotiate within double quotation marks (").
For more information, see SECPACKAGE System Option.
-secpackagelist "package-name-1,[package-name-2,][...,]"
identifies the security package that is used by the server to authenticate incoming client connections. (Use with -sspi.) The package-name value defaults to "Kerberos,NTLM".
Enclose the security package name within double quotation marks ("). Delimit an additional package name with a comma (,).
For more information, see SECPACKAGELIST System Option.

Example

This example illustrates a typical spawner invocation: 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe 
-dnsMatch d18374.na.sas.com -ssc "SAS [Config-Lev1] Object Spawner" 
-xmlconfigfile xmlconfig.xml -sspi -logconfigloc logconfig.xml

Metadata Connection and Security Options

Overview of Metadata Connection and Security Options

Use the following metadata connection options for the object spawner to connect to the metadata server in order to find workspace server and stored process server definitions:
  • -xmlconfigfile
  • -metaserver
  • -metaport
  • -metauser
  • -metapass
  • -metaprofile
  • -metaconnect
  • -metarepository
  • -metaspn
  • -metaencryptalg
  • -metaencryptlevel
For metadata server connection options, you can either specify individual metadata options or point to a file that contains connection options by using -xmlconfigfile. For more information about the metadata configuration options, see System Options for Metadata in SAS Language Interfaces to Metadata.

Syntax Description

-xmlconfigfile | -xcf filename
specifies a fully qualified path to a metadata configuration file that contains a SAS Metadata Server definition to connect to for the complete configuration. On Windows, enclose paths with embedded blank spaces in double quotation marks. On z/OS, specify filenames similar to UNIX file paths due to the requirement for z/OS UNIX System Services.
This option can be abbreviated as -xcf.
-metaserver host name
identifies the metadata server where configuration information is saved and can be queried.
-metaport port
designates the metadata server port.
-metauseruser ID
identifies metadata server user ID.
-metapass userPassword
identifies metadata server password.
-metaprofile filename
specifies the location of the file that contains metadata profiles.
-metaconnect name
identifies the named connection from the -metaprofile file to use as the default metadata server connection.
-metarepository repositoryName
identifies the name of the metadata repository to query.
-metaspn servicePrincipalName
identifies the metadata server service principal name to use when communicating with a metadata server.
-metaencryptalg none | rc2 | rc4 | des |aes | tripledes | sas
specifies the type of encryption to use when communicating with a metadata server. (sas is the short form for sasproprietary.)
-metaencryptlevel credentials | everything
specifies the encryption level to use when communicating with a metadata server.

Examples

EXAMPLE 1: In this example, the object spawner connects to a metadata server by using command line options: 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe 
-metaserver "metaserver.unx.alphacorp.com"
 -metaport 8561 -metauser "sastrust@saspw" -metapass "sasuser1"
EXAMPLE 2: In this example, the object spawner points to a connection file (metadataConfig.xml) that contains metadata server connection information: 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe -xcf metadataConfig.xml

Service Options

Overview of Service Options

Use the following service options to create, modify, and delete object spawner service definitions on Windows only:
  • -install
  • -name
  • -servdir
  • -servuser
  • -servpass
  • -installdependencies
  • -deinstall
For more information, see Update a Windows Object Spawner Service .

Syntax Description

-install | -i <-name name> <-servdir directory> <-servuser user ID> <-servpass password>
instructs the spawner to install as a Windows service. This option can be abbreviated as -i. When asked to install as a service, the spawner records all options that are specified at installation time in the registry under the following key: "SYSTEM\CurrentControlSet\Services\service-name\Parameters"You can also specify options in the start-up parameters when you manually start the spawner service from the Microsoft Windows Services snap-in (services.msc).
-name name
specifies a Windows service name to use when installing the spawner as a service. Use with -install. The default value is SAS Object Spawner Daemon III.
If you specify a service name that contains embedded blank spaces, then you must enclose the name in quotation marks (" ").
Note: If you install more than one spawner as a service on the same machine, then you must use the -name option to give each spawner service a unique name.
-servdir directory
specifies the directory in which to run the Windows service. Use with -install. By default, the directory is: install-dir\Config\Lev1\ObjectSpawner.
-servuser | -su user ID
specifies a user name that the Windows service will run under, when you also specify the -install option. Use with -install. This option can be abbreviated as -su.
-servpass | -sp password
specifies a password for the user name that is specified in the -servUser option. Use with -install. This option can be abbreviated as -sp.
-installdependencies | -idep service-1<;service-2><;...>
specifies the Windows services that must be started before the spawner service starts. The service value is the name of the dependent service that is displayed in the Microsoft Windows Services snap-in (services.msc).
This option can be abbreviated as -idep.
-deinstall | -di –name name
instructs the spawner to uninstall as a Windows service. This option can be abbreviated as -di.
Note: The name value is the spawner service name that is displayed in the Microsoft Windows Services snap-in (services.msc).

Examples

EXAMPLE 1: In this example, the spawner is installed as a Windows service with “SAS [Config-Lev1] Object Spawner” displaying in the Microsoft Windows Services snap-in (services.msc). 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe 
-i -name "SAS [Config-Lev1] Object Spawner"
The spawner is installed under the Windows system user and runs in the default directory (install-dir\ObjectSpawner).
EXAMPLE 2: In this example, the spawner service is dependent on the metadata server starting first: 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe 
-idep "SAS [Config-Lev1] Metadata Server"
EXAMPLE 3: In this example, the spawner service is uninstalled: 
C:\Program Files\SASHome\SASFoundation\9.3\objspawn.exe 
-di -name "SAS [Config-Lev1] Metadata Server"
Copyright © SAS Institute Inc. All rights reserved.