OSF DCE SIG H. Melman (OSF) Request For Comments: 42.3 October 1994 DCECP FUNCTIONAL SPECIFICATION 1. INTRODUCTION A goal of DCE 1.1 is to make DCE easier to administer. One of the current problems with DCE is the fact that there are many different control programs for different components, with different syntaxes. Often, more than one must be used to perform certain operations, such as adding a user to a cell. This Functional Specification describes a new program, known as the _DCE Control Program_, abbreviated `dcecp', providing an administrative user interface that will augment the use of the existing programs, at least for commonly performed tasks. While the licensees and users of DCE 1.0 have found it to be a useful distributed computing platform, they have also found it to be a difficult environment to administer. The feedback we have heard in this area has made the simplification of DCE administration an important goal of DCE 1.1. The fact that DCE is composed of several different components originating from different vendors, is readily apparent when viewing the administrative tools. Many of the difficulties in administering DCE arise from the need to use many different tools that behave inconsistently and operate at a very low level relative to administrative *tasks*[1] (e.g., add a user to a cell, configure a client machine, backup, etc.). This functional specification describes a new administrative tool known as `dcecp' which can perform many of the operations of existing control programs via a new consistent command-line interface. It is expected that DCE *administrators* will use `dcecp' instead of the existing *control programs* to perform most daily operations. In DCE 1.1, `dcecp' will include functionality from the following control programs: `rpccp', `cdscp', `rgy_edit', `acl_edit', `dtscp', and `sec_admin'. That is, it will be able to manipulate data (e.g., directories, entries, groups, principals, accounts, ACL's, etc.) __________ 1. This *boldface* convention is used to introduce terminology the first time it appears in this paper. See the _Terminology_ section, below, for definitions. Melman Page 1 DCE-RFC 42.3 DCECP Functional Specification October 1994 stored in the various databases (e.g., the registry, clearinghouses, ACL managers, etc.). It will also be able to perform certain management operations (e.g, server shutdown, ping, get status, etc.). An important feature of `dcecp' is that it will provide a script language including but not limited to: variables, control structures, and the ability to create new procedures. This will allow administrators to create their own task *commands*. The first version of `dcecp' will include several such task commands implemented as `dcecp' scripts. The `dcecp' Language will be based on *Tcl* (pronounced "tickle"), the embeddable Tool Control Language developed at the University of California at Berkeley. The `dcecp' commands will be implemented as Tcl commands in a Tcl interpreter. This document assumes knowledge of Tcl and to a limited extent, its syntax. 1.1. Changes Since Last Publication The following changes have been made since this document was previously published in [RFC 42.2]. They are given in the order they are found in this document. (a) The `organization modify' command does not support the `-orgid' or `-uuid' option any more. These may not be modified. The text of `principal modify' and `group modify' were updated to state this explicitly as well. They did not accept attribute options for these but the text implied that the attributes could be listed in an attribute list. (b) The options allowed to the `rpcprofile remove' command have been changed. A `-priority' is supported. Also the values of the options have been changed to single values and not lists. (c) The specification of the `-tree' option has been expanded to say that the `-replica' and `-clearinghouse' options are not allowed if `-tree' is used. (d) The description of the `directory merge' command now explicitly states that the `-clearinghouse' option applies only to newly created directories. (e) The description of `link create' has been improved and an example added. The `-linkto' option is no longer required, though the value of the `CDS_LinkTarget' attribute is. Also the format of the `CDS_LinkTimeout' attribute has been specified, both as an attribute list, and as a short format for the `-timeout' option. (f) The `registry modify' command's description was corrected. The command takes no argument and always contacts the master registry. Melman Page 2 DCE-RFC 42.3 DCECP Functional Specification October 1994 (g) The `registry show' command's description was corrected. The optional argument is the name of a registry replica to contact. (h) The description of the `audevents show' command was made more precise. Also command outputs the event class name, not the event class number. (i) The argument given to an `acl' command is either a name or a list of a string binding and a residual name. (j) The description of lists of lists was improved. (k) The 'audfilter' syntax was clarified regarding the `all' action. If `all' is specified, others actions are not output by the `show' command. (l) The conveniences variables names all have an underscore prepended to them. Also some are described to be read-only and others not. The `_p' variable is described to work syntactically and explictly states that the value is an empty string if `_n' has no parent. (m) The arguments to the `server enable' and `server disable' commands is a list of server execution object. Server configuration object names are not allowed. (n) The value of the `-comp' option to the `log list' command is now a list. Also the output of this command no longer prints the message number, just the message text. (o) The end of the description of the `show' operation in the _Common Operations_ section is more accurate with respect to the `registry show' command an ERA's. (p) The description of principal names in the `principal' object was made more precise. (q) The example in `principal create' was corrected so that `- alias' has a value of `yes'. (r) The annotation field of an ERA is now defined to be limited to PCS. (s) The encoding `confidential' has been removed from the `schema' object. (t) The `schema create' command does not allow the `uuid' attribute to be specified if the argument is a list of names. (u) It was specified that the `schema delete' command removes all ERA instances of the schema entry. Melman Page 3 DCE-RFC 42.3 DCECP Functional Specification October 1994 (v) The `schema modify' command can only modify modifiable attributes. (w) The `log modify' command only takes a `-change' option. (x) A `schema catalog' operation was added. (y) The `CDS_ObjectUUID' on the `directory' object is read-only to the user and is set by the system at creation time. (z) The `lastsync' attribute is defined to be the time of the start of the last attempted synchronization. (aa) It is now stated explicitly that the child object in a `directory add' operation must exist or the command will return an error. (ab) The `dts' object can now affect a `dtsd' on another host via an argument to a `dts' command. (ac) Added a new `secval' object. (ad) Added a `-single' option to `object create' and and `directory create'. Added `-single' and `-types' to `object modify' and `directory modify'. (ae) The `login' command explicitly states that it updates the `_u' and `_c' convenience variables. (af) Routing specifiers are now called serviceability routing specifiers. A string syntax was added to both serviceablity and debug routing specifiers. A new field was added to both the tcl and string syntax for private data. The Tcl syntax of Debug Routing Specifiers was changed so that the second element is a list instead of a dot-separated string. (ag) A `-schema' option was added to the `object show' and `directory show' commands to return whether each attribute is single or multi-valued. (ah) Removed the `-recursive' option from `rpcgroup delete' and `rpcprofile delete' and from the `list' operation of both of those objects. (ai) The specification of an argument and of the relevant `_s()' convenience variable was made clear for the `registry', `dts', and `aud' commands. Each can take an argument of a single server name or string binding, not a list. The argument takes precedence over the relevant `_s()' convenience variable if set. Melman Page 4 DCE-RFC 42.3 DCECP Functional Specification October 1994 (aj) The `server modify' command no longer accepts an `-executing' option. The `server start' command now returns the UUID of the started server on success. (ak) A `-binary' option was added to the `create', `modify' and `show' operations of the `server' object. The description of the `data' attribute was updated. (al) The `create' operation on the `server', `hostdata' and `keytab' objects now accepts either an `-attributes' option or attribute options as other commands do. (am) The `repository' flag has been removed from the `flags' attribute of the `server' object. (an) The `catalog' operation on the `server', `hostdata' and `keytab' objects now takes a `-simplename' option. (ao) The syntax of the `executing' attribute of the `server' object was defined (this was formerly called `srvrexec'). (ap) Completely removed the `-recursive' option. (aq) Specified the order of precedence for `_s(cds)' and `- clearinghouse' in the `directory' object. (ar) The `-force' and `-only' options to the `registry delete' command may not be used together. (as) The options on the `registry show' command have been changed slightly. The old `-replica' with no value is now `-replica'. Also `-master' replaces the old `-replica' option with a value. (at) Updated the description of the `endpoint' object. Removed the `-host' option. The `endpoint' may only affect a local endpoint map. The `server' object using the `dced' API's can perform some remotes operations on `dced' (not `rpcd') endpoint maps. Also clarified behavior when lists are passed in as values. (au) The argument to `principal', `group', `organization', and `account' objects is a list of names, but if any are not fully qualified, then none may be. Non-fully qualified names refer to the name in the cell identified by `_s(sec)' if set or to the default cell of the local host if not. (av) Added the `uuid' and `name' objects. Removed the `expand' miscellaneous command as this is now `name expand'. (aw) Added a `utc' object to convert and perform arithmetic on UTC timestamps. Melman Page 5 DCE-RFC 42.3 DCECP Functional Specification October 1994 (ax) The values of the `starton' attribute of the `server' object have been changed to bring them in line with [RFC 47.3]. Also added attributes: `uid', `gid', `directory', and `principals'. (ay) Updated Apendix A. (az) You must specify either `-registry' or `-version' or both on any `keytab add' command. (ba) Added the `aud rewind' command. (bb) The `registry delete' and `registry synchronixe' commands must either have an argument or `_s(sec)' must be set. (bc) The `clock set' command now takes the time as the value of a required `-to' option and the argument can be a remote `dtsd' to contact. (bd) Added the `attrlist' object. (be) The argument to the `registry' commands and its handling of `_s(sec)' has been further specified. (bf) Specified that a UUID may be returned in an ACL entry if `dcecp' cannot convert from the UUID stored in an ACL to a name. (bg) Added a new `cellalias' object for CDS Hierarchica cells support. (bh) Specified that blank lines are given between multiple objects displayed at once, e.g., in `show' commands. (bi) Added description of sequence numbers in `registry' object. (bj) Five new states were added to the `status' attribute of the `registry' object. (bk) Added a `registry dump' command. (bl) Added `name' and `type' attributes to the info displayed by `registry show -master'. (bm) Added `registry verify'. (bn) Added `-randompwd' option to `account modify'. (bo) Removed ERA's from the `registry' object. (bp) Changed `-c' option to `dcecp' to take one value instead of the rest of the arguments. This is so adding more options to Melman Page 6 DCE-RFC 42.3 DCECP Functional Specification October 1994 `dcecp' will not force them to be position dependent. (bq) Added the `-certify' option to `login'. (br) Specified the order of the output of `registry show'. (bs) Specified `-noupdate' on the appropriate RPC commands (bt) Changed the default value of the `courierrole' attribute from `noncourier' to `backup'. (bu) Secified the `user', `host', and `cell' task scripts. (bv) Specified the `-s' option to the `dcecp' program. (bw) Added the global variable `dcecp_verbose_errors' which causes `dcecp' to output the entire contents of `errorInfo' to `stderr' in the event of an error. (bx) Renamed the `schema' object `xattrschema' to match the name of the namespace objects and the ACL manager. (by) Added the following commands: dts catalog clock compare clearinghouse catalog (bz) Added `name get'. (ca) Added the `scope' attribute to `xattrschema'. (cb) Corrected argument handling of `registry catalog'. (cc) Renamed `cellalias' to `cdsalias'. (cd) Changed `cdsalias set -child' to `cdsalias connect'. (ce) Specified the output of `cdscache show'. (cf) Added `cellalias' object for big hierachical cells script. (cg) Addded the following commands: clearinghouse checkpoint clearinghouse repair clearinghouse verify (ch) Added that the `applydefs', `intercell', `scope', and `unique' attributes on the `xattrschema' object are only advisory in DCE 1.1. Melman Page 7 DCE-RFC 42.3 DCECP Functional Specification October 1994 (ci) Changed the default value of the `tolerance' attribute of the `dts' object to 5 minutes as per DCE CR 11089. (cj) The `user' commands take a list of user names as an argument. (ck) Fixed typo in `object show -schema' description. (cl) Added that the user must be `root' to run `cdscache dump'. (cm) Clarified the descriptions of the `goodsince' and `server' attributes of the `account' object. (cn) Changed the description of the `CDS_ObjectUUID' attribute in the `directory' and `clearinghouse' objects. (co) Clarified descriptions of all the attributes of the `directory' object, particularly the `CDS_INCHName', `CDS_UpgradeTo', and `CDS_RingPointer' attributes. (cp) Updated output of CDS commands. The `cdscache show' command output has been changed, also the following attributes of `directory' and `clearinghouse show' commands have changed: Clearinghouse_uuid CH_UUID Clearinghouse_name CH_Name dir_uuid Dir_UUID directory Dir_Name (cq) Added `-local' to all `keytab' commands. (cr) Typo in `masteruuid' attribute of `registry', the value is of type UUID, not integer. (cs) Modified description of `clock set' so that `-to' is optional. (ct) The `rpcgroup add' command now allows the user to enter duplicates entries and does _not_ flag an error. (cu) Changed the format of ERA's of encoding type `void'. (cv) Added the `registry connect' command. (cw) There is a new optional argument `registry catalog' to specify a single name of a cell or a string binding. (cx) Specified the syntax of multiple routing and debug routing specifiers. (cy) Added the `_h' convenience variable. Melman Page 8 DCE-RFC 42.3 DCECP Functional Specification October 1994 (cz) Added the `registry set' command. (da) Specified that `import' only reports an error if no match was found in _any_ of the names specified in the argument list. (db) Renamed `name' in the `service' attribute to be `entryname'. (dc) Removed the `-randompwd' option from the `account modify' command and added the `account generate' command. This is to avoid the case where a password can be changed in the registry but the server crashes before the user is informed of the new password. (dd) Added the `_b(sec)' convenience variable to replace portions of `_s(sec)'. This way `_s' is only set by the user not by `dcecp', and `_b' is only set by `dcecp' and not by the user. Much less confusion can reign. (de) Added the `operations' attribute to the `server' object. It is only available for input, it is not output. (df) Specified that the argument to `registry show -master' can be a cellname. (dg) Added the `-noprivacy' option to all `keytab' commands. (dh) Added a new section on _Warning Messages_. (di) `clearinghouse checkpoint' is now `clearinghouse initiate'. (dj) Cleaned up the new `clearinghouse' commands, particularly `verify'. (dk) Added `secval status'. (dl) The `acl show' command describes the causes of UUID's being displayed instead of names more completely. (dm) Added a `-xattrs' option to `principal', `group', `organization' and `registry show' operations. Some also get a `-all'. (dn) Added `GOESTO' routing specifier. (do) Added the `-uuid' option to `endpoint show'. (dp) Added the `-simplename' option to `cell show' and included some examples. (dq) Changed the `stop' value of the `aud stostrategy' attribute to `save'. Melman Page 9 DCE-RFC 42.3 DCECP Functional Specification October 1994 (dr) `endpoint show' and `delete' take an optional argument of a single string binding to identify an endpoint map to contact. (ds) Added optional `-object' option to `resolve' command. (dt) Provided more argument details for the `clock' object. (du) Removed the argument to `cdsalias connect'. 1.2. Changes For Future Versions This section lists some ideas for `dcecp' which will not appear in the DCE 1.1 release but which should be considered for future releases. Several ideas for future support have been thought out, but since they are not appearing in DCE 1.1 they should not be included in this specification. They are included here so that the ideas can be considered when the support of this functionality is required. (a) If the NSI ever supports more than the `dce' syntax, a `- syntax' option should be added to the relevant `rpcentry', `rpcgroup', and `rpcprofile' commands. The NSI API's take a syntax argument, but since dce is the only supported name syntax, there is no current need to export this functionality to the user. The value for the dce syntax should be `dce'. (b) A `search' operation could be added to several objects so that filtering could be done for searches. By default names of matching objects should be returned so that can be used as input into other commands. An option could be used to specify that the contents of the objects should be returned. The argument, when possible, should optional so that all instances of the object are searched (see the `catalog' operation). If the argument is present it limits the searches scople. Different options can be supported for different types of search criteria. The following come to mind: `-regexp' for regular expression matching, `-match' for globing style matching, `-equal' for string equality, `-filter' for complex filters (such as X.500 filters). Not all options need be supported for each object, but these options should be used for the described functionality when present. (c) It should be possible for `dcecp' to support background tasks. If an `&' is at the end of the line, a thread should be spawned to perform the operation. Users would probably want some form of job control and that could get complicated. (d) A new convenience variable `_a' should be created to allow specification of the authentication and protection level used by RPC's initiated by `dcecp'. There are conflicting goals of providing full access to end users and providing a simple Melman Page 10 DCE-RFC 42.3 DCECP Functional Specification October 1994 interface to complicated concepts available in DCE. Current thoughts include: (i) The variable should be a Tcl array as `_s' is, allowing fine grain settings for each component. Should there be a general default as well? (ii) The values should be a list of two elements specifying the authentication service and the protection level. The actual values should be taken from the last word in the constants defined for the `rpc_binding_set_auth_info()' call. It could also be a list of such values allowing an order choice in the event of failure. Or it could somehow try to collapse the two concepts into one simple string which would hopefully be easy and adequate for the user (e.g., `unauth', `auth', `private'). (iii) If the specified level cannot be used (e.g., the user is not authenticated), the call should fail. Or if a list of values is used, then it could be an ordered list to try in the event of failure. (iv) The effect of the addition of public key technology to DCE on this variable is not clearly understood. Would a ever want to specify secret vs public? Would they ever have the choice or would a login mechanism make that choice for them? (e) Several of the `host' task scripts should be extended to allow remote operations where possible, particularlly `configure' and `unconfigure'. This may require some new restrictions (e.g., `dced' must be `running'), or some new options to the commands. (f) A new `_s(sch)' should be defined for schema entries. Perhaps a corresponding `_b(sch)' as well. 2. TERMINOLOGY The following are the terms used in this document. (a) *Administrator* The person (or persons) responsible for the installation and maintenance of a DCE Cell. They perform various administrative operations and *tasks*. While performing these duties they must have the proper permissions, so they must be members of the appropriate administrative groups. (b) *Argument* Melman Page 11 DCE-RFC 42.3 DCECP Functional Specification October 1994 A parameter given to a command. *Commands* take zero or more arguments followed by zero or more *options*. (c) *Command* Used in this document to mean a Tcl command or `dcecp' script that will be executed if entered as a command (Tcl provides a $PATH-like facility). Almost all `dcecp' commands are named for the type of *object* that they operate on (e.g., "the `acl' command"). This word is also used to refer to object-operation pairs (e.g., "the `acl show' command"). (d) *Control Programs* All of the administrative user interfaces provided with DCE 1.0. This includes but is not limited to: `rpccp', `cdscp', `rgy_edit', `acl_edit', and `dtscp'. (e) *Element* Existing DCE terminology uses this term to refer to elements of RPC profiles. The `dcecp' uses *member* for this purpose. In `dcecp' (and in Tcl), element is used to refer to the contents of lists. (f) *ERA* ERA stands for Extended Registry Attribute. These are extensions to the DCE 1.0 security service added in DCE 1.1 that allow arbitrary attributes to be added to objects in the registry (i.e., principals, groups, organization, and policy objects). They are defined by a schema which is stored in the registry as well. (g) *Member* Existing DCE terminology uses this term to refer solely to members of groups (both RPC groups and registry groups). Other terms are used to refer to objects in other types of containers (e.g., RPC profiles contain *elements*). The arbitrary choice of words has caused confusion for some users. The `dcecp' uses the word `member' to refer to anything stored in container. (h) *Operation* The commands in `dcecp' are usually named for the type of object they act on. The first argument to the command is usually the operation to perform on that object. (i) *Option* Melman Page 12 DCE-RFC 42.3 DCECP Functional Specification October 1994 Tagged arguments to commands. All options begin with a `-' (dash) and are found after all *arguments* in `dcecp' command lines. Some options are optional and some are required.[2] Some options take values and some do not. (j) *String Syntax* A format of a data structure that is understood by `dcecp' and existing control programs. In some cases, data structures have two syntaxes, one that is used in existing control programs, and one that is more natural for `dcecp'. Both are supported by `dcecp'. (k) *Task* A high level operation that an administrator performs, such as add a new user, or configure a new machine. A task is above the level of DCE components (e.g, add principal and account to registry), and usually involves operations on several different components. Usually implemented as dcecp task scripts. (l) *Tcl* The embeddable Tool Command Language. Tcl refers to both the language and to a library (`libtcl.a') that can be linked into a program which provides it. Commands can be added to the language via both C code and Tcl scripts. The `dcecp' language can be considered a dialect of Tcl, i.e., it is Tcl plus some DCE-specific commands. (m) *Tcl Syntax* A format of a data structure that is understood by `dcecp'. In some cases, data structures have two syntaxes, one that is used in existing control programs, and one that is more natural for `dcecp'. Both are supported by `dcecp'. 2.1. Abbreviations The following are abbreviations used in object names, attribute names, and option names: account acct attribute attr clearinghouse ch __________ 2. This may seem strange, but it follows OSF conventions. Melman Page 13 DCE-RFC 42.3 DCECP Functional Specification October 1994 database db default def expiration exp length len lifetime life message msg observed obs password pwd project proj standard std synchronization sync ticket tkt update upd 3. TARGET The `dcecp' and is meant to be used by DCE administrators. The emphasis of the first release will be on a commonly performed tasks of DCE cell administrators. It will have a command-line interface only. Developers will probably find an advantage to using `dcecp', however they are not the primary target user.[3] For example, the most commonly performed task of a DCE developer is to configure a new cell. However, it is not expected that this will be the same for DCE administrators. 4. GOALS AND NON-GOALS The following are goals for `dcecp': (a) The major goal is to simplify the administration of a DCE cell by creating a single powerful and consistent administrative user interface. (b) Emphasis in scheduling development resources must be placed on common everyday administrative duties rather than more esoteric configuration management. Administrators will get more use from a simpler way to add a new user or to modify a CDS entry __________ 3. It is expected that during the course of DCE 1.1 development, developers who have access to early versions of `dcecp', will produce task-oriented scripts that may be of use to DCE administrators. As many of these as is possible and practical will be included in the first release of `dcecp'. Melman Page 14 DCE-RFC 42.3 DCECP Functional Specification October 1994 and its ACL, rather than a new way to create a registry or to initialize a new CDS namespace. (c) The `dcecp' will augment use of existing control programs, it will _not_ replace them. Existing control programs will continue to be installed with DCE, and their use will probably remain required for some administrative operations. See Appendix A for a list of existing control programs commands and the `dcecp' commands that replace them. (d) Any new administrative interfaces required by new DCE 1.1 functionality should be provided via `dcecp' commands rather than new separate control programs. (e) Commands should be remotely invocable. This is currently true for most existing control program operations. The extension of those commands that are not remotely invocable is desired. (f) The `dcecp' must be portable to a variety of different platforms and management situations. Vendors must be able to integrate it into their own management systems. The following are not goals of `dcecp': (a) The `dcecp' will only be used to administer DCE itself, it will _not_ be used to administer applications that are written with DCE. (b) A graphical user interface (GUI) is desirable, but a command line interface is: more portable to a wider variety of platforms, scriptable, and usable over `telnet' lines and on machines not equipped with GUI's. Therefore, the command line interface is more important for the first release of the `dcecp'. (c) This is not DME. The `dcecp' is not meant to replace the need for DME, but rather to substitute for its absence in a very limited manner (but better than the existing control programs have done). Nothing in the design of the `dcecp' should preclude the use of DME in the future. 5. REQUIREMENTS The following are the requirements of `dcecp' as specified in [RFC30] and how they are met by the program described in this functional specification: (a) Existing Control Program Functionality Melman Page 15 DCE-RFC 42.3 DCECP Functional Specification October 1994 (i) Stop servers -- Met with `server stop' operation. (ii) Show/add/modify/delete data -- Met with the `show', `create', `modify', `delete', `add', and `remove' operations on various commands. (iii) Show status -- Met with various `show' operations (iv) Remote operations -- Met by most commands, see the _User Interface_ section for details. (b) Usability (i) Common syntax for all functions -- Met with Tcl and designed syntax. (ii) Help -- Met with `help' operations on all commands. (iii) Provide command line recall/editing -- Met with command- line editing facility. (iv) Scriptability -- Met with Tcl's `source' command and with the interpretation of an argument as a script file to execute. (c) New Functionality (i) Administer serviceability -- Met with the `log' command. (ii) Administer auditing -- Met with new commands: `aud', `audevents', `audfilter', and `audtrail'. (iii) Programmability -- Met with use of Tcl. (iv) Extensibility -- Met with Tcl's `proc' command. (v) Bind to different servers or data -- Met with separate commands, the `s' convenience variable, the `- clearinghouse', etc. (vi) Shell escape -- Met with the `shell' command and Tcl's `exec' command. (vii) Administration of little files -- Met with `hostdata' command. (viii) DCE ping -- Met with the `ping' operation. (ix) Security -- Will be done by existing ACL's. (d) Meet Other DCE 1.1 Goals (i) Code Cleanup -- Will follow the DCE Coding Style Guide [RFC 34]. (ii) Internationalization -- The new `dcecp' code will follow proper internationalization coding practices. Tcl will be internationalized. (iii) Serviceability -- Will use `sams' for message catalogs and messaging API's. The three letter serviceability component name of `dcecp' will be `dcp'. The routine `dce_sprintf' will be used for all messages. See [RFC 23], [RFC 24], and [RFC 34] for details. Melman Page 16 DCE-RFC 42.3 DCECP Functional Specification October 1994 6. FUNCTIONAL DEFINITION Many people seem to get confused trying to understand the relationship between `dcecp' and Tcl. It is a close relationship, but understanding which commands are Tcl commands and which are DCE commands is unimportant. A user of `dcecp' starts the control program and enters interactive commands at the `dcecp>' prompt. There are other use models (e.g., writing scripts and entering commands from the shell command line) but they are less common. An important usability feature of `dcecp' is that it provides command-line recall and editing similar to `ksh''s Emacs mode. At the prompt the user can enter base Tcl commands such as: dcecp> echo foo foo dcecp> lsort {a c e b d} a b c d e dcecp> foreach i [lsort {a c e b d}] {puts stdout $i} a b c d e The Tcl library implements an interpreter that understands all the base Tcl commands. See Appendix C for a list of Tcl commands. Any program using this library has access to these same commands.[4] A typical Tcl program usually implements new project-specific commands. Not surprisingly, `dcecp' implements commands that manipulate DCE data. Users can at the same `dcecp>' prompt enter DCE commands such as: dcecp> object delete /.:/hosts/absolut dcecp> acl modify /.:/hosts -add {user melman -rwx} dcecp> principal create melman -fullname {Howard Melman} __________ 4. This is orthogonal to DCE. The only part of DCE that will use `libtcl' is `dcecp'. The Tcl library will _not_ be part of `libdce'. The goal of DCE is to ship `dcecp' not Tcl, as such if we will not install `libtcl' and the headers for general availability. This does not prevent vendor's from doing this. IT affects only the reference implementation of `dce_config'. The AES mentions neither `dcecp' nor Tcl. Tcl is freely available to all from the internet. Melman Page 17 DCE-RFC 42.3 DCECP Functional Specification October 1994 To the user of `dcecp' there is no visible difference between a base Tcl command and a command that manipulates DCE data. They might see the base Tcl commands when running other programs that use Tcl, but they will only see the DCE commands in `dcecp'. The Tcl and DCE commands can be combined (output not shown for space reasons): dcecp> foreach i [dir list /.: -directories] {dir show $i} This allows an advanced user to write extensible scripts, a feature that we deem very important. For a list of base Tcl commands, see [TCL]. See the _User Interfaces_ section for all other details about the usage of `dcecp'. 7. DATA STRUCTURES This section provides a brief introduction to Tcl data types and then presents several `dcecp' data structures. For a complete reference of Tcl data types, see [TCL MAN]. In Tcl, there is only one data type, strings. All commands, expressions, variable values, and procedure return values are strings. Some Tcl commands interpret the strings in different manners. For example, `eval' treats its *argument* as an expression. The argument it receives is a string. If the argument is `4 + 5' then the returned result is the string `9'. Other Tcl commands interpret their string arguments as lists. In Tcl lists consist of elements separated by white space (space, tab, or newline). The following are three examples of lists with three elements: tom dick harry a b c 1 2 ! There are three meta-characters that are treated specially when parsing lists. They are: (a) Braces are used for grouping. If a left brace is encountered, then the element is terminated by the matching right brace, instead of the next whitespace. Braces nest. The following are also examples of lists with three elements: tom {dick harry} {sue mary jane} a {b {c d e}} f Melman Page 18 DCE-RFC 42.3 DCECP Functional Specification October 1994 (b) Double quotes are also used for grouping, however, there are two differences between them and braces. First they don't nest. Second Tcl will perform command, variable, and backslash substitutions for items within double quotes. Tcl does not perform these substitutions when braces are used. (c) Backslashes are used to escape meta-characters, and to insert non-printing characters. Standard substitutions occur such as `\t' is a tab character, and `\n' is a newline. Braces and double quotes can be inserted in lists with backslashes as follows, again these example lists all have three elements: a b\ c d a b \} The net effect of using these meta-characters and Tcl commands on a command line is that lists appear as elements surrounded by braces, and the top level of braces is not present on output. This last point is tricky; it has to do with how commands are parsed. The best way to explain it is with an example. The Tcl command `lindex' takes two arguments, a list and an integer (remember, both of these are just strings and it is the `lindex' command that interprets these string arguments specially). It returns the element from the list indicated by the second argument. Elements in lists are numbered from zero. So the following command: lindex {a b c} 1 returns the string `b'. The braces in the example are used to group the elements of the list so that they are passed as one argument to the lindex command. Now, the following example returns a list: lindex {a {b c} d} 1 The list returned is `b c', there are no braces around it, but it is a perfectly valid list. To prove this, pass it to the `llength' command which takes one argument, a list, and returns the length as an integer (in Tcl, square brackets perform command substitution, much like backquotes do in command shells): llength [lindex {a {b c} d} 1] This returns the value `2' since the list `b c' has two elements. In `dcecp', there are several data structures used to represent DCE objects such as attributes, bindings, and ACL's. Most of these had some representation in the existing control programs. The `dcecp' often supports these representations for backward compatibility, as they will be recognized by the administrator. This is known as the *string syntax* of the data structure. Often `dcecp' provides a Melman Page 19 DCE-RFC 42.3 DCECP Functional Specification October 1994 representation that is more easily handled by Tcl for these data structures, usually they are lists. This representation is known as the *Tcl syntax* of the data structure. 7.1. Attributes In `dcecp', attributes are represented as a list. The first element is the attribute type. This is usually some string name, but in some cases, OID's or UUID's are acceptable. The following elements in the list are the values. If the attribute is single-valued then the attribute list will have two elements, multi-valued attributes will have more. Attribute lists are lists of attributes. The following is an attribute list of two single-valued attributes: {acctlife 2} {pwdlife none} 7.2. ACL's An ACL is an Access Control List which consists of a set of ACL Entries. Each ACL Entry is defined as a type, an optional key or value, and a required set of permissions. In access checks, the permissions granted to a user are established by checking the type and key of each ACL Entry and or'ing the permissions described therein. Each application is free to define new permission bits. The defined types are listed below:[5] (a) `user_obj' (b) `group_obj' (c) `other_obj' (d) `user' (e) `group' (f) `foreign_user' (g) `foreign_group' (h) `foreign_other' (i) `any_other' (j) `mask_obj' (k) `unauthenticated' (l) `extended' (m) `user_obj_delegate' (n) `group_obj_delegate' (o) `other_delegate' __________ 5. The new "delegate" types are to be added during DCE 1.1 development to support delegation. Melman Page 20 DCE-RFC 42.3 DCECP Functional Specification October 1994 (p) `user_delegate' (q) `group_delegate' (r) `foreign_user_delegate' (s) `foreign_group_delegate' (t) `foreign_other_delegate' (u) `any_other_delegate' All ACL type names are case insensitive. The following are all legal: `user', `USER', and `uSer'. The value of the key may be either a name (e.g., a principal or group name) or a UUID. On output, `dcecp' will always try to generate a name from the UUID stored in the ACL, but if this is not possible, a UUID will be returned. 7.2.1. String syntax The string syntax of ACL Entries is as follows: [:]: The permission bits need not include `-''s for permissions not granted and may be given in any order. Examples of nine ACL Entries follow (the last appears on two lines for space reasons[6]): unauthenticated:-r----- user_obj:crwx--- user:britten:crwx--- user:mahler:-rwx--- foreign_user:/.../C=US/O=OSF/OU=dce/pro/bach:crwxidt group_obj:-rwx--- group:dds:-rwx--- any_other:-r----- extended:c417faf8-8340-11c9-ace3-\ 08001e5559bb.a.b.c.a1.4.0a0b0c0d:-rwx--- 7.2.2. Tcl syntax The core Tcl Syntax of ACL Entries is a list of two or three elements. The first element is the type, the optional second element is the key, and the last element is the set of permission bits. The permission bits are represented as a single character if the permission is granted and as a `-' (dash) if it is not. An ACL is a list of ACL Entries. An example of an ACL is as follows: __________ 6. Line-terminating "\" denotes line-folding of long lines, sometimes as a display meta-character and sometimes as a Tcl meta-character (the distinction will always be clear from context). Melman Page 21 DCE-RFC 42.3 DCECP Functional Specification October 1994 {unauthenticated -r-----} {user_obj crwx---} {user britten crwx---} {user mahler -rwx---} {foreign_user /.../C=US/O=OSF/OU=dce/pro/bach crwxidt} {group_obj -rwx---} {group dds -rwx---} {any_other -r-----}, {extended c417faf8-8340-11c9-ace3-\ 08001e5559bb.a.b.c.a1.4.0a0b0c0d -rwx---} On output the above Tcl Syntax will be used, with one addition. If due to masking[7] there are ineffective bits in an ACL Entry, the entry will be extended with two elements. The first is the string `effective' and the second is the set of effective permissions. This will only be added for those ACL Entries that have ineffective bits. For example: {mask_obj -r-----} {user_obj crwx---} {user britten crwx--- effective -r-----} On input, these two elements are ignored. Also on input, the permission bits need not include `-''s for permissions not granted and may be given in any order. For example, if the user wanted to enter the above ACL to a command, all that they need to type is: {mask_obj r} {user_obj crwx} {user britten wcrx} 7.3. Bindings In RPC, all bindings are represented as string bindings which contain four pieces of information: a protocol sequence, a network address, an endpoint, and an optional object UUID. 7.3.1. String syntax The string syntax of a string binding is as follows: @:
[] The `' can be preceded by the string `endpoint='. There can be no whitespace in the string binding. Examples follow: __________ 7. See [POSIX.6] and [USERGD] for details on masks in ACL's. Melman Page 22 DCE-RFC 42.3 DCECP Functional Specification October 1994 ncadg_udp_ip:130.105.96.3[1234] 001c8234-74ff-1be9-b11c-08002b0f59bb@ncadg_udp_ip:\ 130.105.96.3[1234] Note that in Tcl, square brackets are used to indicate command substitution. So, if a string binding in the string syntax is entered, the brackets must be preceded by a backslash (i.e., escaped) or enclosed in braces (i.e., quoted). Therefore, the above example would not always be accepted by the Tcl parser, two corrected examples of the first string binding follow: {ncadg_udp_ip:130.105.96.3[1234]} ncadg_udp_ip:130.105.96.3\[1234\] 7.3.2. Tcl syntax The Tcl Syntax is a list of 3 or 4 elements as follows:
or
or
Examples follow: ncadg_udp_ip 130.105.96.3 1234 001c8234-74ff-1be9-b11c-08002b0f59bb \ ncadg_udp_ip 130.105.96.3 1234 001c8234-74ff-1be9-b11c-08002b0f59bb \ ncadg_udp_ip 130.105.96.3 7.4. Interface Identifiers An interface identifier describes an interface. Specifically, it contains the UUID, major version number, and minor version number of an interface. Melman Page 23 DCE-RFC 42.3 DCECP Functional Specification October 1994 7.4.1. String syntax The string syntax is as follows, where `' is the string syntax of a UUID. ,. An example follows: 0067b39e-67ac-1be9-abb5-08002b0f59bb,1.2 7.4.2. Tcl syntax The Tcl Syntax is a list of two elements: the UUID in its string syntax and the major and minor version numbers separated by period. An example follows: 0067b39e-67ac-1be9-abb5-08002b0f59bb 1.2 7.5. Serviceability Routing Specifiers Serviceability routing information [RFC 24] is specified as a list of serviceability routing elements. Each routing element contains four fields containing PCS data: (a) The first field specifies a message severity. It must be one of the following: (i) `FATAL' Fatal error, about to exit. (ii) `EXIT' Normal exit. (iii) `WARNING' Error detected, program proceeding. (iv) `NOTICE' Informational notice. (v) `VERBOSE' Verbose informational notice. (b) The second field specifies how the messages should be processed. It must be one of the following: (i) `GOESTO' Set routing the same as another severity field. (ii) `BINFILE' Write binary log entry. (iii) `TEXTFILE' Write human-readable text. (iv) `FILE' Equivalent to `TEXTFILE'. Melman Page 24 DCE-RFC 42.3 DCECP Functional Specification October 1994 (v) `DISCARD' Do not record this level. (vi) `STDOUT' Write human-readable text to standard output. (vii) `STDERR' Write human-readable text to standard error. Note that any debug messages (calls to `DCE_SVC_DEBUG') that are routed through a `BINFILE' route will lose the types of any arguments. (c) The third field specifies where the messages should be sent. Presently, this will always be a filename, although it can be blank for the last three specifiers given above. This field may contain a `%ld' string which will be replaced by the process-ID of the currently-running process. Filenames may _not_ contain colons, semi-colons or spaces. For the `GOESTO' sepcifier, the where field contains the name of another severity field. E.g., you can set notices to be the same as errors, whatever they are set to. It is a reference not a copy. A limited form of log-rolling is available. The where field,, may be followed by `..' where `' is an integer less then 100 indicating the number of files to be kept and `' is an integer indicating the number of entries per file. No more then `' entries will be written to a file, before a new file is started. After `' files have been written, the files wrap back around to the beginning. The file names are formed by appending `.' to the end of the filename, where `' runs from one to the last generation number. (d) The optional fourth field is used for application specific information. Note that the second, third, and optionally the fourth field may be duplicated to allow for multiple routing specifiers. See the specific syntaxes below for example of how this can be specified. 7.5.1. String Syntax The string syntax is as follows: ::[:] For example, to send fatal errors to the console, send errors to a log-rolled file, ignore normal exit reports, send everything to a log file, send informational messages to a temporary binary log, and send warnings to stdout with private data, use the following serviceability routing specification: Melman Page 25 DCE-RFC 42.3 DCECP Functional Specification October 1994 FATAL:TEXTFILE:/dev/console ERROR:TEXTFILE:/tmp/errors.5.100 EXIT:DISCARD: *:FILE:/tmp/svc-log NOTICE:BINFILE:/tmp/log%ld: WARNING:STDOUT:: Multiple routings can be specified by separating several `', `' and optionally `' fields with a semi-colon. E.g.: {ERROR:STDERR:;STDOUT:;FILE:/tmp/jas} {FATAL:FILE:/tmp/jas:private;STDERR:} 7.5.2. Tcl Syntax The Tcl syntax of a serviceability routing specification is a list of four elements. The first element is the severity, the second is the how specification, the third is the where specification, and the fourth is the private field {} The above example in Tcl syntax is as follows: {{FATAL TEXTFILE /dev/console} {ERROR TEXTFILE /tmp/errors.5.100} {EXIT DISCARD} {* FILE /tmp/svc-log} {NOTICE BINFILE /tmp/log%ld } {WARNING STDOUT {} }} Multiple routings can be specified by using a Tcl list for the `', `' and optionally `' fields. E.g.: {ERROR {STDERR STDOUT {FILE /tmp/jas}}} {FATAL {{FILE /tmp/jas private} STDERR}} 7.6. Debug Routing Specifiers A debug routing specification is a list of debug routing elements. Each debug routing element contains four fields with an optional fifth field: (a) The first field is the name of a serviceability component. (b) The second field is a list of period separated subcomponents and levels. If the subcomponent is an asterisk then the level is set for all subcomponents of that component. The level should be a number between zero and nine. This list is parsed in order, so the asterisk may be used to set the initial level for all subcomponents; later entries override earlier ones. Melman Page 26 DCE-RFC 42.3 DCECP Functional Specification October 1994 (c) The third field specifies how the messages should be processed. It is identical to the second field of a serviceability routing element. (d) The fourth field specifies where the messages should be sent. It is identical to the third field of a serviceability routing element. (e) The fifth field is optional and can be used to specify application specific data. Note that the third, fourth, and optionally the fifth field may be duplicated to allow for multiple debug routing specifiers. See the specific syntaxes below for example of how this can be specified. 7.6.1. String Syntax The string syntax is as follows: :.::[:] Multiple sub-component and level specifications can be entered separated by commas. For example: dts:*.1:TEXTFILE:/dev/console dts:msgs.4:DISCARD: dts:msgs.4,states.6:DISCARD: cds:clerk.9:BINFILE:/tmp/log%ld: cds:general.1:STDOUT:: Multiple routings can be specified by separating several `', `' and optionally `' fields with a semi-colon. E.g.: {cds:general.7:FILE:/tmp/jas;STDOUT:;STDERR:} {dts:msgs.2,general.7:STDERR:;STDOUT:;FILE:/tmp/jas}}} 7.6.2. Tcl Syntax The Tcl syntax of a debug routing specification is a list of four or five elements, one for each of the above fields. The second element is a list and may be a list of lists. For example, to set RPC debugging at a minimal level so that all messages go to standard error, use the following: {rpc {* 1} STDERR} The following example sets DTS debugging messages for the general, events, and msgs subcomponents (at the levels indicated for each) to go to a logfile: Melman Page 27 DCE-RFC 42.3 DCECP Functional Specification October 1994 {dts {{general 1} {events 0} {msgs 3}} TEXTFILE /tmp/log} Multiple sub-component and level specifications can be entered as a tcl list. The Tcl syntax of the example in the string syntax section is as follows: {dts {* 1} TEXTFILE /dev/console} {dts {msgs 4} DISCARD} {dts {{msgs 4} {states 6}} DISCARD} {cds {clerk 9} BINFILE /tmp/log%ld } {cds {general 1} STDOUT } Multiple routings can be specified by using a Tcl list for the `', `' and optionally `' fields. E.g.: {cds {general 7} {{FILE /tmp/jas} STDOUT STDERR}} {dts {{msgs 2} {general 7}} {STDERR STDOUT {FILE /tmp/jas}}} 7.7. Other Data Types There are three other data types mentioned in this document: UUID's, UTC times, and Names. They have no Tcl Syntax. For a description of these string syntaxes, see the DCE Documentation. 8. USER INTERFACES The `dcecp' will present a command-line interface to the user with command-line recall and editing capabilities. The commands and command-line editing interfaces are described below. This section describes the following in various sub-sections: (a) _Invocation_ -- How `dcecp' can be started and its modes of operation. (b) _Initialization_ -- The various scripts that are read when `dcecp' is started. (c) _Command Syntax_ -- A description of the design of the command syntax. Also how to invoke external commands, and how `dcecp' deals with commands it does not know. (d) _Abbreviations_ -- The `dcecp' allows objects, operations, and options to be abbreviated to the shortest unique string. (e) _Convenience Variables_ -- Describes builtin variables to make interactive use easier. (f) _Error Handling_ -- The overall approach to return values and error handling. Melman Page 28 DCE-RFC 42.3 DCECP Functional Specification October 1994 (g) _Help System_ -- Describes the available on-line help. (h) _Common Operations_ -- These are operations that are common to many but not all objects. (i) _Common Options_ -- These are options that are implemented in more than one object. (j) _Objects_ -- These are the object commands that `dcecp' will support. Each sub-section describes one object, including the operations that it supports. Variations in the operations of a particular object versus the common operations are described in this section, as well as any non-common operations supported by the object. (k) _Tasks_ -- These are the administrative tasks that `dcecp' will support. They are implemented as object commands so as to have similar syntaxes as other `dcecp' commands. They are more complex and are typically implemented in Tcl code. (l) _Command-line Editing_ -- A description of the command-line editing interface. 8.1. Invocation The `dcecp' is a command-line user interface for administrative commands. There are several methods of invocation: (a) The user starts `dcecp' and then sees the `dcecp' prompt: dcecp> The above is the default prompt. This can be changed using the standard Tcl `tcl_prompt1' and `tcl_prompt2' mechanisms. See [TCL MAN] for details. (b) The user invokes `dcecp' with one argument which is a filename of a `dcecp' script. The script is run and then `dcecp' exits. This method of invocation allows interpreter files (those with `#!/bin/dcecp' as the first line) to work. Tcl sets the `argc', `argv', and `arg0' variables to provide access to command-line arguments. (c) The user invokes `dcecp' with the `-c' option followed by a value which is a set of commands (all on one line separated by `;''s which must be quoted in the shell). The commands are executed and then `dcecp' terminates. For example: $ dcecp -c "directory create /.:/foo" Melman Page 29 DCE-RFC 42.3 DCECP Functional Specification October 1994 The `dcecp' program also accepts a `-s' option which causes it not to contact any servers during initialization.. Specifically it will not try to inherit a login context from the invoking process. This can be useful when trying to invoke `dcecp' when DCE is not functioning properly. 8.2. Initialization When `dcecp' is invoked, it executes the following scripts in the order shown. Note the syntax used for the script locations is Tcl. (a) `[info library]/init.tcl' Contains standard Tcl initialization commands on a per-host basis. Contains definitions for the `unknown' command and the `auto_load' facility. (b) `$dcecp_library/init.dcecp' Contains `dcecp'-specific startup information. The `dcecp' scripts implementing commands and tasks are stored in the directory identified by the Tcl variable `$dcecp_library'. The reference implementation will set `dcecp_library' to `/dcecp' by default. (c) `$env(HOME)/.dcecprc' This file stores user customizations. 8.3. Command Syntax The `dcecp' commands are implemented as procedures in a Tcl interpreter. Commands return strings, and the main interpreter loop displays the results to the user. Errors are displayed as well. In most cases a Tcl object-oriented approach has been used to define the commands. In this approach commands represent a type of object, and have the same name as the object. [-