6 — Advanced Client Configuration

[Previous] [Next] [Contents] [Index]

Refer to the PC-DCE Configuration Panel help and the DCEsetup help files for general information about configuring your cell. This chapter provides advanced client configuration information and contains the following sections:

6.1 Using timesync.exe to Synchronize System Time
6.2 Controlling CDS Cache Operations
6.3 Controlling Client Selection of Security Servers

6.1 Using timesync.exe to Synchronize System Time

PC-DCE includes a timesync.exe process that automatically synchronizes a Windows system's clock with a DTS Server running on the Security Server every time Windows is started. The system will always remain within the defined five minute window that DCE security mandates. This process reduces the need to run dtsd on Windows clients.

NOTE: The Distributed Time Service (dtsd) requires at least three DTS servers per cell to ensure accuracy. For timesync to work on client systems, at least one DTS server must be running on the same machine as the master security server.

Each time a system is started, timesync synchronizes the system clock; however, if the system is not restarted for a long period of time and drifts outside of the five minute window, timesync must be run manually to resynchronize. Otherwise, the user will be unable to log into PC-DCE from that system.

NOTE: On Windows 2000 or Windows NT clients, users must have the Change System Time permission to run timesync manually. Members of the Administrators group have this permission by default, but you may need to grant this right to users who are not members of the Administration group.

To grant rights to change the system time, create a group for the users who need this right. Then:

In Windows NT or Windows NT Terminal Server:

1. Access the Windows User Manager (Start > Programs > Administrative Tools > User Manager).

2. Select Policies > User Rights.

3. In the User Rights Policy dialog, add the group of users and assign the Change the System Time right to the group.

In Windows 2000 or Windows 2000 Terminal Server:

1. From the Windows Control Panel, access Local Security Policy (Start -> Control Panel -> Administrative Tools -> Local Security Policy).

2. Double-click Local Security Policies.

3. Click User Rights Assignment.

4. Click Change the system time.

5. Click Add.

6. Select relevant groups or users.

The CDS cache is a collection of information about servers, clearinghouses, and other CDS resources that a CDS clerk establishes on the local system for its reference. When the CDS clerk receives a CDS server's response to a query, it stores the response in its cache. The next time the clerk needs this information, the clerk retrieves it from the cache rather than issuing a network request to a CDS server.

6.2.1.1 Cache Implementation

The CDS Cache is maintained in two areas: common (global) cache and per-user cache.

• The common cache contains information available to everyone (for example cell name, directory entries, and clearinghouses). This file, called cds_cache.000000000X (X represents a number that increments), is located in PCDCE32\opt\dcelocal\var\adm\directory\cds.

  The common CDS cache information is protected by DCE ACLs.

• The per-user cache contains user-specific information (softlinks, groups, etc.). This file, called cds_server_name_cache.00000000X (X represents a number that increments), is located in PCDCE32\opt\dcelocal\var\adm\directory\cds\machine name.

  Per-user information is protected against unauthorized access by DCE ACLs and, if the machine is using the NTFS file system, by NTFS file security.

In PC-DCE , the CDS Clerk is implemented as a DLL whereas the CDS Advertiser is a separate process (cdsadv). The cache and advertiser interconnect using an Windows-specific interprocess communications protocol.

The cache is periodically dumped to disk in the set of files stored in install_directory\opt\dcelocal\var\adm\directory\cds\*.*.

6.2.1.2 Lifetime of Cached Information

Information remains stored in the cache until either of the following occurs:

• The lifetime (roughly 8-10 hours) of the cached entry expires.

• The user establishes new credentials (probably through a new dce_login). This updates both the common and per-user cache files.

For example, if a user accesses a CDS server first thing in the morning to locate the services, subsequent lookups during the remainder of the day take advantage of the cache. The next morning, this whole process takes place again because the cached data has become stale or the user has logged into DCE again.

None of the CDS cache information stays fresh indefinitely.

6.2.1.3 CDS Cache Size

The CDS Cache Size is tunable. To set the CDS Cache Size, use the CDS_CACHE_SIZE system environment variable. If this variable does not already exist, you must create it.

To create the CDS_CACHE_SIZE environment variable:

1. Log on to Windows using an account with Administrator privileges.

2. Open the Control Panel, double-click the System icon, and click the Environment tab.

3. In the Environment dialog, click anywhere in the System Variables list.

4. In the Variable text box, type CDS_CACHE_SIZE.

5. In the Value text box, type the cache size (in bytes). Specify the size of the cache in bytes between 131072 (128KB) and 16777216 (16MB).

6. Click Set and then click OK.

The increased cache will be available the next time you start your computer.

6.2.1.4 How a Client Selects a Clearinghouse

When a client needs to read data from CDS, it contacts a clearinghouse. Because a cell can contain many clearinghouses, the client needs a mechanism to help it choose a clearinghouse based on clearinghouse performance and availability. For example, for performance reasons the client ideally uses a clearinghouse connected to the local LAN, but may need to connect to another clearinghouse when the local clearinghouse is down.

The client selects a clearinghouse from a list of clearinghouses stored in the client's CDS cache. The client keeps the list sorted in an order that keeps clearinghouses that are both local (on the same LAN) and available at the top of the list. The client attempts to contact clearinghouses in the order that they appear in the list.

6.2.1.5 How a Client Builds the Clearinghouse List

The CDS cache contains a section with entries for each clearinghouse that it knows about. It learns about clearinghouses in the following ways:

• Configuration. A client's cache always contains the clearinghouse of the preferred CDS server, which is the CDS Server Host Name that you enter when running the configuration program.

• Advertisements. Full clients learn about a new clearinghouse when the CDS server that maintains that clearinghouse issues broadcast advertisements. This works only for full clients, and only for new servers on the same LAN.

• Root Directory. A client generally reads the CDS root directory when it initializes its cache, and thereafter when this cached information expires. This is how full clients learn about off-LAN clearinghouses, and how lightweight clients learn about all new clearinghouses.

Each clearinghouse entry in the cache is marked with two flags: OK and OnLAN. The OK flag indicates whether or not the clearinghouse was last known to be responding to requests (available), and the OnLAN flag indicates whether or not the clearinghouse is located on the local LAN.

The client sorts the list in the following order:

1. OK and OnLAN

2. OK and not OnLAN

3. Not OK

The client keeps the OK and OnLAN flags updated using the following methods:

• The CDS advertiser (cdsadv) sets the OnLAN flag for a clearinghouse if it receives a broadcast from that clearinghouse. This makes sense because broadcasts do not go beyond the local LAN.

• Also, at configuration time, the CDS clerk sets the OnLAN flag for the clearinghouse associated with the preferred CDS server. If a user is running the lightweight client (no cdsadv or dced), then this becomes the only server that is flagged as OnLAN.

Note that, at configuration time, the CDS clerk sets the OnLAN flag for the preferred CDS server, even if the preferred CDS server is outside of the LAN. dce_update pings servers that are marked Not OK. If the preferred server (outside the LAN) goes down, dce_update continues to ping it, allowing the server to be sorted to the top of the cache again when the server comes back up.

When a clearinghouse entry is added to the cache, the entry is initially flagged as OK. The CDS clerk flags the entry as Not OK if it tries to reach the clearinghouse but there is no response. The entry gets set to OK again in one of the following ways:

• The CDS advertiser receives a broadcast from the clearinghouse. This only works for full clients, and only if the clearinghouse is located on the local LAN.

• The CDS clerk has tried all of the clearinghouses flagged as OK, starts trying clearinghouses in the Not OK section of the list, and receives a response from the clearinghouse.

• The dce_update process solicits this clearinghouse and it responds. This works for full and lightweight clients, and works whether or not the clearinghouse is located on the local LAN. dce_update solicits clearinghouses on a periodic basis controlled by the CDSUpdateInterval registry key (refer to Section A.1 on page 117).

You can tune the rate at which dce_update solicits clearinghouses by editing values in the registry key \HKEY_LOCAL_MACHINE\SOFTWARE\Entegrity\DCE\Configuration:

• CDSUpdateInterval

  REG_DWORD

  dce_update periodically solicits the clearinghouses listed in the cache that are marked Not OK (see Section 6.2.1.6 on page 94). CDSUpdateInterval sets the interval between updates, in seconds. The default interval is one hour (3600). Any value greater than zero is acceptable. For example, if an interval of 3 hours is desired, set this tunable to 10800.

  You must restart PC-DCE after setting this value. Notice that if NoCDSUpdateThread is set, this value is ignored.

• NoCDSUpdateThread

  REG_DWORD

  Disables the clearinghouse solicit function in dce_update. Only 0 and 1 are acceptable as values. If set to a value of 1, dce_update will not update the cache; if set to a value of 0, dce_update solicits clearinghouses as specified by CDSUpdateInterval. The default value is 0.

  You must restart PC-DCE after setting this value.

The CDS preferencing feature lets you assign integer ranks to clearinghouses. The ranks affect the sorting of the cached clearinghouse list.

6.2.3.1 How CDS Preferencing Works

You assign ranks to clearinghouses in a preference file, which PC-DCE reads at startup. Ranks with lower values are preferred.

If the file does not contain an entry for a particular clearinghouse, PC-DCE calculates a rank. The calculation is based on IP address:

• Clearinghouses with same IP address as local host: rank = 5000
  
• Clearinghouses on same IP subnet as local host: rank = 20000
  
• Clearinghouses on same IP network as local host: rank = 30000
  
• All other clearinghouses: rank = 40000
  

If the file does contain an entry for a particular clearinghouse, this is considered an override. Clearinghouses with override ranks are sorted a little differently from clearinghouses with calculated ranks, as described below.

Section 6.2.1.6 stated that the client sorts the cached clearinghouse list in the following order:

1. OK and OnLAN

2. OK and Not OnLAN

3. Not OK

Ranks affect this sorting as follows:

1. OK and OnLAN, as well as OK and Not OnLAN clearinghouses with override ranks. This section of the list is not sorted any further.

2. OK and Not OnLAN. This section of the list is sorted by rank.

3. Not OK. This section of the list is not sorted any further.

The preference file is a text file named cds_serv_pref located in install_directory\opt\dcelocal\etc. The file contains a series of one-line entries, where each entry consists of a clearinghouse name and the rank for that clearinghouse.

Specify the clearinghouse name (name_ch) using one of the following formats:

/.../cellname/name_ch

/name_ch

name_ch

/.:/name_ch

If the clearinghouse's cellname is not specified, the local cell is assumed.

The rank is a 16-bit unsigned integer (range 0x0000 [0] - 0xffff [65535]). A lower number indicates a stronger preference. A rank of 65535 specifies that the clearinghouse is never to be contacted.

Specify the rank in decimal, octal (with leading "0") or hex (with leading "0x").

Blank lines are ignored. You can include comments after the "#" character.

Example file:

# This is an example preference file
/.:/foo_ch                50  # most preferred clearinghouse
/.:/bar_ch               100
/.../mycellname/baz_ch   100

When you create or edit the preference file, you must:

1. Stop PC-DCE.

2. Delete the CDS cache file (install_directory\opt\dcelocal\var\adm\directory\cds\*.*).

3. Restart PC-DCE.

You can view the rank of a cached clearinghouse on a full client using the following commands:

dcecp -c cdscache show -clearinghouse /.:/name_ch

cdscp show cached clearinghouse /.:/name_ch

Suppose a client's preference file is as follows:

/.:/a_ch               100  # most preferred clearinghouse
/.:/b_ch               200  # preferred local backup
/.:/c_ch               500  # preferred off-LAN backup

Table 6-1 demonstrates cache sorting based on clearinghouse flags and ranks:

Table 6-1: Demonstration of Cache Sorting

Sort Order	Clearinghouse	Flags	Rank
1	a_ch	OK, OnLAN	100 (override)
2	c_ch	OK, Not OnLAN	500 (override)
3	d_ch	OK, OnLAN	20000
4	e_ch	OK, Not OnLAN	30000
5	f_ch	OK, Not OnLAN	40000
6	g_ch	OK, Not OnLAN	40000
7	h_ch	Not OK, Not OnLAN	40000
8	i_ch	Not OK, Not OnLAN	40000
9	j_ch	Not OK, Not OnLAN	40000
10	b_ch	Not OK, OnLAN	200 (override)
11	l_ch	Not OK, Not OnLAN	40000

The first section of the sorted cache includes all OK and OnLAN clearinghouses, as well as OK and Not OnLAN clearinghouses with override ranks. In the example, this section contains three clearinghouses: a_ch, c_ch, and d_ch. Clearinghouse a_ch is the client's most preferred clearinghouse according to its override rank of 100. Clearinghouse c_ch is sorted next even though it is off-LAN because of its override rank of 500. The final entry in the first section is clearinghouse d_ch, which has an automatically assigned rank.

The second section of the sorted cache includes OK and Not OnLAN clearinghouses sorted by rank. In this example, all clearinghouses in this section have automatically assigned ranks. Notice that clearinghouse e_ch is sorted to the top of this section because it is on the client's subnet and therefore has a rank of 30000.

The third section of the sorted cache includes all Not OK clearinghouses and is unsorted. Notice that clearinghouse b_ch appears in this section despite its low rank. When b_ch comes back online and the client detects this, the client will move b_ch to the first section of the cache.

6.2.4 Refreshing Cached Application Server Data

If you are concerned your client is using stale CDS information, you can update the cache as follows:

• Stop DCE services, delete the cache files, and restart DCE services. Global cache and per-user cache are stored in separate files (see Section 6.2.1.1) so you can refresh them individually or delete both files at once.

  This is a brute-force method that effectively resets the cache. However, once you reset the cache using this method, the new cache will initially contain only a single clearinghouse reference (the preferred CDS server, which is the CDS Server Host Name you entered for this client at configuration time). If this server is down or fails before the cache has been repopulated, the client will not be able to fail over to another clearinghouse. Repopulation of the cache occurs when the cache re-initializes (after 8 hours or when the user logs in again), or gradually as on-LAN servers issue broadcasts.

• Programmatically reduce the expiration age to a small value using rpc_ns_mgmt_set_exp_age() and then restore the default value.

  This can be useful in a dynamic environment like a development test lab where cache entries may become stale before they are refreshed. For example, if a server uses Object UUID's and is stopped and restarted while its clients are bound, that new instance of the server is not known to the local client cache. The client cache is stale and the client will not be able to find the server.

  You can use rpc_ns_mgmt_set_exp_age() to refresh the cache every time your client application is started or after trapping the case where rpc_mgmt_is_server_listening() fails. In each case, you can use the call to immediately refresh your cache and then if necessary return to the default cache expiration (usually several hours).

  For details on using this call, refer to the OSF DCE Application Development Guide.

You can use the CDS Preferencing feature to control which CDS clearinghouses that the client runtime queries.

6.3 Controlling Client Selection of Security Servers

Normally, the runtime looks up bindings for a security server by using CDS. However, if CDS is unavailable, the client runtime selects a security server based on the contents of the pe_site file, which is a list of security servers and associated bindings. The runtime starts by trying to contact the server listed at the beginning of the pe_site file. If that server fails to respond, the runtime tries the next server listed in the file. dce_update dynamically updates pe_site to keep the list sorted based on server availability. You can control the rate of update as described in Section 6.3.2.

In early releases of DCE, pe_site was static and you could control runtime selection of security servers by editing this file. Now, by default pe_site is updated dynamically. You can disable dynamic update using the registry key NoSECUpdateThread as described in Section 6.3.2. However, PC-DCE also offers an alternative method of specifying a preferred security server: setting up a special RPC profile, as described in Section 6.3.3 on page 100. This method allows you to retain the advantage of dynamic update.

6.3.1 Forcing the Runtime to Use pe_site

You can force the runtime to use pe_site exclusively, rather than CDS, by setting the environment variable BIND_PE_SITE to 1.

6.3.2 Controlling the Rate of pe_site File Updates

dce_update periodically pings all known security servers and moves servers that do not respond to the bottom of the list contained in the pe_site file. You can tune the rate at which dce_update solicits security servers by editing values in the registry key:

/HKEY_LOCAL_MACHINE/SOFTWARE/Entegrity/DCE/Configuration

The keys to edit are as follows. By default, these keys do not exist, so you need to create them.

• SECUpdateInterval

  REG_DWORD

  SECUpdateInterval sets the interval between pe_site updates, in seconds. The default interval is one hour (3600). Any value greater than zero is acceptable. For example, if an interval of 3 hours is desired, set this value to 10800.

  You must restart PC-DCE after setting this value. Notice that if NoSECUpdateThread is set, this value is ignored.

• NoSECUpdateThread

  REG_DWORD

  Enables or disables the dce_update function that dynamically updates the pe_site file. Only 0 and 1 are acceptable as values. If set to a value of 1, dce_update will not update the pe_site file; if set to a value of 0, dce_update updates pe_site according to SECUpdateInterval.

  You must restart PC-DCE after setting this value.

Because the pe_site file is updated dynamically, you cannot use it to specify a preferred security server unless you disable the dynamic update function. An alternative method of specifying that a client use a particular security server is to set up an alternate RPC profile in the CDS that points to this server, and then set up the client registry key SEC_DEFAULT_ENRY to point to this profile.

Notice that you can create multiple alternate profiles and use SEC_DEFAULT_ENTRY to point to the preferred profile for each client system.

To specify a preferred security server:

1. You need a cut-and-paste source for the interface identifiers for each of the security services. If you are reading this document online, you can cut and paste them from the listing of the rpcprofile show command example below. (You can do this because the interface identifiers for the security services are static, and are the same in this document as they will be if you obtain them from another source.) Otherwise, you must run the rpcprofile show command yourself to view the current cell profile, and then copy the output of this command into a convenient spot from which to cut and paste, such as an open text file.

   C:\> dce_login cell_admin -dce-
   C:\> dcecp
   dcecp> rpcprofile show /.:/cell-profile
   {{d46113d0-a848-11cb-b863-08001e046aa5 2.0} /.../longwood/sec 0 rs_bind}
   {{0d7c1e50-113a-11ca-b71f-08001e01dc6c 1.0} /.../longwood/sec-v1 0 
   secidmap}
   {{8f73de50-768c-11ca-bffc-08001e039431 1.0} /.../longwood/sec 0 krb5rpc}
   {{b1e338f8-9533-11c9-a34a-08001e019c1e 1.1} /.../longwood/sec 0 rpriv}
   {{b1e338f8-9533-11c9-a34a-08001e019c1e 1.0} /.../longwood/sec 0 rpriv}
   {{6f264242-b9f8-11c9-ad31-08002b0dc035 1.0} /.../longwood/lan-profile 0 
   LAN}
   {{4d37f2dd-ed43-0000-02c0-37cf2e000001 4.0} /.../longwood/fs 0 fs}
   {{eb814e2a-0099-11ca-8678-02608c2ea96e 4.0} /.../longwood/subsys/dce/dfs/
   bak 0 bak}
   {{1edd9c80-eed7-1299-a70f-0000c0e26f5f 1.1} /.../longwood/sec 0 
   Entegrity/rdlg_tok}
   

2. To obtain the exact server name of the preferred server, list the names of all security servers by listing the members of the RPC group /.:/sec:

   dcecp> rpcgroup list /.:/sec
   /.../longwood/subsys/dce/sec/master
   /.../longwood/subsys/dce/sec/darwin.explorers.com
   

3. Create the profile:

   dcecp> rpcprofile create /.:/my_profile
   

4. Add entries to this profile that specify your preferred server for all of the required security interfaces.

   In this example we select darwin.explorers.com as the preferred server. The required interfaces are the first five that appear in the cell-profile listing (Step 1). To add an entry, use the following dcecp command:

   rpcprofile add profile_name
   -m server_name
   -interface interface_id
   -priority n
   

   NOTE: The priority setting is useful only if your profile includes multiple entries for a specific interface. For details, refer to the OSF DCE Command Reference.

   For example, to add entries for the required services:

   rs_bind:

   dcecp> rpcprofile add /.:/my_profile 
     -m /.:/subsys/dce/sec/darwin.explorers.com
     -interface {d46113d0-a848-11cb-b863-08001e046aa5 2.0}
     -priority 0
   

   secidmap:

   dcecp> rpcprofile add /.:/my_profile 
     -m /.:/subsys/dce/sec/darwin.explorers.com
     -interface {0d7c1e50-113a-11ca-b71f-08001e01dc6c 1.0}
     -priority 0
   

   krb5rpc:

   dcecp> rpcprofile add /.:/my_profile 
     -m /.:/subsys/dce/sec/darwin.explorers.com
     -interface {8f73de50-768c-11ca-bffc-08001e039431 1.0}
     -priority 0
   

   rpriv (v1.1):

   dcecp> rpcprofile add /.:/my_profile 
     -m /.:/subsys/dce/sec/darwin.explorers.com
     -interface {b1e338f8-9533-11c9-a34a-08001e019c1e 1.1}
     -priority 0
   

   rpriv (v1.0):

   dcecp> rpcprofile add /.:/my_profile 
     -m /.:/subsys/dce/sec/darwin.explorers.com
     -interface {b1e338f8-9533-11c9-a34a-08001e019c1e 1.0}
     -priority 0
   

5. Add a default entry specifying the master security server. This is necessary because if the client is unable to contact a service specified in the alternate profile, it can fall back to the default entry.

   dcecp> rpcprofile add /.:/my_profile 
     -m /.:/subsys/dce/sec/darwin.explorers.com
     -default
   

6. On the client, add the SEC_DEFAULT_ENTRY registry key as a subkey to the key:

   /HKEY_LOCAL_MACHINE/SOFTWARE/Entegrity/DCE/Configuration
   

   Set the value to the name of your alternate profile. For example:

   SEC_DEFAULT_ENTRY:REG_SZ:/.:/my-profile

[Previous] [Next] [Contents] [Index]

To make comments or ask for help, contact support@entegrity.com.

Portions of this document were derived from materials provided by Compaq Computer Corporation. Copyright © 1998-2003 Compaq Computer Corporation.

Copyright © 2003 Entegrity Solutions Corporation & its subsidiaries.

All rights reserved.