wlp

Provision, configure, and start a Liberty instance

This project provides a sample playbook and roles which can be used to provision, configure, and start a basic WebSphere Liberty server instance.

It is a good practice to review the playbook sample contents before executing them. It will help you understand the requirements in terms of space, location, names, authority, and the artifacts that will be created and cleaned up. Although samples are written to operate without the need for the user’s configuration, flexibility is written into the samples because it is not easy to determine if a sample has access to the host’s resources. Review the playbook notes sections for additional details and configuration.

Playbook Summary

• provision.yml - Handles the following tasks:
  • Creating and mounting a zSeries file system (zFS) for Open Multiple Virtual Storage (OMVS)
  • Creating a standard Liberty server instance with the option of custom configuration files
  • Enabling z/OS® authorized services
  • Starting an angel process or a server process
• deprovision.yml - Handles the following tasks:
  • Stopping an angel process or a server process
  • Removing a Liberty server directory
  • Unmounting a zFS file system
  • Deleting a zFS file system
  • Deleting JCL procedure templates

Role Summary

• create_zFS- Holds tasks to create and format a zFS file system.
• mount_zFS- Holds tasks to mount a zFS file system.
• create_server- Holds tasks to create a Liberty server instance.
• configure_server- Holds tasks to transfer optional configuration files for a Liberty server.
• started_server- Holds tasks to create System Authorization Facility (SAF) STARTED profiles for running the Liberty server process as a STARTED task.
• angel_config- Holds tasks to create a SAF STARTED profile for the Liberty angel process to run as a STARTED task, or to create a SAF SERVER profile to enable the Liberty server access to z/OS® authorized services.
• authorized_services- Holds tasks to enable optional z/OS® authorized services.

Permissions

Before getting started, you must ensure you have the proper permissions to use RACF commands to run the roles listed below.

1. started_server
2. angel_config
3. authorized_services

Getting Started

If you are unfamiliar with playbooks, you can review our detailed configuration guide or continue with getting started below.

Optionally, you can use the sample host_setup to discover and create your inventory and host_vars artifacts. Please note that when you use the host_setup, it will generate a configuration for the most common dependencies, some playbooks require more customized configurations, in this case, you can review the sample documentation and add the additional required variables.

1. Update inventory.yml with the information about your systems

zsystem:
  hosts:
    zos:
      ansible_host: zos_target_address
      ansible_user: zos_target_username

2. Update the environment variables for the z/OS® system in host_vars/zos_host.yml

NOTE: if WLP_USER_DIR is not specified, it will default to ${wlp.install.dir}/usr.

# the path to the root of IBM python installation
PYZ: "/usr/lpp/IBM/cyp/v3r8/pyz"

# the path to root of ZOAU installation
ZOAU: "/usr/lpp/IBM/zoautil"

# the path to the root of JAVA installation
JAVA: "/usr/lpp/java170/J7.0_64"

# the path to user directory that contains the server instance configuration
WLP_USER_DIR: '/u/oeusr01'

# the path to the root of Liberty installation
liberty_path: '/usr/lpp/zWAS/WAS900/Liberty/V19R00'

3. Add a name for the zFS dataset that will be mounted to the user directory in host_vars/zos_host.yml

data_set_name: targetuser.liberty.zfs

4. Update user information for creating STARTED profiles in host_vars/zos_host.yml

NOTE: Ensure you have the correct permissions to write to the PROC_LIB you specified.

TARGET_USER: target_user
USER_GROUP: user_group

#Procedure library for JCL Procedure template
PROC_LIB: USER.PRIVATE.PROCLIB

5. Update custom server variables based on the desired behavior for the Liberty instance in host_vars/zos_host.yml

CUSTOMIZE: no
ANGEL: no
AUTHORIZED_SERVICES: no

6. Customize the availability of authorized services on the z/OS® system for the server. Within the authorized_services role, there are variables with boolean values in authorized_services/defaults/main.yml to represent which z/OS® authorized services to enable.

SAFCRED: yes
ZOSWLM: yes
TXRSS: yes
ZOSDUMP: yes
LOCAL_ADAPTER: no
PRODMGR: no
ZOSAIO: no

7. Run playbook

NOTE: Running the commands with tags will have precedence over the conditionals within the playbook

To start the server and angel process (if enabled):

ansible-playbook -i inventory.yml provision.yml

To just start the server:

ansible-playbook -i inventory.yml provision.yml --skip-tags "start_angel"

To just stop the server and keep the angel process:

ansible-playbook -i inventory.yml deprovision.yml --skip-tags "stop_angel"

To just stop the server and angel process:

ansible-playbook -i inventory.yml deprovision.yml --tags "stop,stop_angel"

Copyright

© Copyright IBM Corporation 2021

License

Licensed under Apache License, Version 2.0

Author Information

Stephanie Lieu - @stephanie-lieu or @steph-lieu

Support

Please refer to the support section for more details.