Managing the Object Spawner

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).

On z/OS, the spawner is run as a started task. If you want to create a SAS startup 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, see TKMVSENV File in the SAS Companion for z/OS or your UNIX documentation. [cautionend]

The object spawner executable resides by default in:

Windows:

install-dir\SASFoundation\9.2\objspawn.exe
UNIX:

install-dir/SASFoundation/9.2/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 the 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

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

-dnsmatch
-dnsname
-hostknownby
-sasspawnercn
-allowxcmd
-authproviderdomain
-conversationport
-logconfigloc
-generic
-sspi
-secpackage
-secpackagelist

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 startup 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. [cautionend]

-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 Properties Options Advanced Options Launch 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

-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 the 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\SAS\SASFoundation\9.2\objspawn.exe 
-dnsMatch d18374.na.sas.com -sasspawnercn "SAS [Config-Lev1] Object Spawner" 
-xmlconfigfile xmlconfig.xml -sspi -logconfigloc logconfig.xml

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 "Overview of System Options for Metadata" in the 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\SAS\SASFoundation\9.2\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\SAS\SASFoundation\9.2\objspawn.exe -xcf metadataConfig.xml

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 startup 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. [cautionend]

-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). [cautionend]

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\SAS\SASFoundation\9.2\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\SAS\SASFoundation\9.2\objspawn.exe 
-idep "SAS [Config-Lev1] Metadata Server"

EXAMPLE 3: In this example, the spawner service is uninstalled:

C:\Program Files\SAS\SASFoundation\9.2\objspawn.exe 
-di -name "SAS [Config-Lev1] Metadata Server"

Top of Page