SMAPI Configuration Properties

To allow services to function properly on z/VM, use XEDIT to edit the DMSSICNF COPY file on the MAINT 193 disk. IBM recommends that you keep at least two previous versions of the file as backups. The following SMAPI configuration properties are specified in the DMSSICNF COPY file. (In most cases, an attribute is shown with its initial value):

_________________________________________________________________

Authorization Policy
```
   Authorization_Policy = policy
```
The Authorization Policy determines how each API request is authorized. policy can be:
Authorization_Policy_EsmAuthlist
Specifies that if an External Security Manager (ESM) is installed, SMAPI calls the ESM first to authorize the request. This is the default setting. If the ESM defers (due to the way the ESM is configured) or is not installed, SMAPI uses the SMAPI authorization process, described in Authorizing API Requests, to decide if the request is authorized, and SMAPI calls the ESM to audit the decision (that is, to allow the ESM to record SMAPI's decision). The ESM's logging options control which, if any, of the audit requests result in audit records.
Note:

For requests against a list of n targets, you can get up to n audit requests. SMAPI stops checking the list when the first target is rejected, so you get n audit requests whenever the SMAPI authorization process authorizes the list request, and 1-n audit requests when a list request is ultimately rejected.

This setting logs the result of SMAPI authorization processing when an External Security Manager (ESM) defers the authorization request. If REQUEST=AUDIT results in SAF RC=8, the activity is traced but no message is sent to the operator. For non-zero return codes (other than "ESM not installed"), the activity is traced and a message is sent to the system operator.
Authorization_Policy_EsmOnly

Specifies that SMAPI calls the ESM, and never uses the SMAPI authorization process, described in Authorizing API Requests. If the ESM defers, is not installed, or produces a return code other than "authorized" (RACROUTE SAF RC=0), SMAPI rejects the request.
Note: For requests against a list of n targets, you can get up to n authorization requests. The ESM stops checking the list when the first target is rejected, so you get n audit requests whenever the ESM authorizes the list request, and 1-n audit requests when a list request is ultimately rejected.

Authorization_Policy_AuthlistOnly

Specifies that SMAPI uses the SMAPI authorization process, described in Authorizing API Requests, and never calls the ESM.
_________________________________________________________________
SMAPI Instance Name
```
   SMAPI_Instance_Name = "SMAPI"
```
The SMAPI instance name is used to construct ESM profile names when authorizing requests through an External Security Manager (ESM). For more information, see Configuring SMAPI to use an ESM to Authorize Requests.

_________________________________________________________________
Directory Manager Exit
```
   DM_exit = "DMSSIXDM"
```
The directory manager exit is the code that is called to perform directory manager functions. The DM_exit configurable variable should be set to the name of the REXX exec supplied by your directory manager. The default is set to DMSSIXDM, which is the directory manager exit for the IBM Directory Maintenance Facility. Please contact the supplier of your preferred directory manager for more information on configuring your directory manager exit.

For more information on the implementation of the directory manager exit, see The Directory Manager Exit. For more information on the IBM Directory Maintenance Facility and its specific use with the Systems Management APIs, see the z/VM: Directory Maintenance Facility Tailoring and Administration Guide.

_________________________________________________________________
Authorization Exit
```
   XIA_exit = ""
```
The IBM-supplied authorization routine will check the authorization file to determine whether the requested function is authorized to be performed by the requesting userid (authenticated userid) on behalf of the target userid. An external security manager may implement its own authorization functions for the Systems Management APIs by setting the XIA_exit configurable variable to the name of an authorization REXX exec. The input parameters to this exit shall be the authenticated_userid, target_identifier and function_name specified on the API call. The input parameters will be in EBCDIC (codepage 924). The function call is as follows:
```
   Reason = XIA_exit(authId, targetId, funcName)
```
On input the parameters should be parsed as follows:
```
   Parse Upper Arg authId, targetId, funcName
```
The authorization exit must return a 4-byte binary return code directly followed by a 4-byte binary reason code.
_________________________________________________________________
RPIVAL Program Name
```
   RPIVAL_prog = ""
```
The RPIVAL_prog configurable variable may be used to set the name of a program to be used by an external security manager (ESM) to authenticate userids and passwords supplied by client programs (an RPIVAL program is only required if the ESM does not support DIAGNOSE X’88’). When no value is specified for this setting, the default is RPIVAL. If a different program is used, it must follow the programming conventions (parameter format and return codes) used by RPIVAL. More information on the RPIVAL command may be found in z/VM: RACF Security Server Macros and Interfaces.

_________________________________________________________________
Server_DCSS
```
   Server_DCSS = DCSS_name     
```
The Server_DCSS configurable variable is used to specify the name of the DCSS which will be automatically created and used by the SMAPI server machines for communication with each other.

_________________________________________________________________
Asynch Update Port
```
   Asynch_Update = "55555"             
```
This is an internal port used by SMAPI to receive asynchronous notifications and pass them on via the event stream.

_________________________________________________________________
LOHCOST Server Defaults
```
   LOHCOST Port =  "49998"              /* LOHCOST port               */
   LOHCOST Addr =  "10.70.100.100"      /* LOHCOST IP address         */
   LOHCOST_STACK   = "DTCSMAPI"         /*  private tcp/ip stack       */
   LOHCOST_DIRECTORY = 1                /* directory cache enablement mask */
   LOHCOST_GROUP   = 2                  /* group data cache enablement mask*/
   LOHCOST_METADATA = 4                 /* metadata cache enablement mask */
   LOHCOST_Enabled = LOHCOST_DIRECTORY + LOHCOST_GROUP                    
```
The LOHCOST server is used for caching the system directory data required to satisfy the various query APIs. Making changes to the first three lines requires changes to configuration settings and directory entry changes to other SMAPI servers, and the three enablement mask settings must not be changed. Therefore, the first six lines of this section should not be modified. The last line may be modified as follows:
- To enable LOHCOST caching of directory user data only, set LOHCOST_Enabled = LOHCOST_DIRECTORY
- To enable LOHCOST for support of the METADATA APIs only (no caching of directory manager directory or storage group data), set LOHCOST_Enabled = LOHCOST_METADATA
- To disable LOHCOST caching of directory data and directory manager storage group data, set LOHCOST_Enabled = 0
Note:
- If you are using DirMaint as your directory manager, you should enable LOHCOST_CACHE data only if you use SMAPI to make all changes to the DirMaint group data. If you plan to make changes to the DirMaint group data through the DirMaint interface or other method, the LOCHOST_CACHE will not be updated, and therefore you must not enable LOHCOST_CACHE.
- LOHCOST support for METADATA APIs is always enabled unless LOHCOST_Enabled = 0.
- Because group caching is disabled, the LOHCOST_GROUP property setting in the DMSSICNF COPY file is ignored. Also, the default setting for LOHCOST_GROUP in the IBMCNF COPY file is ignored.
Server Log Level
```
   log_level = 3                                             
```
By default the log level is set to 3, meaning that all request, entry, exit, and parameter information is logged. The log level identifies which debug information is provided and when to provide it. The valid log levels for the systems management server are as follows:

0

No logging.

1

Request logging only – the receipt of a request and confirmation of its completion are logged.

2

Request, entry, and exit – request trace data and entry and exit point trace data is included.

3

Request, entry, exit and parameter logging – all information from log level 2 in addition to parameters and associated log information is provided.

Log entries are written to VSMAPI LOG1 and VSMAPI LOG2 files in the data SFS directory. By default, the files can be found in the VMSYS:VSMWORK1.DATA directory. The server will write time-stamped log entries to VSMAPI LOG1. When the file reaches the maximum size, the file will be copied to VSMAPI LOG2 (replacing previous log entries) and a new VSMAPI LOG1 file will be started. By default, the VSMAPI LOG1 and VSMAPI LOG2 each have a default size of 10000 lines. This default may be altered by changing the LogLimit = value, as described in the Server Log File Size section.

In the event of a worker or request server reboot, SMAPI will save a snapshot of the most recent copies of the SMAPI log files. Up to two levels of the SMAPI log files are saved, with VSMAPI SV1LOG1 and VSMAPI SV1LOG2 being the most recent copies of the log files, and VSMAPI SV2LOG1 and VSMAPI SV2LOG2 being the older set of the log files. By default, these log files are saved in the VMSYS:VSMWORK1.DATA SFS directory.

To view the log file while the server is running, a user can either copy a snapshot of the log file or XEDIT the file using the NOLOCK option.

Note: Do not lock the log file. If you do, this will prevent any further messages from being logged.

_________________________________________________________________
Authorization List and Name List Configuration
```
   NameListFileIdAny = "VSMWORK1 NAMELIST *" 
   AuthListFileIdAny = "VSMWORK1 AUTHLIST *" 
```
The names of the authorization file and the name list file must be configured in DMSSICNF COPY. By default, these files are named VSMWORK1 NAMELIST and VSMWORK1 AUTHLIST during the installation process. If the names of these files are changed, DMSSICNF must reflect this change. For more information on configuring the authorization list or name list files, see Authorizing API Requests and Name Lists.

_________________________________________________________________
SFS Configuration
```
   Server_SFSpool= "VMSYS:"                 /* Default Server filepool   */ 
   Server_SFSdir = "VMSYS:VSMWORK1."        /* Default Server directory  */ 
   Server_DATA   = "VMSYS:VSMWORK1.DATA"    /* Default DATA directory */ 
   Server_SOURCE = "VMSYS:VSMWORK1."        /* Default SOURCE directory */ 
   Server_STATUS = "VMSYS:VSMWORK1.STATUS"  /* Default STATUS directory */
   Server_StatusLog_Max = 2                 /* Default STATUS file num  */
   
   DataDisk = "A"        
   SourceDisk = "B"        
```
The default SFS configuration is defined in DMSSICNF COPY. If the configuration is changed, this must be reflected in the DMSSICNF COPY file. For more information about SFS, see Shared File System Directories.

If you change the SFS configuration, make sure that all of the directories are created, that the servers are enrolled in the file pools, and that the VSMWORK1 AUTHLIST and VSMWORK1 NAMELIST files are in the directory specified in Server_SOURCE. Note that all of these directories should be in the same parent directory.

The Server_STATUS = and Server_StatusLog_Max = attributes are used in conjunction with either the SMAPI_Status_Capture API or the SMSTATUS EXEC. When that API or EXEC completes, there will be an output file created in the VMSYS:VSMWORK1.STATUS directory. The EXEC itself will indicate the name and location of this file. It will be a text file, and can be provided to IBM Service to assist with diagnosing suspected problems. SMAPI will retain the n most recent output files from invocations of the API or EXEC. Note that n is determined by the Server_StatusLog_Max = attribute. See SMAPI_Status_Capture and Capturing SMAPI Data for Problem Resolution for more information.

The DataDisk and SourceDisk variables tell the server profiles where to access the VSMWORK1. and VSMWORK1.DATA SFS directories. By default, they are accessed as file modes B and A, so that executables on those directories supersede executables on other disks (such as the servers' 191 disks and the MAINT 193 disk). An administrator can change this ordering for testing purposes.
Note:
1. The VSMGUARD worker server will grant authority to all the other SMAPI servers that are configured to access the SMAPI file space. Therefore, VSMGUARD must be made an administrator of the VMSYS: file pool. This is done by adding VSMGUARD to the list of users authorized for ADMIN authority. In the default environment, this is done by updating the VMSERVS DMSPARMS file on the VMSERVS 191 disk.
2. For more information on increasing the size of the VMSYS: filepool, if necessary, see z/VM: CMS File Pool Planning, Administration, and Operation.
_________________________________________________________________
VMRM Configuration
```
   VMRM_SFSdir   = "VMSYS:VMRMSVM."    /* Default VMRM filepool and dir  */
```
The default VMRM configuration is defined in DMSSICNF COPY. If the configuration is changed this must be reflected in the DMSSICNF COPY file. For more information about VMRM, see z/VM: Performance.

_________________________________________________________________
Custom APIs
```
   UserParserFileIdAny = "DMSSIUSR NAMES *" 
   ulong = ''                                                              
```
The name of the file used to specify the user-defined custom APIs must be configured in DMSSICNF COPY by setting the UserParserFileIdAny variable. By default, this file is named DMSSIUSR NAMES. This file must be a CMS NAMES file. A sample of this file is included in DMSSIUSR SAMPNAME on MAINT’s 193 disk, as shown below.
```
   * Custom API named "Custom_API_1" with custom exec "CUSTOM1 EXEC"
   :nick.Custom_API_1
   :program.CUSTOM1

   * Custom API named "Custom_API_2" with custom exec "CUSTOM2 EXEC"
   :nick.Custom_API_2
   :program.CUSTOM2
```
The ulong variable should be set to the list of “long” custom APIs. These are APIs that you would like dispatched to the additional worker servers for improved multitasking capability. API names should be blank-separated. Note that the ulong variable has a character restriction of 771 characters. An example:
```
   ulong = "Custom_API_1 Custom_API_2"
```
Use the REXX continuation character (a comma) to continue a clause across the following line.

For more information on user-defined custom APIs and configuring the DMSSICNF COPY file, see Creating Custom APIs.

_________________________________________________________________
Default SYSTEM CONFIG Link Values
```
   System_Config_File_Name = 'SYSTEM'                                     
   System_Config_File_Type = 'CONFIG'                                     
   Parm_Disk_Owner         = 'PMAINT' 
```
These values will be used as the default values in APIs that update SYSTEM CONFIG, when any of the link parameters are left to the default value.

Note: The Parm_Disk_Number and Parm_Disk_Password values are no longer included in the DMSSICNF COPY file. These values are now hardcoded to CF0 for the disk number, and to a comma for the password (indicating a password is not provided).

_________________________________________________________________
Dump Processing Values
```
   Dump_Processing_Location = "VMSYSU:OPERATNS."
   Dump Processing Interval = "1"             
```
The location entry specifies an SFS directory or minidisk where a processed dump should be placed by the dump handler (if activated). If specifying a minidisk, both the owner and the virtual device should be given. Example:
```
    Dump_Processing_Location = "MAINT 999"
```
The interval entry specifies the interval (expressed in minutes) at which the OPERATNS server will check its reader for new dump files to process automatically.

Important: To activate automated dump handling, you must first uncomment the entry for the OPERATNS server in the DMSSISVR NAMES file (see The Server Names File) and also allocate enough space to contain the dump files, at the location specified by the Dump_Processing_Location = entry above.

A sample profile exec for the OPERATNS server is provided in file OPERATNS SAMPPROF on MAINT's 193 disk. This sample profile must be copied to each OPERATNS's 191 disk as PROFILE EXEC in order to complete activation of dump handling.

_________________________________________________________________
IMAGE RECYCLE Maximum Wait Time
```
   Max_Image_Wait_Time = 120                                     
```
The Max_Image_Wait_Time = attribute is used to specify the maximum wait time in seconds that the Image_Recycle API will wait for an image to deactivate before attempting to reactivate the image. For more information, see Image_Recycle.

_________________________________________________________________
Server Log File Size
```
   LogLimit = 10000                                             
```
Log entries are written to VSMAPI LOG1 and VSMAPI LOG2 files in the data SFS directory. While the log_level = value determines which debug information is written to those files, the LogLimit = value determines the size of those files. The default size is 10000 lines.

_________________________________________________________________
Temporary Virtual Device Number and Access Mode
```
   Temp_Disk_Vdev = 'A91'  
   Temp_Acc_Mode  = 'C' 
```
These constants specify that the TCPIP IFCONFIG command will have a VDEV default of A91, and that it will be accessed dynamically by SMAPI worker servers as file mode C.