OSF DCE SIG		H. Melman (OSF)
Request For Comments: 35.0		January 1993

LOCATION OF INSTALLED DCE FILES

INTRODUCTION

This is the guideline for locating the DCE files (executables, libraries, configuration files, etc.) on target client and server systems for DCE 1.0. DCE has no architectual dependencies upon this guideline. It should be considered as a recommendation to venders and as a description of the default reference implementation configuration.

GOALS

The main purpose for (re)structuring the location of DCE files is to provide a uniform model for supporting administrators, application programmers, and users of DCE components. A minimum of configuration effort should be required to install and run DCE on various platforms.

Other objectives are:

1. Accommodating conventional centralized file organizations (i.e., Unix systems such as OSF/1 and SVR4 -- see Appendix A) by utilizing DCE DFS facilities in the cell wide environment.
2. Uniformity across different system architectures by separating architecture independent, architecture dependent and machine private files in respective subtrees.
3. Portability to non-Unix environments, although the model is derived and implemented on Unix based systems.
4. Separating areas which require frequent daily write operations from read only areas.
5. Privileged DCE components should be able to find their databases without being spoofed by a malicious user.
6. Utilizing DCE cell-wide file access where available (i.e., DFS).
7. Collecting DCE files in distinct hierarchies, separated from the base operating system organization.
8. Removing absolute path name references from the documentation (i.e., administration guides and manual pages) and include instructions only in the DCE Porting and Testing Guide [PORTG], DCE Administration Guide [ADMIN] and the DCE Release Notes [RELN].
9. Allow for multiple versions concurrently operating inside cells, only associate local systems (machines) to a particular DCE release. Support for installation, de-installation, and upgrade procedures.

DCE SUBTREES

This leads into three distinct sets which need to be combined in organizing the DCE file locations. These are listed in descending order, which means that it's preferable for several reasons (such as easier upgrading and de-installing of DCE) to include as many files as sensible into the first tree structure.

dceshared

For one set of files it's appropriate to create a top-level branch into DCE in the form <path-from-root>/<product-name>/<subdirectory(ies)>/* (e.g., /opt/dce1.0/bin/vos). This set can either be kept on local systems or preferably exported to the DCE cell via DFS. Therefore, sharable files including binaries (addressed via @sys) are stored here. dceshared is a read-only subtree.

In fact, all files generated by a DCE build, all files delivered to binary licensees, and, if appropriate, all files delivered to source licensees will be initially stored, kept and upgraded in this location. If necessary, copies or symbolic links to the other locations will be generated.

Note: With the exception of dceshared/etc, all files in dceshared will be kept unmodified over the lifetime of an installed DCE release. If necessary, configuration and data files are only stored as templates in this location. The actual working set of data files are located below dcelocal/var, dcelocal/etc, and dceshared/etc.

Although the DCE Executive and various server packages have to be licensed separately to binary licensees, this guideline is based on the assumption that one wants to utilize the DCE capability of sharing files cell wide. Storing and managing these files in a central place and running certain servers on dedicated server systems are two distinct tasks.

Note: DCE object files, as they will be shipped to end-users are separated in different packages (Executive and various Servers). Each of these licensed packages are self-contained, which means they include the complete set of required files. The Executive, for example, contains all utilities for application programmers including DCE header files and libdce.a. Since users in DFS cells may not want to have replicas of these files physically stored on their local system, they can remove their locally installed dceshared tree and redirect the default symbolic link to the cell wide dceshared (see below), if these particular files are available there. This applies similarly to the Server packages.

For the capability of initially booting and configuring the cell (i.e., Big Bang), the appropriate files for mandatory servers (CDS and Security) have to be available on that server machine (see dcelocal), but files for the optional servers (e.g., GDS, LM Server) may reside in remote filesets, dependent on the configuration (i.e., availability of DFS). Nevertheless, we strongly recommend that server systems should keep copies of the minimal set of tools and data files local for the capability of stand-alone operation and emergency maintenance (see dcelocal).

dceshared is by default /opt/dce, which in turn is, on newly initialized systems, a symbolic link to /opt/dce1.0. After configuring the system into the DFS based cell environment, this symbolic link usually points to /:/opt/dce1.0 (short form of /.:/fs/opt/dce1.0) -- see also below. This accommodates the requirement for the initial cell set-up phase (i.e., Big Bang), where dceshared must be available on that local system.

The pointer of dceshared has a version number associated with the path name. This provides the capability of running multiple DCE versions in one cell which may be required in an intermediate phase of upgrading to a new release. An additional advantage would be a cleaner de-installation procedure. In case of upgrades to a newer release, configuration files which are kept in dceshared/etc need to be transferred to the new subtree and linked back to the old release.

dcelocal

dcelocal serves two purposes:

1. It is necessary that a small set of DCE files be on the local disk to start up the various DCE components, for local configuration, and for log info. Except for diskless support, none of these files have to be available in the root partition, since DCE initialization takes place after mounting the local file systems. If diskless is supported, very few files (e.g., dfsd) must have copies in the root partition (i.e., /sbin).
2. The appropriate files on DCE servers which have to be local to the server station must be stored under dcelocal. All server specific data files are located below dcelocal/var/dce-component-name.

The default path for dcelocal is set to /opt/dcelocal. This is a fixed path name eventually determined and documented by vendors.

The contents of dcelocal may vary from machine to machine inside a DCE cell. Every machine must have local access to files for running the system stand-alone (if disconnected or partitioned from cell), and must have local access to those files which are necessary to initialize it as DCE client station up to activating DFS access in the cell.

Pitfall: Administrators have to be aware that during DCE initialization only executables in dcelocal/bin are reliably available. Therefore, startup procedures such as rc-scripts should address executables through dcelocal rather than /usr/bin, even if these same files supposed to be there.

There is no version number attached to dcelocal, since multiple DCE versions are not supported on single machines and servers are generally capable of serving previous releases.

Conventional Unix Locations

A small set of DCE files and directories should be accessible in conventional locations for:

1. user convenience for frequently used utilities such as idl in usr/bin and localtime in /etc/zoneinfo.
2. DCE application programmers' requirements who expect header files in /usr/include (or a subdirectory thereof, i.e., /usr/include/dce) and libraries in /usr/lib (i.e., libdce.a).

The intention is to store the complete set of delivered DCE files (except those which are created during runtime) in the first two subtree structures. Files which are required in conventional Unix locations and executables in dcelocal may be duplicates of files and templates in dceshared. Vendors will eventually decide which set of files they want to be available in their standard locations (such as /usr/bin) and whether they want them copied or just created as symbolic links.

DEFAULT SETTINGS AT COMPILE-TIME

For convenience, and due to the necessity of supporting traditional Unix file system organizations as well as non-Unix systems, we need to introduce a mechanism which allows us to point to the top of the product-specific DCE trees (i.e., dceshared and dcelocal -- see discussion above). A compile rather than a run time selection is necessary for security reasons, which excludes the use of environment variables.

The introduction of a separate configuration file provides enough flexibility and protection for this purpose. Nevertheless, there are two issues which cannot completely be solved by using this approach:

1. To support multiple DCE releases per cell, a version number would always be associated with the path name. If not using yet another level of indirection, the symbolic links - for example - created for files such as /usr/bin/idl to dceshared/bin/idl would have to have this version number in the path name, requiring additional reconfiguration work while upgrading DCE (i.e., redirecting all symbolic links to the new release).
2. Since DCE binary products contain the whole set of necessary files (i.e., files in dceshared and in dcelocal) one may want to redirect to the cell wide available dceshared and delete the local copies. Again, this would require changing all symbolic links (similar to issue (a)). The same effort would be required after the Big Bang configuration.

The preferable and much more elegant technique would be the use of symbolic links (in Unix) for addressing the locations dceshared. There is no such requirement for dcelocal, since it can be determined at compile time which path on the local system ought to be used. Given the right access settings on the directory containing the symbolic link (write for root or administrator, read for other users), the protection is equivalent to using a configuration file. Most of the other (non-Unix) operating systems provide techniques similar to symbolic links (e.g., aliases, symbolic names).

An additional advantage of this approach would be the avoidance of a separate configuration file and respective lookups during run time via a function call (i.e., getdcepath()). Traversing a symbolic link which is kept on the local system should be slightly faster than opening and parsing a file.

The path name for the entry containing the symbolic link will be passed to the DCE sources during compile time. It will be implemented in setting -D flags on compiler command lines:\*(f!

This method was used for DCE 1.0, it is being changed for DCE 1.1. Please see [RFC 34.0] for details on the new mechanism.

-DDCESHARED_PATH="/opt/dce" -DDCELOCAL_PATH="/opt/dcelocal

These flags will be defined in a central location (osf.dce.mk) using the variable DCEPATHS. Each individual Makefile which requires these values must add ${DCEPATHS} to CFLAGS. Vendors can modify the default entries in osf.dce.mk or overwrite DCEPATHS in the environment (e.g., setenv DCEPATHS "xxx"). Future DCE releases may use a common include file (i.e., dce.h) instead.

The install script for the DCE components will have to create a symbolic link from /opt/dce to /opt/dce1.0 and to create the directory /opt/dcelocal with appropriate rights.

This approach is sufficient since system vendors can easily change these few entries to accommodate their system design and requirements (e.g., /opt/dce to /usr/dce).

Some care must be taken by system administrators who are frequently using files located in dceshared or dcelocal and therefore need them to be set in their PATH variable. In using different workstations, this could be different depending on system vendor defaults. Not avoidable for dcelocal. But even for dceshared, an administrator or user of DCE usually wants to access the right DCE version for the given workstation rather than the latest DCE release which could be easily accessible via a link from /:/opt/dce to /:/opt/dce[latest].

Again, this problem occurs if multivendor systems with different default settings in a given cell are used. A solution certainly would be an additional indirection managed by the respective user using something like $MACHINE. However, this needs to be documented in the DCE Administration Guide.

DOCUMENTATION

DCE utilities and services which expect files in these locations (e.g., BosConfig in the bos command) must be modified respectively, and references in the documentation (i.e., man pages) must meet this guideline. Instead of using absolute path names, the references in the documentation are relative to the respective roots of DCE file locations. The same notation as used in this document (dceshared and dcelocal) for identifying the path prefix is used.

The following documents should contain information about this guideline:

1. Installation Notes (Part of DCE Administration Guide):

   Explanation of how to prepare the installation of DCE (e.g., set up /opt as separate file system with sufficient space).

2. Big Bang configuration (Part of DCE Administration Guide):

   Basically elaborating the cases that after initial configuration the access to dceshared might be reconfigured to utilize DFS access.

3. DCE Porting and Testing Guide:

   Porting instructions for setting and compiling the default values.

4. DCE Release Notes:

   Status of this proposal, actual directory layout, version numbering etc.

5. DCE Administration Guide:

   Explanation of naming conventions in documentation for locations relative to dceshared and dcelocal, hints and pitfalls for administrators, probably example configuration scenarios.

DIRECTORY LAYOUT

The following directories will be created during DCE installation: [\(<- indicates a symbolic link pointing to the first entry ]

All directories are created with Unix permissions set to rwxr-xr-x with user root and group bin. In subsequent configurations, the Security Service might define roles for several administrators (principals or groups). A conceivable scenario could be:

1. Software Administrator (owner of installed software packages), with write and modification permission for the entire set of files included in dceshared (except dceshared/etc/*).
2. Cell Administrator, with read and write permission to cell wide configuration and log files.
3. DCE Service Administrators (responsible for a particular DCE service such as Security), with read and write permission to data files for respective service. In most cases one might want to design a separate Security Service Administrator, while a single Cell Administrator is responsible for the remaining DCE services.
4. Local DCE System Administrator (responsible for client setups), with read and write permission to respective local files.

The directory structure supports such a model which can be easily managed if ACLs are available. Specific files might require different access permissions to be determined by component suppliers.

1. dceshared will be created as /opt/dce which is a symbolic link (/opt/dce1.0 \(<- /opt/dce)

   This is an entry always physically located at the local machine, and therefore the Local DCE System Administrator (or the respective Software Administrator) must have write permission to modify this link. The general procedure would be to redirect this link from the local to the cell wide accessible fileset as soon as the local system is configured and the cell is available.

   Note: Since this link is crucial for protecting the local station if running as client and the server station if acting as service requester, special care must be taken. This symbolic link must be created in a protected directory (only Local System Administrator have write and modification permission). If this cannot be guaranteed with /opt, /etc would be an alternative.

2. dceshared/bin

   Utilities for applications programmers and DCE users, DCE administration utilities, server processes (daemons).

3. dceshared/etc

   Templates of configuration files etc., which are in architecture dependent format.

   Note: In accordance with the efforts at OSF and AT&T of moving traditional administration utilities out of /etc, we should avoid storing any executables in any of the outlined etc directories. Only configuration files and administration databases belong in etc directories.

4. dceshared/etc/zoneinfo (Write permission for Cell Admin)

   Templates of respective configuration tables.

5. dceshared/examples

   Example and test executable files

6. dceshared/lib

   Application libraries (libdce.a) and DCE internal libraries.

   Note: If there are libraries remaining, which are only necessary for building DCE itself, they should go into this location.

7. dceshared/nls/msg/${LANG}

   Contains the delivered message catalogues (*.cat) files for each supported language.

8. dceshared/share/doc

   Complete set of DCE documentation as organized right now.

9. dceshared/share/etc

   Templates of common (shared) configuration files.

10. dceshared/share/include \(<- /usr/include/dce

    Application header files and DCE internal header files. This entire directory is linked to /usr/include/dce, but in future DCE releases we might want to separate and link only those files which are necessary for writing DCE based applications.

    Note: Stub files should not be exported (the binaries already exist in libdce.a).

11. dceshared/share/sources

    DCE sources and build tools as organized in the ODE build tree.

12. dcelocal

    directory (default: /opt/dcelocal)

13. dcelocal/bin

    DCE administration utilities and Server processes (daemons) necessary for local client system initialization and for respective server stations.

14. dcelocal/etc (Write permission for Local System Admin)

    Local (machine-private) configuration files maintained by client systems.

15. dcelocal/var/adm/dce-component-name (Write permission for Local System Admin)

    Storage of log files (including core images) and cache files, maintained by client systems only. For convenience, symbolic links from /var/adm/dce/client/dce-component-name will be created.

    Note: It has been asked why shouldn't servers put caches and logs here as well. That's a good question. Except for the probability of name-clashes (GDS, for example, has the same names but different sub-directories for clients and servers), there's no further technical reason. Mainly, it's for the sake of cleanliness. We want to separate client from server files. In cases, such as de-installation we basically have to remove the entire server subtree.

16. dcelocal/var/dce-component-name (Write permission for Service Admin)

    This subtree contains all data files (configuration files, databases, etc.) which are maintained by each of the DCE servers. To provide high availability and (in case of the Security Service) appropriate protection, data files associated to a service are usually physically located at the server site. Therefore they are stored in separate trees below dcelocal/var. If a DCE component provides several services such as fileset location server in DFS, respective substructures may be created (e.g., file/filesetloc). Files in dcelocal/var/dce-component-name are only those which are accessed by dedicated servers; other data files which are shared among DCE components will be located in dceshared/etc.

    If one service does not assume the files to be physically local, this organization allows for treating this subtree as exportable fileset, for example.

    Note: Configuration and log files relative to client systems are not stored here; they are in dcelocal/etc and dcelocal/var/adm/dce-component-name. In general, the sub-directories dcelocal/var/dce-component-name are explictly preserved for server usage only (i.e., for databases, config files, logs, ...). Therefore, one will find something under dcelocal/var/adm/dce-component-name on every (client) system and dcelocal/var/dce-component-name will only be populated on those systems which are running as server for that particular component.

17. dcelocal/var/dce-component-name/adm (Write permission for Service Admin)

    This subdirectory should be maintained by each service to store log files (including core images) and cache files generated by servers. Since users may expect log files in conventional locations, /var/adm/dce/dce-component-name will be created as symbolic links to these directories.

18. /etc/zoneinfo

    Copies of templates in dceshared/etc/zoneinfo, modified if necessary.

    Note: Since these files may already existent and respectively modified on the local system, the installation procedure must take care not to simply overwrite them!

19. /krb5 (Write permission for Local System Admin)

    Directory for Kerberos configuration files for conventional Kerberos 5 environment. Symbolic links to appropriate files in dcelocal/etc.

20. /sbin

    Small set of executables required in the root partition, derived and copied from dceshared/bin.

    Note: Although this is an exact subset of executables to be found in dcelocal as well, keeping the copy in dcelocal/bin is sensible, since on running systems /sbin is usually not set in $PATH.

21. /usr/bin

    Utilities for applications programmers and DCE users. Most of these are symbolic links pointing to dceshared/bin. On server stations, copies of respective executables may be necessary for the capability of initializing the system.

    Note: Some of these, such as login and su, may actually be local copies for required high availability.

22. /usr/lib

    Symbolic link from libdce.a to dceshared/lib/libdce.a.

23. $NLSPATH

    Copies of NLS message catalogues (*.cat files) for respective languages.

    Note: Rather than creating symbolic links to respective locations in dceshared/nls/msg/${LANG}, copies are necessary for performance and availability.