This post covers the customising you need to consider enterprise use of the Liberty MQWEB server. It covers
- Setup the USS path and defining an alias for the mq executable’s directory
- Do you have common configuration across mqwebuser.xml files?
- Decide if you want to use setmqweb.
- Setting up the server’s certificate and keyring
- Setting up the trust store
- Setting up the Angel process(es)
- Reserving the TCP/IP Port number
- Customising the jvm.option
- To prevent the web server coming up if the Angel process is missing
- Setting the time zone
- Customising the mqwebuser.xml
- SAF definitions
- Setting the log sizes so the logs can be viewed
- Letting requests in from outside of the LPAR
- dspmqweb/setmqweb – which instance to use?
- Selecting which IP stack to use
- Customising ISPF option 3.17 – Unix Directory List
Setup the USS path and defining an alias for the mq executable’s directory
To be able to use the dspmweb and setmqweb commands you need to point to the command location.
You can add to the user’s .profile file, or the /etc/profile the statement
export PATH=/usr/lpp/mqm/V9R1M1/web/bin:$PATH
If you have multiple releases of MQ in your environment you could set up shell commands like v913dspmqweb.sh
/usr/lpp/mqm/V9R1M3/web/bin/dspmqweb "$@"
But this causes extra work when you need to migrate to the new release. It might be better to set up an alias
ls -s /usr/lpp/mqm/V9R1M3/web/bin /v913
ls -s /usr/lpp/mqm/V9R1M3/web/bin /mqcur
so you just need to type /v913/dspmweb or /mqcur/setmqweb
As part of the migration to a newer release you just change the alias.
Do you have common configuration across mqwebuser.xml files?
If you have multiple mqweb instances, either because you have multiple LPARs in a sysplex, or you have to support different release of MQ concurrently, you may want to put common configuration in an include file. For example created a file common.xml to hold the configuration and put
<include location=”common.xml” optional=”false”/>
in the mqwebuser.xml file.
Decide if you want to use setmqweb.
You can update your *.xml configuration files, or use setmqweb to update mqwebuser.xml for you.
Some organisations do not allow manual changes to configuration. You have to change a configuration file, have it reviewed, and use automation to deploy it.
For test systems it may be ok to use the setmqweb command and change things dynamically.
If you make a change using setmqweb, it updates the mqwebuser.xml file, by adding/changing a <variable name=”…” value=”..”/> statement.
If you are using SAF authentication and certificate authentication
You will need keyring with the certificate to identify the server (the key store). You will need a keyring to identify the certificates you trust (the trust store). You could use the same keyring for both – but this is not good practice.
The server’s certificate and key store keyring
You need to decide if the MQWEB server uses the same certificate as CICS, WAS and z/OS Connect etc. on the same LPAR. You could have a common certificate to simplify administration. The certificate needs a Subject Alternative Name, to identify the machine the certificate came from. This can be the DNS name or the dotted address (9.20.4.6) depending on your set up. It might be easier to define both. Note the RACF command
RACDCERT .. ALTNAME(IP(10.1.1.2) IP(10.1.1.3) DOMAIN(‘WWW.ME.COM’) DOMAIN(‘WWW.LAST.COM’))…
accepts multiple entries, but only uses the last one. The above command gave produced a certificate with
Subject's AltNames:
IP: 10.1.1.3
Domain: WWW.LAST.COM
This means you many only be able to use the certificate only on the LPAR that has been defined, (if you move the server to a different LPA, it will have a different IP address, and your clients will complain – see below). You may be able to something clever things with VIPA (Virtual IP addressing) where your Sysplex has one IP address and this maps to different IP addresses on each LPAR.
If you have the wrong IP or Domain then the browser gets a message like “Your connection is not private. Attackers may try to steal your information from 10.1.1.2. NET:ERR_COMMON_NAME_INVALID”
The trust store keyring.
The trust store keyring has the certificates to authenticate what has been sent from the client. For example, a copy of any self signed certificate, or the Certificate Authorities of the Web Browser’s certificate.
This keyring could be sysplex wide, and shared by CICS, WAS, Z/OS connect etc – assuming they have the same people connecting to them.
The certificates may have been configured with owner CERTAUTH rather than an userid.
My definitions
<sslDefault sslRef="defaultSSLConfig"/>
<ssl id="defaultSSLConfig"
sslProtocol="TLSv1.2"
keyStoreRef="racfKeyStore"
trustStoreRef="racfTrustStore"
clientAuthenticationSupported="true"
clientAuthentication="true"
serverKeyAlias="MYMQWEB/>
<keyStore filebased="false" id="racfKeyStore"
location="safkeyring://START1/KEY"
password="password"
readOnly="true"
type="JCERACFKS"/>
<keyStore filebased="false" id="racfTrustStore"
location="safkeyring://START1/TRUST"
password="password"
readOnly="true"
type="JCERACFKS"/>
<webAppSecurity allowFailOverToBasicAuth="false"/>
- The sslDefault points to the ssl with the same ID
- The ssl points to
- the key store with the servers certificate with the id racfKeyStore
- the trust store to validate connecting clients, with the id racfTrustStore
Create an angel
You need an Angel process to handle the SAF (RACF) security requests – the MQ documentation tells you this.
Typically the Angel started task is started at IPL, and shut down at system shut down.
All instances of Liberty Web Server running on an LPAR can all use the same Angel, for example the z/OSMF angel IZUANG1.
You cannot shut down the Angle process if it is in use, but if you cancel it, the servers using it will stop working (hang) and may abend.
You may want to consider more than one Angel process, and not share it.
When the Angel process has started, it uses no CPU, as the Web Servers execute code within the Angel address space, on the Web Server’s threads – just like MQ, DB2 etc.
Customise jvm.options
Stop if there is no Angel process
If the Angel process is not running at Liberty startup, then the Web Server may continue to come up. People will not be authorised to access it, but the Web Server will be running. This is pretty useless.
You can specify an option so the liberty server (MQWEB) does not start if the Angel task is not running.
I use
-Dcom.ibm.ws.zos.core.angelRequired=true
#-Dcom.ibm.ws.zos.core.angelName=MYANGEL
-Dcom.ibm.ws.zos.core.angelRequired=true
If the angel process is not available then the MQWEB stops when it detects the angel is not available.
#-Dcom.ibm.ws.zos.core.angelName=MYANGEL
If you are using a names Angel, uncomment this and specify the Angel name.
If you are using the unnamed Angel, leave this commented.
Set the time zone
The time zone is picke up from TZ in /etc/profile, but you can override it by specifying
-Duser.timezone=Europe/London
This sets the time-zone of the messages in the message.log and trace.log files.
Reserve the TCP/IP port number
It is a good idea to talk to the networking team and get them to update the TCP/IP configuration for example
PORT
20 TCP OMVS NOAUTOLOG ; FTP Server
21 TCP OMVS ; FTP Server
22 TCP SSHD* ; port for sshd daemonrver
23 TCP TN3270 ; Telnet 3270 Server
...
1414 TCP CSQ9CHIN ; CSQ9 MQ TCP Listener
...
9443 TCP MQWEB ; Colin Paice MQWEB
Customise mqwebuser.xml
Message log and trace file settings
If the trace or message files are too big, you cannot view them. You have to use edit to look at them, but if the file is too large, browse is substituted and browse does not do code page conversion, so you are looked at raw ascii characters in an EBCDIC browser.
<variable name=”maxTraceFileSize” value=”20″/>
<variable name=”maxTraceFiles” value=”20″/>
<variable name=”maxMsgTraceFileSize” value=”20″/>
<variable name=”maxMsgTraceFiles” value=”20″/>
The file size values are in MB.
You should consider keeping you messages.log files for a week or so, so make the number of files large enough.
SAF – Access to RACF
If you are using SAF (RACF or other z/OS security manager) to manage access and authorisation you will have a default entry like
<!--
Example SAF Registry
-->
<safAuthorization racRouteLog="NONE" id="saf" />
<safRegistry id="saf" />
<safCredentials unauthenticatedUser="WSGUEST" profilePrefix="MQWEB"
suppressAuthFailureMessages="false" />
I use <safAuthorization racRouteLog=”ASIS”… to get RACF violation messages on the joblog during set up. See here.
<safRegistry suppressAuthFailureMessages=”false”… prints out violation messages. See here.
Let request in from outside z/OS
For this to work you have to edit the mqwebuser.xml file and uncomment
<variable name="httpHost" value="*"/>
<!--
-->
By default it only allows request from the same z/OS system – so not allowing browsers access.
dspmqweb/setmqweb – which instance to use?
This page says you must use
export WLP_USER_DIR=WLP_user_directory
This is fine when you have one mqweb instance on one LPAR. You might want a shell program to set this every time. For example, the program disMQPAweb.sh
export WLP_USER_DIR=/u/mqmweb/MQPA
/usr/lpp/mqm/V9R1M1/web/bin/dspmqweb "$@"
Then you can use /usr/lpp/mqm/V9R1M1/web/bin/dspmqweb as before.
If you have multiple releases of MQ in your environment you might want to point to the command in the script, so dspMQPA.sh might have
export WLP_USER_DIR=/u/mqmweb/MQPA
/usr/lpp/mqm/V9R1M1/web/bin/dspmqweb "$@"
Though it might be better to have a shell script mq911 with an optional queue manager parameter
Selecting which IP stacks to use.
There is an article from IBM, which gives two ways of configuring it. Changing the httpEndpoint, or specifying an environment variable
Customise ISPF z/OS UNIX Directory List
In the MWEB directory are message logs and trace logs. When the file fills up, it renames the old file to include the date and time, for example messages_20.07.29_16.49.29.0.log , and creates a new message.log or trace.log
If you are using ISPF 3.17 (z/OS UNIX Directory List) to use the files, it only displays the first 15 characters of the file name, so you get lots of files with a name like “messages_20.07.” where 20 is the year, and 07 is the month.
The default layout for the z/OS UNIX Directory List displays by default some unhelpful fields. You can arrange the fields, (but not make the filename field wider).
If you go to the OPTIONS on the top line, and select “2. Directory List Column Arrangement… ” you can change what fields are displayed, and the order. I set the widths of all fields to 0, except for
- Type 04
- Modified 19 (if you specify a smaller value you only get the YYYY-MM… not the time)
- Size 10
The documentation says
- Modified The date and time the file was last changed.
- Changed The date and time the status of the file was last changed.
I do not know the difference between these two.
Controlling what is displayed
In the directory list you can use sort commands
Looking at a log or trace file
If you sort by Modified A the newer files will be at the top, so you can look at the “modified” column to look for the time the file was created, and so get the order of the files.
You can use the line command / to display the options.
You can use e to edit, or V to use edit in browse mode.
Browse displays a mess because it does not do conversion
ColinPaice 