Pegasus Enhancement Proposal (PEP)

PEP #: 284

PEP Type:  Functional

Title: Enhancement: Porting Pegasus to i5/PASE platform

Version: 1.6  

Created: 7 Nov 2006 

Authors: Jun Feng Liu (liujunf@cn.ibm.com)

Status:  Approved

Version History:

Abstract:  This document describes the design for moving CIM functionality to run in Portable Application Solutions Environment (PASE) for V5R5 (and back to V5R4). Also include some specific features for i5/PASE.

Definition of the Problem

Pegasus server has been part of OS400 base system in V5R3 and V5R4 releases.  However, porting open source code to i5/ILE has proved to be very inefficient in terms of development resource.  The ability to use OpenSSL for secure http functionality and porting CMPI APIs has been hindered by the tremendous work effort and technical difficulties for the i5 system, and to date these critical functions have not been supported.

IBM iSeries will drop the supporting to the i5/ILE and port Pegasus from i5/ILE to i5/PASE. This document will describe the modification to be done as the following:

-        Support new PEGASUS_PLATFORM defination: PASE_ISERIES_IBMCXX

-       Add macro PEGASUS_OS_PASE to protect  I5/PASE specific code

-       Add several new ICU messages in pegasusServer_en.txt

Proposed Solution

Porting work already finished based on Pegasus version 2.5.1, the product close to the end of FVT. FVT target date is 11/17. We plan to merge the code into cvs main branch to catch the updating in the future release. The merge works include two steps. The main idea is to remove the obsolete i5/ILE code from cvs at step one(OS400 macro will be removed from the code stream), then merge our platform specific code into cvs at step two.

The PEP describes the i5/PASE specific logic will be submitted to main branch. Then a bunch of bugzillas that associated with the PEP will be created to record the code changes.

 The PEP does not involve the details of each modification. But it covered all the files that will be changed. We will use bugzilla to recorder the detail information of the code changes.  Product based on the Pegasus 2.5.1, so the code change list is based on the comparison with Pegasus 2.5.3 code.

- Makefile

 
pegasus/mak/platform_PASE_ISERIES_IBMCXX.mak
PEGASUS\mak\shared-library-unix.mak

Following makefile is updated to involve i5/PASE specific code into build. ---  We will check if the macro PEGASUS_PLATFORM equal to PASE_ISERIES_IBMCXX and do some specific logic for i5/PASE.  Here we only list the files that we plan to modify, not include the detail of code changes. We will use bugzilla and diff file to maintain the details

PEGASUS\src\Clients\cimconfig\Makefile
PEGASUS\src\Pegasus\Common\Makefile
PEGASUS\src\Pegasus\Compiler\cmdline\cimmof\Makefile
PEGASUS\src\Pegasus\ControlProviders\CertificateProvider\Makefile
pegasus/src/Pegasus/Security/Authentication/Makefile
pegasus/src/Pegasus/ProviderManagerService/ProviderAgent/Makefile
PEGASUS\src\Server\Makefile

Add several message entry for i5/PASE platform. The change will be attached

here with diff files.

 --- pegasusServer_en.txt

src.Server.cimserver.NO_AUTHORITY.PEGASUS_OS_PASE:string {"PGS10040: Caller should be privileged user. Server will not run."}
src.Server.cimserver.NOT_OFFICIAL_START.PEGASUS_OS_PASE:string {"PGS10041: cimserver can not be started by end user."}
src.Server.cimserver.SET_CCSID_ERROR.PEGASUS_OS_PASE:string {"PGS10042: set ccsid failed, server stop."}
src.Server.cimserver.SERVER_JOB_NAME.PEGASUS_OS_PASE:string {"PGS10043: CIM Server's Job Name is: {0}."}
src.Server.cimserver.SYNTAX_ERROR.PEGASUS_OS_PASE.PEGASUS_OS_PASE:string {"PGS10058: Found syntax error when trying to migrate cimserver_planned.conf in /QIBM/UserData/OS400/CIM."}
Pegasus.Server.CIMServer.INVALID_SSLCONFIGURATION.PEGASUS_OS_PASE:string {"PGS13201: The sslTrustStore configuration property must be equal to the exportSSLTrustStore property.  CIM Server not started."}
Pegasus.Server.SSLContextManager.INVALID_CONF_HTTPS_REQUIRED.PEGASUS_OS_PASE:string {"PGS13311: Do not set the \"sslClientVerificationMode\" property to \"required\" if HTTP is disabled because the cimserver will be unable to properly shutdown. It is recommended that you change the property value to \"optional\". The CIM server is not started."}
ProviderManager.ProviderAgent.cimprovagt.NOT_OFFICIAL_START.PEGASUS_OS_PASE:string {"PGS13810:  provider agent can not be started by end user."}
ProviderManager.ProviderAgent.cimprovagt.SET_CCSID_ERROR.PEGASUS_OS_PASE:string {"PGS13811:  set ccsid failed. stop."}
ProviderManager.ProviderAgent.cimprovagt.PROVAGET_JOB_NAME.PEGASUS_OS_PASE:string {"PGS13812:  Provider Agent's Job Name is: {0}."}
ProviderManager.ProviderAgent.ProviderAgent.RECEIVE_SYN_SIGNAL.PEGASUS_OS_PASE:string {"PGS14010:  "\"{0}\" received synchronous signal."}
ProviderManager.ProviderAgent.ProviderAgent.RECEIVE_ASYN_SIGNAL.PEGASUS_OS_PASE:string {"PGS14011:  "\"{0}\" received asynchronous signal."}

- i5PASE specific code changes focus on:

1.       Platform specific define

Pegasus for I5/PASE has its own platform define:

\PEGASUS\src\Pegasus\Common\Platform_PASE_ISERIES_IBMCXX.h

Related header will be modified to include Platform_PASE_ISERIES_IBMCXX.h

\PEGASUS\src\Pegasus\Common\Config.h

Constants.h is updated to covered the PASE default define.

\PEGASUS\src\Pegasus\Common\Constants.h

# elif defined(PEGASUS_OS_PASE)

#  undef CIMSERVER_LOCK_FILE

#  define CIMSERVER_LOCK_FILE "/QOpenSys/QIBM/UserData/UME/Pegasus/cimserver_start.lock"

#  undef PEGASUS_SSLCLIENT_CERTIFICATEFILE

#  define PEGASUS_SSLCLIENT_CERTIFICATEFILE  "/QOpenSys/QIBM/UserData/UME/Pegasus/client.pem"

#  undef PEGASUS_SSLCLIENT_RANDOMFILE

#  define PEGASUS_SSLCLIENT_RANDOMFILE      "/QOpenSys/QIBM/UserData/UME/Pegasus/ssl.rnd"

#  undef PEGASUS_SSLSERVER_RANDOMFILE

#  define PEGASUS_SSLSERVER_RANDOMFILE      "/QOpenSys/QIBM/UserData/UME/Pegasus/ssl/keystore/cimserver.rnd"

#  undef PEGASUS_LOCAL_AUTH_DIR

#  define PEGASUS_LOCAL_AUTH_DIR            "/QOpenSys/var/UME"

#  undef PEGASUS_LOCAL_DOMAIN_SOCKET_PATH

#  define PEGASUS_LOCAL_DOMAIN_SOCKET_PATH  "/QOpenSys/var/UME/cimxml.socket"

#  undef PEGASUS_PAM_STANDALONE_PROC_NAME

#  define PEGASUS_PAM_STANDALONE_PROC_NAME  "/QOpenSys/QIBM/ProdData/UME/Pegasus/bin/cimservera"

#  undef PEGASUS_PROVIDER_AGENT_PROC_NAME

#  define PEGASUS_PROVIDER_AGENT_PROC_NAME  "/QOpenSys/QIBM/ProdData/UME/Pegasus/bin/cimprovagt"

2.       Default Configuration properties:

Following table list the default configuration properties value on i5/PASE.

3.       Logger wrap:

We do not hope logs grow to unlimited size, we make it wrapped at a specified size. Macro PEGASUS_PASE_LOG_BACKUP_POSTFIX is used to define the postfix that will add to the log file to back it up. It’s default value is “.bak”. Macro PEGASUS_PASE_LOG_WRAP_SIZE specifies the size of the log file wrap. It’s default value is 4M. When the log file gets bigger than PEGASUS_PASE_LOG_WRAP_SIZE, we copy it to a back up file, and then truncate the log file.  If the back up file already exists, it will be removed.

The functionality will be move to PEP 302 as a common feature. Will not check in the part code with this PEP :

\PEGASUS\src\Pegasus\Common\Logger.cpp

4.       Security:

 Pegasus authorization/authentication should integrate with i5 system. List several modification here:

• \PEGASUS\src\Pegasus\Common\SystemUnix.cpp
  

      Updated SystemUnix.cpp System::isPrivilegedUser() function to check *IOSYSCFG and *ALLOBJ on i5 system.

      Change to set the profile handle, not to call setuid( ).  This means to change System::changeUserContext in SystemUnix.cpp for PASE to set the profile handle. 

•  \PEGASUS\src\Pegasus\Security\Authentication\SecureBasicAuthenticator.cpp
  

In SecureBasicAuthenticator.cpp there currently exists some OS400-specific logic to do user and password verification. For the PASE environment this basic logic will remain, but will be modified to use functions that are available to the PASE platform.

• \PEGASUS\src\Pegasus\Security\UserManager\AuthorizationHandler.cpp

• \PEGASUS\src\Pegasus\ControlProviders\CertificateProvider\CertificateProvider.cpp

• \PEGASUS\src\Pegasus\Server\CIMOperationRequestAuthorizer.cpp

Keeping the OS400 logic but that it will be protected by the PEGASUS_OS_PASE macro. On i5, we always check authorization if remote user. but always allow local privileged users through. Check authorization for local non-privileged users. (Other platform check authorization for all the non-privileged user)

Dummy code here:
#if !defined(PEGASUS_OS_PASE)
        if ( ! System::isPrivilegedUser(userName) )
#else
        if ( ! String::equalNoCase(authType,'Local')||! System::isPrivilegedUser(userName) )
#endif
         { //... do authorization here

          }

• \PEGASUS\src\Pegasus\ProviderManager2\OOPProviderManagerRouter.cpp

7.       Command Line

Several of the Pegasus commands have OS-400 specific authority checks that are protected by the PEGASUS_OS_OS400 macro. These checks will remain but will instead be protected by the PEGASUS_OS_PASE macro.

Keep the ‘quiet’ option character used to specify no output to stdout for Cimprovider, Cimconfig and Cimmof/Cimmofl

8.       CCSID

 CCSID is a special concept on i5, we require to set it to 1208 to support g11n, but it effect socket bind function, so have to restore it when the bind function invoke. The code implemented in following source file with PEGAUS_OS_PASE protection

\PEGASUS\src\Pegasus\Common\HTTPAcceptor.cpp

\PEGASUS\src\Pegasus\Common\HTTPConnector.cpp

\pegasus\src\Pegasus\ProviderManager2\cimprvagt.cpp

9.       Logging changes for Pegasus and Out-of-process providers

 The cimserver and provider agent signal handler flow for the synchronous signals should write the error info to the Pegasus log, write the job name to the Pegasus log, and change job attributes to save the job log before the process exits.

The CIM server uses out-of process provider. It will fork a child process according to the provider module and user request context. The PASE process is basically an i5/OS native job and i5/OS creates job logs for it.  The provider code run in ILE part may throw exception. I5OS native system can record the error information into job log. As a result, the information reported by server will go into the server job log and providers’ information will save in their own job logs. It not easy to find out the failure information from so many job logs. 

Synchronous exceptions from ILE are always converted to signals by i5/OS PASE infrastructure. We want those signals can be caught by signal handler of the CIM provider process. The signal handler will write the job name informaion into Pegasus log file, so that user can found related job log.  Synchronous Signal include SIGFPE, SIGILL, SIGSEGV.

The server and provider agent have a signal handler for sigterm and sighup. This handler does the graceful shutdown. These signals happen for an asynchronous external event such as ending the job. We do not modify the signal handle for this. Pegasus already have graceful shutdown for sigterm and sighup

\PEGASUS\src\Pegasus\ProviderManager2\ProviderAgent\ProviderAgent.cpp

\PEGASUS\src\Pegasus\ProviderManager2\ProviderAgent\ProviderAgent.h

\PEGASUS\src\Pegasus\ProviderManager2\ProviderAgent\cimprovagt.cpp

\PEGASUS\src\Pegasus\Server\CIMServer.cpp

\PEGASUS\src\Server\cimserver.cpp

Rationale

Schedule

Discussion

Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
EMC Corporation; Symantec Corporation; The Open Group.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 Liu Jun Feng 10/11/2007