Configure the UKO server

Prerequisite tasks

The following tasks need to be completed before you can complete this chapter:

• A Liberty angel process must be running. If this is a named angel, you will need the angel name ${WLP_ANGEL_NAME}.
• The UKO database must be set up.
• The required network configuration must be completed.
• The UKO agent is not required to start up the server. You will need the agent though, once you want to install keys into z/OS keystores.

Directory setup

The following directories need to be created:

• ${UKO_SERVER_DIRECTORY} - the directory where the configuration files of the active UKO server (server.env and jvm.options) are residing
• ${WLP_OUTPUT_DIR} - optional output directory for the server logs, otherwise they will be created in the ${UKO_SERVER_DIRECTORY}

The ${UKO_SERVER_DIRECTORY} requires a special format. WebSphere Liberty expects to find the configuration files in a directory with the name of the server under ${WLP_USER_DIR}/servers/. It is recommended to use the name of the UKO server started task ${UKO_SERVER_STC_NAME} as server name, so that the ${UKO_SERVER_DIRECTORY} will be ${WLP_USER_DIR}/servers/{UKO_SERVER_STC_NAME}.

The createDirectories step of the server example workflow will guide you through the creation of the required directories as well as the allocation of ZFS datasets that will be mounted there.

Configuration files and folders

The configureUkoServer step of the server example workflow will help you with this part of the instructions.

cd ${WLP_USER_DIR}/servers/${UKO_SERVER_STC_NAME}
ln -s ${UKO_INSTALL_DIR}/EkmfWeb.properties EkmfWeb.properties
ln -s ${UKO_INSTALL_DIR}/apps apps
ln -s ${UKO_INSTALL_DIR}/configDropins configDropins; 
ln -s ${UKO_INSTALL_DIR}/resources resources
ln -s ${UKO_INSTALL_DIR}/server.xml server.xml

Create the server procedure

Run the createServerProc step of the server example workflow to create a procedure to start the server and copy it to your ${UKO_ZOS_PROCLIB}. Alternatively, you can use the following sample procedure and replace all ${placeholders} to match your environment:

//${UKO_SERVER_STC_NAME} PROC PARMS='${UKO_SERVER_STC_NAME}'
// SET WLPHOME='${WLP_INSTALL_DIR}'
//*
//STEP1    EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,
//  PARM='PGM &WLPHOME./lib/native/zos/s390x/bbgzsrv --clean &PARMS.'
//STEPLIB  DD DSN=${DB2_HLQ}.SDSNEXIT,DISP=SHR
//         DD DSN=${DB2_HLQ}.SDSNLOAD,DISP=SHR
//         DD DSN=${DB2_HLQ}.SDSNLOD2,DISP=SHR
//STDOUT   DD   SYSOUT=*
//STDERR   DD   SYSOUT=*
//STDIN    DD   DUMMY
//STDENV   DD   *
_BPX_SHAREAS=YES
JAVA_HOME=${JAVA_HOME}
WLP_USER_DIR=${WLP_USER_DIR}
#JVM_OPTIONS=<Optional JVM parameters>
//*
// PEND
//

Configure security for the server

Perform the statements in the Security setup for the Liberty server chapter. Those are covered in the configureSecurity step of the server example workflow.

Start the server

You are now ready to start the server. Issue the following command:

/START ${UKO_SERVER_STC_NAME}

Alternatively, you can use the startServer step of the server example workflow. The validateConsoleAPI sub-step checks whether the user ID running the step is allowed to issue console commands and whether a task with the ${UKO_SERVER_STC_NAME} is already running. Afterwards, in the startServer_console sub-step, it issues the START command to the console.

Note: To use that part of the workflow, your userid needs to be enabled to use the console API. The provided workflow is sending console requests to /zosmf/restconsoles/consoles/defcn. This means that the name of the console that is used to issue the command is generated by the REST Console API, by adding CN to the logon user ID.

For example, if user UKOSTC plans to accept the default console name, UKOSTCCN, this user can issue this RACF command to set console attributes for the console:

ADDUSER UKOSTCCN OPERPARM(AUTH(MASTER) ROUTCODE(ALL))

If the user ID is longer than 6 characters, the user ID is truncated. For example, if the user ID is UKORACF, the console name is UKORACFN.

Refer to the z/OSMF documentation for more information on issuing commands from a system console.

What's next

• Finish the server setup by defining the key hierarchy
• If you plan to create keys for z/OS, set up a UKO agent