Troubleshooting
Problem
IBM i administrators can route specified connections to different subsystems based on two criteria:
1) The client TCP/IP address
2) The user ID passed on the connection
The criteria are not exclusive.
For more information about routing connections based on client IP address or user ID, see, "Routing Connections to Subsystems based on user ID" or SET_SERVER_SBS_ROUTING procedure .
This document describes how to configure a set of host server jobs to run in a custom subsystem based on the IP address of the client.
Resolving The Problem
Certain jobs can be run in user-defined subsystems. In addition, the same types of client requests can be routed to multiple subsystems based on the TCP/IP address of the client. This functionality allows system administrators to control work management properties (such as job priority or storage pool) on a subsystem-by-subsystem basis. The connection is directed to a job in a particular subsystem at the inception of the connection, when the only information available is the TCP/IP socket information (client and host IP addresses and ports).
All the host server daemon jobs run in the QSYSWRK subsystem except for the file (QPWFSERVSD) and database server (QZDASRVSD) daemon jobs, which run in the QSERVER subsystem.
All the host server daemon jobs run in the QSYSWRK subsystem except for the file (QPWFSERVSD) and database server (QZDASRVSD) daemon jobs, which run in the QSERVER subsystem.
The server jobs allocated for each client connection - Network Print (QNPSERVS); Remote command and program call (QZRCSRVS); Central (QZSCSRVS); Data Queue (QZHQSSRV); Signon (QZSOSIGN), and Database (QZDASOINIT), default to QUSRWRK subsystem.
The DDM server jobs (QRWTSRVR), file server jobs (QPWFSERVSO), and NetServer client jobs (QZLSFILE) can also be customized to run in different or multiple subsystems.
Create a New Subsystem or Modify an Existing Subsystem Description
It all starts with a subsystem description that has the proper settings to allow a host server prestart job to run within that subsystem. Do that by creating a new subsystem description and adding the entries that it needs or make a copy of the default subsystem description and remove what you don't need. Usually it is easiest to make a copy of the QUSRWRK subsystem. For example, create a new subsystem, CRTSBSD SBSD(MYSBSD) POOLS((1 *BASE)) or make a copy of QUSRWRK, CRTDUPOBJ OBJ(QUSRWRK) FROMLIB(QSYS) OBJTYPE(*SBSD) NEWOBJ(MYUSRWRK). If you make a copy of the QUSRWRK subsystem, be certain to remove the job queue entry on your copy (RMVJOBQE SBSD(MYUSRWRK) JOBQ(QUSRNOMAX)). Only one subsystem can allocate the job queue at a time. If you made a copy of QUSRWRK the prestart job entries are already in your subsystem description; unless you want to modify them, there is nothing further that must be done. If you created a new subsystem description, then you need to add the appropriate prestart job entries to the subsystem description. For example, I want to direct my ODBC connections to the MYSBSD subsystem so I need to add a prestart job entry for the database host server: ADDPJE SBSD(MYSBSD) PGM(QZDASOINIT) JOBD(QGPL/QDFTSVR) CLS(QSYS/QPWFSERVER). The program value cannot change from the one specified in the original subsystem but the other values might be different. Be sure to check the class value (CLS keyword); it defaults to *SBSD for a value. If you use the default value and do not have a class with the same name as your subsystem description, the prestart jobs fail to start. It is recommended that the Start jobs (STRJOBS) parameter for the prestart job entry is set to *YES because the STRHOSTSVR command does not start the prestart jobs in nondefault subsystems. Remember to start this custom subsystem during the startup program and after backups complete.
Configuring the Host Servers
Create a New Subsystem or Modify an Existing Subsystem Description
It all starts with a subsystem description that has the proper settings to allow a host server prestart job to run within that subsystem. Do that by creating a new subsystem description and adding the entries that it needs or make a copy of the default subsystem description and remove what you don't need. Usually it is easiest to make a copy of the QUSRWRK subsystem. For example, create a new subsystem, CRTSBSD SBSD(MYSBSD) POOLS((1 *BASE)) or make a copy of QUSRWRK, CRTDUPOBJ OBJ(QUSRWRK) FROMLIB(QSYS) OBJTYPE(*SBSD) NEWOBJ(MYUSRWRK). If you make a copy of the QUSRWRK subsystem, be certain to remove the job queue entry on your copy (RMVJOBQE SBSD(MYUSRWRK) JOBQ(QUSRNOMAX)). Only one subsystem can allocate the job queue at a time. If you made a copy of QUSRWRK the prestart job entries are already in your subsystem description; unless you want to modify them, there is nothing further that must be done. If you created a new subsystem description, then you need to add the appropriate prestart job entries to the subsystem description. For example, I want to direct my ODBC connections to the MYSBSD subsystem so I need to add a prestart job entry for the database host server: ADDPJE SBSD(MYSBSD) PGM(QZDASOINIT) JOBD(QGPL/QDFTSVR) CLS(QSYS/QPWFSERVER). The program value cannot change from the one specified in the original subsystem but the other values might be different. Be sure to check the class value (CLS keyword); it defaults to *SBSD for a value. If you use the default value and do not have a class with the same name as your subsystem description, the prestart jobs fail to start. It is recommended that the Start jobs (STRJOBS) parameter for the prestart job entry is set to *YES because the STRHOSTSVR command does not start the prestart jobs in nondefault subsystems. Remember to start this custom subsystem during the startup program and after backups complete.
Configuring the Host Servers
IBM Navigator for i can be used to customize the daemon so that nondefault subsystems are used. Starting with IBM i 7.3, routing to the subsystem by IP address can also be done by using the SQL stored procedure SET_SERVER_SBS_ROUTING.
The Navigator for i GUI changed significantly from the "Heritage version" to the "New" version. This document presents images accomplishing the same task from both versions.
Navigator for i (Heritage version) for IBM i 7.2 and previous:
Do the following:
| 1. | Start IBM Navigator for i. |
| 2. | Expand the Network container, then Servers. |
| 3. | Click IBM i Access Servers. A list of servers appears in the right pane of Navigator. |
| 4. | Right-click on the server you want to customize, and select Properties. Note: For DDM/DRDA and the IBM i NetServer, you must select TCP/IP rather than 'IBM i Access Servers'. You see a General tab with where you can specify that the server is started with TCP/IP. A Subsystems tab (see the following image) where you can determine whether you use the system defaults (QUSRWRK), whether all clients get routed to one subsystem (could be the default or a custom subsystem), or whether only certain TCP/IP addresses get routed to the custom subsystem. The last two options also allow for an alternate action to be defined when the prestart job is not available. The alternate action options are to reject the request or to run in the current subsystem as a batch-immediate job. The current subsystem is defined as the subsystem in which the daemon runs (QSYSWRK for most servers). |
For this example, I want to route only one client, at IP address 9.10.77.68 into the MYSBSD subsystem when it is available and connections from that system must be rejected when that subsystem isn't available (maybe because the program that runs on that machine puts update locks on files I need to back up and I want an easy way to shut down just those connections for a time to run backups). All other connections remain in the QUSRWRK subsystem and be diverted to the default subsystem when QUSRWRK isn't available. The first thing I need to do is to change the option from 'Use server defaults' to 'Specific client' as shown next.
Next, I have to click 'Add' to create my entry for the specific system that I want routed to the MYSBSD subsystem. When you click 'Add', you see a dialog box like the one shown in the next image. You must select which IP family (IPv4 or IPv6) you are using, an IP address appropriate for that family or a range of addresses, and a subnet mask. For my example I'm using an IPv4 address. Note the subnet mask applied to this address. Anything other than a value of all 255's (host route) results in multiple addresses being directed to this new subsystem. Because it is my intent to affect only this one client, I use the subnet mask, 255.255.255.255. Note also that I set the alternate action to 'Reject'. If I do not set the action to 'Reject', when I end the MYSBSD subsystem, this system is able to make new connections that run in the QSERVER subsystem, and I do not get the effect I want; preventing connections from this client when the subsystem is ended. Depending on what results you want, you might want to leave this action at the default, allowing connections to occur when the subsystem is not available.
Once all of the fields are completed on this dialog and OK is pressed, you see the database properties updated as shown next. Note the custom entry is added, and there is also an entry for the client '<Public>' This last entry is created for all other client addresses that are not selected by a previous entry. You can add as many entries to this list as you need.
New Navigator for i for IBM i 7.3 and later:
Navigate to and click "IBM Host Servers":
Right-click on the server to be customized and select "Subsystem Routing":
Where the configuration is stored
A table containing the configuration details can be generated by running the following SQL query:
SELECT * FROM QSYS2.SERVER_SBS_CONFIGURATION
ORDER BY SERVER_NAME, SERVER_SEARCH_ORDER;
The subsystem routing information is stored in user index QUSRSYS/QYSMSVRE. It is updated whenever entries are added, edited, or removed, and changes take effect immediately.
Historically, user index objects are not stable and can become damaged during an IPL. For this reason, it is recommended that you save this object to a save file after every modification and then restore it from your startup program during each IPL to guarantee its uninterrupted functionality. Create a save file (CRTSAVF FILE(QGPL/RTGIDX) TEXT('Save of QUSRSYS/QYSMSVRE User Index')). Anytime that the index is modified, save this object (SAVOBJ OBJ(QYSMSVRE) LIB(QUSRSYS) DEV(*SAVF) SAVF(QGPL/RTGIDX)). Add the command to restore it to your startup program (RSTOBJ OBJ(QYSMSVRE) SAVLIB(QUSRSYS) DEV(*SAVF) SAVF(QGPL/RTGIDX)). For more information about modifying your startup program, see Changing the IPL Start-Up Program.
Historically, user index objects are not stable and can become damaged during an IPL. For this reason, it is recommended that you save this object to a save file after every modification and then restore it from your startup program during each IPL to guarantee its uninterrupted functionality. Create a save file (CRTSAVF FILE(QGPL/RTGIDX) TEXT('Save of QUSRSYS/QYSMSVRE User Index')). Anytime that the index is modified, save this object (SAVOBJ OBJ(QYSMSVRE) LIB(QUSRSYS) DEV(*SAVF) SAVF(QGPL/RTGIDX)). Add the command to restore it to your startup program (RSTOBJ OBJ(QYSMSVRE) SAVLIB(QUSRSYS) DEV(*SAVF) SAVF(QGPL/RTGIDX)). For more information about modifying your startup program, see Changing the IPL Start-Up Program.
If you suspect the object is damaged, you can check the history log for message CPI116D referencing the QYSMSVRE index in the QUSRSYS library (DSPLOG MSGID(CPI116D)). You can also dump the object and check the eye-catcher information in the resulting output for routing information. Use the following command:
DMPSYSOBJ OBJ(QYSMSVRE) CONTEXT(QUSRSYS)
If the object is damaged, you must delete the object and restore from a previous backup. If you do not restore the object, the next use of a host server job causes it to re-create with the default settings. In other words, all connections are routed to the original default subsystems for that server. Do not rename the damaged index, as an internal system pointer is used to access the index and new connections continue to use the renamed index. Renaming the index simply makes it difficult to locate.
Related Information
[{"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"Component":"Host Servers","Platform":[{"code":"","label":""}],"Version":"Version Independent","Edition":"","Line of Business":{"code":"LOB57","label":"Power"}}]
Historical Number
18653736
Was this topic helpful?
Document Information
Modified date:
02 June 2022
UID
nas8N1019587