This document covers the following topics:
The runtime environment consists of a set of binaries and shared libraries on non-Windows systems (called dynamic link libraries or DLLs on Windows) and tools to monitor and manage the DCOM multi-user environment.
DCOM on Windows platforms is highly integrated with some basic operating system services such as process management, thread management, memory management and I/O functionality, since it requires these services to provide the DCOM functionality in a reasonable and way with high performance. On Windows, these services are provided by the kernel system and typically present a callable interface contained in the Win32 set of functions.
EntireX DCOM contains an implementation of a subset of the Microsoft Windows Kernel Services (Win32 Service Routines). This implementation provides basic services required for the EntireX DCOM runtime environment. The functionality required is implemented in different components of EntireX DCOM. Similar to the way in which the Windows kernel services are provided, the functionality is either provided in the user context (i.e. it is executed in a library that is linked to the user's application), or it is delegated to an out-of-process service (i.e. in a daemon process for UNIX).
Typically all services that do not need any coordination with other applications on the system are implemented in a library. The services that affect the whole system are performed by the external service. This approach avoids costly communication for all library-based services, but still provides the full Win32 semantics for all services with global scope.
The EntireX DCOM runtime environment can be classified as follows:
The Win32 system call library (libmutant)
The Windows kernel emulation process (ntd)
The authentication subsystem (paulad and paulas.exe)
The RPC runtime library (librpcrt4)
The TCP/IP loadable transport client library (librpcltccm)
The TCP/IP loadable transport server library (librpcltscm)
The Service Control Manager (rpcss)
The OLE32 library (libole32)
The Automation library (liboleaut32)
The registration server (regsvr)
The registry editor (regedit)
The DCOM configuration utility (dcomcnfg)
The monitoring tool (sermon)
The Running Object Table display tool (irotview)
The Structured Storage viewer utility (stgview)
These elements of the EntireX DCOM runtime environment are described in the following sections.
EntireX DCOM contains an implementation of a subset of the Microsoft Win32 Application Programming Interface (API) on non-Windows platforms. This implementation has been dubbed "Mutant".
The Mutant provides the system services required by EntireX DCOM and in addition those APIs which are considered to be required by typical DCOM applications. The following aspects, amongst others, are supported:
Process-and-thread APIs (based on the Posix threading model)
Synchronization APIs (events, semaphores, mutexes, critical sections, wait primitives)
The registry API
File I/O
File mapping
String processing
Impersonation
Security
The current release does not support the Win32 GUI-related APIs (windows, controls, drawing primitives etc.).
The Win32 subsystem is provided as a shared library (libmutant), daemon processes (ntd, paulad, ntdstarter) and a Windows service process (paulas.exe).
This library provides Win32 APIs on non-Windows platforms. EntireX DCOM applications access the Win32 APIs only through the libmutant library and thus must link with it. In order to handle objects shared between different EntireX DCOM applications, the libmutant library uses the services provided by ntd.
ntd, which typically runs as one daemon process per machine, maintains the global state shared by multiple DCOM applications (e.g. objects referred to by shared handles, and the system registry).
Since a running ntd is required for executing EntireX DCOM applications, it has to be started by
$ ntwopper ntd
ntd implicitly starts the EntireX daemons paulad and rpcss and that ntd, paulad and rpcss continue to run after you log off.
To stop ntd, type
$ sermon shutdown
This will also shut down all processes that were using ntd's services. Especially the EntireX daemon processes paulad and rpcss are shut down implicitly by this command.
This is the initial process that starts all other relevant daemons during startup of ntd. In dcomconfig there is an environment variable, COOL_NTD_INIT_IMAGE, that must point to the ntdinit process, for example:
COOL_NTD_INIT_IMAGE=$EXXDIR/$EXXVERS/bin/ntdinit
When ntd starts up, it launches ntdinit, which in turn checks the environment variable COOL_NTD_INIT_START
This variable specifies a set of characters (for example, 12...). Then
ntdinit looks for the set of environment variables COOL_NTD_INIT_COMMAND_x,
where x represents one of the characters in the
sequence specified by COOL_NTD_INIT_START. Subsequently, ntdinit starts the
processes that are defined by the COOL_NTD_INIT_COMMAND_x
variables. Typical definitions could be:
COOL_NTD_INIT_START=12 COOL_NTD_INIT_COMMAND_1=+$EXXDIR/$EXXVERS/bin/paulad COOL_NTD_INIT_COMMAND_2=+$EXXDIR/EXXVERS/bin/rpcss
The processes paulad and rpcss must be started in this way. Otherwise certain functions will not work correctly (authentication, impersonation).
For more information about COOL_NTD_INIT_START and COOL_NTD_INIT_COMMAND, see the section Environment Variables.
In order to start other DCOM servers under a different UNIX user ID, there must be one (lightweight) daemon which has the appropriate rights to launch other processes for different users. ntdstarter must be owned by root and must have the setuid and setgrid flags set. ntd will launch any other DCOM server which is to run under a different user ID than ntd itself using ntdstarter. The full path name of ntdstarter is specified in the environment variable COOL_RUNAS_STARTER.
The processes paulad and paulas.exe are the authentication subsystem processes that handle communication between a UNIX machine and the Windows domain controller.
On UNIX, all authentication is handled by a standalone daemon called paulad. The acronym paula stands for private authentication layer. It is responsible for communication with paulas.exe on the domain controller.
The daemon paulad is started implicitly when ntd is started.
If paulad terminates, all applications must be terminated and ntd has to be restarted. This is because the context of the secure channel that was established between ntd and paulad is lost and cannot be subsequently re-established.
paulad provides the following options:
-help: provides help information.
-local: performs authentication against the
local password file (see the environment variable COOL_PAULA_NTPWDFILE)
-[no]rpc: enables
(-rpc) or disables (-norpc) all
RPC requests to the domain controller. The default for UNIX is
-rpc.
By default, paulad uses the endpoint 1666 and the ncacn_ip_tcp transport. You can assign a different endpoint by setting the environment variable COOL_PAULA_DC_ENDPOINT accordingly.
Note:
The value you specify must be the same as the value that
paulas.exe uses on the Windows domain controller.
This is a Windows service process, and it must run on the primary domain controller for the domain where authentication will be used.
By default, the endpoint 1666 is used for communication. You can assign a different endpoint by supplying a value of type REG_DWORD for the name Endpoint under the key HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\Paula. The value you specify must be the same as the value that paulad uses on the UNIX machine.
You can also set the endpoint by typing:
paulas -stop paulas -endpoint number paulas -start
where number is replaced by the new endpoint number.
In order to provide secure communication between paulas.exe and paulad, all traffic between them is encrypted with a strong encryption algorithm. This algorithm requires a shared password between the two.
On UNIX, the password is stored in a file under the location pointed to by the environment variable COOL_PAULA_RPC_PASSWORD_FILE. In order to avoid users overriding this variable, it should not use the "+" feature of dcomconfig and must be readable only by the user running paulad.
On Windows this is stored in the file %SystemRoot%\System32\paula.txt.
The password file must contain a single line of text of up to 64 characters. Leading and trailing blanks and tab characters are relevant in this file. This entire line of text is used to encrypt the communication. SAG strongly recommend using a long and random string of numbers, upper and lowercase characters that cannot be easily remembered even by authorized personnel.
In order to secure the communication, you must use an NTFS file system for your Windows system disk and set an ACL on this file that allows access to it only for members of the administrator's group.
ntpasswd allows you to make DCOM authentication locally. This tool
works similarly to the passwd command on UNIX. By
default, you can only set and change your own password. Only the owner of the
file and the root user can also set and change the passwords of other users (in
this case you specify a user name as argument). The password entered is then
hashed and stored in the file pointed to by the environment variable
COOL_PAULA_NTPWDFILE (the default is
$EXXDIR/$EXXVERS/etc/ntpasswd.txt). Please make sure that
all users have read access to the file.
When paulad is started with the command-line argument
-local, ntd will authenticate the user against this
local password file instead of using the service
paulas.exe on your Windows domain controller.
Remember that the passwords must match the Windows passwords if there is any client/server communication with a Windows machine.
Note:
If the file pointed to by the environment variable
COOL_PAULA_NTPWDFILE does not exist, the user whose password is set first will
become the owner of the file. This need not necessarily be the user who
executes ntpasswd.
The RPC runtime environment consists of a set of shared libraries that are either loaded by the OLE32 runtime environment or linked to directly by RPC applications that do not use DCOM.
In particular there are the following libraries:
librpcrt4.so: the RPC runtime library
librpcltccm.so: the TCP/IP transport protocol access layer for clients
librpcltscm.so: the TCP/IP transport protocol access layer for servers
Access to these libraries and their functions is transparent for any OLE32 application.
There are no specific privileges required for these libraries.
There is a privileged helper process named coolprip that is used by rpcss to bind privileged TCP/IP ports. The coolprip binary must be owned by root, and the setuid bit has to be set for the owner. In addition, the file has to be located in a directory that is included in the search path for executables ($PATH).
The OLE service control manager rpcss (called SCM in previous versions of Windows) is the component that maintains the class cache and the running object table (ROT). It is responsible for OXID (Object eXporter ID) resolution and ping services in the DCOM implementation. It is also the RPC endpoint mapper. This program must be active on each machine that wants to run any DCOM application.
The rpcss is started implicitly by launching the ntd process.
On non-Windows platforms, rpcss is implemented as a daemon process, which is the equivalent of a Windows service manager process.
The rpcss process offers its services via TCP/IP to DCOM applications and to rpcss service managers on remote machines. It waits for applications to contact a well-known communications endpoint (port 135) to service their requests.
Since the endpoint currently defined for rpcss is in the range of the privileged TCP/IP ports, the UNIX daemon process needs root permission to declare its willingness to accept incoming service requests. For security reasons, there are some restrictions in the UNIX system that apply to applications that run with root privileges. Due to these restrictions a root-owned application is not allowed to use shared libraries outside the system library directories. To overcome this security restriction, the UNIX implementation of rpcss does not get root permissions itself, but makes use of a root-owned helper process. This helper application is started transparently by rpcss when privileged access to the port is required.
In the UNIX implementation, the rpcss service manager is based on the services provided by the Mutant environment.
The OLE32 library (libole32.so) provides the basic
DCOM functionality as well as higher-level technologies (structured storage,
naming and binding etc.). Each DCOM application must link with the OLE32
library. Before doing any other calls into this library, the application must
be initialized with a call to CoInitializeEx(). The
CoUninitialize() call frees all resources and closes
all open RPC commands.
There are no special privileges required for this library.
The Automation component of EntireX DCOM contains the following parts:
The Automation shared library liboleaut32.so
The type libraries stdole2.tlb and stdole32.tlb
The mktyplib, the port of the Microsoft Type Library Generator
The Automation library is required by mktyplib, midl (if creating type libraries with midl) and all Automation objects and controllers.
There are no specific privileges required for this library.
These type libraries describe the standard Automation interfaces. They are needed for all interfaces derived from IDispatch, ITypeInfo and IEnumVariant. See the Microsoft documentation for further details.
This is a DLL surrogate executable which enables DLL servers to run in
a surrogate process. To enable DLL servers to run in a surrogate process, a
named value
dllsurrogate=<surrogate-path>
under the key HKEY_CLASSES_ROOT\AppID\<appID-value>
must be specified. If <surrogate-path> is an
empty string, then the default surrogate dllhost is used.
There are no error codes specific to EntireX DCOM, other than the ones documented by Microsoft.
Help information can be found in the mktyplib help page (activated by
mktyplib -help) and existing Microsoft documentation for
mktyplib.
The EntireX DCOM version of mktyplib is based on version 2.0.0 of mktyplib on Windows. EntireX DCOM specific version information is available in the signature.
This section provides a brief description of the utilities available in the runtime environment.
The regsvr utility is an application that is used to register and un-register proxy/stub libraries.
Usage: regsvr [-u] [-s]
libraryname
where -u means un-register the server instead of
registering it, and -s requests silent operation (no
output messages).
If the call is successful, OK will be output, otherwise a message "failed to load ..." will be output.
Refer also to the Microsoft documentation for regsvr32.
The Software AG registry editor is an X11/Motif application with similar (but not identical) functionality and look and feel to the Microsoft Registry Editor, Version 4.0.
The regedit editor has a user-friendly graphical user interface (GUI) which provides the following features:
Browsing the current registry keys, as well as string, DWORD and binary values
Expanding and collapsing branches of the current registry tree
Adding new keys and values
Editing values
Removing keys and values
Renaming keys
Importing registry data from files
Exporting registry (sub)trees to files
The program consists of the following parts:
regedit: executable (required)
regedit.uid: binary UID resources used by Motif (required)
regedit.ad: app-defaults file (optional)
The regedit.uid files must be located either in a system default location for UID files (e.g. for X11 environments: /usr/lib/X11/app-defaults, or for Sun: /usr/openwin/lib/app-defaults) or in one of the directories listed in the UIDPATH environment variable.
If you do not wish to copy it to a system default location, set the UIDPATH variable, e.g. (using C Shell syntax):
if (! $?UIDPATH) then
setenv UIDPATH %U:<path>/%U
else
setenv UIDPATH ${UIDPATH}:%U:<path>/%U
endif
where <path> is the directory in which regedit.uid is located.
For more information on the functionality of the registry editor, consult the online help provided with it. Refer also to the Microsoft documentation for regedit.
The DCOM Configuration Utility dcomcnfg is a command-line utility. It allows you to configure the following settings. These settings are stored in the DCOM registry under the key HKEY_CLASSES_ROOT\SOFTWARE\Microsoft\OLE
EnableDCOM DefaultLaunchPermission DefaultAccessPermission LegacyAuthenticationLevel LegacyImpersonationLevel DefaultConfigurationPermission
You can also configure the DCOM application settings that are stored under the key HKEY_CLASSES_ROOT\AppID\<app-id> , where <appid> is a GUID that identifies one application, under the value names:
AccessPermission LaunchPermission RemoteServerName RunAs ConfigurationPermission
The EnableDCOM value specifies whether DCOM is to be enabled (value Y) or disabled (value N) on the machine.
The DefaultLaunchPermission and DefaultAccessPermission values control which users are by default allowed to launch DCOM servers or access already running DCOM servers. Correct values are valid user or group names known on the machine and the special value "Everyone", which grants launch/access permission to any user.
The LegacyAuthenticationLevel value specifies the default level of authentication information to be sent with RPC packets across process (and machine) boundaries. The following values are allowed:
0: Default
1: None
2: Connect
3: Call
4: Packet
5: PacketIntegrity
6: PacketPrivacy
The LegacyImpersonationLevel value specifies the default level of impersonation for applications. The following values are valid.
1: Anonymous
2: Identify
3: Impersonate
4: Delegate
Note, however, that the Passthrough Authentication service paula and the NTLMSSP authentication service on Windows support only the "Identify" and "Impersonate" settings.
DefaultConfigurationPermission values can be a list of users who have permissions to alter the AppID settings in the registry.
Application-specific settings can be specified under HKEY_CLASSES_ROOT\AppID\<app-id> , where <appid> is a GUID identifying the application. The default launch and access permissions can be overridden for specific applications by defining LaunchPermission and AccessPermission values as described above. To delete these values, set them to the special value "Default".
You can specify, by setting the RunAs value, the identity with which a server will be launched. Valid values are any usernames known to the machine as well as the special value Launching User which specifies that the given DCOM server will be launched under the user ID of the client process on whose behalf the server is started. To delete the RunAs value, set it to the special value "Default".
The RemoteServerName value can be used to specify a remote machine name on which the server executable resides. The special value "This Computer" directs dcomcnfg to delete the RemoteServerName value from the registry.
ConfigurationPermission values list the users who have the permission to alter the AppID setting of the specified server in the registry.
Note:
Only the system user (the user under whose ID ntd is
running) is allowed to alter the DefaultConfigurationPermission and
ConfigurationPermission values. Only users who have been granted
ConfigurationPermission can change the configuration values for applications (
RunAs, RemoteServerName etc.)
Calling dcomcnfg -init initializes the AppIDs in the
registry from the CLSID entries. You must execute dcomcnfg -init
when EntireX DCOM is installed and each time a new application is to be
configured for which there is no AppID key in the registry.
Run dcomcnfg -help for usage information.
In addition to ntd and the libmutant shared library, there is a command-line tool called sermon which provides basic administration services for the Windows subsystem.
You can obtain a summary of sermon facilities by typing sermon
help.
This is a simple Motif-based tool that displays all objects currently registered in the Running Object Table (ROT).
Usage:
irotview
To refresh the display select Refresh from the menu.
Refer also to the Microsoft documentation for irotview.
This console-based utility displays the contents of a structured storage file (e.g. names of embedded storage and streams and hexadecimal dump of stream contents).
Usage:
stgview <options> <docfile>
For a description of the supported options, run the utility with the
-h option.
This is a tool to view the contents of a type library. The output is in idl format.
Usage:
tlviewer <type library> [ <outputfile> [/o]]
If no outputfile is specified, the default value for the output file is tlviewer.out.
The option /o (which is the default) forces tlviewer to generate a message file tlviewer.msg.
Example:
tlviewer vartypes.tlb vartypes-tlb.out
(reads the type library vartypes.tlb and writes the output to file vartypes-tlb.out).
The registry can be edited using either regedit or the sermon tool, both of which access the registry through the Win32 registry APIs.
The registry on non-Windows platforms is a multiuser registry.
The memory resident registry is maintained by ntd. When ntd is started, it attempts to load the file $COOL_PERSISTREG/regdata.reg. If the file is not found, ntd creates this file automatically with default settings.
While ntd is running, it checks on a regular basis if the memory resident registry has changed. If it has changed, the file $COOL_PERSISTREG/regdata.cur is written (overwriting any existing version) as a snapshot of the current registry.
In addition, when ntd is started it creates a backup of the registry in a file named $COOL_PERSISTREG/regdata.bak.
Note:
The persistent (i.e. disk-resident) registry
$COOL_PERSISTREG/regdata.reg will only be updated in the
following circumstances:
If you type sermon shutdown.
If you type sermon registry commit.
If you use regsvr to register or unregister proxy/stub libraries.
Therefore, it is important to shut down ntd cleanly with sermon
shutdown before switching off or rebooting the host.
The following features are not currently supported by the regedit editor:
Working with remote registries
Renaming keys
Copying keys