Skip to content
CA Common Services for z/OS - 14.1
Documentation powered by DocOps

Start the Hardware Interface Service

Last update December 1, 2016

Follow these steps to learn how to configure the service and its environment, and start the service.

  1. Set Up the Service.
  2. Prepare the Service Started Task.
  3. APF-Authorize the Load Libraries.
  4. Configure Service User ID Security.
  5. Configure the User Security.
  6. Start the Service.

Set Up the Service

If you do not use CA CSM to configure the service, use the Install Utility to set up the service. You can reuse the utility to set up more service instances for the deployment on multiple systems.

During the setup process, you provide the site-specific information that you previously collected. This information is used to generate the setup JCL jobs.

Important! After you have run a setup job, you cannot alter the results using the setup software. You can use the setup software to create a region, or you can manually customize the JCL members for the existing region.

Follow these steps:

  1. Ensure that the dsnpref.CC2DLINK data set is in your system linklist.
    For example, include the following LNKLST statement in SYS1.PARMLIB(PROGxx):

    LNKLST ADD NAME(LNKLST00) DSNAME(dsnpref.CC2DLINK)
    Note: You can also create a STEPLIB to the data set name (DSN) in your TSOPROC (that is, allocate it to ISPLLIB).
  2. At the ISPF/PDF TSO Command Shell prompt, execute the following command:

    EXEC 'dsnpref.CC2DJCL(INSTALL)'

    The Install Utility panel appears.

    Note: On each of the Install Utility panels, you can use the following keys:
    • Enter to proceed to the next panel
    • F1 to display the online help
    • F3 to return to the previous panel
    • F4 to exit and return to the main menu 
  3. Press Enter.
    The Install Utility Primary Menu panel appears.
  4. Perform the following steps:
    1. Enter 1.
      The Parameters Primary Menu panel appears.
    2. Enter A to start the parameter review process.
      The first of a sequence of Parameters panels appears.
    3. Specify the name of the CSI data set and zones that were used during the installation. Press Enter.
    4. Complete each of the panels as they open. Press Enter at the completion of each panel. You can take the default options or can specify site-specific values.
  5. Enter 4.
    The SETUP Primary Menu panel appears.
  6. Enter 1.
    A panel appears for you to define the region name.
  7. Enter the name (rname), an ID (i), and a description of the region you are setting up.
    • i
      Is an alphanumeric character that differentiates the setup for different regions.

    The Install Utility uses the name that you entered to generate the started task JCL job. For example, if you enter REGION01 as the name, your started task JCL job is REGION01.

  8. Complete each of the SETUP panels as they open. Accept the default values, or specify site-specific values.
    The setup software generates a series of jobs in the dsnpref.CNTL data set.

  9. Submit and run the following jobs in the listed sequence. Do not proceed with any job until the previous job has completed successfully. Each job returns condition code 0 if successful.
    • Si2SHALC
      Allocates the shared run-time data sets.
    • Si5LDPDS
      Copies some PDS members to dsnpref.PARMLIB for use by the region. The member names include the Si prefix (for example, SiHISPRM).
    Note: The utility also generates the following two jobs: S i90DUMP and S i91REST. If a shared DASD is not available, the jobs help you deploy the configuration files for your region to a target system. The S i90DUMP job creates a backup data set that includes the configuration files for the region, which you deploy to the target system. The backup data set is dsnpref.DFDSS.SHARED (containing files that multiple regions can share). The S i91REST job, when submitted on the target system, restores the configuration files from the backup data set. In addition to deploying the configuration files, you also deploy the target libraries. CA CSM can help you with this deployment.
  10. Press F3.
    You return to the Primary Menu panel 

Prepare the Service Started Task

The Install Utility generates a started task member for each service instance you set up. Review it to verify that it meets your site-specific requirements. You can then copy it to a procedure library with the required authority.

Note: To assist you with the future deployment, you can update the started task member to use z/OS static system symbols.

Follow these steps:

  1. Review and update the DD statements in the service started task member dsnpref.CNTL(hisname) for your site-specific requirements.
  2. Copy the reviewed member to SYSx.PROCLIB.

  3. Grant the user ID associated with the service UPDATE authority on the run-time data sets created by the installation and setup processes.
  4. Authorize the user ID of the service for the BCPii application program interface (API) and resources.

APF-Authorize the Load Libraries

Most products have their own load library but also require the load libraries of supporting services. The CC2DLOAD load library must be APF-authorized.

The examples use the FACILITY resource class (HWISAFCL=FACILITY) and the HI$RV resource name prefix (HWISAFPF=HI$RV).

To APF-authorize your load libraries, add the run-time load libraries to the APF list, SYS1.PARMLIB(IEAAPFxx).

To dynamically APF-authorize the load libraries, issue the following z/OS command:

SETPROG APF,ADD,DSNAME=?loadlib,VOLUME=?volser
  • ?loadlib
    Specifies the name of the load library.
  • ?volser
    Specifies its volume serial number.

To dynamically APF-authorize load libraries that Storage Management Subsystem (SMS) controls, issue the following z/OS command:

SETPROG APF,ADD,DSNAME=?loadlib,SMS

Configure Service User ID Security

The Hardware Interface Service requires the BCPii authority to retrieve information from the HMC as well as authority to each particular resource it wishes to access.  Follow the steps appropriate for your security system to grant these authorities. After you set up the proper authority, refer to the next section to verify your work.

Note: In the following examples, community_name must be in uppercase (for example, BCPII) and cpc_name must be a full SNA network name of the CPC (for example, IBM390PS.MF01).

CA ACF2™ for z/OS

  1. To get started, enter the following CA ACF2 commands in TSO: 

    $KEY(HWI) TYPE(FAC)

    $USERDATA('community_name')

  2. To grant the Hardware Interface Service BCPii authority to retrieve information from the HMC, issue the following CA ACF2 commands in TSO:

    APPLNAME.HWISERV UID(hisrv_user_id) SERVICE(READ) ALLOW

  3. Grant the Hardware Interface Service authority to access a CPC and each of its LPARS.  Be sure to issue the following CA ACF2 commands in TSO for every CPC you want to access with the Hardware Interface Service:

    TARGET.- UID(hisrv_user_id) SERVICE(READ) ALLOW

    TARGET.cpc_name UID(*************STCSYS) SERVICE(READ) ALLOW

    TARGET.cpc_name.- UID(*************STCSYS) SERVICE(UPDATE) ALLOW

    UID(*) SERVICE(READ) ALLOW

  4. Grant the Hardware Interface Service authority to access Capacity Records. Be sure to issue the following CA ACF2 commands in TSO for each CPC you granted authority for in Step 2.

    CAPREC.- UID(hisrv_user_id) SERVICE(READ) ALLOW

    CAPREC.cpc_name UID(*************STCSYS) SERVICE(READ) ALLOW

    CAPREC.cpc_name.- UID(*************STCSYS) SERVICE(UPDATE) ALLOW

    UID(*) SERVICE(READ) ALLOW

CA Top Secret® for z/OS

  1. To get started, enter the following CA ACF2 commands in TSO: 

    TSS ADDTO(tssdept) IBMFAC(HWI)

  2. To grant the Hardware Interface Service BCPii authority to retrieve information from the HMC, issue the following CA ACF2 commands in TSO:

    TSS PER(hisrv_user_id) IBMFAC(HWI.APPLNAME.HWISERV) ACCESS(READ)

  3. Grant the Hardware Interface Service authority to access a CPC and each of its LPARS.  Be sure to issue the following CA ACF2 commands in TSO for every CPC you want to access with the Hardware Interface Service:

    TSS PER(hisrv_user_id) IBMFAC(HWI.TARGET.cpc_name) ACCESS(READ) APPLDATA('community_name')

    TSS PER(hisrv_user_id) IBMFAC(HWI.TARGET.cpc_name.*) ACCESS(READ)

  4. Grant the Hardware Interface Service authority to access Capacity Records. Be sure to issue the following CA ACF2 commands in TSO for each CPC you granted authority for in Step 2.

    TSS PER(hisrv_user_id) IBMFAC(HWI.CAPREC.cpc_name) ACCESS(READ)
    TSS PER(hisrv_user_id) IBMFAC(HWI.CAPREC.cpc_name.*) ACCESS(READ)

RACF

  1. To grant the Hardware Interface Service BCPii authority to retrieve information from the HMC, issue the following RACF commands in TSO: 

    RDEFINE FACILITY HWI.APPLNAME.HWISERV UACC(NONE)

    PERMIT HWI.APPLNAME.HWISERV CLASS(FACILITY) ID(hisrv_user_id) ACCESS(READ)

  2. Grant the Hardware Interface Service authority to access a CPC.  Be sure to issue the following RACF commands in TSO for every CPC you want to access with Hardware Interface Service:

    RDEFINE FACILITY HWI.TARGET.cpc_name UACC(NONE) APPLDATA('community_name')

    PERMIT HWI.TARGET.cpc_name CLASS(FACILITY) ID(hisrv_user_id) ACCESS(READ)

  3. Grant the Hardware Interface Service authority to access an LPAR. Be sure to issue the following RACF commands in TSO for each CPC you granted authority for in Step 2 so no LPARs are excluded.

    RDEFINE FACILITY HWI.TARGET.cpc_name.* UACC(NONE) APPLDATA('community_name')

    PERMIT HWI.TARGET.cpc_name.* CLASS(FACILITY) ID(hisrv_user_id) ACCESS(READ)

  4. Grant the Hardware Interface Service authority to access Capacity Records. Be sure to issue the following RACF commands in TSO for each CPC you granted authority for in Step 2.

    RDEFINE FACILITY HWI.CAPREC.cpc_name UACC(NONE) APPLDATA('community_name')

    PERMIT HWI.CAPREC.cpc_name CLASS(FACILITY) ID(hisrv_user_id) ACCESS(READ)

    RDEFINE FACILITY HWI.CAPREC.cpc_name.* UACC(NONE) APPLDATA('community_name')

    PERMIT HWI.CAPREC.cpc_name.* CLASS(FACILITY) ID(hisrv_user_id) ACCESS(READ)

  5. Refresh RACF by submitting the following RACF command in TSO:

    SETROPTS RACLIST(FACILITY) REFRESH

Security Validation Messages

To validate that you have configured security correctly, review the service HISLOG after the service has started.

  • If the security configuration is correct, HISLOG has the following messages: 

    NK8030 HIS INITIAL TOPOLOGY COLLECTION STARTING. H/W INTERFACE: BCPII

    NKAA20 10 - COLLECTING INFORMATION ABOUT THIS SYSTEM

    NS1001 HISRV SUBSYSTEM INITIALIZATION COMPLETE. SSID: HIS

    NKAA20 20 - RETRIEVING ALL CPC NAMES

    NKAA20 30 - BUILDING TOPOLOGY UNDER CPCS

    ...

    NK8031 HIS INITIAL TOPOLOGY COLLECTION FINISHED. H/W INTERFACE: BCPII ENTITIES: nn

  • If the security configuration is incorrect, HISLOG has the following messages:

    NK8030 HIS INITIAL TOPOLOGY COLLECTION STARTING. H/W INTERFACE: BCPII

    NKAA20 10 - COLLECTING INFORMATION ABOUT THIS SYSTEM

    NS1001 HISRV SUBSYSTEM INITIALIZATION COMPLETE. SSID: HIS

    NKAA73 UNABLE TO CONTACT BCPII A/S. REQUEST: 1 TYPE: operation_type (BCPII RC D/X: 3842 00000F02)

    NK8032 HIS INITIAL TOPOLOGY COLLECTION ERROR. H/W INTERFACE: BCPII

Configure the User Security

The Hardware Interface Service lets you accomplish the following goals:

  • Authorize all users to access or alter specific entities in the Hardware Interface Service topology model.
  • Authorize specific users to use specific restricted requests or facilities.

This functionality is achieved through security resources known to the Hardware Interface Service. The default security resource class is CAHIS. If you plan to use this default, ensure that you define the class to your security product. Alternatively, you can use the HWISAFCL initialization parameter to specify an already defined class to use. Specify the parameter in the PARMLIB(SiHISPRM) member.

The resources can have an optional common user-defined prefix. Best practice states that this prefix contains a special character, for example, HI$RV. To specify the prefix, use the HWISAFPF initialization parameter. Specify the parameter in the PARMLIB(SiHISPRM) member.

Authorize Users for Entities

The following resources let you authorize users to access the entities in the Hardware Interface Service topology model:

  • [prefix.]ENTITY.LCL.CURRENT (the CURRENT group)
  • [prefix.]ENTITY.LCL.SAME (the SAME group)
  • [prefix.]ENTITY.OTHER (the OTHER group)
Note: Substitute prefix. as specified by the HWISAFPF parameter.

An entity is assigned to a resource in the following way:

  • The Enterprise and Installation entities are not assigned to any group but are always read-only.
  • An entity on which the service is executing is assigned to the CURRENT group. The current Ensemble, CPC, and LPAR entities are assigned to the CURRENT group.
  • The children of an entity in the CURRENT group are assigned to the SAME group.
  • Other entities are assigned to the OTHER group.

The following examples grant user authorities using different security products:

  • USER1 has the authority to work with all entities.
  • USER2 has the authority to work with the local entities.
  • USER3 has the authority to work with the local Enterprise, CPC, and LPAR entities.
  • USER4 has the authority to work with the child entities of the local Enterprise, CPC, and LPAR.
  • USER5 has the authority to work with other entities.

The examples use the FACILITY resource class (HWISAFCL=FACILITY) and the HI$RV resource name prefix (HWISAFPF=HI$RV).

Example: Grant User Authorities Using CA ACF2™ for z/OS

To define the security resources and grant users access to the entities, issue CA ACF2 commands in TSO, for example:

[ACF]

SET RESOURCE(FAC)

COMPILE *

$KEY(HI$RV) TYPE(FAC)

ENTITY.- UID(USER1) SERVICE(READ) ALLOW

ENTITY.LCL.- UID(USER2) SERVICE(READ) ALLOW

ENTITY.LCL.CURRENT UID(USER3) SERVICE(READ) ALLOW

ENTITY.LCL.SAME UID(USER4) SERVICE(READ) ALLOW

ENTITY.OTHER UID(USER5) SERVICE(READ) ALLOW

STORE

[END]

Example: Grant User Authorities Using CA Top Secret® for z/OS

To define the security resources and grant users access to the entities, issue CA Top Secret commands in TSO. For example:

TSS ADDTO(acid) IBMFAC(HI$RV)

TSS PERMIT(USER1) IBMFAC(HI$RV.ENTITY.) ACCESS(READ)

TSS PERMIT(USER2) IBMFAC(HI$RV.ENTITY.LCL.) ACCESS(READ)

TSS PERMIT(USER3) IBMFAC(HI$RV.ENTITY.LCL.CURRENT) ACCESS(READ)

TSS PERMIT(USER4) IBMFAC(HI$RV.ENTITY.LCL.SAME) ACCESS(READ)

TSS PERMIT(USER5) IBMFAC(HI$RV.ENTITY.OTHER) ACCESS(READ)

Example: Grant User Authorities Using RACF

To define the security resources and grant users access to the entities, issue RACF commands in TSO, for example:

RDEFINE FACILITY HI$RV.ENTITY.* UACC(NONE)

RDEFINE FACILITY HI$RV.ENTITY.LCL.* UACC(NONE)

RDEFINE FACILITY HI$RV.ENTITY.LCL.CURRENT UACC(NONE)

RDEFINE FACILITY HI$RV.ENTITY.LCL.SAME UACC(NONE)

RDEFINE FACILITY HI$RV.ENTITY.OTHER UACC(NONE)

SETROPTS RACLIST(FACILITY) REFRESH

PERMIT HI$RV.ENTITY.* CLASS(FACILITY) ID(USER1) ACCESS(READ)

PERMIT HI$RV.ENTITY.LCL.* CLASS(FACILITY) ID(USER2) ACCESS(READ)

PERMIT HI$RV.ENTITY.LCL,CURRENT CLASS(FACILITY) ID(USER3) ACCESS(READ)

PERMIT HI$RV.ENTITY.LCL.SAME CLASS(FACILITY) ID(USER4) ACCESS(READ)

PERMIT HI$RV.ENTITY.OTHER CLASS(FACILITY) ID(USER5) ACCESS(READ)

Authorize Users for Requests

The Hardware Interface Service acts as if a user is APF authorized if that user is defined to the resource, [prefix.]USER.AUTH.  The users that you want to define to this resource can vary greatly depending on your intended use of the Hardware Interface Service. Refer to the following examples to grant user authorities for your specific security product.

Note: prefix. is the optional resource name prefix as specified by the HWISAFPF parameter.

The examples use the FACILITY resource class (HWISAFCL=FACILITY) and the HI$RV resource name prefix (HWISAFPF=HI$RV).

Example: Grant User Authorities Using CA ACF2™ for z/OS

To define the security resources and authorize a user (usern), issue CA ACF2 commands in TSO, for example:

[ACF]

SET RESOURCE(FAC)

COMPILE *

$KEY(HI$RV) TYPE(FAC)

USER.AUTH UID(usern) SERVICE(READ) ALLOW

STORE

[END]

Example: Grant User Authorities Using CA Top Secret® for z/OS

To define the security resources and authorize a user (usern), issue CA Top Secret commands in TSO, for example:

TSS ADDTO(acid) IBMFAC(HI$RV)

TSS PERMIT(usern) IBMFAC(HI$RV.USER.AUTH) ACCESS(READ)

Example: Grant User Authorities Using RACF

To define the security resources and authorize a user (usern), issue RACF commands in TSO, for example:

RDEFINE FACILITY HI$RV.USER.AUTH UACC(NONE)

SETROPTS RACLIST(FACILITY) REFRESH

PERMIT HI$RV.USER.AUTH CLASS(FACILITY) ID(usern) ACCESS(READ)

Start the Service

To start the service, issue the following command from the MVS console:

S service_name,REUSASID=YES

service_name is the name of the service started task or job.

Note: To stop the service, issue the following command from the MVS console: P  service_name.
Was this helpful?

Please log in to post comments.

  1. Lori Thomas
    2016-05-05 11:11

    This doc is terrible - I need to see the entire topic, not just a one-liner that says what the rest of the doc will do.

    1. Bauman, James A
      2016-05-05 11:30

      Thank you for the feedback Lori. We will review the content and restructure it to a more user-friendly format. Stay tuned...

    1. Bauman, James A
      2016-05-10 05:25

      Hi Lori Thomas - 

      We restructured the topic a bit. Please have a look and us know if this works for you. 

      Thanks!