DCE and DFS for Linux Installation and Configuration Guide

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

E.1 Controlling CDS Cache Operations

This appendix is copied and modified from the Entegrity PC-DCE Administrator's Guide.

E.1.1 CDS Cache Overview

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.

E.1.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 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 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 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/*.*.

E.1.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.

E.1.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.

See /opt/dcelocal/etc/setup_state, for examples of environment variables. You can add the environment variable CDS_CACHE_SIZE=<size in bytes> there.

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

E.1.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.

E.1.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. cdsadv pings servers that are marked Not OK. If the preferred server (outside the LAN) goes down, cdsadv 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 cdsadv 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. cdsadv solicits clearinghouses on a periodic basis (documentation is not completer here: controlled by the CDSUpdateInterval registry key (DELETE?? REPLACE ? refer to Section A.1, Registry Keys, on page 117).

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

E.1.2.1 How CDS Preferencing Works

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

If the file does not contain an entry for a particular clearinghouse, 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 E.1.1.6, How a Client Sorts the Clearinghouse List 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 DCE.

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

3. Restart 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 5-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.

E.1.3 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 E.1.1.1, Cache Implementation) 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.

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

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

Copyright © 2001-2004 Entegrity Solutions Corporation & its subsidiaries