COMPAQ PROPRIETARY INFORMATION RELEASE NOTES Version 3.0 of Compaq DCE for OpenVMS VAX and OpenVMS Alpha Version 3.0 Version 3.0 of Compaq DCE for OpenVMS VAX and OpenVMS Alpha replaces Digital DCE for OpenVMS VAX and OpenVMS Alpha Version 1.5. Version 3.0 is a complete kit that does not require a previous version of Compaq DCE for OpenVMS for installation. Version 3.0 can be installed on a new system or can be installed as an update to a previous version of DCE for OpenVMS. ________________________ Note ________________________ Compaq DCE for OpenVMS V3.0 supports OpenVMS Version 6.2, 7.1, 7.2. See Sections 1.1 and 15 for new features and important restrictions and known problems. ______________________________________________________ 1 Services Compaq DCE Offers Version 3.0 of Compaq DCE for OpenVMS VAX and OpenVMS Alpha consists of the following services: o Remote Procedure Call (RPC) service provides connections between individual procedures in an application across heterogeneous systems in a transparent way. o Interface Definition Language (IDL) compiler (required for developing distributed DCE applications). o Threads service provides user-mode control and synchronization of multiple operations. Threads is packaged with the base operating system. o Cell Directory Services (CDS) provides a location- independent method of identifying resources within a cell. A cell is the smallest group of DCE systems that share a common naming and security domain. o Distributed Time Service (DTS) provides date and time synchronization within a cell. 1 o DCE Security Services provides authentication and authorization within a cell and is based upon MIT's Kerberos private key encryption system. 1.1 New Features in Version 3.0 Version 3.0 of Compaq DCE for OpenVMS VAX and OpenVMS Alpha includes the following new features. (For more information on these new features, see the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Product Guide, unless otherwise stated.) o OSF DCE R1.2.2 support. Compaq DCE for OpenVMS VAX and OpenVMS Alpha V3.0 is based on The Open Group's R1.2.2 version of DCE. Full documentation for features common to OSF DCE R1.2.2 is available in the R1.2.2 documentation. This version adds the following new features to DCE: - dced daemon and dcecp control program The RPC daemon (DCE$RPCD.EXE) has been replaced by a combined RPC and security client daemon (DCE$DCED.EXE). In addition, various command line programs (rpccp, cdscp, dtscp, acl_edit, rgy_edit) have been consolidated into a single new program (dcecp). The new commands which are available via dcecp can be seen by issuing the following command: $ dcecp -c help - Auditing A new auditing daemon (DCE$AUDITD.EXE) is available in DCE for OpenVMS V3.0. The configuration modify menu of the DCE setup command procedure allows this feature to be enabled or disabled, as well as the dcecp command line program. - Serviceability enhancements See Section 18 for information on using the routing file that is available as part of the new serviceability enhancements. 2 - New dtscp commands $ dtscp show clock resolution $ dtscp show time provider timeouts detected $ dtscp show local server not in group $ dtscp show servers not in group - New dts time providers DCE$SETUP.COM now allows you to configure one of the following time providers: Null Time Provider NTP Time Provider This functionality can be accessed via the configuration modify submenu. o Kernel Threads and Thread Manager upcalls support New in DCE for OpenVMS V3.0 is support for running DCE applications with Kernel Threads and upcalls enabled. o RPC_UNSUPPORTED_NETIFS and RPC_SUPPORTED_NETADDRS DCE for OpenVMS V3.0 adds the ability to control the use of DCE on systems with multiple network interfaces and/or IP addresses. o LDAP support DCE support for LDAP over GDA (Intercell communication) and LDAP over NSID (Windows NT access to the Name Service Interface) is available in DCE for OpenVMS V3.0. o DCE Privacy Kit included in base DCE kit The DCE Privacy kit has been retired, and the functionality has been combined into the base DCE kit. You now can use packet level privacy without a separate kit or license. This functionality is activated by setting the protect_level parameter in the rpc_binding_set_auth_info call to rpc_c_protect_level_pkt_privacy. 3 2 Contents of the Kits Compaq DCE for OpenVMS has four kits available: o Runtime Services Kit o Application Developer's Kit o CDS Server Kit o Security Server Kit Note that the right to use the Runtime Services Kit is included as part of the OpenVMS license. The other kits each require a separate license. The following sections list the contents of each of these kits. 2.1 Runtime Services Kit The Runtime Services provide the basic services required for DCE applications to function. The Runtime Services Kit contains the following: o NTLM (Windows NT LAN Manager) security (OpenVMS Alpha Version 7.2-1 and higher only) o Authenticated CDS Advertiser and Client Support o CDS Browser o DCE Control Program (dcecp) o CDS Control Program (cdscp) o Authenticated DCE RPC runtime support (supports DECnet, TCP, and UDP) o RTI (Remote Task Invocation) RPC for the Compaq ACMSxp TP product o Security Client Support o Integrated Login o A DCE_LOGIN tool for obtaining credentials o A RGY_EDIT tool for registry maintenance functions o KINIT, KLIST, and KDESTROY Kerberos tools 4 o An ACL_EDIT tool for access control lists (ACLs) for DCE objects o RPC Control Program (rpccp) o Name Services Interface Daemon (nsid); also known as the PC Nameserver Proxy o Native Kerberos support o XDS Directory Services o XDS Object Managment 2.2 Application Developer's Kit The Application Developer's Kit is used by developers to build DCE applications. The Application Developer's Kit contains the following: o The above contents of the Runtime Services Kit o A mechanism to act as a porting aid in mapping MSRPC calls to DCE RPC calls (OpenVMS Alpha Version 7.2 and higher only) o Required DCE application development header files o Interface Definition Language (IDL) compiler o DCE IDL Compiler with C++ Extensions (Object-Oriented RPC) o Generic Security Service (GSSAPI) o LSE Templates for IDL o UUID Generator o .H (Include) files and .IDL files for application development o Sample DCE applications 5 2.3 CDS Server Kit The CDS Server provides the naming services necessary for DCE clients to locate DCE server applications. The CDS Server Kit includes the following: o CDS server (cdsd) o Global Directory Agent (GDA) The Global Directory Agent (GDA) lets you link multiple CDS namespaces using the Internet Domain Name System (DNS), X.500, or LDAP. 2.4 Security Server Kit The Security Server provides security services necessary for authenticated RPC calls between DCE client and server applications to function. The Security Server Kit includes the following: o Security server (secd) o Tool used to create the security database (sec_create_db) o Security server administrative tool (sec_admin) 3 Installation/Configuration Prerequisites In addition to shutting down DCE itself, DCE RPC MUST also be shut down before installing DCE for OpenVMS V3.0. Failure to do so can result in inability to start DCE for OpenVMS V3.0. For DCE for OpenVMS V1.5, the proper shutdown order should be as follows: 1. Shut down DCE and clean up temp files $ @SYS$MANAGER:DCE$SETUP CLEAN 2. Shut down RPC $ @SYS$MANAGER:DCE$RPC_SHUTDOWN If you are running a version of DCE for OpenVMS prior to V1.5, then simply performing the first command will shut down both DCE and RPC. 6 As of OpenVMS V7.2, DCE RPC is supplied as part of the OpenVMS operating system, and may be running without a full DCE kit installed. In this situation, you only need to perform the second command listed above to shut down RPC. Compaq DCE for OpenVMS VAX and OpenVMS Alpha must be installed by running the DCE$INSTALL.COM procedure. Do not install the product by invoking the POLYCENTER Software Installation utility (PCSI) directly. DCE$INSTALL.COM calls PCSI and performs several preinstallation and postinstallation tasks. To install DCE, run the DCE$INSTALL.COM procedure as follows: $ @ddcu:DCE$INSTALL.COM [help] ! optional PCSI help See the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Installation and Configuration Guide for more information. Make sure that you run DCE$INSTALL.COM from a valid directory. Errors may occur during the installation that leave the default directory invalid. See the first chapter in the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Installation and Configuration Guide for information on installation and configuration prerequisites. You must configure DCE before starting it if you are installing DCE for the first time. Enter the following command: $ @SYS$MANAGER:DCE$SETUP CONFIGURE 3.1 Reconfiguring after Installation If you are installing a new version of Digital DCE for OpenVMS VAX and OpenVMS Alpha over an existing version, you do not have to reconfigure DCE after the installation. Before the installation, stop the DCE daemons by entering the following command(s): $ @SYS$MANAGER:DCE$SETUP CLEAN If you currently have DCE for OpenVMS V1.5 installed, you must also shut down RPC by issuing this command: $ @SYS$MANAGER:DCE$RCP_SHUTDOWN Then, after the installation, enter the following command: $ @SYS$MANAGER:DCE$SETUP START 7 3.2 Configuration prerequisite on OpenVMS V6.2 After installation of DCE for OpenVMS V3.0 on an OpenVMS 6.2 system, certain operations must be performed in order to enable DCE to operate correctly. After the first installation of DCE for OpenVMS V3.0 on V6.2, it is necessary to execute the following command file to properly set the timezone information on the system: $ @SYS$MANAGER:UTC$TIME_SETUP Once this command procedure has been run, and after DCE has been configured, the following two lines should be added to the system startup procedure, SYS$MANAGER:SYSTARTUP_VMS.COM: $ @SYS$MANAGER:DCE$TIME_SETUP $ @SYS$STARTUP:DCE$STARTUP These command procedures must be called in the order shown above. 4 Troubleshooting A chapter on troubleshooting is part of the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Product Guide. This chapter includes the following sections: o General troubleshooting hints o Time zone and time synchronization problems o Client/Server Check List 5 Updates to the System Login File To define foreign commands, have the system manager add the following to your SYLOGIN.COM after the installation: $ If F$SEARCH("SYS$MANAGER:DCE$DEFINE_REQUIRED_COMMANDS.COM")- .NES. "" THEN @SYS$MANAGER:DCE$DEFINE_REQUIRED_COMMANDS.COM $ If F$SEARCH("SYS$COMMON:[DCE$LIBRARY]DCE$DEFINE_OPTIONAL_COMMANDS.COM")- .NES. "" THEN @SYS$COMMON:[DCE$LIBRARY]DCE$DEFINE_OPTIONAL_COMMANDS.COM 8 6 Sizing for a Large Number of Users The DCE daemons require a number of system resources for each concurrent DCE client or server process. The default number of resources allocated to the daemons is based on a maximum of 70 concurrent users (servers and clients) running on a node. If you are running more than 70 DCE users on a node, you must do the following: 1. Stop DCE if it is running. 2. Define a system-wide logical called DCE$MAX_USERS to the maximum number of users desired. For example, to configure DCE for a maximum of 80 users, enter the following: $ define/system dce$max_users 80 Add this command to your system startup command file so that it is executed prior to starting DCE. 3. Restart DCE. Refer to Section 8.1 for information about adding TCP/IP sockets if the current number of sockets is insufficient for the number of DCE users running on the node. 7 Support for Applications The Application Developer's Kit provides support for building DCE applications using DCE Services. It provides Application Programming Interfaces (APIs) to RPC communication services, security services, and CDS name services via the RPC Name Services Interface (NSI). (Version 1.1 of Digital DCE for OpenVMS VAX and OpenVMS Alpha replaced the Local Directory Services (LDS) with the Cell Directory Services (CDS).) The Application Developer's Kit contains the IDL compiler and Runtime support. The header files and IDL files for developing applications are installed in the following directory: SYS$COMMON:[DCE$LIBRARY] DCE applications must also be linked with the following shareable image: SYS$LIBRARY:DCE$LIB_SHR.EXE This image provides the entry points and global symbol definitions for the DCE API services. 9 A link options file, SYS$COMMON:[DCE$LIBRARY]DCE.OPT, is also provided. It is recommended that this options file be included when linking your DCE applications. For example: $ LINK PROG,DCE:DCE/OPT Linking applications in this way makes your build procedures more portable between OpenVMS VAX and OpenVMS Alpha. It also prevents link environment changes from requiring changes to command files. To help you port a Microsoft RPC application to the DCE format, a shareable image called SYS$LIBRARY:MSRPC_MAPPING_ SHR.EXE can be used to link with the RPC application. This new image provides entry points that map a subset of Microsoft RPC calls to their DCE equivalents. To identify which APIs have been mapped, see the MSRPC_MAPPING.H file. This file must be included in the RPC application. 8 Using TCP/IP Services for OpenVMS (UCX) with DCE Version 3.0 of Compaq DCE for OpenVMS VAX and OpenVMS Alpha requires modification of several TCP/IP parameters for proper operation. You should carefully look through the parameters discussed in this section to understand any impact they may have on your local system. The changes necessary are dependent on which version of TCP/IP Services for OpenvMS you are using. Most of the modifications listed in this section are not necessary when using TCP/IP Services for OpenVMS V5 or greater. Any changes needed for V5 or greater are indicated as such in the text. All parameter changes described below, except for the cdsLib service definition, involve volatile parameters. That is, if TCP/IP is restarted on your system, the parameter settings revert back to predefined defaults, unless the configuration is also modified. The appropriate commands to modify both the volatile and configuration values are shown in the following sections. ________________________ Note ________________________ DCE$SETUP checks for incorrect TCP/IP settings. If DCE$SETUP cannot read the settings, an error message is written to DCE$SETUP.LOG. If you have TCP/IP Services for OpenVMS V5.x installed, then DCE$SETUP.COM does not check or modify the parameters. ______________________________________________________ 10 8.1 Sufficient TCP/IP Sockets DCE RPC and CDS use TCP/IP sockets for interprocess communication. The UCX default maximum number of sockets is inadequate for most DCE sites. It is recommended that this parameter be set to a value of at least 250. Your site may require a higher value if you are using UCX for other than DCE. To modify the number of TCP/IP sockets, enter the following commands with the appropriate value for the number of sockets. For example: $ UCX SET COMMUNICATION /DEVICE_SOCKETS=250 $ UCX SET CONFIGURATION COMMUNICATION /DEVICE_SOCKETS=250 If the number of sockets is insufficient for the number of DCE users running on the node, increase the number of device sockets by two for each additional DCE user (client or server). 8.2 Sufficient UCX Small and Large Buffers The number of UCX small and large buffers necessary for proper performance depends on the number of network software applications running on your system. As a minimum for DCE sites, the following values are recommended: Maximum Small Buffers = 600 Maximum Large Buffers = 200 Before you configure DCE, you should check the maximum and peak values for both small and large buffers as follows: $ UCX SHOW COMMUNICATION $ UCX SHOW COMMUNICATION/MEMORY A nonzero drop value or a nonzero wait value indicates that you should increase the maximum buffer value. In general, the maximum value should be at least 20 percent higher than the peak value. Additionally, these counts will change in the future, and should be checked periodically, making adjustments as necessary. For example: $ UCX SET COMMUNICATION/SMALL=(MAXIMUM:600) $ UCX SET CONFIGURATION COMMUNICATION/SMALL=(MAXIMUM:600) $ UCX SET COMMUNICATION/LARGE=(MAXIMUM:200) $ UCX SET CONFIGURATION COMMUNICATION/LARGE=(MAXIMUM:200) See the UCX System Management Guide for more information on tuning UCX. 11 8.3 UCX TCP Protocol Settings DCE CDS is sensitive to the values of the TCP protocol parameters of the underlying TCP communication package. Improperly setting these parameters may cause CDS client operations to appear to hang. (Hangs occur when the TCP parameters are incorrectly set and CDS client operations initiate operations that result in very large data messages being transferred between CDS clients and servers.) If this happens, other CDS clients continue to function and the hung client process may be aborted. You can examine the current settings of the UCX TCP protocol parameters with the command: $ UCX SHOW PROTOCOL TCP /PARAMETER 8.3.1 OpenVMS UCX TCP Parameter Settings The correct default settings for the UCX TCP protocol parameters on OpenVMS VAX systems are as follows: $ UCX SHOW PROTOCOL TCP /PARAMETERS TCP MTU size segment: disabled Delay ACK: disabled Loopback: disabled Drop timer: 600 Probe timer: 75 Receive Send Checksum: enabled enabled Push: disabled disabled Quota: 4096 4096 Note that the TCP /LOOPBACK and TCP/DELAY_ACK parameters must be disabled on Compaq DCE for OpenVMS. If either of these parameter settings do not match the default settings above, enter one of the following sets of commands: $ UCX SET PROTOCOL TCP /NODELAY ! Valid on TCPIP V5 $ UCX SET CONFIGURATION PROTOCOL TCP /NODELAY ! Valid on TCPIP V5 $ UCX SET PROTOCOL TCP /NOLOOPBACK $ UCX SET CONFIGURATION PROTOCOL TCP /NOLOOPBACK 12 8.4 cdsLib Service Definition CDS uses a TCP service definition in the UCX services database. This service defines the port number for CDS client and clerk communication. The DCE$SETUP CONFIGURE operation should properly define this service for you. By default, port number 1234 is used. If your site has another application that has defined a service using port 1234, the CONFIGURE operation will ask you to choose another port number for use with the cdsLib service. After Compaq DCE for OpenVMS is configured, should you need to change the port number assigned to the cdsLib service (for example, you want to install an application that needs port 1234), use the following commands: $ UCX SET NOSERVICE "cdsLib" The current service definition is displayed and you are asked if you wish to delete it. Answer YES and enter the following command. $ UCX SET SERVICE "cdsLib" /PORT=nnnn /file=NL: - /USER=DCE$SERVER /PROTOCOL=TCP /PROCESS=DCE$CDSCLERK Where nnnn is an unused port number to be used by CDS. Note that four additional ports are defined: o cdsAdver uses port number 1235 for process DCE$CDSADV o cdsDiag uses port number 1236 for process DCE$CDSD o kerberos5 uses port number 88 for process DCE$SECD o ntp uses port number 123 for process DCE$DTS_NTP_ PROVIDER $ UCX SHOW SERVICE This command lets you examine the current UCX service definitions. The State for all of the DCE services should be Disabled. Also note that the service definitions in UCX are permanent settings; that is, once defined, they will still be set if UCX is restarted. For this reason, you do not need to put changes to the service definitions in your UCX startup procedure. This service definition is required on TCP/IP V5 as well as V4. 13 9 Using MultiNet with DCE Version 3.0 of Compaq DCE for OpenVMS can be used with TGV, Inc.'s MultiNet product in place of Compaq's TCP/IP Services for OpenVMS. If you want to use MultiNet with Compaq DCE for OpenVMS, you must contact TGV, Inc. for a copy of MultiNet, which contains support for DCE[1]. Then, follow the installation procedure and choose MULTINET when the installation process prompts you for the specific TCP/IP product you want to use. Add or replace the following command to the system startup command procedure (SYS$MANAGER:SYSTARTUP.COM) after the startup commands for the network transports, DECnet and/or Compaq TCP/IP Services: $ @SYS$STARTUP:DCE$STARTUP START MULTINET To configure DCE with MultiNet, enter the following command: @SYS$STARTUP:DCE$STARTUP CONFIG MULTINET Otherwise, DCE will expect TCP/IP communications to be provided by UCX. The SYSGEN parameter MAXBUF must be set to a value greater than the maximum message size to be transferred between the CDS Clerk and CDS clients. If MAXBUF is not large enough, client processes will hang in an I/O wait state. If this happens, other CDS clients will continue to function and the hung process may be aborted without affecting them. The recommended setting for MAXBUF is 20,000 bytes or greater. (If you have a large CDS database with many directories, you may have to set it even higher.) If DCE processes hang while performing name service requests that transfer larger amounts of data, you probably need to increase the value of MAXBUF as follows: $ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE ACTIVE SYSGEN> SET MAXBUF nnnn ! nnnn = new value for MAXBUF SYSGEN> WRITE ACTIVE SYSGEN> USE CURRENT SYSGEN> SET MAXBUF nnnn ! nnnn = new value for MAXBUF SYSGEN> WRITE CURRENT SYSGEN> EXIT ____________________ [1] Compaq is not responsible for third-party application support. Any issues around third-party IP applications should be directed to those third- party companies and not to Compaq. 14 Note that this setting will remain in effect until the next time AUTOGEN is invoked. Make the changes permanent by editing SYS$SYSTEM:MODPARAMS.DAT and adding MIN_MAXBUF = nnnn and then invoking AUTOGEN as described in the installation and configuration guide. For further information on modifying SYSGEN parameters or on AUTOGEN, refer to the OpenVMS system management documentation. 10 Using PathWay with DCE Version 3.0 of Compaq DCE for OpenVMS has been designed to be used with Wollongong's PathWay product in place of Compaq's TCP/IP Services for OpenVMS.DCE[1]. If you wish to use PathWay with Compaq DCE for OpenVMS, you must contact Wollongong for availability information and for a copy of PathWay that contains support for DCE. Then, follow the installation procedure and choose PATHWAY when the installation process prompts you for the specific TCP/IP product you want to use. Add the following command to the system startup command procedure (SYS$MANAGER:SYSTARTUP.COM) after the startup commands for the network transports, DECnet and/or DEC TCP /IP Services: @SYS$STARTUP:DCE$STARTUP START PATHWAY To configure DCE with PathWay, enter the following command: @SYS$STARTUP:DCE$STARTUP CONFIG PATHWAY Otherwise, DCE will expect TCP/IP communications to be provided by UCX. 11 Using TCPware with DCE Version 3.0 of Compaq DCE for OpenVMS can also be used with Process Software's TCPware product in place of Compaq's TCP/IP Services for OpenVMS. If you wish to use TCPware with Compaq DCE for OpenVMS, you must contact Process Software for a copy of TCPware, which contains support for DCE[1]. ____________________ [1] Compaq is not responsible for third-party application support. Any issues around third-party IP applications should be directed to those third- party companies and not to Compaq. 15 Then, follow the installation procedure and choose TCPWARE when the installation process prompts you for the specific TCP/IP product you want to use. Add the following command to the system startup command procedure (SYS$MANAGER:SYSTARTUP.COM) after the startup commands for the network transports, DECnet and/or DEC TCP/IP Services: @SYS$STARTUP:DCE$STARTUP START TCPWARE To configure DCE with TCPware, enter the following command: @SYS$STARTUP:DCE$STARTUP CONFIG TCPWARE Otherwise, DCE will expect TCP/IP communications to be provided by UCX. 12 Kerberos The DCE Security Server makes UDP port 88 (service name "kerberos5") available for use by native Kerberos clients for authentication. Kerberos realm names must match the cell name of the DCE security server. Support for native kerberos5 clients has undergone minimal interoperability testing. 13 Windows NT LAN Manager Another mechanism to provide Authenticated RPC has been added to DCE for OpenVMS. Support for NTLM (Microsoft's NT LAN manager protocol) has been added in OpenVMS Alpha Version 7.2-1 and higher. To use Authenticated RPC, a client passes its user security information (credentials) to the client's runtime. The client runtime forwards these credentials to the server runtime through 3-legged protocol exchange. This provides a secure mechanism for authenticating the client, and also allows server impersonation of that client. To select NTLM security, set the authn_svc parameter of the rpc_binding_set_auth_info call to rpc_c_authn_winnt. More information about manipulation of the data structures involved can be found in Section 17. 16 14 Linking RPC Stub Modules into Shareable Images If you build shareable images that contain RPC generated stub modules, you should use a linker options file. PSECT statements in the linker options file are used to resolve differences in the PSECT attributes between the RPC generated object file and the new shareable image. The following sections discuss how to solve problems that can arise when you create, link against, or activate a shareable image that contains RPC generated stub modules. This section can be summarized as follows: o Program sections (PSECTs) in shareable images should be SHR,NOWRT or NOSHR,WRT unless the image is installed with privileges. o Program sections in modules linked against shareable images must match exactly or conflicting PSECT errors will occur. o Until the program runs, you may have to correct PSECT attributes as far back as the shareable image. The PSECT attributes of the RPC generated interface specifications (IFspecs) should be set to the following: (GBL,SHR,NOWRT) RPC interface specs usually do not change, so it is rarely required that they be set to a writable PSECT attribute. RPC interface specs are frequently shared. If your shareable image contains more than one cluster and the same interface spec is defined in multiple object modules, these interface specs can be effectively collected into the same global cluster with the GBL PSECT attribute. Note that, in this case, the first module encountered by the linker that defines the IFspec will be used to initialize the value of the IFspec in the shareable image. A map file can help you identify and correct problems with PSECTs and their contents. The contents of any PSECT should be nonzero. If you find a zero byte PSECT, you may need to explicitly specify the module name in the options file. The module name can be specified directly on its own or as part of the /library/include=() statement associated with an object library. PSECTs should not be zero unless they are initialized at runtime, and this presumes that the PSECT is writable (WRT). 17 14.1 Errors Creating a Shareable Image The following examples show some of the errors that might occur when you try to create a shareable image with RPC stub object modules. $ link/share/exe=myshr.exe/map=myshr.map - _$ test1_mgr,test1_sstub,dce:dce.opt/opt %LINK-I-BASDUERRS, basing image due to errors in relocatable references %LINK-W-ADRWRTDAT, address data in shareable writeable section in psect TEST1_V0_0_S_IFSPEC offset %X00000000 in module TEST1_SSTUB file USER:[MY.CODE.DCE]TEST1_SSTUB.OBJ; $ The PSECT name is causing the linker problem. To correct this problem, create an option file including the following line, and place it on your link command line as follows: $ create myopt.opt PSECT= TEST1_V0_0_S_IFSPEC, shr,nowrt,gbl ctrl-z $ $ link/share/exe=myshr.exe/map=myshr.map - $_ test1_mgr,test1_sstub,dce:dce.opt/opt,myopt.opt/opt This will remove the link problems so that you can create a shareable image. There are still errors in this shareable image whose solutions are shown in the following examples. 14.2 Errors Linking Against a Shareable Image Once you have a shareable image, you may still see linker problems related to the PSECT attributes between the shareable image and new object files. In the following example, a main routine is linked against the same shareable image from the previous example. The new object module references some of the same variables defined by the RPC stub module. $ link/exec=test1d/map=test1d.map test1_main,sys$input/opt myshr.exe/share ctrl-z %LINK-W-MULPSC, conflicting attributes for psect TEST1_V0_0_S_IFSPEC in module TEST1_MAIN file USER:[MY.CODE.DCE]TEST1_MAIN.OBJ; $ 18 If you search the map files of both myshr.map and test1d.map for the PSECT TEST1_V0_0_S_IFSPEC, you will see that the PSECT attributes for this PSECT match; however, the map files are incorrect. The solution to this link problem is to include the PSECT directive in a linker options file for the offending PSECT name. The previous example simply typed in the options from the command line, but you should place these linker statements in a linker option file. The options are typed in from SYS$INPUT in the following example: $ link/exec=test1d/map=test1d.map test1_main,sys$input/opt PSECT= TEST1_V0_0_S_IFSPEC, shr,nowrt,gbl myshr.exe/share ctrl-z $ 14.3 Errors Activating Shareable Images When you run this program, the following results occur: $ run test1d %DCL-W-ACTIMAGE, error activating image MYSHR -CLI-E-IMAGEFNF, image file not found SYS$LIBRARY:MYSHR.EXE $ To allow the image activator to check a directory other than SYS$LIBRARY for your new shareable image, you must define a logical name or you must copy your new shareable image into SYS$LIBRARY. In the following example, a logical name is defined and the program is run again with the following results. $ define MYSHR sys$disk:[]myshr.exe; $ $ run test1d %DCL-W-ACTIMAGE, error activating image MYSHR -CLI-E-IMGNAME, image file USER:[MY.CODE.DCE]MYSHR.EXE; -SYSTEM-F-NOTINSTALL, writable shareable images must be installed $ The problem is in the myshr.exe image: myshr.exe has PSECTs whose PSECT attributes specify both SHR and WRT. The solution is to add the correct PSECT attributes to the myshr.opt options file which is used to build the myshr.exe shareable image. This can be done on the command line, as follows: 19 $ link/share/exe=myshr.exe/map=myshr.map - $_ test1_mgr,test1_sstub,dce:dce.opt/opt,sys$input/opt psect= TEST1_V0_0_S_IFSPEC, shr,nowrt,gbl psect= RPC_SS_ALLOCATE_IS_SET_UP, noshr,wrt,gbl psect= RPC_SS_CONTEXT_IS_SET_UP, noshr,wrt,gbl psect= RPC_SS_SERVER_IS_SET_UP, noshr,wrt,gbl psect= RPC_SS_THREAD_SUPP_KEY, noshr,wrt,gbl psect= RPC_SS_CONTEXT_TABLE_MUTEX,noshr,wrt,gbl psect= TEST1_V0_0_C_IFSPEC, shr,nowrt,gbl $ All of the PSECTs that existed in the myshr.map mapfile that had SHR and WRT attributes were changed so that the PSECT was either SHR,NOWRT or NOSHR,WRT. The choice depends upon your use of the data item. IFspecs are usually shared and nonwritable. The RPC_SS PSECTs are written and not generally shared among program images linked against the shareable image. The following example tries to relink the main program again, but another problem occurs: $ link/exec=test1d/map=test1d.map test1_main,sys$input/opt PSECT= TEST1_V0_0_S_IFSPEC, shr,nowrt,gbl myshr.exe/share ctrl-z %LINK-W-MULPSC, conflicting attributes for psect TEST1_V0_0_C_IFSPEC in module TEST1_MAIN file USERE:[MY.CODE.DCE]TEST1_MAIN.OBJ $ Because the PSECT attributes of the TEST1_V0_0_S_IFSPEC PSECT were changed in the shareable image, its reference in test1_main.obj is not correct. To solve this problem, add the correct PSECT attribute. For example: $ link/exec=test1d/map=test1d.map test1_main,sys$input/opt PSECT= TEST1_V0_0_S_IFSPEC, shr,nowrt,gbl PSECT= TEST1_V0_0_C_IFSPEC, shr,nowrt,gbl myshr.exe/share $ In the final example, the test1d program is run and the desired results occur. $ run test1d ncacn_ip_tcp 16.32.0.87 3314 ncacn_dnet_nsp 63.503 RPC270002590001 ncadg_ip_udp 16.32.0.87 1485 20 15 Restrictions and Known Bugs The following sections provide details on restrictions and known bugs in this version of Compaq DCE for OpenVMS. 15.1 Documentation All documentation except the online help can be found in the DOCUMENTATION subdirectory of the field test CD. The Open Group's DCE documentation for the 1.2.2 release is provided in HTML format. OpenVMS specific documentation (Product Guide, Reference Guide, Installation and Configuration Guide) is available as well. 15.2 OpenVMS Supported Versions Compaq DCE for OpenVMS V3.0 includes support for OpenVMS V6.2, V7.1-*, and V7.2-* on both VAX and Alpha. 15.3 Kernel Threads and UPCALLS Support As of OpenVMS V7.2-1, Compaq DCE for OpenVMS V3.0 now supports DCE applications on Alpha built with Kernel Threads and Thread Manager upcalls enabled. The DCE daemons (dced, secd, cdsd, etc.) are shipped with Kernel Threads disabled. Enabling Kernel Threads and Thread Manager upcalls on these images is not currently supported. 15.4 DCE Applications Need Not Be Relinked Although there are many new APIs in this version of DCE, existing DCE applications need not be relinked before they can run on this release. However, if the application developer wishes to use any of the new APIs, then it will be necessary to recompile and relink. 15.5 DTS Server The following time server commands are not supported in this release: $ dtscp show decnet time source 21 15.6 Integrated Login and OpenVMS External Authentication As of OpenVMS V7.1, the operating system provides support for external authentication via PATHWORKS. DCE Integrated Login is incompatibile with this functionality. DCE$SETUP.COM will warn the user if external authentication is enabled on the host system. If Integrated Login is enabled in spite of the warning, external authentication will be disabled and applications that are dependent on external authentication may not function as expected. 15.7 Minimum Global Pages Compaq DCE for OpenVMS VAX and OpenVMS Alpha Version 3.0 has increased global pages requirements as follows: o Compaq DCE for OpenVMS VAX now requires 3750 global pages before installation. (Previously the requirement was 3000.) o Compaq DCE for OpenVMS Alpha now requires 7350 global pages before installation. (Previously the requirement was 6000.) 15.8 RTI (Remote Task Invocation) RPC RTI RPC is a transactional RPC that is provided for use with Compaq's ACMSxp TP product. RTI RPC requires OSI TP from the OSI Application Developer's Toolkit. 15.9 Format of X.500 Cell Names X.500 cell names have the form c=country/o=organization /ou=organization unit. X.500 cell names can contain spaces or hyphens if they are enclosed in double quotes, but underscores are never allowed, even if they are enclosed in double quotes. For example, the X.500 cell names /c=us /o=digital/ou="excess cell" and /c=us/o=digital/ou="excess- cell" are allowed, but /c=us/o=digital/ou=excess_cell and /c=us/o=digital/ou="excess_cell" are not allowed. 15.10 Shutting Down Compaq DCE for OpenVMS Before Reinstallation If you are installing Compaq DCE for OpenVMS Version 3.0 over an existing version of DCE on a common system disk in a OpenVMS Cluster environment, be sure to shut down DCE and RPC on all nodes that share the common system disk before the installation. If you do not shut down DCE and RPC, parts of DCE and your OpenVMS cluster may exhibit undesirable characteristics. 22 If you are reinstalling Compaq DCE for OpenVMS Version 3.0 over a Version 1.x kit and you are using Integrated Login, and if you do not shut down DCE on all nodes that share the common system disk, you can cause the LOGINOUT image to fail to run on all of the nodes that share the common system disk. You can correct this problem by shutting down and restarting DCE on the affected nodes. However, if LOGINOUT is not running, you cannot log in; therefore, you must reboot the system to correct the problem. 15.11 Configuring a CDS Replica Clearinghouse Before you configure a CDS replica clearinghouse, make sure that the system clock is synchronized to within seconds of the CDS master server. To validate the time, use the following command: $ dtscp show local servers This shows the skew between the host and all other DTS servers in the cell. 15.12 Reconfiguring a CDS Replica Clearinghouse If it becomes necessary to reconfigure or rebuild a host that includes a CDS replica clearinghouse, you may find that the creation of the clearinghouse succeeds but the skulk that is executed immediately after fails. If this happens, you will see the following message: *** The creation of the CDS Replica Clearinghouse has succeeded *** but the namespace has been left in an inconsistent state. *** This condition will correct itself in a short period of time. *** Once the command "cdscp set dir /.: to skulk" can be *** successfully executed the namespace will be consistent and *** the replica clearinghouse will be fully operational. *** In the meantime you can replicate directories. This is a known restriction. The situation will clear itself in about an hour; however, you will not be able to create any other clearinghouses until this condition has been corrected. If you want to correct the problem immediately, you can restart DCE on the master server. You will then be able to skulk the root directory and add additional clearinghouses. 23 15.13 Privileged User Refreshing Credentials When a priviledged process creates or refreshes credentials, the owner UIC for the files is [DCE$SERVER]. If a privileged process needs to refresh credentials for an unprivileged process, the privileged process should first change its owner UIC to be the same as the unprivileged process and disable its privileges. Otherwise, the owner UIC for the updated credentials will be [DCE$SERVER], and the unprivileged process may no longer be able to read its own credentials. 15.14 Support for Integrated Login Before DCE Startup on OpenVMS Systems If your OpenVMS system startup allows interactive logins to occur before DCE is started, the interactive logins that occur before DCE is started will not support Integrated Login. If you interactively log in to OpenVMS before DCE is started, you must specify your OpenVMS username and password. You will not be logged in with DCE credentials. (If you log in after DCE is started on systems where Integrated Login is enabled, it is recommended that you specify your DCE principal name and password at the username and password prompts when using Integrated Login.) 15.15 Support for Integrated Login Before DCE Startup on OpenVMS Workstations If your OpenVMS system startup allows DECwindows Motif to start up and display the DECwindows login box before DCE is fully started, the first DECwindows login will not support Integrated Login. In this case, Integrated Login will not be supported even if the first login occurs after DCE is up and running. If DECwindows Motif displays the DECwindows login box before DCE is started, you must specify your OpenVMS username and password. You will not be logged in with DCE credentials. (If the DECwindows login box is displayed on your workstation after DCE is started and Integrated Login is enabled, it is recommended that you specify your DCE principal name and password at the username and password prompts when using Integrated Login.) 24 15.16 32-Character Restriction on DCE Principal Names for Integrated Login When you log in to an OpenVMS system that has Integrated Login enabled, you can specify either your OpenVMS username or your DCE principal name at the username prompt. However, the DCE principal name you specify can contain no more than 32 characters. If your principal name and cell name combination contains more than 32 characters, specify the OpenVMS username that is associated with your DCE account instead. (This username is entered in the DCE$UAF file.) You should still enter your DCE password to obtain DCE credentials even if you specify your OpenVMS username. 15.17 Running DCE IMPORT in Batch Mode Without Password If you run DCE IMPORT in batch mode and you do not supply a password for the DCE account on the command line, the password valid flag incorrectly remains set in the DCE registry. Because a password was not supplied, the flag should indicate password not valid and the user should not be allowed to log in. A scan of the DCE account via RGY_EDIT reveals the incorrect flag setting (password valid when actually the password is not valid). However, the user will not be allowed to log in (which is the correct behavior). 15.18 Potential Integrated Login and SYSGEN Problems The Integrated Login component of Compaq DCE for OpenVMS uses the SYSGEN parameter LGI_CALLOUTS. LGI_CALLOUTS must be set to 1 only in the ACTIVE SYSGEN parameter set when DCE is running with Integrated Login enabled. LGI_CALLOUTS must never be set to 1 in the CURRENT SYSGEN parameter set - this would prevent all logins from occurring on a subsequent reboot of the system. The following paragraphs discuss the reasons for this restriction and solutions if the problem occurs. If Integrated Login is enabled on your system, the DCE startup and configuration procedure, DCE$SETUP.COM, sets the SYSGEN parameter LGI_CALLOUTS to 1 in the ACTIVE SYSGEN parameter set when DCE is started and resets the parameter when DCE is shut down. LGI_CALLOUTS must never be set to 1 in the CURRENT SYSGEN parameter set because, in that case, the next time the system is booted the LGI_CALLOUTS parameter is set in the ACTIVE SYSGEN parameter set before DCE is started. This prevents logins from occurring. 25 If the ACTIVE value of LGI_CALLOUTS is set to 1 when DCE and Integrated Login are not running, the following error is displayed when LOGINOUT attempts to run (for example, for interactive or batch logins): No logical name match Consequently, all users are prevented from logging in to the system. This problem can occur if, for example, a SYSGEN parameter is modified in the following way while Integrated Login is enabled. This prevents logins because it causes LGI_ CALLOUTS to be set to 1 the next time the system is booted. $ RUN SYS$SYSTEM:SYSGEN SYSGEN> SET param value SYSGEN> WRITE CURRENT SYSGEN> EXIT $ The correct way to modify a SYSGEN parameter is to make the change in MODPARAMS.DAT and then run AUTOGEN. If it is essential to modify a SYSGEN parameter without using MODPARAMS.DAT and AUTOGEN, you must ensure that if you use ACTIVE, you write the parameters into ACTIVE only; and if you use CURRENT, you write the parameters into CURRENT only. Do not copy the ACTIVE parameters into CURRENT. Following are two examples of acceptable ways to modify a SYSGEN parameter: $ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE CURRENT SYSGEN> SET param value SYSGEN> WRITE CURRENT SYSGEN> EXIT $ $ RUN SYS$SYSTEM:SYSGEN SYSGEN> USE ACTIVE ! optional, default is ACTIVE SYSGEN> SET param value SYSGEN> WRITE ACTIVE SYSGEN> EXIT $ If you cannot log in because LGI_CALLOUTS is set to 1 and DCE is not running, there are two solutions, as follows: 26 o If you are already logged into the system, use SYSGEN to correct the problem. $ RUN SYS$SYSTEM:SYSGEN SYSGEN> SET LGI_CALLOUTS 0 SYSGEN> WRITE ACTIVE SYSGEN> EXIT $ o Reboot the system with a conversational boot and ensure the LGI_CALLOUTS parameter is zero. SYSBOOT> SET LGI_CALLOUTS 0 SYSBOOT> C 15.19 Support for Packet Privacy Compaq DCE for OpenVMS supports the rpc_c_prot_level_pkt_ privacy level of data encryption as of this baselevel. Recent changes in the government's encryption regulations allow this functionality to be provided in the base DCE kit, as opposed to a separate product (as was done in previous versions of DCE for OpenVMS). See the documentation on rpc_binding_set_auth_info for details. 15.20 DCE IDL Compiler and C++ Exceptions A client using the DCE IDL compiler with C++ extensions invokes methods on objects that causes IDL generated client stub code to be invoked. By default, communications errors or remote faults that occur during the stub's processing cause exceptions to be raised using the DCE Threads exception handling mechanism. Therefore, C++ code that needs to catch and respond to these exceptions must also use the DCE Threads exception handling mechanism. Some, but not all, C++ compilers have built-in language support for exceptions. Exceptions are not supported in older versions of the DEC C++ for OpenVMS compilers. C++ application code that processes exceptions returned from DCE IDL stubs should continue to use DCE Threads exceptions if using compilers without exceptions support. You can avoid the raising of exceptions from DCE IDL stubs by using the [comm_status] and [fault_status] ACF attributes. For more information, see the Guidelines for Error Handling chapter in the DCE Application Development Guide. 27 15.21 Automatic Registration of Servers In the IDL compiler, servers are now automatically registered by server stubs. If you call rpc_server_ register_if(), the "already registered" status is returned. (Remove the call to rpc_server_register_if() from the server.cxx file before you build the example programs in Chapter 15 of the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Product Guide.) 15.22 Support for sigwait() The DCE Application Guide and DCE Reference Guide include incorrect information about support for sigwait(). DECthreads does not support sigwait() on the OpenVMS platform. 15.23 Server Programming When running DCE server applications on OpenVMS Alpha V6.2 systems, it is possible to exhaust the server thread stack space if your server makes use of the %f or %e conversion characters for formatting output. For example, the following printf statement could cause an overflow of the server thread stack: printf ("The computed value = %f\n", value); This error can cause the server to terminate with an unexpected error code such as an Access Violation or a Reserved Operand Fault. If you experience this type of error, you must add a call to the RPC routine rpc_mgmt_set_server_stack_size specifying a stack size of at least 14000, prior to calling rpc_server_listen. 15.24 Compiling Stubs on Alpha If a stub is compiled on Alpha with optimization switched on, it may not handle exceptions correctly, depending on the version of DEC C. Therefore, on Alpha, you should compile stubs with optimization switched off, unless you are sure that the version of DEC C that is on your system handles this situation correctly. 28 15.25 Using the -cpp_cmd (/PREPROCESS) IDL Compiler Option on OpenVMS Alpha When you specify the -cpp_cmd (/PREPROCESS) option in an IDL command, the IDL compiler preprocesses any IDL or ACF sources by invoking the DEC C compiler with the /PREPROCESS_ONLY qualifier. Because of a bug in some versions of the DEC C compiler on OpenVMS Alpha, the IDL compiler may incorrectly report source line numbers and contents when it reports error messages. If your IDL and ACF source files do not use C preprocessor directives (such as #define), then you do not need to specify the -cpp_cmd (/PREPROCESS) option. Otherwise, the workaround is to change multiline comments to a series of single line comments. 15.26 UCX Runtime Calls Not Thread Safe Note that UCX Runtime Calls are not always thread safe. UCX has two main application programming interfaces: VMS system services (for example, $ASSIGN, $QIO, $CANCEL) and the C socket library. Of these two, the VMS system services are fully thread-safe, while the socket library is not. The most common problem with sockets is the select() call, which blocks the entire process (not just the calling thread) until the specified I/O events occur (or the timeout expires). 15.27 POSIX The OpenVMS POSIX product has been retired, and support for the POSIX command line has been removed from Compaq DCE for OpenVMS VAX and OpenVMS Alpha V3.0. The OpenVMS C runtime support for many of the POSIX calls has improved, and most applications should see no change in behavior. Only those applications which require the POSIX command line interface are affected. 15.28 C RTL Routine Sleep Not Thread Safe The C RTL routine sleep is not thread safe. The sleep call may wake up prematurely if calls to DCE APIs are made at the same time. It is recommended that you use a thread safe mechanism such as pthread_delay_np, pthread_cond_wait, pthread_cond_timedwait, and pthread_cond_signal to delay a thread. For more information on these APIs, please refer to the OSF DCE Application Development Reference Manual. 29 15.29 Ordering of System Startup Procedures The order of startup procedures should be as follows: DECnet, TCP/IP software, DCE, then DCE applications. 15.30 Case-Sensitivity of DCE Utilities Some input to Compaq DCE for OpenVMS utilities is case-sensitive (for example, CDSCP entity attribute names). Since the DCL command line interface converts all input to uppercase before passing it to a utility, some input to the DCE utilities will need to be enclosed in quotation marks (" "). When you enter commands directly at DCE utility prompts, you should not use the quotation marks because case-sensitivity is preserved. (Case-sensitivity is not preserved by the Integrated Login utilities DCE$UAF, IMPORT, and EXPORT because these are true native OpenVMS applications.) 15.31 CDSCP Commands Requiring a Local Server There are several CDSCP commands that assume the presence of a CDS server on the local system. These commands will not execute properly in the absence of a local server. At present, CDSCP will return the following error: Failure in routine: cp-xxxxxxx not registered in endpoint map (dce/rpc) The affected commands are: CDSCP SHOW SERVER CDSCP DISABLE SERVER CDSCP CREATE CLEARINGHOUSE 15.32 DCE command line programs fail with SMG error If the process has it's UIC set to DCE$SERVER, and does not have the BYPASS privilege set, DCE command line utilities will fail with the following error: error creating SMG virtual keyboard. %NONAME-E-NOMSG, Message number 00000002 The resolution to this problem is to either run under a UIC other than DCE$SERVER, or to set the BYPASS privilege on accounts set to the DCE$SERVER UIC. This problem does not effect the running of the DCE deamons, only user processes. 30 15.33 Dumping the CDS Cache The CDSCP and DCECP commands to examine the CDS cache will fail if CDSCP or DCECP is run under a Process UIC other than [DCE$SERVER]. $ CDSCP DUMP CLERK CACHE Cannot map -1 - check id and protection An error occured calling a CDS API function. (dce / cds) $ DCECP -C CDSCACHE DUMP Cannot map -1 - check id and protection Error: The cache dump failed in an indeterministic mode. To work around this restriction, issue the following DCL command before you invoke CDSCP or DCECP: $ SET UIC [DCE$SERVER] Remember to reset your UIC to its original value after you use this command. 15.34 CDS Clerk Failing on UCX Shutdown If you issue a SYS$STARTUP:UCX$SHUTDOWN command while running DCE, you may get a CDS Clerk failure and an Access Violation. You may then encounter problems restarting the CDS Clerk (and DCE itself) with the DCE$SETUP START command. The primary problem is that UCX is being shut down while DCE is still active. Since DCE uses UCX, DCE should always be shut down first. To recover from this problem, you need to shut down DCE first and then restart. Simply trying to restart without first shutting DCE down will not fix the underlying problem. Because temporary files may be left in an indeterminate state, you may also want to perform a DCE$SETUP CLEAN operation before restarting. 15.35 Global Directory Agent Configuration The Global Directory Agent (GDA) is configured on the OpenVMS node that contains the CDS Master Replica name server. The DNS domain name (for example, zko.dec.com) and the Internet Address of an authoritative DNS Master Bind Server (for example, 16.32.2.11) are required during configuration if you are using DNS Bind style cellnames. 31 Before access to multiple CDS namespaces is possible, the following are required after the configuration: 1. The Master Bind Server identified during configuration becomes the repository for information the GDA requires to resolve the Internet addresses and binding information needed by CDS to access foreign cell name spaces. This applies to DNS Bind cellnames only. See the Intercell Naming chapter in the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Product Guide for the binding information content, location, and access. 2. Authenticated access to foreign (intercell) cell name space requires performing the RGY_EDIT cell command. The information needed for the cell command requires coordination with the foreign cell administrator. For more information, see both the Administering a Multicell Environment chapter in the OSF DCE Administration Guide and the Intercell Naming chapter in the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Product Guide. 3. Before doing the RGY_EDIT cell command, you must first delete the krbtkt account for the foreign cell if one already exists. Similarly, the administrator for the foreign cell must also delete the krbtkt account in the foreign cell's registry for your cell. For example, if your cell is called first_cell and the foreign cell is called second_cell, then you must run RGY_EDIT on first_ cell to delete the account called krbtkt/second_cell, and the administrator on second_cell must delete the registry account called krbtkt/first_cell. After the cell command, both cell administrators should rerun DCE_LOGIN before attempting authenticated cross- cell requests. If you are unsuccessful in configuring intercell communication, check for the following: o The clocks on the systems that are attempting to communicate show times that differ by no more than five minutes. (Use DTS to change the system time once you are running DCE.) o CDS has the information that should be contained in the CDS_GDAPointers field in the cell's root directory. If CDS does not have this information in the cell's root directory, restart the GDA daemon process (DCE$GDAD) by entering the following commands: 32 $ STOP/ID=xxxxxxxx $ @sys$manager:dce$setup start where xxxxxxxx is the PID of the DCE$GDAD process. 15.36 Changes to RPC Shutdown In DCE for OpenVMS V1.5, a change was made to disassociate RPC shutdown from DCE shutdown. This was done to allow RPC only applications to remain active while DCE changes were being made. In DCE V1.5, DCE$SETUP stop/clean/clobber did not call the RPC shutdown procedure, and merely gave a warning that RPC would not be shut down. DCE V3.0 requires that dced (the new RPC endpoint mapper) be shut down during certain operations. Therefore, the behavior of DCE V3.0 has changed, and the RPC shutdown procedure is now called from DCE$SETUP.COM. This requires the system manager to be aware of any RPC-only applications that may be active at the time of DCE configuration operations. 15.37 IDL error when installing DCE If installing DCE over an existing implementation, you may see an IDL error if the DCE Application Developer's Kit was previously installed, but is not being installed for the upgrade. The installation is attempting to remove the DCL commands which are associated with the developer's kit from DCLTABLES.EXE, and failing. This error can safely be ignored - answer NO to the question "Do you want to terminate?". %PCSI-E-MODDELERR, error deleting module IDL_CLD from library %PCSI-E-OPFAILED, operation failed Terminating is strongly recommended. Do you want to terminate? [YES] n 15.38 Owner error when installing DCE When installing DCE on OpenVMS VAX V6.2, you may see the following errors: %PCSI-E-ERROWNER, error in owner specification 'DCE$SERVER' %PCSI-E-OPFAILED, operation failed or %PCSI-E-PARUDF, the directory [DCELOCAL.ETC] has not been provided by a previous Install or Register operation - file ownership and protection update skipped 33 followed by: Terminating is strongly recommended. Do you want to terminate? [YES] n These errors can safely be ignored - answer NO to the question "Do you want to terminate?". 15.39 Port Error during DCE configuration If the error shown below occurs during DCE configuration, your system has the TCP/IP NTP daemon configured. Since DCE also provides an NTP daemon, you must decide which one you intend to use. If you choose to use the DCE NTP daemon, then you must disable the TCP/IP NTP daemon via your TCP/IP configuration program before you can enable the DCE one. If you choose to use the TCP/IP NTP daemon, then you can ignore the following error, and answer "Y" to the question about whether you want to proceed. *************************** ERROR ******************************** Port number 123 is in use by a service other than "ntp". Please check configuration! Service "ntp" must use port number 123. ***************************************************************** Press to continue . . . Do you want to proceed with this operation (YES/NO/?) [N]? 15.40 Exception during DCE Configuration Verification Program When the DCE Configuration Verification Program (CVP) or the test option from the DCE main menu is run, the following error may occur: %CMA-F-EXCCOPLOS, exception raised; some information lost This error can be ignored. 34 15.41 Problem converting DTS local to DTS global server Modification of the DCE configuration to convert an existing DTS local server to a DTS global server results in the following error: ERROR- An error occurred attempting to log in to DCE with principal name "cell_admin" Sorry. Password Validation Failure. - Cannot log in with zero-length password (dce/sec) Do you wish to try another principal name? If you answer yes to this question, and give the cell_admin username and password to the prompts, the conversion to the DTS global server will be successful. 15.42 Problems with Sun Solaris DCE system as CDS master There are known problems with Sun Solaris V2.6 and Transarc DCE V2.1 as the CDS master if you are attempting to configure a split server configuration using DCE on OpenVMS, Tru64 UNIX or Windows NT. Solaris V2.4 and Transarc DCE V1.1 work correctly. Contact your DCE vendor for further information. 15.43 Compile Warning in Example Programs The CXX example programs may produce the following warning on compilation: IDL_ms.IDL_call_h = (volatile rpc_call_handle_t)IDL_call_h; ...............^ %CXX-W-CASTQUALTYP, type qualifier is meaningless on cast type at line number 117 in file USER$1:[DCE12.EXAMPLES.RPC.IDLCXX. ACCOUNT]ACCOUNT_SSTUB.CXX;1 This warning can be safely ignored. 15.44 "Missing" CXX library Some versions of CXX may not include the library SYS$LIBRARY:LIBCXXSTD.OLB. If this is the case, this line may be removed from the options file found in SYS$COMMON:[DCE$LIBRARY]DCE_CXX.OPT. 35 15.45 Unknown Ethernet Device on Host System If your system is relatively new, it is possible that DCE might not know about the Ethernet device on the system. DCE uses the Ethernet device to obtain an Ethernet address which is used in the generation of UUIDs. If you see errors such as the following: %UUIDGEN-F-RPC_MESSAGE, Received Error Status: "no IEEE 802 hardware address (dce / rpc)" then your Ethernet device is not known by DCE. You can define one additonal Ethernet device in the table used by DCE by defining the logical name DCE$IEEE_802_DEVICE to the name of your Ethernet device as shown in the following example: DEFINE/SYSTEM DCE$IEEE_802_DEVICE EWA0 This will allow DCE to operate using the Ethernet device named EWA0 (a device type of DE500). 15.46 Public Key routines not supported on OpenVMS DCE public key technology is not currently supported on OpenVMS. The pkc_* routines and classes (pkc_add_trusted_key, etc.) are not in DCE$LIB_SHR.EXE, and will generate undefined symbols if an application which uses them attempts to link. The Open Group has stated their intention to replace the existing public key technology in DCE with a non-interoperable replacement, based on X.509v3, in a future release. "Note that there has been such a high volume of change activity in the IETF relative to Public Key Infrastructure (PKI) and Kerberos that the [RFC 68.3] functionality will not be forward compatible with this Specification. Therefore, current users of DCE 1.2.2-based products with [RFC 68.3] functionality should refrain from deploying the public key based login support."¹ For this reason, Compaq is not supplying the obsolete public key functionality in DCE for OpenVMS V3.0. For additional information on the status of public key in DCE, see the Open Group's DCE website at: http://www.opengroup.org/tech/dce/ ¹Draft Technical Standard - DCE 1.2.3 Public Key Certificate Login, Draft 0.8, The Open Group, August 1998 36 15.47 Audit Trail Files Require UNIX-like File Specifications The command to show the DCE audit trail files requires a UNIX style file specification. For example: $ dcecp -c audtrail show /dcelocal/var/audit/adm/central_trail 15.48 Installation Warnings Some systems may see warnings during DCE installation, as shown below: The following product will be installed to destination: DEC VAXVMS DCE V3.0 DISK$MOOSE2_SYS:[VMS$COMMON.] %PCSI-I-RETAIN, file [SYSEXE]DTSS$SET_TIMEZONE.EXE was not replaced because file from kit does not have higher generation number %PCSI-I-RETAIN, file [SYSLIB]DTSS$RUNDOWN.EXE was not replaced because file from kit does not have higher generation number %PCSI-I-RETAIN, file [SYSUPD]DTSS$INSTALL_TIMEZONE_RULE.COM was not replaced because file from kit does not have higher generation number %PCSI-I-RETAIN, file [SYSUPD]DTSS$TIMEZONE_RULES.DAT was not replaced because file from kit does not have higher generation number These warnings can be safely ignored. They indicate that certain files which may also be provided by OpenVMS are newer than the files in the DCE kit. 37 16 New APIs for Authenticated RPC The following APIs are included in DCE Version 1.5 and above to manipulate the sec_winnt_auth_identity structure. They are supported on OpenVMS V7.2-1 and up. 16.1 RPC_WINNT_SET_AUTH_IDENTITY NAME rpc_winnt_set_auth_identity - This function is called by the client RPC application to allocate and populate a WINNT auth_identity structure to be used as a parameter to rpc_binding_set_auth_info(). The caller must use the rpc_winnt_free_auth_identity() function to free the WINNT auth_idenity. The strings that are passed in may be ASCI or Unicode (UCS-4) strings. The input flag will tell which type of strings they are. SYNOPSIS #include PUBLIC void rpc_winnt_set_auth_identity ( rpc_winnt_auth_string_p_t Username; rpc_winnt_auth_string_p_t Password; rpc_winnt_auth_string_p_t Domain; unsigned __int64 CharacterSetFlag; rpc_auth_identity_handle_t *auth_identity; unsigned32 *stp) PARAMETERS INPUT username - Pointer to a null terminated string containing username. password - Pointer to a null terminated string containing password. domain - Pointer to a null terminated string containing domain. CharacterSetFlag SEC_WINNT_AUTH_IDENTITY_UNICODE 4 byte Unicode (UCS-4) SEC_WINNT_AUTH_IDENTITY_ANSI ASCII (ISO8859-1) OUTPUT auth_identity - Pointer to a pointer to WINNT auth_identity structure. stp - Pointer to returned status. 38 ________________________ Note ________________________ Be sure to allocate space for three strings (username, password, domain). The string variables will probably be pointers of type unsigned_char_t if the strings are ASCII or pointers of type wchar_t if the strings are Unicode (UCS-4). If the domain string is a valid empty string, then the domain of the computer will be used. ______________________________________________________ 16.2 RPC_WINNT_FREE_AUTH_IDENTITY NAME rpc_winnt_free_auth_identity - This function is called by the client RPC application to free a a WINNT auth_identity structure that was previously allocated by a call to rpc_winnt_set_auth_identity(). SYNOPSIS #include PUBLIC void rpc_winnt_free_auth_identity ( rpc_auth_identity_handle_t *auth_identity, unsigned32 *stp) PRAMETERS INPUT auth_identity - Pointer to a pointer to WINNT auth_identity structure. On output auth_identity will be set to NULL. OUTPUT stp Pointer to returned status. 17 New APIs for Impersonation in DCE The following APIs are included in DCE Version 1.5 and above to support server impersonation of a client. This means that the server runs with the security credentials of the client, and all of the capabilities of the client belong to the server. 39 17.1 RPC_IMPERSONATE_CLIENT NAME rpc_impersonate_client - This function is called by the server application to allow the current server thread to run with all of the client privileges. SYNOPSIS #include void rpc_impersonate_client( rpc_binding_handle_t binding_handle, rpc_status_t *status) PARAMETERS INPUT binding_handle - Specifies a server-side call handle for this RPC which represents the client to impersonate. OUTPUT status - Specifies a pointer to an unsigned 32 bit integer that holds a status code. 17.2 RPC_REVERT_TO_SELF NAME rpc_revert_to_self - This function is called by the server application to revert back to its original security context after impersonating a client. SYNOPSIS #include rpc_revert_to_self(*status) PARAMETERS INPUT NONE OUTPUT status - Specifies a pointer to an unsigned 32 bit integer that holds a status code. 40 17.3 RPC_REVERT_TO_SELF_EX NAME rpc_revert_to_self_ex - This function is called by the server application to revert back to its original security context after impersonating a client. This acts as a call to rpc_revert_to_self(); SYNOPSIS #include rpc_revert_to_self_ex( rpc_binding_handle_t binding_handle, rpc_status_t *status) PARAMETERS INPUT call handle - This parameter is ignored. OUTPUT status - Specifies a pointer to an unsigned 32 bit integer that holds a status code. 17.4 Enhanced RPC Security APIs For more information on existing enhanced RPC security APIs, see the Compaq DCE for OpenVMS VAX and OpenVMS Alpha Reference Guide. 18 The Routing File To use routing file services on OpenVMS, you will need to define the following logical name for the process or the system for which logging information is desired: (Syntax is exact for the routing file). $ define/sys DCE_SVC_ROUTING_FILE "dce_local/var/svc/routing." This will enable DCE applications to find and interpret the routing file and direct any output to the locations specified in the routing file. You can also set the number of buffered writes to perform before data is flushed to the file, as shown below: $ define/sys DCE_SVC_FSYNC_FREQ 10 The example above will flush the buffer every 10 writes. 41 18.1 Specifying Filenames in the Routing File The OpenVMS routing file uses UNIX style filenames when specifying output log files. You can see examples of this in the current routing file that is found in the directory dce$common:[var.svc]routing. The DCE code that reads the routing file uses colons and forward slashes to parse the routing file data lines for output files. 18.2 Using the Routing File The routing file contains examples of how to set up logging for various components. See the routing file itself for additional information. The routing file can be found in DCE$COMMON:[VAR.SVC]ROUTING.; 42