1.*************************************************************************** 2.* Software Testing Automation Framework (STAF) 3.* (C) Copyright IBM Corp. 2001, 2004 4.* 5.* This software is licensed under the Eclipse Public License (EPL) V1.0. 6.**************************************************************************** 7 8.*************************-START-OF-PROLOG-**************************** 9.* 10.* File Name : Configuration SCRIPT 11.* Descriptive Name : Software Test Automation Framework Configuration 12.* Detail: 13.* 14.* This file contains the STAF configuration options. 15.* 16.**************************-END-OF-PROLOG-***************************** 17:ih1.configuration 18:i2.instructions 19:h1 id=config.Configuration 20:p.STAF is configured through a text file called the STAF Configuration File. 21This file may have any name you desire, but the default is STAF.cfg. The 22STAF Configuration File is read and processed line by line. Whitespace at 23the front of the line is removed before processing. Blank lines, or 24lines containing only whitespace are ignored. You may continue a configuration 25statement onto the next line by placing a "\" as the last character of the 26line. The maximum length for a line in the STAF Configuration File is 2048 27characters. The various configuration statements are described in the following 28sections. 29:p.You may use variables for all the values of configuration statement options, 30with the exception of the :xph.SET VAR:exph. configuration statement itself. 31However, these variables must be either predefined STAF variables (see 32:hdref refid=varcon.) or be previously defined in the STAF Configuration File 33via the :xph.SET VAR:exph. configuration statement (see below). 34.* 35.*--------------------------------------------------------------------- 36.* 37:h2 id=commentscfg.Comments 38:h3.Description 39:p.You specify a comment by placing a pound sign, #, as the first character 40on the line. Comment lines are ignored. 41:h4.Examples 42:xmp. 43# This is a comment line 44:exmp. 45.* 46.*--------------------------------------------------------------------- 47.* 48:i1.machine name 49:ih1.configuration 50:i2.machine name 51:h2 id=machinecfg.Machine Nickname 52:h3.Description 53:p.You may specify a nickname for your machine using the 54MACHINENICKNAME configuration statement. 55:p.This allows you to override the machine nickname which is set to the 56value of the STAF/Config/Machine system variable by default. 57This primarily affects the data stored by services such as the Log and 58Monitor services, which store data based on the machine from which it came 59by using the STAF/Config/MachineNickname system variable as part of the 60directory path when creating logs and monitor data. 61By allowing the STAF/Config/MachineNickname system variable to be overridden, 62it allows you to better manage your data. 63:p. 64The machine nickname is not used to communicate with other systems and does 65not have any effect on trust. 66:p.This option is used in both connected and disconnected modes 67(e.g. disconnected mode is when you are not using a network interface). 68 69:h4.Syntax 70:xmp. 71MACHINENICKNAME <Nickname> 72:exmp. 73:p.:xph.<Nickname>:exph. is the nickname you wish to use for your machine. It is 74case sensitive. 75:h4.Examples 76:xmp. 77MACHINENICKNAME testmachine1 78MACHINENICKNAME JohnDoe 79:exmp. 80.* 81.*--------------------------------------------------------------------- 82.* 83:ih1.configuration 84:i2.network interfaces 85:i2.connection providers 86:i1.network interfaces 87:i1.connection providers 88:h2 id=networkcfg.Network Interfaces 89:h3.Description 90:p.You indicate that you wish to send and accept requests on a network 91interface using the INTERFACE configuration statement. 92The INTERFACE configuration statement registers 93connection providers (also called network interfaces, or interfaces 94for short). 95 96:h4.Notes: 97:ol. 98:li.Currently, STAF provides two network interfaces, secure TCP/IP and 99non-secure TCP/IP (except a secure TCP/IP interface is not yet provided 100for z/OS). 101.* or Windows IA64 102The default STAF configuration file configures a secure ssl interface 103as the default interface and also configures a non-secure tcp interface 104(except on z/OS where only a non-secure tcp interface is configured). 105STAF also allows you to plug in network interfaces 106(aka connection providers) so that you can create your own 107connection provider which can communicate via any mechanism you 108choose (e.g. a Serial Line, NetBIOS, or SNA). 109Connection provider interfaces are C/C++ based so they are platform 110specific. However, we haven't provided any documentation yet on how 111to do this. 112:li.An interface named local is also provided with STAF. Requests 113coming from the local system will appear as though they came from an 114interface named "local" and a system identifier of "local". 115:eol. 116:h4.Syntax 117:xmp. 118INTERFACE <Name> LIBRARY <Implementation Library> [OPTION <Name[=value]>]... 119:exmp. 120:p.:xph.<Name>:exph. is the name by which this network interface 121(aka Connection Provider) will be known on this machine. 122:p.:xph.LIBRARY:exph. is the name of the shared library / DLL 123which implements the network interface (aka Connection Provider). 124STAF provides one implementation library called STAFTCP which 125provides support for both secure and non-secure TCP/IP communcation. 126:p.:xph.OPTION:exph. specifies a configuration option that will be passed on 127to the shared library / DLL which implements the connection provider. 128You may specify multiple :xph.OPTION:exph.s for a given connection provider. 129See :hdref refid=staftcp. for acceptable options for the STAFTCP shared 130library / DLL. 131:h4.Examples 132:xmp. 133INTERFACE ssl LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550 134INTERFACE tcp LIBRARY STAFTCP OPTION SECURE=No OPTION PORT=6500 135INTERFACE tcp2 LIBRARY STAFTCP 136INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6600 137INTERFACE serial LIBRARY STAFSER 138:exmp. 139.* 140.*--------------------------------------------------------------------- 141:ih1.configuration 142:i2.STAFTCP network interface 143:i2.STAFTCP connection provider 144:i1.network interfaces 145:i1.connection providers 146:i1.STAFTCP 147:i1.TCP/IP 148:i1.port 149:i2.STAFTCP Connection Provider 150:h3 id=staftcp.STAFTCP Connection Provider 151:p.The STAFTCP connection provider shared library / DLL supports 152TCP/IP communication. STAF supports both secure and non-secure 153TCP/IP communication on most platforms. 154STAF supports both IPv4 and IPv6. IPv6 is supported in the IPv6 enabled version of STAF. 155:p.Each STAFTCP connection provider configured on a single machine must use a unique 156port number. To communicate to a remote machine running STAF, your machine and the 157remote machine must both have a STAFTCP connection provider configured with the same 158SECURE option value and the same PORT option value. A non-secure STAFTCP connection 159provider cannot communicate to a secure STAFTCP connection provider. Also, a secure 160TCP connection provider can only communicate to another secure TCP connection provider 161if the same certificate is used. 162:p.The STAFTCP connection provider supports the following :xph.OPTIONs:exph.&colon. 163:p.:xph.CONNECTTIMEOUT=<Number>:exph. specifies the maximum time in milliseconds to wait 164for a connection attempt to a remote system to succeed. The default is 5000 165(5 seconds). You may need to increase this value if you are consistently 166receiving return code 16 when trying to communicate with distant STAF systems. 167Note that the total time to wait for a connection to a remote system to succeed 168is :xph.(CONNECTTIMEOUT * CONNECTATTEMPTS) + (CONNECTRETRYDELAY * (CONNECTATTEMPTS - 1)):exph.. 169If using the defaults, the maximum total time to wait for a connection to a remote 170system to succeed is (5000 * 2) + (1000 * 1), which equals 11 seconds. 171The :xph.CONNECTATTEMPTS:exph. and :xph.CONNECTRETRYDELAY:exph. values are operational 172parameters that can be set in the STAF configuration file. 173:p.:xph.PORT=<Number>:exph. specifies the TCP/IP port on which this 174connection provider listens for connections. 175The default port is 6550 if option :xph.SECURE=Yes:exph.. 176The default port is 6500 if option :xph.SECURE=No:exph.. 177Each STAFTCP connection provider configured on a single machine 178must use a unique port number. 179:p.:xph.PROTOCOL=<IPv4 | IPv6 | IPv4_IPv6>:exph. specifies the communication protocol that this 180connection provider uses. The possible values are :xph.IPv4:exph., :xph.IPv6:exph., 181or :xph.IPv4_IPv6:exph.. When this option is absent, the default is :xph.IPv4_IPv6:exph. 182which indicates to use both IPv4 and IPv6 protocols. 183This option is only valid for IPv6 enabled versions of STAF. 184:p.:xph.SECURE=<Yes | No>:exph. specifies whether to use secure or 185non-secure TCP/IP. Secure TCP/IP uses OpenSSL. This option is 186not available on z/OS where only non-secure TCP/IP is currently supported. 187The default is No. 188:p.:xph.SSL/CACertificate:exph. specifies the fully qualified path to the 189file containing the STAF CA certificate list used for secure connections. 190This option is only valid if option :xph.SECURE=Yes:exph. is specified. 191The default is {STAF/Config/STAFRoot}/bin/CAList.crt which is a list 192of the default server certificate provided with STAF. 193:p.:xph.SSL/ServerCertificate:exph. specifies the fully qualified path to 194the file containing the STAF server certificate used for secure connections. 195This option is only valid if option :xph.SECURE=Yes:exph. is specified. 196The default is {STAF/Config/STAFRoot}/bin/STAFDefault.crt which is a 197self-signed x509 default certificate provided with STAF. 198:p.:xph.SSL/ServerKey:exph. specifies the fully qualifed path to the file 199containing the STAF server key used for secure connections. 200This option is only valid if option :xph.SECURE=Yes:exph. is specified. 201The default is {STAF/Config/STAFRoot}/bin/STAFDefault.key which is a 202default server key provided with STAF. 203:p. 204:h4.Examples 205:xmp. 206INTERFACE ssl LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550 207INTERFACE tcp LIBRARY STAFTCP OPTION SECURE=No OPTION PORT=6500 208INTERFACE tcp2 LIBRARY STAFTCP OPTION PORT=6501 209INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6700 OPTION PROTOCOL=IPv6 210INTERFACE tcp4 LIBRARY STAFTCP OPTION CONNECTTIMEOUT=15000 211INTERFACE ssl2 LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6551 \ 212 OPTION SSL/CACertificate={STAF/Config/STAFRoot}/bin/MyCAList.crt \ 213 OPTION SSL/ServerCertificate={STAF/Config/STAFRoot}/bin/MySTAF.crt \ 214 OPTION SSL/ServerKey={STAF/Config/STAFRoot}/bin/MySTAF.key 215:exmp. 216.* 217.*--------------------------------------------------------------------- 218.* 219:i1.Service registration 220:ih1.configuration 221:i2.Service registration 222:ih1.registration 223:i2.Service registration 224:h2 id=serviceregcfg.Service Registration 225:h3.Description 226:p.External services are registered with the SERVICE configuration statement. 227:h4.Syntax 228:xmp. 229SERVICE <Name> LIBRARY <Implementation library> &lbrk.EXECUTE <Executable>&rbrk. 230 &lbrk.OPTION <Name[=Value]>&rbrk.... &lbrk.PARMS <Parameters>&rbrk. 231:exmp. 232:p.or 233:xmp. 234SERVICE <Name> DELEGATE <Machine> &lbrk.TONAME <Remote Service Name>&rbrk. 235:exmp. 236 237:p.:xph.<Name>:exph. is the name by which this service will be known on this 238machine. 239:p.:xph.LIBRARY:exph. is the name of the shared library / DLL 240which implements the service or acts as a proxy for the service. See the 241information for each external service to determine the appropriate value 242for this option. 243:p.:xph.EXECUTE:exph. is used by service proxy libraries / DLLs to specify what 244the proxy library should execute. For example, for a Java service, this might 245be the name of the Java jar file which actually implements the service. This 246option has no significance for non-proxy service libraries. See below for 247information regarding the JSTAF service proxy library. 248Otherwise, see the documentation provided by the service proxy library. 249:p.:xph.OPTION:exph. specifies a configuration option that will be passed on 250to the service library / DLL. This is typically used by service proxy 251libraries to further control the interface to the actual service 252implementation. You may specify multiple :xph.OPTION:exph.s for a given 253service. See below for acceptable options for the JSTAF 254service proxy library. Otherwise, see the documentation provided with the 255service (proxy) library. 256:p.:xph.PARMS:exph. specifies optional parameters that will be passed to the 257service during initialization. 258:p.:xph.DELEGATE:exph. specifies the machine to which to delegate this service. 259This machine must be running STAF V3.0.0 or later. 260:note.From a trust perspective, the tcp interface names on the "delegated to" 261service machine and on the machine delegating service requests to it must match 262or the trust statement for the machine that is delegating service requests 263must use a wildcard to match any interface. 264:p.:xph.TONAME:exph. is the name of the service on :xph.<Machine>:exph. to 265which the delegated requests will be sent. The default is the same name as 266specified with :xph.<Name>:exph.. 267:h4.Examples 268:xmp. 269SERVICE MONITOR LIBRARY STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 4096" 270SERVICE LOG LIBRARY STAFLog 271.*SERVICE SAMPLER LIBRARY RXSTAF EXECUTE C:\STAF\bin\Sample.cmd PARMS "Sample Data" 272SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\service\STAX.jar \ 273 OPTION J2=-Xmx128m 274SERVICE SAMPLEJ LIBRARY JSTAF EXECUTE C:\STAF\services\Sample.jar \ 275 PARMS {STAF/Config/STAFRoot}\bin\sample.dft 276SERVICE MYLOG DELEGATE TestSrv1 277SERVICE PAGER DELEGATE pagesrv.austin.ibm.com 278SERVICE EVENT DELEGATE EventSrv TONAME DB2EVENT 279SERVICE NOTIFY LIBRARY Notify PARMS "24 Hours 7 Days" 280SERVICE ZIP LIBRARY STAFEXECPROXY EXECUTE STAFZip 281:exmp. 282.*--------------------------------------------------------------------- 283.* XXX: Commented out since don't support REXX services in STAF V3 284.*:h3 id=rxstaf.RXSTAF service proxy library 285.*:p.The library RXSTAF acts as a proxy for STAF services implemented in the 286.*REXX language. 287.*:p.The :xph.EXECUTE:exph. option for a Rexx service should specify the full 288.*path to the Rexx script that implements the service. 289.*:p.RXSTAF supports the following :xph.OPTION:exph.s&colon. 290.*:p.:xph.DEBUG:exph. specifies that Rexx service code should be re-read 291.*for every service request, thus, allowing debugging without stopping STAFProc. 292.*If this option is not specified, the Rexx service code is read in once at 293.*initialization time and a tokenized image is created. This tokenized image 294.*is used for all service requests, and any changes to the Rexx service code 295.*will not be reflected until STAFProc is stopped and started again. 296.*:note text=Warning.Using the :xph.DEBUG:exph. option will degrade the 297.*service's performance. 298.*:h4.Examples 299.*:xmp. 300.*OPTION Debug 301.*:exmp. 302.*--------------------------------------------------------------------- 303:i2.Java Service Registration 304:i2.JSTAF 305:ih1.configuration 306:i2.Java Virtual Machine 307:h3 id=jvmcfg.JSTAF service proxy library 308:p.The library JSTAF acts as a proxy for STAF services implemented in the 309Java language. The minimum version of Java that JSTAF requires depends on 310the operating system for which STAF was built: 311:ul. 312:li.Java 1.4.2 or newer is required by JSTAF provided in the STAF binaries for 313Windows, Linux i386/amd64/ppc, zLinux, AIX, IBM i, and HP-UX. 314:li.Java 5.0 or newer is required by JSTAF provided in the STAF binaries for 315Solaris and FreeBSD. 316:li.Java 6.0 or newer is required by JSTAF provided in the STAF binaries for 317z/OS. 318:li.Java 7.1 or newer is required by JSTAF provided in the STAF binaries for 319Linux ppc64le. 320:li.Java 8.0 or newer is required by JSTAF provided in the STAF binaries for 321Mac OS X. 322:eul. 323:note.JSTAF in a 32-bit version of STAF requires a 32-bit version of Java. 324Similarly, JSTAF in a 64-bit version of STAF requires a 64-bit version of Java. 325:p.The :xph.EXECUTE:exph. option for a Java service should specify the 326fully-qualified name of the jar file that implements the service. The 327jar file will be automatically added to the class path by JSTAF. 328:note.In versions of STAF prior to 2.4.0, the name of the Java class that 329implements the service was specified for the :xph.EXECUTE:exph. option and 330you had to make sure that the service's class files were in the class path. 331This is still supported, but this method is deprecated and will be removed 332in a future version of STAF. 333:p.JSTAF supports the following :xph.OPTION:exph.s&colon. 334:p.:xph.JVMName=<Name>:exph. specifies the name for the JVM you want the Java 335service to run in. If the JVM does not already exist, it will be created. 336If no JVMName is specified, then the Java service will run in the default JVM, 337named STAFJVM1, which is created the first time a Java service is registered 338with no JVMName specified. 339This option allows JSTAF to run Java services in different JVMs. 340:p.:xph.JVM=<Executable>:exph. specifies the name of the desired Java 341executable. The default is "java". Note, this option is only valid for the 342first service created with a given :xph.JVMName:exph.. 343:p.:xph.J2=<Java option>:exph. specifies one or more arbitrary Java option(s) 344that should be passed to the JVM. You can find more information on these 345options by using the command "java" (for standard options) and "java -X" 346(for non-standard options), or by consulting your Java documentation. 347Note that -X options can vary depending on which Java implementation 348(e.g. Oracle Java 7 vs IBM Java 6) you installed. Note, this option 349is only valid for the first service created with a given :xph.JVMName:exph.. 350:note.If you are using the HP-UX IA64 64-bit version of STAF, you must specify 351the -d64 option to the JVM. This can be done by specifying :xph.J2=-d64:exph. 352:p.:xph.MAXLOGS=<Number>:exph. specifies the maximum number of log files 353for the JVM that should be saved. The default is 5. 354The JVM log files are stored in the :xph.{STAF/DataDir}/lang/java/jvm/<JVMName>:exph. 355directory and contain JVM start information such as the date/time when the JVM 356was started, the JVM executable, and the J2 options used to start the JVM. 357In addition, it contains any other information logged by the JVM, including any 358errors that may have occurred while the JVM was running. 359The current JVM log file is named :xph.JVMLog.1:exph. and saved JVM log files, if any, 360are named :xph.JVMLog.2:exph. to :xph.JVMLog.<MAXLOGS>:exph.. 361Note, this option is only valid for the first service created with a 362given :xph.JVMName:exph.. 363:p.:xph.MAXLOGSIZE=<Number>:exph. specifies the maximum size, in bytes, for 364the JVM log file(s). The default is 1048576 (1M). 365This option determines when to create a new JVM log file. When the JVM is 366started, if the size of a JVM log file exceeds the maximum size specified 367by this option, a new JVM log file will be created. 368Note, this option is only valid for the first service created with a 369given :xph.JVMName:exph.. 370:p. 371:note.You can view the JVM log for a Java service that is currently 372registered using the STAFJVMLogViewer utility. 373Section :hdref refid=STAFJVMLogViewer. provides more information on this utility. 374:p. 375:h4.Examples 376:xmp. 377OPTION J2=-verbose&colon.gc 378OPTION "J2=-cp {STAF/Config/BootDrive}/MyJava/Extra.jar{STAF/Config/Sep/Path}{STAF/Env/Classpath}" 379OPTION J2=-Xms128m 380OPTION J2=-Xmx512m 381OPTION J2=-d64 382OPTION "J2=-Xmx1024m -XX&colon.MaxPermSize=256m -XX&colon.PermSize=256m" 383OPTION JVMName=MyJVM1 384OPTION JVM=/opt/sunjdk1.4.0/jre/bin/java 385OPTION MAXLOGS=2 386OPTION MAXLOGSIZE=2048 387:exmp. 388:p. 389If you wanted to run the STAX Java service in a JVM, called MyJVM1, with a maximum heap 390size of 1024M, and wanted the Event and EventManager Java services to run in a 391different JVM, called MyJVM2, with a maximum heap size of 512M, you could specify 392the following service registration lines in the STAF.cfg file (or dynamically 393register the services in this order using the specified options). 394:xmp. 395SERVICE STAX LIBRARY JSTAF EXECUTE C:/STAF/service/STAX.jar \ 396 OPTION JVMName=MyJVM1 OPTION J2=-Xmx1024m 397SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/service/STAFEvent.jar \ 398 OPTION JVMName=MyJVM2 OPTION J2=-Xmx512m 399SERVICE EventManager LIBRARY JSTAF EXECUTE C:/STAF/services/EventManager.jar \ 400 OPTION JVMName=MyJVM2 401:exmp. 402.* 403.*--------------------------------------------------------------------- 404:i2.Perl Service Registration 405:i2.PLSTAF 406:ih1.configuration 407:i2.Perl Interpreter 408:h3 id=plstaf.PLSTAF service proxy library 409:p.The library PLSTAF acts as a proxy for STAF services implemented in the 410Perl language. PLSTAF is currently supported on Windows (IA32), Linux (IA32), 411and Mac OS X. On Linux IA32, PLSTAF is currently only supported with Perl 5.8.0. 412:p.The :xph.EXECUTE:exph. option for a Perl service should specify the name of 413the .pm file (without the .pm extension) that implements the service. 414:p.PLSTAF supports the following :xph.OPTION:exph.s&colon. 415:p.:xph.USELIB=<Directory>:exph. specifies the directory containing the .pm file 416that implements the service. You must use the USELIB option unless you have 417set (prior to starting STAFProc) environment variable PERLLIB to include the 418directory containing the .pm file that implements the service. 419:p.:xph.MAXLOGS=<Number>:exph. specifies the maximum number of log files 420for the Perl interpreter that should be saved. The default is 5. 421The Perl interpreter log files are stored in the 422:xph.{STAF/DataDir}/lang/perl/<serviceName>:exph. 423directory and contain the Perl interpreter start information such as the 424date/time when the Perl interpreter was started and the Perl service 425executable. In addition, it contains any other information logged by the Perl 426service and interpreter, including any errors that may have occurred while the 427Perl interpreter was running. 428The current Perl interpreter log file is named :xph.PerlInterpreter.1:exph. 429and saved Perl interpreter log files, if any, 430are named :xph.PerlInterpreter.2:exph. to :xph.PerlInterpreter.<MAXLOGS>:exph.. 431:p.:xph.MAXLOGSIZE=<Number>:exph. specifies the maximum size, in bytes, for 432the Perl interpreter log file(s). The default is 1048576 (1M). 433This option determines when to create a new Perl interpreter log file. When the 434Perl interpreter is started, if the size of a Perl interpreter log file exceeds 435the maximum size specified by this option, a new Perl interpreter log file will 436be created. 437:Note.The PLSTAF service proxy library uses embedded Perl directly within the 438STAFProc executable. This means that if a Perl service has a fatal error which 439terminates the Perl interpreter, the STAFProc executable will also be terminated. 440To prevent this, you can use the STAFEXECPROXY service proxy library when 441registering a Perl service. 442:Note.To configure Perl services, prior to starting STAFProc, environment 443variable PERLLIB must be set to include the directory containing the PLSTAF.pm 444and PLSTAFService.pm files (located in the "bin" directory in the STAF 445installation root directory). 446:Note.To configure Perl services, the directory containing the PLSTAF library 447(PLSTAF.dll on Windows, libPLSTAF.so on Linux, libPLSTAF.dylib on Mac OS X) 448must be in the operating system's library path (PATH on Windows, LD_LIBRARY_PATH 449on Linux, DYLD_LIBRARY_PATH on Mac OS X) prior to starting STAFProc. 450:Note.When configuring Perl services on Linux with Perl 5.8.0, the directory 451containing the Perl 5.8.0 libperl.so file must be included in environment 452variable LD_LIBRARY_PATH prior to starting STAFProc. 453:Note.When removing a Perl service (or when shutting down STAF if Perl 454services had been configured), you may see a message in the STAFProc output 455similar to: "Perl exited with active threads". This message can be ignored. 456:p. 457:h4.Examples 458:p. 459:xmp. 460SERVICE Device1 LIBRARY PLSTAF EXECUTE DeviceService 461SERVICE Device2 LIBRARY STAFEXECPROXY EXECUTE DeviceService \ 462 OPTION PROXYLIBRARY=PLSTAF 463SERVICE testA LIBRARY STAFEXECPROXY EXECUTE myTestService \ 464 OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=C:\MyServices 465:exmp. 466.* 467.*--------------------------------------------------------------------- 468:i2.STAFEXECPROXY 469:i2.STAFEXECPROXY 470:ih1.configuration 471:h3 id=stafexecproxy.STAFEXECPROXY service proxy library 472:p.This library will allow you to execute an external STAF service within a 473new executable, rather than directly within the STAFProc executable. For 474example, this library could be used to run the Zip service in a separate 475executable, or run a Perl service where the Perl interpreter will run in a 476separate executable. 477:p.Running an external STAF service in a separate executable will ensure 478that if the service has a fatal error, the error will not kill STAFProc. 479In addition, this allows monitoring of the external service's system 480resource utilization, since you can view the utilization for the new 481executable (otherwise, if the service was running within the STAFProc 482executable, then the service's resource utilization would be part of 483the STAFProc resource utilization). 484:p.Note that using the STAFEXECPROXY 485library will introduce a level of IPC communication for all service 486requests to the service; rather than STAFProc sending the requests 487directly to the service, STAFProc will send the request to the 488STAFEXECPROXY library, which will then send the request to the new 489executable, which will then send the request to the service (processing 490the service result will have the same path in reverse). So, for external 491STAF services where performance is critical, such as the Log and Monitor 492services, using the STAFEXECPROXY library is not recommended. 493:p.Note that since the JSTAF proxy library already runs the Java STAF service 494in a new executable (the JVM), using the STAFEXECPROXY library for Java STAF 495services is not supported (if you attempt to register a Java STAF service 496using the STAFEXECPROXY library, you will get an RC 27, Service 497configuration error). 498:p.The :xph.EXECUTE:exph. option is used to indicate the service library to 499execute, or if the 500service will be executed by a proxy library, it will be used to indicate 501what service executable the proxy library should execute. For example, 502for the Zip service, "STAFZip" would be used for the EXECUTE value. For a 503Perl service, which uses the PLSTAF proxy library, the service .pm module 504would be used for the EXECUTE value. 505:p.STAFEXECPROXY supports the following :xph.OPTION:exph.s 506:xmp. 507 [OPTION PROXYLIBRARY=<ProxyLibrary>] 508 [OPTION PROXYENV=<Variable=Value>]... 509:exmp. 510(note that all other :xph.OPTION:exph.s will be passed to the service 511library / DLL)&colon. 512:p.:xph.OPTION PROXYLIBRARY=<ProxyLibrary>:exph. is used to indicate the proxy 513library to use for the 514external service. For example, you would use OPTION PROXYLIBRARY=PLSTAF 515for a Perl service. Note that this OPTION will not be passed on to the 516service library / DLL. 517:p.:xph.OPTION PROXYENV=<Variable=Value>:exph. allows you to specify 518environment variables that will be set for the STAFEXECPROXY executable (in 519addition to or replacing the environment variables that were set when STAFProc 520was started). This allows you to set environment variables for the 521STAFEXECPROXY executable without requiring that these environment variables be 522set for STAFProc. 523This option is particularly useful for Perl STAF services, which on many 524Unix platforms require LD_PRELOAD to be set to the libperl library file 525location. However, setting LD_PRELOAD prior to starting STAFProc can 526cause incompatibility issues for processes started via STAFProc. 527So, you can use OPTION PROXYENV to specify the LD_PRELOAD environment 528variable for the STAFEXECPROXY executable, without having it set for STAFProc's 529environment. To "unset" an environment variable, you can set the <Value> to 530be blank. You may specify any number of PROXYENV OPTIONs. 531:p.STAFExecProxy.exe (STAFExecProxy on Unix) is the separate executable for the 532external service that will be displayed in the operating system's process 533list. You can determine the PID for the STAFExecProxy executable by 534running "HANDLE LIST HANDLES LONG". 535:p.You may only run a single external service within a single STAFExecProxy 536executable (multiple services that use the STAFEXECPROXY library will each 537have a unique STAFExecProxy executable). 538:p. 539:h4.Examples 540:xmp. 541SERVICE Zip LIBRARY STAFEXECPROXY EXECUTE STAFZip 542:exmp. 543:xmp. 544SERVICE Device LIBRARY STAFEXECPROXY EXECUTE DeviceService \ 545 OPTION PROXYLIBRARY=PLSTAF 546:exmp. 547:xmp. 548SERVICE getenvvar LIBRARY STAFEXECPROXY EXECUTE \ 549 GetEnvVar OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=/usr/local/staf/services \ 550 OPTION PROXYENV=LD_PRELOAD=/usr/lib/perl5/5.8.8/i386-linux-thread-multi/CORE/libperl.so \ 551 OPTION PROXYENV=TESTVAR=abcdef 552 553:exmp. 554:xmp. 555SERVICE getenvvar LIBRARY STAFEXECPROXY EXECUTE \ 556 GetEnvVar OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=/usr/local/staf/services \ 557 OPTION PROXYENV=LD_PRELOAD=/opt/ActivePerl-5.8/lib/CORE/libperl.so \ 558 OPTION PROXYENV=ANT_HOME= \ 559 OPTION "PROXYENV=MESSAGE=This is a test message" 560 561:exmp. 562.* 563.*--------------------------------------------------------------------- 564.* 565:i1.Service loader registration 566:ih1.configuration 567:i2.Service loader registration 568:ih1.registration 569:i2.Service loader registration 570:h2 id=serviceloadercfcg.Service Loader Registration 571:h3.Description 572:p.Service loaders are registered with the SERVICELOADER configuration statement. 573:h4.Syntax 574:xmp. 575SERVICELOADER LIBRARY <Implementation library> &lbrk.EXECUTE <Executable>&rbrk. 576 &lbrk.OPTION <Name[=Value]>&rbrk.... &lbrk.PARMS <Parameters>&rbrk. 577:exmp. 578 579:p.:xph.LIBRARY:exph. is the name of the shared library / DLL 580which implements the service loader or acts as a proxy for the service loader. See the 581information for each service loader to determine the appropriate value 582for this option. 583:p.:xph.EXECUTE:exph. is used by service proxy libraries / DLLs to specify what 584the proxy library should execute. For example, this might be the name of 585the Java jar file which actually implements the service loader. This 586option has no significance for non-proxy service libraries. See the Service Registration 587section for information regarding the JSTAF service proxy library. 588:p.:xph.OPTION:exph. specifes a configuration option that will be passed on 589to the service loader library / DLL. This is typically used by service proxy 590libraries to further control the interface to the actual service loader 591implementation. You may specify multiple :xph.OPTION:exph.s for a given 592service loader. See the Service Registration section 593for acceptable options for the JSTAF 594service proxy library. Otherwise, see the documentation provided with the 595service (proxy) library. 596:p.:xph.PARMS:exph. specifies optional parameters that will be passed to the 597service loader during initialization. 598:h4.Examples 599:xmp. 600# Default Service Loader Service for LOG, MONITOR, RESPOOL, and ZIP services 601SERVICELOADER LIBRARY STAFDSLS 602 603# HTTP Service Loader Service for Java services (for Windows) 604SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/bin/STAFHTTPSLS.jar \ 605 PARMS "CONFIGFILE http://server1.company.com/project/stafhttpsls.cfg" 606 607# HTTP Service Loader Service for Java services (for Unix) 608SERVICELOADER LIBRARY JSTAF EXECUTE /usr/local/staf/lib/STAFHTTPSLS.jar \ 609 PARMS "CONFIGFILE http://server1.company.com/project/stafhttpsls.cfg" 610 611# Custom Service Loader Service written in Java 612SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/services/CustomServiceLoader.jar 613:exmp. 614 615:ih1.Service Loaders 616:i2.Default Service Loader Service (STAFDSLS) 617:h3 id=STAFDSLS.Default Service Loader Service (STAFDSLS) 618:p.The default service loader service is implemented by library STAFDSLS and 619is written in C++. It can dynamically load the Log, Zip, Monitor, and ResPool 620C++ services. This service loader is configured automatically in the default 621STAF.cfg file as follows: 622:xmp. 623# Add default service loader 624serviceloader library STAFDSLS 625:exmp. 626 627:ih1.Service Loaders 628:i2.HTTP Service Loader Service (STAFHTTPSLS) 629:h3 id=STAFHTTPSLS.HTTP Service Loader Service (STAFHTTPSLS) 630:p.The HTTP service loader service is implemented by jar file STAFHTTPSLS.jar 631and is written in Java and is installed as part of STAF Java support in a typical 632installation of STAF. It can dynamically load any STAF service written in Java. 633It can download the jar file for a STAF Java service (or a zip file that contains 634the jar file) from a web server or from a file on the local machine. It uses a 635configuration file to determine what services it can load. To use the HTTP 636service loader service, a Java runtime must be installed and you must add a 637:xph.SERVICELOADER:exph. configuration statement to the STAF configuration file 638including a :xph.CONFIGFILE:exph. parameter specifying the location of the 639HTTPSLS configuration file you created for it. 640:p. 641When STAF encounters a request for a service that isn't currently registered, 642it checks each service loader that is registered in the STAF configuration file 643to see if it handles this service. The HTTP service loader service reads its 644HTTPSLS configuration file (first downloading it from a web server if needed) 645to see if it can handle this service. If so, it downloads the service from the 646specified location to a temporary directory on the local machine (and unzips it 647if necessary to access the STAF service jar file) and submits an :xph.ADD:exph. 648request to the :xph.SERVICE:exph. service to register the service. This way, 649STAF is able to load whatever Java services you want. Also, note that each 650time the HTTP service loader service attempts to load a service, it reads its 651HTTPSLS configuration file, so you can update the HTTPSLS configuration file 652and it will read it the next time it attempts to load a service (without 653restarting STAFProc). Note that whenever STAF is restarted, the :xph.tmp:exph. 654directory in the STAF data directory is deleted which means the temporary jar 655files that the HTTP service loader service downloaded will be deleted since 656they are stored in the STAF :xph.tmp:exph. data directory's 657:xph.service/<Serviceloader Name>:exph. sub-directory. 658:p. 659The HTTP service loader service can reduce the maintenance for obtaining and 660managing STAF Java services by: 661:ul. 662:li.Obtaining specified versions of STAF Java services from a web server 663instead of having to manually download each service and manually configure the 664service in the STAF configuration file on all machines that require the service(s). 665:li.Providing the ability to specify a zip file on a web server that contains 666a jar file for a STAF Java services (e.g. STAF Java services are provided in 667zip files on the SourceForge website) and automatically unzipping the file to 668obtain the jar file for the STAF Java service. 669:li.Providing the ability to specify where to download STAF Java services from 670via a configuration file that resides on a web server as this file only needs 671to exist in one place and can be used by many machines. 672:eul. 673 674:h4.Syntax 675:xmp. 676SERVICELOADER LIBRARY JSTAF EXECUTE <Fully-qualified name of STAFHTTPSLS.jar> 677 [OPTION <Name[=Value]>]... 678 PARMS "CONFIGFILE <ConfigFileLocation> 679 [DOWNLOADATTEMPTS <NumDownloadAttempts>] 680 [DOWNLOADRETRYDELAY <DelayInSeconds>]" 681:exmp. 682:p. 683:xph.LIBRARY:exph. must always be :xph.JSTAF:exph. which is the STAF Java 684service proxy library (because the HTTP Service Loader is written in Java). 685:p. 686:xph.EXECUTE:exph. specifies the location of the jar file which implements 687the HTTP service loader service. On Windows, specify 688:xph.{STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar:exph.. 689On Unix, specify :xph.{STAF/Config/STAFRoot}/lib/STAFHTTPSLS.jar:exph.. 690:p. 691:xph.OPTION:exph. specifies a configuration option that will be passed to JSTAF 692to further control the interface to the JVM where this service loader will be run. 693You may specify multiple :xph.OPTION:exph.s. See section :hdref refid=jvmcfg. 694for acceptable options to the JSTAF service proxy library. 695For example, you can override the version of Java that you want the HTTP service 696loader service to use via the :xph.JVM=<Java Path>:exph. option when you create 697a new JVM by also using the :xph.JVMName=<JVM Name>:exph. option. 698:p. 699:xph.PARMS:exph. specifies the parameters that will be passed to the service 700loader during initialization where: 701:ul. 702:li.:xph.CONFIGFILE:exph. specifies the location of the configuration file 703used by the HTTP service loader service. This can be a fully-qualified path 704to a file on the local machine or it can be a url to the location of the 705HTTPSLS configuration file on a web server. The contents of this file must 706follow the syntax specified in section :hdref refid=HTTPSLSConfigFile. or the 707HTTP Service Loader Service registration will fail. This parameter is required. 708This option will resolve STAF variables. 709:li.:xph.DOWNLOADATTEMPTS:exph. specifies the maximum number of attempts that the 710HTTP Service Loader will make to try to download a file. The default is 3. 711This option will resolve STAF variables. 712:li.:xph.DOWNLOADRETRYDELAY:exph. specifies the number of seconds that the HTTP 713Service Loader will delay before retrying to download a file if the 714previous download attempt failed. The default is 5. This option will 715resolve STAF variables. 716:eul. 717 718:h4.Examples 719 720:xmp. 721# Add HTTP Service Loader Service on Windows using local HTTPSLS config file 722SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar \ 723 PARMS "CONFIGFILE {STAF/Config/STAFRoot}/bin/httpsls.cfg" 724 725# Add HTTP Service Loader Service on Unix using HTTPSLS config file on SourceForge website 726SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/lib/STAFHTTPSLS.jar \ 727 PARMS "CONFIGFILE http://staf.sourceforge.net/current/STAFHTTPSLS.cfg" 728 729# Add HTTP Service Loader Service on Windows using HTTPSLS config file on a web server 730SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar \ 731 OPTION JVMName=HTTPSLS OPTION JVM=C:/java1.5.0_12/bin/java \ 732 PARMS "CONFIGFILE http://server.company.com/project/httpsls.cfg \ 733 DOWNLOADATTEMPTS 3 DOWNLOADRETRYDELAY 7" 734:exmp. 735:p.Note that you can register the HTTP service loader service multiple times 736specifying unique values for the :xph.CONFIGFILE:exph. parameter. 737For example, you may have one HTTP service loader service that downloads STAF 738Java services like STAX, Event, Cron, and Email from the SourceForge website 739and you may have a second HTTP service loader service that downloads your 740custom STAF Java services from your own web server. 741 742:h4 id=HTTPSLSConfigFile.HTTPSLS Configuration File 743 744:p.The HTTP service loader service is configured through a text file 745called the HTTPSLS configuration file. This file may have any name you 746desire and can be located on a web server or on the local machine. The 747HTTPSLS configuration file is read and processed line by line. Whitespace 748at the front and end of each line is removed before processing. Blank 749lines, or lines containing only whitespace, are ignored. You may continue 750a configuration statement onto the next line by placing a "\" as the last 751character of the line. 752:p.Each service that you want the HTTP service loader service to load must 753have a :xph.SERVICE:exph. entry in the HTTPSLS configuration file. The syntax 754for each service is similar to the :xph.SERVICE:exph. syntax used when 755registering a STAF service in the STAF configuration file. 756 757:h5.Comments 758 759:p.You specify a comment by placing a pound sign, #, as the first non-blank 760character in the line. Comment lines are ignored. For example: 761:xmp. 762# This is a comment line 763:exmp. 764 765:h5.Service Registration 766 767:p.External Java services are registered with the :xph.SERVICE:exph. 768configuration statement. The syntax is: 769:xmp. 770SERVICE <Name> LIBRARY JSTAF EXECUTE <Location of Service Jar or Zip File> 771 [ZIPPATH <Path to Service Jar File>] 772 [OPTION <Name[=Value]>]... 773 [PARMS "<Service Parameters>"] 774:exmp. 775 776:xph.SERVICE:exph. specifies the name of the STAF service to be 777registered. 778:p. 779:xph.LIBRARY:exph. must always be JSTAF which is the STAF Java service 780proxy library as the HTTP Service Loader only supports loading Java 781services. 782:p. 783:xph.EXECUTE:exph. specifies the url for the Java jar file which 784implements the service. Or, it can specify the url of a zip file that 785contains the Java jar file if the :xph.ZIPPATH:exph. option is also 786specified. Or, it can specify the fully-qualified name of the Java jar 787file that resides on the local machine. This option will resolve STAF 788variables. For example: 789:xmp. 790 http://server1.company.com/staf/myservice.jar 791 http://prdownloads.sourceforge.net/staf/STAXV333.zip 792 C:/STAF/services/stax/STAX.jar 793 {STAF/Config/STAFRoot}/services/email/STAFEmail.jar 794:exmp. 795:p. 796:xph.ZIPPATH:exph. specifies the path to the service jar file in the 797zip file specified by the :xph.EXECUTE:exph. option. Note that this 798option should only be used if the :xph.EXECUTE:exph. option specifies 799a url for a zip file that can be unzipped using the STAF ZIP service. 800This option does not resolve STAF variables. For example: 801:xmp. 802 stax/STAX.jar 803 myService.jar 804:exmp. 805:p. 806:xph.OPTION:exph. specifies a configuration option that will be passed 807on to JSTAF to further control the interface to the JVM where this 808service will be run. You may specify multiple :xph.OPTION:exph.s for 809a given service. See section :hdref refid=jvmcfg. for valid 810options that can be specified for the JSTAF service proxy library. 811:p. 812:xph.PARMS:exph. specifies parameters that will be passed to the 813service during initialization. 814 815:h5.Examples 816 817:xmp. 818# Register the custom SERVICE1 service, downloading it from a web server 819SERVICE SERVICE1 LIBRARY JSTAF EXECUTE http://www.company.com/service1.jar 820 821# Register the custom SERVICE2 service, downloading it from a web server 822SERVICE SERVICE2 LIBRARY JSTAF EXECUTE http://www.company.com/service2.jar \ 823 OPTION JVMName=SERVICE2 824 825# Register the STAX V3.3.0 service, downloading it from the SourceForge website 826SERVICE STAX LIBRARY JSTAF \ 827 EXECUTE http://prdownloads.sourceforge.net/staf/STAXV333.zip \ 828 ZIPPATH stax/STAX.jar \ 829 OPTION JVMName=STAX OPTION J2=-Xmx1024m \ 830 PARMS "EXTENSIONXMLFILE C:/staf/services/extensions.xml" 831 832# Register the Cron V3.3.2 service, downloading it from the SourceForge website 833SERVICE CRON LIBRARY JSTAF \ 834 EXECUTE http://server.company.com/staf/CronV332.zip \ 835 ZIPPATH cron/STAFCron.jar OPTION JVMName=CRON 836 837# Register the Email service (which resides in a jar file on the local machine) 838SERVICE EMAIL LIBRARY JSTAF EXECUTE C:/STAF/services/email/STAFEmail.jar \ 839 PARMS "MAILSERVER NA.relay.ibm.com \ 840 BACKUPMAILSERVERS \"LA.relay.ibm.com EMEA.relay.ibm.com\"" 841:exmp. 842:p. 843A sample HTTP Service Loader Service Configuration File is available 844on SourceForge that can be used to download the latest versions of 845STAF Java services available on SourceForge such as STAX, Event, 846Cron, EventManager, etc. It is located at 847http://staf.sourceforge.net/current/STAFHTTPSLS.cfg. 848Note that you may need to customize this HTTPSLS configuration file 849for the services that you use by changing parameters for some services 850(like the :xph.MAILSERVER:exph. and :xph.BACKUPMAILSERVERS:exph. parameters 851for the Email service) and/or you may need to run some services like STAX 852in its own JVM with a larger maximum heap size for the JVM by adding some 853:xph.OPTION:exph.s. Or, you may not use use some of the services so you 854may want to remove them, or you may want to download the STAF Java service 855zip files and put them on your own web server for faster download times, etc. 856 857.* 858.*--------------------------------------------------------------------- 859.* 860:i1.Authenticator registration 861:ih1.configuration 862:i2.Authenticator registration 863:ih1.registration 864:i2.Authenticator registration 865:h2.Authenticator Registration 866:h3.Description 867:p.Authenticator services are registered with the AUTHENTICATOR configuration statement. 868The first Authenticator registered is the default, unless overridden by using the 869:xph.DEFAULTAUTHENTICATOR:exph. operational parameter. 870:h4.Syntax 871:xmp. 872AUTHENTICATOR <Name> LIBRARY <Implementation library> &lbrk.EXECUTE <Executable>&rbrk. 873 &lbrk.OPTION <Name[=Value]>&rbrk.... &lbrk.PARMS <Parameters>&rbrk. 874:exmp. 875 876:p.:xph.<Name>:exph. is the name by which this authenticator service will be 877known on this machine. The name cannot be "none" as this is reserved for use by STAF. 878If you want to authenticate across systems, you must register the authenticator on 879each system using the same name (case-insensitive). 880:p.:xph.LIBRARY:exph. is the name of the shared library / DLL which implements 881the authenticator service or acts as a proxy for the authenticator service. 882See the information for each authenticator to determine the appropriate value 883for this option. 884:p.:xph.EXECUTE:exph. is used by service proxy libraries to specify what 885the proxy library should execute. For example, this might be the name of the 886Java jar file which actually implements the authenticator service. 887This option has no significance for non-proxy service libraries. See the 888Service Registration section for information regarding the JSTAF 889service proxy library. 890:p.:xph.OPTION:exph. specifies a configuration option that will be passed on 891to the shared library / DLL. This is typically used by service proxy 892libraries to further control the interface to the actual service 893implementation. You may specify multiple :xph.OPTION:exph.s for a given 894authenticator service. See the Service Registration section for acceptable options 895for the JSTAF service proxy library. Otherwise, see the documentation 896provided with the service (proxy) library. 897:p.:xph.PARMS:exph. specifies optional parameters that will be passed to the 898authenticator service during initialization. 899 900:h4.Examples 901:xmp. 902AUTHENTICATOR MyAuth LIBRARY JSTAF EXECUTE C:/STAF/services/MyAuth.jar 903 904AUTHENTICATOR AuthSample LIBRARY JSTAF \ 905 EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \ 906 OPTION JVMName=Auth \ 907 PARMS "UserPropertiesFile {STAF/Config/STAFRoot}/services/authsample.properties" 908:exmp. 909.*--------------------------------------------------------------------- 910:ih1.registration 911:i2.Authenticator registration 912:h3 id=sampleAuth.Sample Authenticator 913:p.A sample authenticator service is provided by STAF and is available 914via the 915.*b2h html <A HREF="http://staf.sourceforge.net/getcurrent.php">Download STAF</A> website. 916It is called AuthSample and is available as a jar file called 917AuthSampleV300.jar. 918 919:h4.Registration Syntax 920:p.To try out user trust, you can register the sample authenticator as 921follows (assuming you downloaded it to a services directory created in the 922STAF root directory). 923:xmp. 924AUTHENTICATOR AuthSample LIBRARY JSTAF \ 925 EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \ 926 PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/authsample.properties" 927:exmp. 928 929:p.:xph.LIBRARY:exph. must be JSTAF for this sample authenticator 930as it is implemented in Java. 931:p.:xph.EXECUTE:exph. must be the fully-qualified name of the AuthSampleV300.jar 932file. 933:p.This sample authenticator has the following required parameter: 934:ul. 935:li.:xph.UserPropertiesFile:exph. specifies the fully-qualified name of 936a file that contains the user identifiers and passwords that this 937authenticator supports. The format of a user properties file must be 938that of a Java Properties file. A property file contains a set of strings. 939Properties in a file are declared with the syntax name=value. The 940name specifies the user identifier and the value specifies its password. 941:eul. 942:p.To perform user authentication across systems, the authenticator 943must be registered as the same name (case-insensitive) on all machines 944where you want to use user trust authentication and with the same 945user properties file (e.g. one that supports the same user identifiers 946and passwords). 947 948:h4.User Properties File 949:p.An example of a user properties file is: 950:xmp. 951# User Properties File for the Sample Authenticator 952 953User1=Password1 954User2=Password2 955User3=Password3 956User4=Password4 957User5=Password5 958:exmp. 959:p.You can specify any user identifiers and passwords that you want 960in a user properties file. 961However, if you specify any confidential information (e.g. any real 962passwords that you want to protect), you should only use the secure 963TCP interface so that this information is protected when sent over 964the network. 965.* 966.*--------------------------------------------------------------------- 967.* 968:i1.Operational parameters 969:ih1.configuration 970:i2.Operational parameters 971:h2 id=opparms.Operational parameters 972:h3.Description 973:p.STAFProc allows you to set various parameters which affect the general 974operation of STAF. The SET configuration statement lets you set 975these general operational parameters. 976:h4.Syntax 977:xmp. 978SET &lbrk.CONNECTATTEMPTS <Number>&rbrk. 979 &lbrk.CONNECTRETRYDELAY <Number>&lbrk.s|m|h|d|w&rbrk.&rbrk. 980.* &lbrk.MAXFILES <Number>&rbrk. 981 &lbrk.MAXQUEUESIZE <Number>&rbrk. 982 &lbrk.MAXRETURNFILESIZE <Number>&lbrk.k|m&rbrk.&rbrk. 983 &lbrk.HANDLEGCINTERVAL <Number>&lbrk.s|m|h|d&rbrk.&rbrk. 984 &lbrk.INITIALTHREADS <Number>&rbrk. 985 &lbrk.THREADGROWTHDELTA <Number>&rbrk. 986 &lbrk.DATADIR <Directory Name>&rbrk. 987 &lbrk.INTERFACECYCLING <Enabled | Disabled>&rbrk. 988 &lbrk.DEFAULTINTERFACE <Name>&rbrk. 989 &lbrk.DEFAULTAUTHENTICATOR <Name>&rbrk. 990 &lbrk.ENABLEDIAGS&rbrk. 991 &lbrk.STRICTFSCOPYTRUST&rbrk. 992 &lbrk.RESULTCOMPATIBILITYMODE <Mode>&rbrk. 993 &lbrk.DEFAULTSTOPUSING <Method>&rbrk. 994 &lbrk.DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE&rbrk. 995 &lbrk.DEFAULTFOCUS <Background | Foreground | Minimized>&rbrk. 996 &lbrk.PROCESSAUTHMODE <Authentication Mode>&rbrk. 997 &lbrk.DEFAULTAUTHUSERNAME&rbrk. 998 &lbrk.DEFAULTAUTHPASSWORD&rbrk. 999 &lbrk.DEFAULTAUTHDISABLEDACTION <Disabled Action>&rbrk. 1000 &lbrk.DEFAULTSHELL <Shell>&rbrk. 1001 &lbrk.DEFAULTNEWCONSOLESHELL <Shell>&rbrk. 1002 &lbrk.DEFAULTSAMECONSOLESHELL <Shell>&rbrk. 1003:exmp. 1004:p.:xph.CONNECTATTEMPTS:exph. specifies the maximum number of times to attempt 1005to connect to a remote system. The default is 2. 1006Note that a trace warning message is generated for each failed attempt if the 1007Warning trace point is enabled. 1008You may also change this setting dynamically using the MISC service's SET command. 1009:p.:xph.CONNECTRETRYDELAY:exph. specifies the maximum time in milliseconds to 1010wait after a failed connection attempt to a remote system before trying to connect 1011again (if the maximum number of times to attempt to connect to a remote system has 1012not been reached yet). The default is 1000 (i.e., 1 second). 1013You may also change this setting dynamically using the MISC service's SET command. 1014The retry delay time may be expressed in milliseconds, seconds, minutes, hours, 1015days, or weeks. Its format is :xph.<Number>[s|m|h|d|w]:exph., where :xph.<Number>:exph. 1016is an integer >= 0 and indicates milliseconds unless one of the 1017following case-insensitive suffixes is specified: s (for seconds), 1018m (for minutes), h (for hours), d (for days), or w (for weeks). 1019Examples of valid values include :xph.2s:exph. or :xph.2000:exph.. 1020.*:p.:xph.MAXFILES:exph. specifies the maximum number of files STAFProc may have 1021.*open. The default is 500. 1022.*Note that this option only has effect on OS/2 systems. 1023.*Since STAF V3 is not supported on OS/2, this option has been deprecated. 1024:p.:xph.MAXQUEUESIZE:exph. specifies the maximum size of the queue associated 1025with each process' handle. The default is 100. 1026You may also change this setting dynamically using the MISC service's SET command. 1027:p.:xph.MAXRETURNFILESIZE:exph. specifies the maximum size of a file that 1028can be returned by a START request submitted to the PROCESS service running 1029on this machine or by a GET FILE request submitted to the FS service running 1030on this machine. The default is 0 which indicates not to limit the maximum 1031size of returned files. Limiting the maximum returned file size can 1032help prevent out of memory issues as these requests put the entire returned file 1033contents in a result string which can consume a lot of memory for large files. 1034This value may be expressed in bytes, kilobytes, or megabytes. 1035Its format is :xph.<Number>[k|m]:exph. where :xph.<Number>:exph. is an integer 1036>= 0 and indicates bytes unless one of the following case-insensitive suffixes 1037is specified: :xph.k:exph. (for kilobytes) or :xph.m:exph. (for megabytes). 1038The calculated value cannot exceed :xph.4294967295:exph. bytes. 1039Examples of valid values include :xph.100000:exph., :xph.500k:exph., or 1040:xph.5m:exph.. 1041:p.Note that in addition to setting the :xph.MAXRETURNFILESIZE:exph. operational 1042parameter, you can also set the STAF/MaxReturnFileSize variable in the request 1043variable pool of the handle that submitted the request. The lowest of these two 1044values is used as the maximum return file size (not including 0 which indicates 1045no limit). Or, if you're using STAX, it also provides a :xph.MAXRETURNFILESIZE:exph. 1046parameter that can be set when registering the STAX service or dynamically via the 1047STAX service's SET MAXRETURNFILESIZE request. See the 1048.*b2h html <A HREF="http://staf.sourceforge.net/current/STAX/staxug.html">STAX User's Guide</A> 1049for more information. 1050:p.:xph.HANDLEGCINTERVAL:exph. specifies the time interval that the 1051Handle Manager's garbage collection polling loop will wait between 1052loops before polling each remote handle specified in the notification 1053list to see if the remote machine is still running the same instance 1054of STAFProc and if the handle still exists. The default is 60000 1055(i.e. 1 minute). You may also change this setting dynamically using 1056the MISC service's SET command. The time interval may be expressed in 1057milliseconds, seconds, minutes, hours, or days. Its format is 1058:xph.<Number>[s|m|h|d]:exph., where :xph.<Number>:exph. is an integer 1059>= 0 and indicates milliseconds unless one of the following 1060case-insensitive suffixes is specified: s (for seconds), m (for minutes), 1061h (for hours), or d (for days). Note that the calculated value 1062cannot be less than 5 seconds and cannot exceed 24 hours. Examples of 1063valid values include :xph.2m:exph., :xph.45s:exph., or :xph.50000:exph.. 1064:p.:xph.INITIALTHREADS:exph. specifies the number of threads initially created 1065to handle service requests. The default is 5. 1066:p.:xph.THREADGROWTHDELTA:exph. specifies the number of additional threads which 1067should be created when all existing threads are busy. The default is 1. 1068:p.:xph.DATADIR:exph. specifies the directory that STAF and its services will 1069use to write data. The default is :xph.{STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}:exph.. 1070Note that this directory name must be unique per instance of 1071STAFProc running on a single machine. Also, make sure to include the 1072"SET DATADIR" line in the STAF configuration file at the beginning of the 1073file, before any services are registered, since the data directory can be 1074used during service registration. 1075See :hdref refid=datadircfg. for more information about the 1076STAF data directory and its contents. 1077:p.:xph.INTERFACECYCLING:exph. specifies whether to enable or disable automatic 1078interface cycling. The default is to enable automatic interface cycling. 1079You may also change this setting dynamically using the MISC service's SET command. 1080Recognized values are the following: 1081:ul compact. 1082:li.:xph.ENABLED:exph. - Enables automatic interface cycling which means that 1083if you do not specify an interface in the endpoint when submitting a STAF 1084request, STAF will attempt to connect to the endpoint using all of the 1085interfaces (aka connection providers) that are configured (instead of just the 1086default interface). STAF will first try to connect via the cached interface 1087(if one exists for this endpoint). If this endpoint is not cached, STAF will 1088first attempt to connect via the default interface. If the connect attempt 1089fails, STAF will start attempting to connect using other configured interfaces 1090until one works or there are no more interfaces left to try. If a connect 1091attempt succeeds, STAF will cache the interface that worked for this endpoint 1092so that the next STAF request that specifies this endpoint will try to connect 1093first using the cached interface. 1094:p.Note that automatic interface cycling only has an effect if there are 1095multiple interfaces configured in the STAF configuration file on the 1096machine that is submitting a STAF request. 1097Also, note that the MISC service provides a LIST ENDPOINTCACHE request to 1098show the cached endpoints and a PURGE ENDPOINTCACHE request to purge one 1099or more cached endpoints. 1100:p. 1101:li.:xph.DISABLED:exph. - Disables automatic interface cycling which means that 1102if you do not specify an interface in the endpoint when submitting a STAF request, 1103STAF will only try to connect to the endpoint using the default interface. 1104:eul. 1105:p.:xph.DEFAULTINTERFACE:exph. specifies the name of the network interface 1106(aka connection provider) to use, by default. If not specified, the first 1107interface registered is the default. 1108You may also change this setting dynamically using the MISC service's SET command. 1109:p.:xph.DEFAULTAUTHENTICATOR:exph. specifies the name of the Authenticator to 1110use, by default. If not specified, the first Authenticator registered is the 1111default. If no authenticators are registered, the default authenticator is 1112:xph.none:exph.. 1113You may also change this setting dynamically using the MISC service's SET command. 1114:p.:xph.ENABLEDIAGS:exph. specifies to enable diagnostics. The default is 1115to disable diagnostics. 1116You may also enable (or disable) recording diagnostics dynamically 1117using the DIAG service. 1118:p.:xph.STRICTFSCOPYTRUST:exph. specifies to enable strict trust checking 1119when copying a file or directory using the FS service. The default is 1120to disable strict trust checking (e.g. do lenient trust checking) on a FS 1121COPY request when the machine submitting the request is the same as the 1122machine where which the file/directory is being copied. 1123That is, :xph.STRICTFSCOPYTRUST:exph. specifies that a trust check should be done to 1124verify that MachineA trusts MachineB when MachineA submits a COPY request to the 1125FS service on MachineB to copy a file or directory back to MachineA. 1126The default is to do lenient trust checking so that MachineA does not have 1127to trust MachineB since why would MachineA ask MachineB to copy the file/directory 1128if he didn't want the copy to work. 1129You may also change this setting dynamically using the FS service's SET command. 1130:p.:xph.RESULTCOMPATIBILITYMODE:exph. specifies the compatibility mode used 1131when sending the result from a STAF service request back to a pre-STAF V3 system. 1132Recognized values are the following: 1133:ul compact. 1134:li.:xph.VERBOSE:exph. - 1135When structured data (see :hdref refid=marshall.) is returned in 1136the result buffer string, this option indicates to automatically unmarshall 1137the data and provide it in a "verbose format" which is easy to read. 1138This "verbose format" is equivalent to the output provided when using the 1139STAF executable's -verbose option (see :hdref refid=stafexecmd.). 1140This is the default mode. 1141:li.:xph.NONE:exph. - This indicates that no changes to the result buffer string will 1142be made. Note that marshalled data is not as easy to read. 1143:eul. 1144You may also change this setting dynamically using the MISC service's SET command. 1145:p.:xph.DEFAULTSTOPUSING:exph. allows you to specify the default method used 1146to STOP processes. See :hdref refid=psstop. for more information on available 1147methods. 1148You may also change this setting dynamically using the PROCESS service's SET command. 1149:p.:xph.DEFAULTNEWCONSOLE:exph. specifies that processes should be STARTed in a 1150new console window. So, if a process's stdout/stderr is not redirected, it will be 1151unavailable. This is the default for Windows systems. 1152.*and OS/2. 1153You may also change this setting dynamically using the PROCESS service's SET command. 1154:p.:xph.DEFAULTSAMECONSOLE:exph. specifies that processes should be STARTed in 1155the same console as STAFProc. So, if a process's stdout/stderr is not redirected, 1156it will be written to STAFProc's stdout/stderr. This is the default on Unix systems. 1157.*This option has no effect on OS/2. 1158You may also change this setting dynamically using the PROCESS service's SET command. 1159:p.:xph.DEFAULTFOCUS:exph. specifies the focus that is to be given to new windows 1160opened when starting a process on a Windows system. The default focus mode is Background. 1161This option only has effect on Windows systems. &varres. 1162See :hdref refid=procstr. for more information on the :xph.FOCUS:exph. option. 1163You may also change this setting dynamically using the PROCESS service's SET command. 1164:p.:xph.PROCESSAUTHMODE:exph. specifies the mode by which usernames/passwords 1165are authenticated when starting processes. The value of this option is platform 1166specific. Recognized values are the following: 1167:ul compact. 1168:li.:xph.DISABLED:exph. - This indicates that the user may not specify a username/password 1169with which to authenticate when starting a process. This mode is available on 1170all platforms. This is default mode. 1171:li.:xph.WINDOWS:exph. - This indicates that windows-based authentication should be used. 1172This mode is only available on Windows systems. 1173See :hdref refid=winuser. for more information. 1174:li.:xph.NONE:exph. - This indicates that usernames will be honored but not authenticated. 1175In this mode, passwords are ignored and processes are started under the indicated 1176username. This mode is only available on Unix systems. 1177.*:li.PASSWD - This indicates that usernames/passwords will be authenticated using 1178.*entries stored in the /etc/passwd file. This mode is only available on Unix systems. 1179.*:li.SHADOW - This indicates that usernames/passwords will be authenticated using 1180.*entries stored in the /etc/shadow file. This mode is only available on Unix 1181.*systems. 1182:eul. 1183:note.Previously, :xph.PASSWD:exph. and :xph.SHADOW:exph. were supported values 1184for the :xph.PROCESSAUTHMODE:exph. on Unix systems, but support for for these 1185modes has been removed. 1186:p. 1187You may also change this setting dynamically using the PROCESS service's SET command. 1188:p.:xph.DEFAULTAUTHUSERNAME:exph. specifies the username under which processes 1189will be started, by default. Note, this option IS valid even if process 1190authentication has been disabled. 1191You may also change this setting dynamically using the PROCESS service's SET command. 1192:p.:xph.DEFAULTAUTHPASSWORD:exph. specifies the password with which processes 1193will be authenticated, by default. Note, this option IS valid even if process 1194authentication has been disabled. 1195You may also change this setting dynamically using the PROCESS service's SET command. 1196:p.:xph.DEFAULTAUTHDISABLEDACTION:exph. specifies what default action should be 1197taken if the user specifies a username/password on a request to start a process 1198when process authentication has been disabled. The following values are 1199recognized: 1200:ul compact. 1201:li.:xph.IGNORE:exph. - This indicates that the username/password should be ignored. The 1202request will be processed as if the user had not specified these parameters. 1203This is the default. 1204:li.:xph.ERROR:exph. - This indicates that an error should be passed back to the user. 1205:eul. 1206You may also change this setting dynamically using the PROCESS service's SET command. 1207:p.:xph.DEFAULTSHELL:exph. specifies the default shell to use when starting a 1208process via a separate shell. The default shell used for Unix systems is /bin/sh. 1209The default shell used for Windows systems is "cmd.exe /c". 1210You may also change this setting dynamically using the PROCESS service's SET command. 1211:p.:xph.DEFAULTNEWCONSOLESHELL:exph. specifies the default shell to use when 1212starting a process in a new console window (e.g. :xph.NEWCONSOLE:exph.) via a separate shell, overriding 1213the :xph.DEFAULTSHELL:exph. value if specified. 1214You may also change this setting dynamically using the PROCESS service's SET command. 1215:p.:xph.DEFAULTSAMECONSOLESHELL:exph. specifies the default shell to use when 1216starting a process in the same console as STAFProc (e.g. :xph.SAMECONSOLE:exph.) via a separate shell, 1217overriding the :xph.DEFAULTSHELL:exph. value if specified. 1218You may also change this setting dynamically using the PROCESS service's SET command. 1219:p. 1220A shell value can contain substitution characters described in the following table. 1221:table cols='* 4* *' align='c l c'. 1222:tcap.Substitution Characters for Shells 1223:thd. 1224:c.Substitution character 1225:c.Description 1226:c.Supported systems 1227:ethd. 1228:row. 1229:c.%c 1230:c.Substitute the values specified by the :xph.COMMAND:exph. and 1231:xph.PARMS:exph. options. 1232:c.Windows and Unix 1233:row. 1234:c.%C 1235:c.Same as %c, except the substituted value will be quoted (with all 1236nested quotes properly escaped). 1237:c.Windows and Unix 1238:row. 1239:c.%p 1240:c.Substitute the value specified by the :xph.PASSWORD:exph. option, 1241or an empty string if no :xph.PASSWORD:exph. is provided. 1242:c.Windows and Unix 1243:row. 1244:c.%P 1245:c.Same as %p, except the substituted value will be quoted (with all 1246nested quotes properly escaped). 1247:c.Windows and Unix 1248:row. 1249:c.%t 1250:c.Substitute the value specified by the :xph.TITLE:exph. option, 1251or <Unknown> if no :xph.TITLE:exph. is provided. 1252:c.Windows and Unix 1253:row. 1254:c.%T 1255:c.Same as %t, except the substituted value will be quoted (with all 1256nested quotes properly escaped). 1257:c.Windows and Unix 1258:row. 1259:c.%u 1260:c.Substitute the value specified by the :xph.USERNAME:exph. option, 1261or an empty string if no :xph.USERNAME:exph. is provided. 1262:c.Windows and Unix 1263:row. 1264:c.%U 1265:c.Same as %u, except the substituted value will be quoted (with all 1266nested quotes properly escaped). 1267:c.Windows and Unix 1268:row. 1269:c.%w 1270:c.Substitute the value specified by the :xph.WORKLOAD:exph. option, 1271or <Unknown> if no :xph.WORKLOAD:exph. is provided. 1272:c.Windows and Unix 1273:row. 1274:c.%W 1275:c.Same as %w, except the substituted value will be quoted (with all 1276nested quotes properly escaped). 1277:c.Windows and Unix 1278:row. 1279:c.%x 1280:c.Substitute the values specified by the :xph.COMMAND:exph. and 1281:xph.PARMS:exph. options followed by input/output redirection, if 1282I/O options are specified on the :xph.PROCESS START:exph. request 1283(e.g. :xph.STDIN, STDOUT:exph.). When using this option, do not 1284specify any redirection in the :xph.COMMAND/PARMS:exph. values. 1285:c.Windows and Unix 1286:row. 1287:c.%X 1288:c.Same as %x, except the substituted value will be quoted (with all 1289nested quotes properly escaped). 1290:c.Windows and Unix 1291:row. 1292:c.%% 1293:c.Substitute a %. 1294:c.Windows and Unix 1295:etable. 1296 1297:notel compact. 1298:li.When specifying a shell value, it must contain one of the following: %c, %C, %x, %X. 1299:li.The use of %c versus %C, as well as %x versus %X, is highly dependent 1300on the shell you specify. 1301If the shell expects the command and parameters to be parsed as a single string, 1302then use %C or %X. If the shell expects the command and parameters to be parsed as separate 1303strings, then use %c or %x. 1304:li.Specifying 'su - %u -c %C' as the shell when starting a process on a UNIX system 1305(so that it simulates the environment of the user specified by the :xph.USERNAME:exph. option) 1306will cause variables specified via an ENV option to not be set for the process. 1307:enotel. 1308 1309:h4.Examples 1310:xmp. 1311SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2s 1312.*SET MAXFILES 1000 1313SET MAXQUEUESIZE 1000 1314SET MAXRETURNFILESIZE 25m 1315SET HANDLEGCINTERVAL 50s 1316SET INITIALTHREADS 10 THREADGROWTHDELTA 3 1317SET DATADIR /test/stafdata 1318SET DEFAULTINTERFACE tcp 1319SET DEFAULTAUTHENTICATOR SampleAuth 1320SET ENABLEDIAGS 1321SET RESULTCOMPATIBILITYMODE none 1322SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE 1323SET DEFAULTFOCUS minimized 1324SET PROCESSAUTHMODE windows DEFAULTAUTHUSERNAME testuser DEFAULTAUTHPASSWORD tupass 1325SET PROCESSAUTHMODE none DEFAULTAUTHUSERNAME guest DEFAULTAUTHDISABLEDACTION error 1326SET DEFAULTSHELL "C:/cygwin/bin/bash.exe -c %C" 1327SET DEFAULTSAMECONSOLESHELL "/bin/csh -c %C" 1328SET DEFAULTNEWCONSOLESHELL "xterm -title %T -e /bin/sh -c %X" 1329SET DEFAULTSHELL "su - %u -c %C" 1330:exmp. 1331.* 1332.*--------------------------------------------------------------------- 1333.* 1334:ih1.configuration 1335:i2.variables 1336:ih1.variables 1337:i2.configuration 1338:h2 id=varcfg.Variables 1339:h3.Description 1340:p.You may set STAF variables in the system or shared variable pool at startup by 1341using the SET VAR configuration statement. SET VAR will set a variable to a certain 1342value. The variable is created if it does not exist. 1343:p.Note that you may SET multiple variables with a single request. 1344:h4.Syntax 1345:xmp. 1346SET &lbrk.SYSTEM | SHARED&rbrk. VAR <Name=Value> &lbrk.VAR <Name=Value>&rbrk. ... 1347:exmp. 1348:p.:xph.SYSTEM:exph. means the variable is to be set in system variable pool. 1349This is the default. 1350:p.:xph.SHARED:exph. means the variable is to be set in shared variable pool. 1351:p.:xph.VAR:exph. means the variable to be set. Name is the name of the variable 1352and Value is the value of the variable. 1353:h4.Examples 1354:xmp. 1355SET VAR WebServer=testsrv1.test.austin.ibm.com 1356SET SHARED VAR "Author1=Jane Tester" VAR "Author2=John Tester" 1357SET SYSTEM VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log 1358:exmp. 1359.* 1360.*--------------------------------------------------------------------- 1361.* 1362:ih1.configuration 1363:i2.trust 1364:ih1.trust 1365:i2.configuration 1366:h2 id=trustcfg.Trust 1367:h3.Description 1368:p.You may grant access to machines or users by using the TRUST configuration 1369statement. 1370:p.Trust configuration statements for machines are based on the network 1371identification of the system. In particular, different trust levels can be 1372given to the same system coming in through different networking interfaces. 1373Both logical and physical identifiers may be used in trust configuration 1374statements for machines. 1375:p.Trust configuration statements for users require that you have 1376an authenticator registered. 1377:h4.Syntax 1378:xmp. 1379TRUST LEVEL <Level> < DEFAULT | MACHINE <Machine> &lbrk.MACHINE <Machine>&rbrk.... | 1380 USER <User> &lbrk.USER <User>&rbrk.... > 1381:exmp. 1382:p.:xph.LEVEL:exph. is the level of trust that you wish to grant, 1383see :hdref refid=trstcon. for a list of trust levels. 1384&varres. 1385:p.:xph.DEFAULT:exph. indicates that you wish to set the default trust level. 1386This is the trust level that will be used for machines which have no 1387explicit trust level set. If no default has been specified in the STAF 1388Configuration file, the default is set to 3. 1389:p.:xph.MACHINE:exph. indicates a specific machine for which to set a trust 1390level. 1391&varres. 1392The format for <Machine> is: 1393:xmp. 1394 &lbrk.<Interface>&colon.//&rbrk.<System Identifier> 1395:exmp. 1396where: 1397:ul compact. 1398:li.:xph.<Interface>:exph. is the name of the network interface. 1399It is case-insensitive. 1400If the name of a network interface is not specified, wildcard '*' is 1401substituted which will match any network interface name. 1402:li.:xph.<System Identifier>:exph. is a valid network identifier for the network 1403interface. It is case-insensitive. 1404Logical or physical identifiers may be specified for the system 1405identifier. Physical identifiers are the lowest-level identifier 1406available via the specified network interface. Logical identifiers are more 1407human readable identifiers that ultimately map to physical identifiers. 1408For example, for a TCP/IP interface, the physical identifier for a 1409machine is the IP address, while the logical identifier for a machine 1410is the hostname. 1411:eul. 1412:p.Note that you can specify match patterns (e.g. wild cards) in the 1413interface and the system identifier. These patterns recognize two 1414special characters, '*' and '?', where '*' matches a string of 1415characters (including an empty string) and '?' matches any single 1416character (the empty string does not match). 1417:p.Note that if you specify the hostname in a trust specification 1418for a TCP/IP interface, you must specify the long host name 1419(and/or wildcards). 1420:p.Note that if you specify a port (e.g. @6500) at the end of the 1421system identifier, it will be removed. 1422:p.Requests coming from the local system will now appear as though 1423they came from an interface named "local" and a system identifier 1424of "local". This allows you to specify a trust level for local 1425requests. (In STAF V2.x, local requests were automatically granted 1426a trust level of 5.) 1427:p.:xph.USER:exph. indicates a user for which to set a trust level. 1428&varres. 1429The format for <User> is: 1430:xmp. 1431 &lbrk.<Authenticator>&colon.//&rbrk.<User Identifier> 1432:exmp. 1433where: 1434:ul compact. 1435:li.<Authenticator> is the name of the authenticator. 1436It is case-insensitive. If an authenticator is not specified, the default 1437authenticator is used. 1438:li.<User Identifier> is a valid user identifier for the authenticator. 1439It is case sensitive. 1440:eul. 1441:p.Note that you can specify match patterns in the authenticator name 1442and the user identifier. These patterns recognize two special characters, 1443'*' and '?', where '*' matches a string of characters (including an 1444empty string) and '?' matches any single character (the empty string 1445does not match). 1446 1447:h4 id=userTrustMatching.How to determine Effective Trust for a User 1448:p.If multiple trust specifications would match the same user, 1449STAF will rank the matching specifications as follows and use the 1450match with the highest (i.e. lowest numbered) rank: 1451:ol compact. 1452:li.Exact match of authenticator and user identifier 1453:li.Exact match of authenticator, wildcard match of user identifier 1454:li.Wildcard authenticator match, exact match of user identifier 1455:li.Wildcard authenticator match, wildcard match of user identifier 1456:eol. 1457If multiple trust specifications match within the same rank, the 1458lowest matching trust level will be used. 1459 1460:h4 id=machineTrustMatching.How to determine Effective Trust for a Machine 1461 1462:p.If multiple trust specifications would match the same system, 1463STAF will rank the matching specifications as follows and use the 1464match with the highest (i.e. lowest numbered) rank: 1465:ol compact. 1466:li.Exact match of interface and physical network identifier 1467:li.Exact match of interface and logical network identifier 1468:li.Exact match of interface, wildcard match of physical network identifier 1469:li.Exact match of interface, wildcard match of logical network identifier 1470:li.Wildcard interface match, exact match of physical network identifier 1471:li.Wildcard interface match, exact match of logical network identifier 1472:li.Wildcard interface match, wildcard match of physical network identifier 1473:li.Wildcard interface match, wildcard match of logical network identifier 1474:eol. 1475If multiple trust specifications match within the same rank, the 1476lowest matching trust level will be used. 1477 1478:note.The user authentication overrides the machine authentication. 1479For example, if the machine trust level is 3 and the authenticated user 1480has a trust level of 4, then the handle will have a trust level of 4. 1481If the user has been authenticated, but there are no user authentication 1482trust matches, the machine trust level is used. If there is no 1483machine trust level specified, then the default trust level is used. 1484 1485:ih1.examples 1486:i2.trust 1487:h4.Examples 1488:xmp. 1489TRUST DEFAULT LEVEL 3 1490TRUST LEVEL 5 MACHINE local&colon.//local 1491TRUST LEVEL 5 MACHINE client1.austin.ibm.com MACHINE client3.raleigh.ibm.com 1492TRUST LEVEL 5 MACHINE 9.3.224.16 1493TRUST LEVEL 4 MACHINE tcp&colon.//mysystem.site.com 1494TRUST LEVEL 0 MACHINE badguy.austin.ibm.com 1495TRUST LEVEL 3 MACHINE tcp2&colon.//9.3.224.* 1496TRUST LEVEL 2 MACHINE *.austin.ibm.com 1497TRUST LEVEL 2 MACHINE tcp*&colon.//*.site.com 1498TRUST LEVEL 5 USER John@company.com USER Jane@company.com 1499TRUST LEVEL 0 USER badguy@company.com 1500TRUST LEVEL 3 USER *@company.com 1501TRUST LEVEL 4 USER SampleAuth&colon.//*@company.com 1502TRUST LEVEL 1 USER *&colon.//* 1503:exmp. 1504.* 1505.*--------------------------------------------------------------------- 1506.* 1507:ih1.configuration 1508:i2.start/shutdown notifications 1509:ih1.start/shutdown notifications 1510:i2.configuration 1511:h2 id=notifycfg.Start/Shutdown Notifications 1512:h3.Description 1513:p.You may specify that you want notifications sent to certain 1514machines/processes when STAF is either started or shutdown. You do this by 1515using the NOTIFY configuration statement. Notifications are handled by the 1516STAF Queue service, see :hdref refid=queuesrv. for more information. 1517 1518:note.You may also dynamically register for SHUTDOWN notifications via the 1519SHUTDOWN service, see :hdref refid=shutds.. 1520:note text=Warning.In order for the receiving machine to accept the 1521notifications, it must specify a default or explicit trust level of at least 15223 for this machine. As of version 2.2.0 of STAF, the default trust level 1523is 3, so no explicit action is necessary on systems running this version of 1524STAF (or higher).:enote. 1525:h4.Syntax 1526:xmp. 1527NOTIFY <ONSTART | ONSHUTDOWN> MACHINE <Machine> &lbrk.PRIORITY <Priority>&rbrk. 1528 <NAME <Name> | HANDLE <Handle>> 1529:exmp. 1530:p.:xph.ONSTART:exph. indicates that a notification should be sent when 1531STAF is fully initialized. The type of the message will be the string :xph.STAF/Start:exph. 1532with a blank message. 1533:p.:xph.ONSHUTDOWN:exph. indicates that a notification should be sent when 1534STAF is shutdown. The type of the message will be the string :xph.STAF/Shutdown:exph. 1535with a blank message. 1536:p.:xph.MACHINE:exph. indicates the machine to receive the message. 1537:p.:xph.PRIORITY:exph. indicates the priority of the message. The default is 15385. 1539:p.:xph.NAME:exph. specifies that all processes with the given registered 1540name on the given machine should be notified. This option is usually 1541preferred over :xph.HANDLE:exph., as it is difficult to know the desired 1542handle in advance. 1543:p.:xph.HANDLE:exph. specifies that the process with the given handle on the 1544given machine should be notified. 1545:h4.Examples 1546:xmp. 1547NOTIFY ONSTART MACHINE Server1 PRIORITY 3 NAME EventManager 1548NOTIFY ONSHUTDOWN MACHINE Server1 NAME EventManager 1549:exmp. 1550.* 1551.*--------------------------------------------------------------------- 1552.* 1553:ih1.configuration 1554:i2.tracing 1555:ih1.tracing 1556:i2.configuration 1557:h2 id=tracecfg.Tracing 1558:h3.Description 1559:p.STAF provides various tracing facilities to help in auditing and debugging. 1560STAF externalizes these facilities through trace points. Enabling a particular 1561trace point causes trace messages to be generated whenever a particular event 1562occurs, such as a service request resulting in an "Insufficient Trust Level" 1563(aka "Access Denied") error code. 1564Care should be taken when enabling trace points, as certain trace points, 1565such as ServiceResult, can lead to large quantities of trace messages being 1566generated. In these cases, it is best to limit tracing to only specific 1567services. 1568:p.You may enable or disable STAF trace points and STAF services for tracing 1569using the :xph.TRACE:exph. configuration statement. In addition, you can set the 1570trace output destination and set the default tracing state for newly 1571registered services. By default, all STAF services are enabled for tracing. 1572Also, if you are using the default STAF configuration file provided, 1573only the :xph.ERROR:exph. and :xph.DEPRECATED:exph. trace points are enabled 1574by default. 1575:note.The :xph. TRACE ENABLE/DISABLE SERVICE(S) :exph.statements affect the current 1576list of services. So, if you add line :xph. TRACE DISABLE ALL SERVICES :exph. 1577to the configuration file and then register any external services later in the 1578configuration file, those services will not necessarily be disabled. 1579To ensure that all registered services are disabled, either set the default 1580service state to disabled, or add the :xph.TRACE:exph. statements after the 1581:xph.SERVICE:exph. configuration statements in the configuration file. 1582 1583:h4.Syntax 1584:xmp. 1585TRACE ENABLE ALL [ TRACEPOINTS | SERVICES ] 1586TRACE ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> 1587TRACE ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... 1588TRACE ENABLE SERVICE <Service> [SERVICE <Service>]... 1589 1590TRACE DISABLE ALL [ TRACEPOINTS | SERVICES ] 1591TRACE DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> 1592TRACE DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... 1593TRACE DISABLE SERVICE <Service> [SERVICE <Service>]... 1594 1595TRACE SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] > 1596TRACE SET DEFAULTSERVICESTATE <Enabled | Disabled> 1597TRACE SET MAXSERVICERESULTSIZE <Number>[k|m] 1598:exmp. 1599:p.See the TRACE service, section :hdref refid=tracesrv., 1600for information on the above options. 1601:p.See table :hdref refid=tracepointref. for a list of valid trace points. 1602 1603:h4.Examples 1604:xmp. 1605TRACE SET DESTINATION TO STDERR 1606TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc 1607TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc APPEND 1608TRACE SET DESTINATION TO STDOUT FILE {STAF/Config/STAFRoot}/bin/STAF.trc 1609TRACE SET DESTINATION TO STDERR FILE {STAF/Config/STAFRoot}/bin/STAF.trc 1610TRACE ENABLE ALL 1611TRACE DISABLE SERVICE "Sem" 1612TRACE ENABLE TRACEPOINTS "Error ServiceAccessDenied" 1613TRACE DISABLE SERVICES "Process Queue Var" 1614TRACE SET DEFAULTSERVICESTATE Enabled 1615TRACE SET MAXSERVICERESULTSIZE 10k 1616:exmp. 1617:p. In order to ensure that you are only tracing service results on 1618the var and sem services, and that tracing for all other services is 1619disabled (including services registered in the future) do this &colon. 1620:xmp. 1621TRACE SET DEFAULTSERVICESTATE Disabled 1622TRACE DISABLE ALL SERVICES 1623TRACE DISABLE ALL TRACEPOINTS 1624TRACE ENABLE TRACEPOINTS "ServiceResult" 1625TRACE ENABLE SERVICES "VAR SEM" 1626:exmp. 1627 1628.* 1629.*--------------------------------------------------------------------- 1630.* 1631:ih1.configuration 1632:i2.example 1633:ih1.examples 1634:i2.configuration file 1635 1636:h2 id=examplescfg.Configuration File Examples 1637 1638:h3 id=defaultcfg.Default Configuration File 1639:p.This is the default configuration file provided with STAF. 1640:xmp keep=14. 1641# Turn on tracing of internal errors and deprecated options 1642trace enable tracepoints "error deprecated" 1643 1644# Enable TCP/IP connections 1645interface ssl library STAFTCP option Secure=Yes option Port=6550 1646interface tcp library STAFTCP option Secure=No option Port=6500 1647 1648# Set default local trust 1649trust machine local://local level 5 1650 1651# Add default service loader 1652serviceloader library STAFDSLS 1653:exmp. 1654 1655:h3 id=examplecfg.Configuration File Example 1656:note text='Warning'.This configuration file contains references to fictional services, 1657machines, etc. and is provided for informational purposes only. Please do 1658not try to use this as your actual STAF.cfg file. It is unlikely to 1659work.:enote. 1660:xmp keep=7. 1661# --------------------------------------------------------------------- 1662# STAF Configuration File 1663# --------------------------------------------------------------------- 1664# Set the writeable location where STAF can write data 1665SET DATADIR E:\test\stafdata 1666 1667# Enable TCP/IP connections 1668interface ssl library STAFTCP option Secure=Yes option Port=6550 1669interface tcp library STAFTCP option Secure=No option Port=6500 option ConnectTimeout=10000 1670 1671# Set default local trust 1672trust machine local&colon.//local level 5 1673 1674# Add default service loader 1675serviceloader library STAFDSLS 1676 1677# --------------------------------------------------------------------- 1678# STAF Log Mask Variable 1679# --------------------------------------------------------------------- 1680SET SHARED VAR STAF/Service/Log/Mask="START STOP WARNING FATAL ERROR" 1681 1682# --------------------------------------------------------------------- 1683# Setup Trust Levels 1684# --------------------------------------------------------------------- 1685TRUST DEFAULT LEVEL 2 1686TRUST LEVEL 3 MACHINE test1.austin.ibm.com MACHINE test2.test.austin.ibm.com 1687TRUST LEVEL 5 MACHINE automate.austin.ibm.com 1688TRUST LEVEL 4 MACHINE *.test.austin.ibm.com 1689TRUST LEVEL 3 USER IBM&colon.//*@us.ibm.com 1690TRUST LEVEL 4 USER JohnDoe@company.com 1691TRUST LEVEL 0 USER BadGuy@company.com 1692 1693# --------------------------------------------------------------------- 1694# Delegated Services 1695# --------------------------------------------------------------------- 1696SERVICE pager DELEGATE globpager.test.austin.ibm.com 1697 1698# --------------------------------------------------------------------- 1699# Java Services 1700# --------------------------------------------------------------------- 1701 1702# Operating system independent name for my STAF services directory 1703SET SYSTEM VAR myServiceDir={STAF/Config/STAFRoot}{STAF/Config/Sep/File}services 1704 1705SERVICE STAX LIBRARY JSTAF \ 1706 EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAX.jar \ 1707 OPTION J2=-Xms64m OPTION J2=-Xmx128m 1708SERVICE Event LIBRARY JSTAF \ 1709 EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAFEvent.jar 1710 1711# --------------------------------------------------------------------- 1712# C++ Services 1713# --------------------------------------------------------------------- 1714SERVICE log LIBRARY STAFLog 1715SERVICE monitor LIBRARY STAFMon 1716SERVICE respool LIBRARY STAFPool 1717 1718# --------------------------------------------------------------------- 1719# Notifications 1720# --------------------------------------------------------------------- 1721NOTIFY ONSTART MACHINE automate.austin.ibm.com PRIORITY 3 NAME EventManager 1722NOTIFY ONSHUTDOWN MACHINE automate.austin.ibm.com NAME EventManager 1723 1724# --------------------------------------------------------------------- 1725# Activate tracing 1726# --------------------------------------------------------------------- 1727TRACE SET DESTINATION TO FILE {STAF/DataDir}/user/STAF.trc 1728TRACE ENABLE TRACEPOINTS "ServiceAccessDenied Error" 1729TRACE ENABLE SERVICES "Process Trust" 1730:exmp. 1731.* 1732.*--------------------------------------------------------------------- 1733.* 1734:ih1.configuration 1735:i2.tuning 1736:ih1.tuning 1737:i2.configuration 1738:h2 id=tunecfg.Tuning 1739:h3.Description 1740:p.STAF provides a way to tune its thread stack size. This is done via setting 1741a "STAF_THREAD_STACK_SIZE" environment variable before STAFProc gets started. User 1742can use this environment variable to set STAF's thread stack size in kilobytes. 1743:h4.Examples, to set the thread stack size to 128KB 1744:xmp. 1745On Unix: export STAF_THREAD_STACK_SIZE=128 1746On Windows: set STAF_THREAD_STACK_SIZE=128 1747:exmp. 1748.* 1749.*--------------------------------------------------------------------- 1750.* 1751:ih1.configuration 1752:i2.data directory structure 1753:ih1.data directory structure 1754:i2.configuration 1755:h2 id=datadircfg.Data Directory Structure 1756:p. 1757By default, STAF and its services will write data to: 1758:xph.{STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}:exph.. 1759For example: :xph.C:\STAF\data\STAF:exph. on Windows systems or :xph./usr/local/staf/data/STAF:exph. 1760on Unix systems or :xph./Library/staf/data/STAF:exph. on Mac OS X systems. 1761The :xph.STAF/DataDir:exph. system variable is set to the fully-qualified name 1762of this directory. 1763:p. 1764You may use the DATADIR operational parameter to change the writeable data directory for STAF. 1765This directory name must be unique per instance of STAF running on a single machine. 1766:p. 1767Note that the ability to change the data directory allows you to install STAF to a shared location 1768(e.g. a read-only directory that is accessible via a mounted drive, etc.) and use a unique 1769writeable data directory per instance of STAF. 1770:p. 1771The following table describes the structure of the STAF data directory: 1772:table cols='* 4*' align='l l'. 1773:tcap.Data Directory Structure 1774:thd. 1775:c.Directory Name 1776:c.Description 1777:ethd. 1778:row. 1779:c.:xph.{STAF/DataDir}/tmp:exph. 1780:c.This is the location where temporary data can be stored. 1781This directory and all of its contents will be removed and an empty :xph.tmp:exph. 1782directory is created whenever STAFProc is restarted. 1783:row. 1784:c.:xph.{STAF/DataDir}/user:exph. 1785:c.Other user data (e.g. from testcases, applications, etc.) can be stored in this 1786directory. You should create subdirectories within this directory to when storing your 1787data. 1788:row. 1789:c.:xph.{STAF/DataDir}/service:exph. 1790:c.This directory exists if one or more external services are (or have been) registered. 1791If a service stores persistent data, it should create a subdirectory within this 1792directory using its registered service name (in lower-case) and store its data in this 1793subdirectory. For example: 1794:xmp. 1795{STAF/DataDir}/service/event 1796{STAF/DataDir}/service/log 1797{STAF/DataDir}/service/stax 1798:exmp. 1799:row. 1800:c.:xph.{STAF/DataDir}/lang/java/jvm:exph. 1801:c.This directory exists if one or more external Java services are (or have been) registered. 1802For each JVM created for Java services, STAF will create a subdirectory within this 1803directory using the name of the JVM. The log files for the JVM (e.g. :xph.JVMLog.1:exph.) 1804will be stored in this subdirectory. For example: 1805:xmp. 1806{STAF/DataDir}/lang/java/STAFJVM1/JVMLog.1 1807{STAF/DataDir}/lang/java/STAX/JVMLog.1 1808:exmp. 1809:row. 1810:c.:xph.{STAF/DataDir}/lang/java/service:exph. 1811:c.This directory exists if one or more external Java services are (or have been) registered. 1812For each Java service registered, STAF will create a subdirectory within this 1813directory using the registered service name and a subdirectory with it named :xph.jars:exph.. 1814This subdirectory will contain nested jar files for the service, if any are provided 1815by the service. For example: 1816:xmp. 1817{STAF/DataDir}/lang/java/service/Event/jars 1818{STAF/DataDir}/lang/java/service/STAX/jars 1819:exmp. 1820:row. 1821:c.:xph.{STAF/DataDir}/register:exph. 1822:c.For STAF's use only. This directory is used for storing registration data, if any, 1823specified when this version of STAF was installed. 1824:etable. 1825:p. 1826:ih1.configuration 1827:i2.Unix temporary diretory 1828:ih1.Unix STAF Temporary Directory 1829:i2.configuration 1830:h3 id=tempdir.Unix STAF Temporary Directory 1831:p. 1832On Unix systems, STAF also writes a few files to the /tmp directory by default 1833for each instance of STAFProc that is running. 1834You can override the location of the directory by setting the STAF_TEMP_DIR 1835environment variable. However, you must use the same STAF_TEMP_DIR environment 1836variable for all instances of STAFProc in order for STAF to make sure that each 1837STAFProc instance has a unique STAF_INSTANCE_NAME and a unique {STAF/DataDir}. 1838Note that you should not specify {STAF/DataDir}/tmp for the value of the 1839STAF_TEMP_DIR environment variable because each time STAFProc starts, it 1840deletes the {STAF/DataDir}/tmp directory and this occurs after STAF creates 1841some of these files. 1842:p. 1843The following files are created in the Unix STAF Temporary Directory when 1844starting STAFProc (and are deleted when STAFProc is shutdown). 1845:p. 1846:ul. 1847:li.:xph.<STAF_INSTANCE_NAME>.tmp:exph. 1848:note.:xph.<STAF_INSTANCE_NAME>:exph. will be replaced with the actual 1849STAF Instance Name which defaults to "STAF" unless it is overridden by setting 1850the STAF_INSTANCE_NAME environment variable. 1851:li.:xph.DataDir_<DATADIR>.tmp:exph. 1852:note.:xph.<DATADIR>:exph. will be replaced with the resolved value of the 1853{STAF/DataDir}variable, with the slashes replaced with dashes. 1854For example: :xph.DataDir_-usr-local-staf-data-STAF.tmp:exph. 1855:li.:xph.STAFIPC_<STAF_INSTANCE_NAME>:exph. 1856:p. 1857This is a socket file used by the Unix Local IPC connection provider. 1858If this socket file is inadvertently deleted, local service requests will fail 1859with RC 21 (STAF Not Running). 1860:li.:xph.STAFIPC_<STAF_INSTANCE_NAME>JSTAF_<JVMName>:exph. 1861:p. 1862This is a socket file used by a STAF JVM that was created when registering a 1863STAF Java service. There will be one socket file for each STAF JVM. 1864:note.:xph.<JVMName>:exph. will be replaced by the actual STAF JVM name. 1865:eul. 1866:p. 1867:warning.Do not delete these files while the STAFProc instance 1868is running.:ewarning. 1869:p. 1870When submitting a request to the "local" interface to communicate with 1871a STAFProc instance, the STAF_INSTANCE_NAME environment variable must be 1872set (if the STAFProc instance is not using the default name "STAF"). Also, 1873on Unix only, the STAF_TEMP_DIR environment variable must be set 1874(if the STAFProc instance is not using the default "/tmp" directory). 1875Otherwise, the local service request will not be able to communicate with 1876that STAFProc instance and RC 21 (STAF Not Running) will be returned. 1877 1878 1879