Configuration file keyword descriptions
The configuration data might contain line comments. Line comments begin with either an asterisk (*) or a hash/pound (#) character, and continue to the end of the line. When configuration involves data set names that include hash/pound (#), such characters must be escaped using a backslash (\) so that they are not interpreted as comments.
- CONFIG=name
- name is the name of the configuration as specified by the client. At least one configuration is expected with a name of DEFAULT. Other configuration keywords apply to the current CONFIG name, in top-down order.
- APPLID=applid (Optional)
- The ADFzCC server uses C runtime services to
switch user context when spawning processes for requesting clients that provide a valid
user ID and password. These services are associated with the OMVSAPPL resource (or the IPVAPPL resource if PASSTK is specified) of the APPL class by
default, if the APPL class is active. If this is the case, the authenticating user ID must
have READ access to the OMVSAPPL or IPVAPPL resource of the APPL class.
Alternatively, your configuration file can specify APPLID=applid, where applid is a 1- to 8-character resource name defined to the APPL class. When APPLID is configured, the ADFzCC server will use the specified APPL class applid rather than OMVSAPPL or IPVAPPL.
The APPLID parameter must be specified under the CONFIG=DEFAULT configuration.
- PASSTK=nnn (Optional)
- The server can be configured to use PassTickets to start sessions for authenticated clients. If you specify the PASSTK parameter in your configuration, the server will
generate and use PassTickets for requesting clients that provide a valid user ID and a valid
password or passphrase.
After successfully connecting to the server, a client can start new sessions for the period in minutes specified by nnn without having to re-authenticate. Allowable values are 1 to 720 (12 hours). If PASSTK is specified without a value, the default is 480 (8 hours).
If PASSTK is not specified PassTickets will not be generated or used by the server. This feature is primarily to facilitate multifactor authentication (MFA) clients. See Using PassTickets for more details.
The PASSTK parameter must be specified under the CONFIG=DEFAULT configuration.
- WORKDIR=/path
- The CONFIG=DEFAULT set of parameters needs the WORKDIR=path keyword. This keyword specifies where the server can write semi-permanent (existing at least while the server task is running) files. A sample job, IPVMKDIR is supplied in the sample library to create this path.
- ATTLS=YES|NO (Optional)
- The Application Transparent Transport Layer Security (AT-TLS) feature of z/OS® Communication Server can be used to secure communications between the ADFzCC server and connecting clients. See Using AT-TLS for encrypted communications for more details.
- SSL_REQUIRED=YES|TLSV1.2|TLSV1.3|NO (Optional, default is NO)
- Determines whether SSL/TLS encrypted communications are
mandatory for the server and the desired protocol level. SSL/TLS communications are achieved by
using the System SSL APIs. The default protocol level is TLS 1.2 when YES is specified.
To use TLS 1.2, clients must be at level 14.1.0 or later. To use TLS 1.3, clients must be at level 15.1.0 or later.
If SSL encryption is used, then the server uses a certificate stored in either a RACF® keystore, when specified via the SSL_KEYRING keyword, or a GSKKYMAN managed key database and certificate for this server as specified in the SSL_CERT keyword or, if that keyword is omitted, at the WORKDIR specified location.
- SSL_CERT=/path/keyringfile (optional, for use of user created certificate)
- The path and name of a key database that contains a stored certificate that is used by the server. This parameter is passed to the gsk toolkit as the GSK_KEYRING_FILE setting. If this parameter is omitted, the server attempts to create a key database and self-signed certificate as it starts up.
- SSL_CERTPW=keyringpw (optional, for use of user created certificate)
- The password to be used to access the certificate repository. If omitted, the server uses a default password.
- SSL_KEYRING=userid/keyring
- If SSL is being used for the server, this configuration option provides the userid and keyring name for a certificate being held in a SAF keyring. The userid should match the ID used when creating the keyring.
- SSL_LABEL=labelstring (optional, for use of user created certificate)
- The label of the certificate from the key database to be used.
- SPAWN_ACCT=accountdata
- Allows specification of the account data used for the spawned address space. This is as per the _BPX_ACCT_DATA environment variable discussed in the z/OS® UNIX™ System Services Planning manual.
- SPAWN_TIME=nn
- Allows specification of the CPU time limit, in seconds, used for the spawned address space.
- SPAWN_PROGRAM=PROGRAM
- Specification of the program that is launched for the client connection. The server checks the existence of the named program. If you want to specify the name of a z/OS® UNIX™ executable file, rather than a load module in a STEPLIB data set, include the path. Otherwise, the server creates a sticky bit file in the WORKDIR specified location. Sticky bit is the mechanism in the z/OS® UNIX™ file system of indicating that this file is a load library member. The program is launched as a UNIX System Services process, but can be a traditional z/OS® program.
- SPAWN_STEPLIB=steplib1:steplib2 (optional)
- Allows specification of the run libraries that are used for the spawned address space. Support
for continuing library specifications is provided by ending a line with the colon character.
If the run libraries are not all APF authorized, you must ensure that the _BPX_SHAREAS environment variable is set to NO to avoid a potential abend S306. The server will then spawn the participating products in their own address space. You can add a STDENV DD statement to set the environment variable in the server procedure. For example:
//STDENV * _BPX_SHAREAS=NO /* - SPAWN_PARMS_SECTION
- This entry marks the beginning of extra parameters that are passed to the spawned process. The contents of this area are determined by the products that use the server.
- MIXEDCASEPASS=YES|NO (optional, default is NO)
- Determines whether uppercase translation is performed for incoming passwords for this system. If this system supports mixed case passwords, set this to YES and specify this keyword in the CONFIG=DEFAULT section.
- SPAWN_REGIONSZ=nnn (optional, default is to inherit the region size of the server)
- Determines the region size (in MB) for the launched process. Participating products being launched have their own recommendations for this sizing.