Document revision date: 19 July 1999

OpenVMS Connectivity Developer Guide


Previous Contents Index

The difference between REG$K_EXPAND_SZ and REG$K_SZ

A string is a set of characters usually in human-readable form. Many value entries in the OpenVMS Registry are written using a string (REG_SZ) or an expandable string (REG_EXPAND_SZ) format. An expandable string is usually human-readable text, but it can also include a variable that will be replaced when the string is called by an application.

For example, on a Windows NT system, in the value entry %SystemRoot%\System32\Bootok.exe, %SystemRoot% is the expandable portion of the variable. This part is replaced with the actual location of the directory that contains the Windows NT system files.

REG$_DISPOSITION

The REG$_DISPOSITION item code is an output item code. It is a longword and takes one of the following values:
Disposition value Description
REG$K_CREATENEWKEY The key did not exist and was created.
REG$K_OPENEXISTINGKEY The key existed and was opened.

REG$_FLAGOPCODE

The REG$_FLAGOPCODE item code is an input item code. It is a longword flag that indicates how the REG$_DATAFLAGS input item code should be matched against the data flags field in the OpenVMS Registry database. It takes one of the following values:
Operator code options Description
REG$K_ANY The data field in the OpenVMS Registry database must contain at least one of the flags in the REG$_DATAFLAGS input item code.
REG$K_EXACTMATCH The REG$_DATAFLAGS input item code must match exactly the data flags field in the OpenVMS Registry database.
REG$K_EXCLUDE The data flags field in the OpenVMS Registry database must not contain the flags in the REG$_DATAFLAGS input item code.
REG$K_INCLUDE The data flags field in the OpenVMS Registry database must contain, at a minimum, the flags in the REG$_DATAFLAGS input item code.
REG$K_NOTANY The data field in the OpenVMS Registry database must not contain any of the flags in the REG$_DATAFLAGS input item code.

REG$_FLAGSUBKEY

The REG$_FLAGSUBKEY item code is an input item code. It is a longword Boolean field that indicates the following:

REG$_KEYID

The REG$_KEYID item code is an input item code. It is a longword that contains the key identifier.

REG$_KEYRESULT

The REG$_KEYRESULT item code is an output item code. It is a longword that receives a key identifier. The key identifier can be passed to other Registry calls using the REG$_KEYID item code.

REG$_KEYPATH

The REG$_KEYPATH item code is an input item code. It is a string of Unicode characters that specifies a key path. A Unicode character is 4 bytes long.

REG$_LASTWRITE

The REG$_LASTWRITE item code is an output item code. It is a quadword representation of absolute time that receives the time a specified key was last written to (including changes to its values).

REG$_LINKCOUNT

The REG$_LINKCOUNT item code is an output item code. It is longword count of the number of symbolic links that refer to the item.

REG$_LINKPATH

The REG$_LINKPATH item code is, depending on the function code, either an input or an output item code. It is a string of Unicode characters that specifies the key path to which a specified key is linked. A Unicode character is 4 bytes long.

REG$_LINKTYPE

The REG$_LINKTYPE item code is, depending on the function code, either an input or an output item code. It is longword type that indicates the link type.
Link Type Description
REG$K_NONE No link (default)
REG$K_SYMBOLICLINK Symbolic (logical) link

REG$_NEWNAME

The REG$_NEWNAME item code is a string of Unicode characters that specifies the new name of the key.

REG$_NOTIFYFILTER

The REG$_NOTIFYFILTER item code is an input item code. It is a longword mask that specifies which changes to the specified key and its subkeys and values to report. It takes any combination of the following values:
Value Description
REG$M_CHANGEATTRIBUTES An attribute change of the specified key or its subkeys.
REG$M_CHANGELASTSET Changes to the last write time of the specified key or its subkeys.
REG$M_CHANGENAME A key name change, including creation and deletion, of the specified key or its subkeys.

Note

The system report changes to subkeys of the specified key only if the REG$_FLAGSUBKEY item code is set to 1.

REG$_PATHBUFFER

The REG$_PATHBUFFER item code is an output item code. It is a buffer that receives a set of either key paths or value paths, separated by a null Unicode character (4 bytes long). (The third longword of the item descriptor contains the number of bytes written to the buffer.)

REG$_REQLENGTH

The REG$_REQLENGTH item code is an output item code. It is a longword that receives the required buffer size (in bytes) to complete the operation successfully.

REG$_RETURNSTATUS

The REG$_RETURNSTATUS item code is an output item code. It is a longword that receives the final completion status for a specified operation. For more information, see the Condition Values Returned section of this chapter.

REG$_SECACCESS

The REG$_SECACCESS item code is an input item code. It is a longword mask that specifies the desired security access for the new key. It takes any combination of the following values:
Security access mask Description
REG$M_ALLACCESS A combination of the following access values:
  • REG$K_CREATELINK
  • REG$K_CREATESUBKEY
  • REG$K_ENUMSUBKEYS
  • REG$K_NOTIFY
  • REG$K_QUERYVALUE
  • REG$K_SETVALUE
REG$M_CREATELINK Allows creation of a symbolic link.
REG$M_CREATESUBKEY Allows creation of subkeys.
REG$M_ENUMSUBKEYS Allows enumeration of subkeys.
REG$M_EXECUTE Allows read access.
REG$M_NOTIFY Allows change notification.
REG$M_QUERYVALUE Allows queries of subkey data.
REG$M_READ A combination of the following access values:
  • REG$K_ENUMSUBKEYS
  • REG$K_QUERYVALUE
  • REG$K_NOTIFY
REG$M_SETVALUE Allows setting of values and data.
REG$M_WRITE A combination of the following access values:
  • REG$K_CREATESUBKEY
  • REG$K_SETVALUE

REG$_SECURITYPOLICY

The REG$_SECURITYPOLICY item code is an input item code. It is a longword that specifies the security policy to enforce for the key. It takes the following value:
Policy Setting Description
REG$K_POLICY_NT_40 Access is required to the first key and the requested key (default).

REG$_SEPARATOR

The REG$_SEPARATOR item code is an empty item code that provides a separator between sets of item codes.

Using this item code, you can group multiple requests into a single call to the $REGISTRY service. If you use this multiple-request feature, use the REG$_SEPARATOR item code to indicate the end of the set of item codes for the current request and that there is another request to process.

REG$_SUBKEYINDEX

The REG$_SUBKEYINDEX item code is an input item code. It is a longword that specifies the index of the subkey to retrieve.

REG$_SUBKEYNAME

The REG$_SUBKEYNAME item code is an input item code. It is a string of Unicode characters that specifies the name of a subkey. A Unicode character is 4 bytes long.

REG$_SUBKEYNAMEMAX

The REG$_SUBKEYNAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest subkey name.

REG$_SUBKEYSNUMBER

The REG$_SUBKEYSNUMBER item code is an output item code. It is a longword that receives the number of subkeys contained in a specified key.

REG$_VALUEINDEX

The REG$_VALUEINDEX item code is an input item code. It is a longword that specifies the index of the value to retrieve within a specified key. Note that the value index starts at zero and can be any value up to one less than the count returned by REG$_VALUENUMBER.

REG$_VALUEDATA

The REG$_VALUEDATA item code is, depending on the function code, either an input or output item code. It is a buffer that contains either the value data component to write to the OpenVMS Registry (input), or it receives a data value component from the OpenVMS Registry (output).

REG$_VALUEDATAMAX

The REG$_VALUEDATAMAX item code is an output item code. It is a longword that receives the length (in bytes) of the specified key's longest data component value.

REG$_VALUENAME

The REG$_VALUENAME item code is, depending on the function code, either an input or an output item code. It is a string of Unicode characters that specifies the name of a value.

REG$_VALUENAMEMAX

The REG$_VALUENAMEMAX item code is an output item code. It is a longword that receives the length (in characters) of a specified key's longest value name.

REG$_VALUENUMBER

The REG$_VALUENUMBER item code is an output item code. It is a longword that receives the number of values contained in a specified key.

REG$_VOLATILE

The REG$_VOLATILE item code identifies the volatility of an item. As an output, it returns the volatility of the object. On OpenVMS, volatile keys and values are lost when all nodes running an OpenVMS Registry server are rebooted. (In a standalone system, volatile keys and values are lost when the system reboots.)
Volatile Type Description
REG$K_CLUSTER The item is removed when the cluster reboots.
REG$K_NONE The item is not volatile (default).
Function Modifiers You can optionally specify the high-order bits of a function code value with function modifiers. These individual bits can alter the operation of the function.

For example, you can specify the function modifier REG$M_CASE_SENSITIVE with the function REG$FC_CREATE_KEY. When you use the function and function modifier together, the data passed to the OpenVMS Registry is treated as case sensitive. The two values are written in DEC C as REG$M_CASE_SENSITIVE | REG$FC_CREATE_KEY.

The OpenVMS Registry function modifiers are defined in the header file REGDEF.H.

REG$M_CASE_SENSITIVE

Use case-sensitive matching for keys and values.

REG$M_DISABLE_WILDCARDS

Treat wildcard characters as normal characters for this function.

REG$M_IGNORE_LINKS

Force the operation to not follow any symbolic links associated with a key or a value.

By default, if a key or value is symbolically linked to another key or value, the system follows all links so that the operation specified by the function code is performed on the linked key or value.

When you specify the REG$M_IGNORE_LINKS function modifier, the operation specified by the function code affects only the specified key or value, not the linked key or value.

By default, if a key or value has a symbolic link, it can not be deleted. If you specify the REG$M_IGNORE_LINKS function modifier, the system deletes the key or value.

REG$M_NOW

Write to disk immediately, regardless of the REG$_CACHEACTION item code value.


Part 3
OpenVMS Events

This part contains reference information about OpenVMS Events.


Chapter 11
OpenVMS Events

11.1 What are Events?

On a Windows NT system, an event is any significant occurrence in the system or an application---for example, a service starting or stopping, a user logging on or off, or accessing resources. When the system encounters an event, the Event Log service writes the event (or audit entry) in the form of a record that contains date and time, source, category, event number, user, and computer information to a system, security, or application log, creating an audit trail. On Windows NT systems, you display these logs and their recorded events using the Event Viewer.

With COM Version 1.0 for OpenVMS, OpenVMS wrote all COM for OpenVMS events to the DCOM$EVENTLOG.RPT text file. With COM Version 1.1 for OpenVMS, OpenVMS supports both Windows NT logging and Advanced Server for OpenVMS logging of COM for OpenVMS events. You can now log a COM for OpenVMS event (such as the starting of a COM server on OpenVMS), and review these OpenVMS events from a Windows NT system or an OpenVMS system.

For a detailed review of OpenVMS Events dependencies and a description of how OpenVMS Events interacts with other parts of the OpenVMS infrastructure, see Section 4.9.

11.1.1 Suggested Reading

The following sources can provide you with more information on Events and related topics:

11.2 Overview of OpenVMS Events

The system logs OpenVMS Events to a Windows NT event log, to the Advanced Server for OpenVMS event log, and to a log file on the OpenVMS system.

You can use the following techniques to view OpenVMS Events:

11.2.1 Viewing OpenVMS Events Using Windows NT Event Viewer

Use the following procedure to view OpenVMS Events through the Windows NT event viewer:

  1. Start the Windows NT event viewer.
    From the Start menu, select Programs, Administrative Tools, Event Viewer.
  2. From the Event Viewer window, click the menu bar Log option. Click Select Computer...., and select the OpenVMS system from the list box.
  3. From the Event Viewer window, click the menu bar Log option. Click System to display the System event log. The System event log contains the COM for OpenVMS events.
    To display COM for OpenVMS events only, use the following procedure:

11.2.2 Viewing OpenVMS Events Using Advanced Server for OpenVMS Event Viewer

Use the following procedure to view the COM for OpenVMS events:

  1. Ensure that the Advanced Server for OpenVMS is running.
  2. Enter the following Advanced Server for OpenVMS ADMINISTRATOR command:


      $ ADMIN SHOW EVENTS/TYPE=SYSTEM/SOURCE=DCOM/FULL 
    

    The viewer displays COM for OpenVMS events only, along with any additional information associated with the COM for OpenVMS event.

11.2.3 Event Logging on OpenVMS Only

In some cases, you might want to write and view COM for OpenVMS events only on an OpenVMS system. In place of the Windows NT log, Compaq has included an alternate event logger that writes COM event information to an OpenVMS file. You can find this file in the following location:


SYS$MANAGER:DCOM$EVENTLOG.RPT 

COM for OpenVMS creates this event logging report automatically when the COM server (DCOM$RPCSS) encounters an error. The event logger appends new events at the bottom (end) of the file. A logged event has the following format:


event type : ddd mmm dd hh:mm:ss yyyy
First event message
 
event type : ddd mmm dd hh:mm:ss yyyy
Second event message
. 
. 
. 

Example 11-1 shows the contents of an event log.

Example 11-1 Sample OpenVMS Event Log

$ Type SYS$MANAGER:DCOM$EVENTLOG.RPT 
 
(1)
ERROR : Tue Sep 15 11:18:54 1998 
Unable to start a DCOM Server: {5E9DDEC7-5767-11CF-BEAB-00AA006C3606} 
Runas (null)/SMITH 
The Windows NT error: 1326 
Happened while starting: device:[account]SSERVER.EXE 
 
(2)
ERROR : Tue Sep 15 19:14:45 1998 
The server {0C092C21-882C-11CF-A6BB-0080C7B2D682} did not register 
with DCOM within the required timeout. 
 

  1. The system logged the first error event on Tue Sep 15 11:18:54 1998. The COM server (DCOM$RPCSS) was unable to start the COM application device:[account]SSERVER.EXE on behalf of the client running under the SMITH account. (The client may have received an error such as "access denied.") The resulting Windows NT error was 1326, which translates as "Logon failure: unknown user name or bad password."
    If you see this error, check the validity of the user account using the OpenVMS Authorize utility (AUTHORIZE).
  2. The system logged the second error event on Tue Sep 15 19:14:45 1998. The COM server (DCOM$RPCSS) was able to start the COM application {0C092C21-882C-11CF-A6BB-0080C7B2D682}, but the application did not run successfully. The application failed to register with DCOM$RPCSS within the specified time limit. (The client may have received an error such as "Server execution failed" CO_E_SERVER_EXEC_FAILURE.)
    If you see this error, run the server application interactively to determine its integrity.

NTA$EVENTW

Allows an application to record information in the event log files.

The NTA$EVENTW routine completes all operations synchronously.


Format

NTA$EVENTW [nullarg], func, itmlst, evsb


Arguments

nullarg


OpenVMS usage: reserved
type: longword (unsigned)
access: read only
mechanism: by value

Reserved for Compaq use.

func


OpenVMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by value

Function code specifying the function NTA$EVENTW is to perform. The func argument is a longword containing this function code. The $EVENTDEF macro defines the names of each function code.

itmlst


OpenVMS usage: address of item list
type: 64-bit address
access: read only
mechanism: by value

Item list specifying information about the event source or the event. The itmlst argument is the 64-bit address of a list of item descriptors, each of which describes an item of information. An item list in 64-bit format is terminated by a quadword of 0.

The following diagram shows the 64-bit format of a single item descriptor.


evsb


OpenVMS usage: address of status block
type: 64-bit address
access: write only
mechanism: by reference

Event status block to contain the completion status for the requested operation.

NTA$EVENTW sets the status block to 0 upon request initiation. Upon request completion, the EVT$L_VMS_STATUS field contains the primary (OpenVMS) completion status for the operation.

If an error occurs, EVT$L_NT_STATUS (if non-zero) is the secondary error status to further define the error condition. Function Codes

EVT$_FC_REGISTER_EVENT_SOURCE

Open an association with an event log.
Item code Required Parameter Data type
EVT$_SERVER_NAME No Input String (4-byte Unicode)
EVT$_SOURCE No Input String (4-byte Unicode)
EVT$_HANDLE Yes Output Unsigned longword

EVT$_FC_REPORT_EVENT

Generate an event log entry.
Item code Required Parameter Data type
EVT$_HANDLE Yes Input Unsigned longword
EVT$_EVENT_TYPE Yes Input Word mask
EVT$_EVENT_CATEGORY No Input Word
EVT$_EVENT_ID Yes Input Longword
EVT$_USER_SID No Input NT Security ID
EVT$_NUMSTRINGS No Input Word
EVT$_DATASIZE No Input Longword
EVT$_STRING_ARRAY No Input Array of varying-length descriptors. (4-byte Unicode)
EVT$_RAW_DATA No Input Binary data

EVT$_DEREGISTER_EVENT_SOURCE

Close an association with an event log.
Item code Required Parameter Data type
EVT$_HANDLE Yes Input Unsigned longword
Item Codes
Item Code Parameter Type Data Type
EVT$_SERVER_NAME Input String
EVT$_SOURCE Input String
EVT$_HANDLE Input/Output Unsigned longword
EVT$_EVENT_TYPE Input Word mask
EVT$_EVENT_CATEGORY Input Word
EVT$_EVENT_ID Input Longword
EVT$_USER_SID Input NT security ID
EVT$_NUMSTRINGS Input Word
EVT$_DATASIZE Input Longword
EVT$_STRING_ARRAY Input Array of string pointers
EVT$_RAW_DATA Input Binary data
Description The NTA$EVENTW routine allows you to register and deregister an event source and report event data. This event logging allows you to record information from within an application. You can use the events routines to track progress within an application or identify problems encountered by an application.

The NTA$EVENTW routine completes synchronously; that is, control is returned to the caller only after the request completes.

Use the following process to write event data:

  1. Register the event source.
    This operation defines the event log to which the system writes event data.
  2. Report the event.
    This operation causes the system to write the information to the appropriate event log.
  3. Deregister the event source.
    This operation frees resources acquired as part of the event source registration operation.

Condition Values Returned

SS$_NORMAL Service completed successfully.
SS$_ACCVIO One of the arguments cannot be read/written.
SS$_BADPARAM Bad parameter.
SS$_NOPRIV Insufficient privilege to access the specified event log.
SS$_TIMEOUT Request timed out.
SS$_UNREACHABLE Events service unavailable.
SS$_REJECT The Windows NT LAN Manager server encountered an error. See the Win32 status for more information.

11.3 Writing Your Own Events

By default, the system logs DCOM events generated by COM for OpenVMS. In addition to recording COM for OpenVMS events, the system can also log COM application events for COM applications that you create.

The COM for OpenVMS kit includes sample code that shows how to generate an application event using Win32 APIs. You can use this example as is on a Windows NT system. The example also builds correctly using the instructions for building COM for OpenVMS applications on OpenVMS (to get the required header files from DCOM$LIBRARY). See Chapter 6 for these instructions. The example also includes the linking instructions to build the example using Wind/U.

11.4 Troubleshooting OpenVMS Events

Errors that occur during event reporting can be difficult to trace because of the number of intervening software layers through which the event passes. The following list describes how OpenVMS Events pass through other software layers until they are recorded in the Windows NT log.

  1. An application calls one of the Win32 event functions (RegisterEventSource, ReportEvent, or DeregisterEventSource).
  2. Using the supplied arguments, the Win32 API builds an appropriate item list and calls the NTA$EVENTW routine.
  3. The NTA$EVENTW routine validates the information supplied (function code, item list, and so on) and builds an appropriate item list for the SYS$ACM system service.
    If NTA$EVENT detects any errors NTA$EVENT returns the errors to the Win32 API using R0 and the event status block.
  4. The SYS$ACM system service validates the information and passes it to the NT ACME.
    If SYS$ACM detects any errors, SYS$ACM returns the errors to NTA$EVENTW using R0 and the ACM status block..
  5. The NT ACME passes the supplied information (using an IPC pipe) to a dispatcher in the Advanced Server for OpenVMS.
    If the NT ACME detects any errors, the NT ACME returns the errors to the caller using the ACM status block.
  6. The Advanced Server for OpenVMS dispatcher validates the information and calls the appropriate routines to perform the requested operation (register, report, or deregister).
    If the Advanced Server for OpenVMS detects any errors, it reports the errors to the NT ACME. The NT ACME passes the errors back to the other callers.

Checking the contents of the event status block help you determine where the failure might have happened. Table 11-1 lists (in order of importance) the checks you should perform.

Table 11-1 Troubleshooting OpenVMS Events Failures
R0 Status Status Field Value Component to Check
Failure (bit 0 clear) EVT$L_NT_STATUS field is nonzero. Error most likely occurred within Advanced Server for OpenVMS.
Failure EVT$L_VMS_STATUS field is nonzero and the EVT$L_NT_STATUS is zero. Error most likely occurred within the SYS$ACM system service or the NT ACME.
Failure EVT$L_VMS_STATUS is zero and EVT$L_NT_STATUS is zero. Error most likely occurred within the SYS$ACM system service.

Note

The Win32 API usually converts the error status to an appropriate NT error status code and makes it available through the GetLastError Win32 API. (The status returned by the event API simply indicates a generic failure.)


Part 4
Authentication

This part contains reference information about authenticating users and applications between platforms.


Chapter 12
Authentication

12.1 What is Authentication?

Authentication is the act of verifying a user's identity by the computer system before permitting access to the system. After successfully authenticating a user, the system binds the user's authorization information to the user's process in the form of credentials. The system uses these credentials to determine whether to grant or deny access to system resources.

OpenVMS provides both native (SYSUAF-based) and Windows NT-compatible authentication and authorization capabilities as follows:

After OpenVMS successfully authenticates a user (either native or Windows NT), OpenVMS attaches the user's native credentials to the process using a structure known as a persona. If the system used Windows NT for authentication, OpenVMS also attaches the user's Windows NT credentials to the process (as an extension to the persona).

12.2 Acquiring Windows NT Credentials Using NTA$LOGON

NTA$LOGON is a utility that allows you to acquire NTLM credentials. All processes that need Windows NT security to access the OpenVMS Registry or COM for OpenVMS facilities require NTLM credentials.

You must provide NTA$LOGON with a user account name, a password, and (if required) a domain name. NTA$LOGON uses the Authentication and Credential Management (ACM) Authority to contact the domain controller and acquire a Windows NT access token. NTA$LOGON merges the Windows NT information with the user's OpenVMS credentials.

For a detailed review of NTA$LOGON dependencies and a description of how NTA$LOGON interacts with other parts of the OpenVMS infrastructure, see Section 4.8 and Section 4.9 (especially the ACME server and Advanced Server for OpenVMS server).

To use the NTA$LOGON utility, you can enter any of the following:

Table 12-1 shows the NTA$LOGON utility command line parameters.

Table 12-1 NTA$LOGON Utility Command Line Parameters
Argument Value Required/Optional
P1 User account name. If an account name is needed but was not specified on the command line, NTA$LOGON prompts for input. Optional
P2 Password. If a password is needed but was not supplied on the command line, NTA$LOGON prompts for input (echoing suppressed). Optional

Example 12-1 shows a typical NTA$LOGON session to acquire credentials.

Example 12-1 Sample NTA$LOGON Session

    $ NTLOGON :== $NTA$LOGON 
    $ NTLOGON joesmith 
    Password: 

Note

Windows NT domain names and user account names are not case sensitive. NTA$LOGON converts all domain names and user account names to uppercase. If you specify a password on the command line, DCL converts all characters to uppercase, unless you enclose the password in quotation marks ("").

12.2.1 NTA$LOGON Optional Qualifiers

NTA$LOGON accepts the following optional qualifiers:

12.2.2 Examples of Using NTA$LOGON to Acquire Windows NT Credentials

Example 12-2 shows how a user acquires NT credentials for the first time.

Example 12-2 Acquiring Windows NT Credentials for the First Time

    $ NTLOGON :== $NTA$LOGON 
    $ NTLOGON/LIST 
    ERROR: NtOpenProcessToken() failure: -1073741700 0xc000007c 
    %SYSTEM-E-NOSUCHEXT, no such extension found 
 
    $ NTLOGON/LOG JOESMITH 
    [Persona #1 NT extension: Account= "JOESMITH" Domain= "NT_DOMAIN" ] 
    Password: 

Example 12-3 shows how the user replaces the Windows NT credentials.

Example 12-3 Replacing Windows NT Credentials

    $ NTLOGON/DELETE 
    $ NTLOGON/OVERRIDE_MAPPING/DOMAIN=OTHER_DOMAIN 
    Username: janebrown 
    Password: 

Example 12-4 shows how a user saves a password in a disk file. The system requests that the user enter the password twice with echoing suppressed.

Example 12-4 Saving a Password to a File

    $ NTLOGON :== $NTA$LOGON 
    $ NTLOGON/WRITE_FILE=DEV:[DIR]NTA$LOGON.DAT COM_SERVER 
    Password: 
    Confirm:  
    $ NTLOGON/READ_FILE=DEV:[DIR]NTA$LOGON.DAT/LIST 
    File DEV:[DIR]NTA$LOGON.DAT contains the following records: 
    02-MAR-1999 16:57:23.20 COM_SERVER 

After you have created this file, you can add the following to a DCL command procedure:


    $ NTLOGON :== $NTA$LOGON 
    $ NTLOGON/READ_FILE=DEV:[DIR]NTA$LOGON.DAT COM_SERVER 

12.3 The Authentication and Credential Management (ACM) Authority

The Authentication and Credential Management authority authenticates users and determines the user security profile for OpenVMS and Windows NT. The ACME_SERVER process provides these ACM services. The ACME_SERVER process uses plug-in modules called ACME agents. ACME agents perform the actual work of responding to authentication requests, query requests, and event requests.

The OpenVMS ACME agent (VMS$VMS_ACMESHR.EXE) provides OpenVMS native services. The MSV1_0 ACME agent (PWRK$MSV1_0_ACMESHR.EXE, an Advanced Server for OpenVMS product component) provides Windows NT connectivity services.

The MSV1_0 ACME agent forwards Windows NT connectivity service requests from NTA$LOGON and SSPI/NTLM to an Advanced Server for OpenVMS process running on one or more systems in the cluster. The PWRK$ACME_SERVER logical name can contain a comma-delimited list of cluster node names to which the MSV1_0 ACME can forward requests. Running the Advanced Server for OpenVMS process on more than one cluster node and including the node names in the PWRK$ACME_SERVER logical name allows the MSV1_0 ACME agent to fail over a request automatically if a connection is interrupted. If the logical name is undefined, the system defaults to the local machine name.

The ACME_SERVER process must be present on any system running RPC or COM for OpenVMS. However, the Advanced Server for OpenVMS process needs to be present on only one node in the cluster.

12.3.1 Windows NT Authentication on OpenVMS

Because the ACME_SERVER returns to its callers a complete OpenVMS persona with the requested attached Windows NT persona extension, the VMS ACME agent enforces the following rules:

12.3.2 Authenticating a Windows NT User; Granting Windows NT Credentials to an OpenVMS Process

To authenticate a Windows NT user on OpenVMS and attach the Windows NT user's credentials to an OpenVMS process, do the following:

  1. Define a HOSTMAP entry in the Advanced Server for OpenVMS database.
    A HOSTMAP entry defines the association between a Windows NT user account and a local OpenVMS user account. When OpenVMS authenticates a Windows NT user, OpenVMS uses the HOSTMAP entry to map the OpenVMS user account to the Windows NT user account and build the local OpenVMS user profile and the Windows NT user profile. If no HOSTMAP entry exists, OpenVMS uses the Windows NT user account name as the local OpenVMS user account name.
    Use the Advanced Server for OpenVMS ADMINISTER utility to define HOSTMAP information. For example, to map Windows NT user FRED to the local OpenVMS user account FREDERICK, enter the following command:


      $ ADMINISTER ADD HOSTMAP FRED FREDERICK 
    

    If FRED is defined in trusted domain FINANCE, you must specify the trusted domain name in the HOSTMAP entry. For example:


      $ ADMINISTER ADD HOSTMAP FINANCE\FRED FREDERICK 
    

  2. Enable the OpenVMS user account for hostmapping.
    By default, OpenVMS can use only OpenVMS user accounts that have the EXTAUTH flag set for hostmapping. This policy allows the OpenVMS system manager to control which OpenVMS user accounts can be used with Windows NT authentication.
    (You can override this per-account restriction systemwide by setting the IGNORE_EXTAUTH bit [bit number 11 (decimal)] in the SECURITY_POLICY system parameter.)
    Use the AUTHORIZE utility to set the EXTAUTH flag on an OpenVMS user account. For example, you can enable the EXTAUTH flag for the OpenVMS user account FREDERICK as follows:


      $ AUTHORIZE MODIFY FREDERICK/FLAG=EXTAUTH 
    

12.3.3 Managing the ACME_SERVER Process (ACME Server Commands)

To start the ACME_SERVER process and configure the MSV1_0 ACME agent at system startup, add the following entry to SYLOGICALS.COM:


  $ DEFINE NTA$NT_ACME_TO_BE_STARTED YES 

You can also start the ACME_SERVER process manually using the following startup command file:


  $ @SYS$STARTUP:NTA$STARTUP_NT_ACME 

To shut down ACME_SERVER, enter the following command:


  $ SET SERVER ACME/EXIT 

If an abnormal condition in an ACME agent prevents a normal server shutdown, use the /ABORT qualifier in the place of the /EXIT qualifier to force the ACME_SERVER to terminate.

To turn on ACME_SERVER logging, enter the following command:


  $ SET SERVER ACME/LOG 

This command creates a ACME$SERVER.LOG file in the SYS$MANAGER directory. You might find this file useful when you are trying to diagnose potential problems.

To display the ACME_SERVER configuration information, enter the following command:


  $ SHOW SERVER ACME[/FULL] 

12.3.4 Configuring the MSV1_0 ACME Agent

Table 12-2 lists and describes systemwide logical names you can use to control certain features of the MSV1_0 ACME agent.

Table 12-2 MSV1_0 ACME Agent Logical Names
Logical name Description
PWRK$ACME_SERVER Comma-delimited list of cluster SCS node names that are running Advanced Server for OpenVMS processes that can service Windows NT connectivity requests. If you do not define the node names, the MSV1_0 ACME agent tries to connect to the Advanced Server for OpenVMS process on the local system.
PWRK$ACME_RETRY_COUNT The maximum number of retry attempts the MSV1_0 ACME agent performs when connecting to an Advanced Server for OpenVMS process. The default value is 10.
PWRK$ACME_RETRY_INTERVAL The number of tenths of seconds between retry attempts. The default is 2.5 seconds.


Previous Next Contents Index

  privacy and legal statement  
6539P006.HTM