Name

dced_intro - Introduction to the DCE host daemon routines

Description

This introduces the DCE host daemon application programming interface: the dced API.  This API gives management applications remote access to various data, servers, and services on DCE hosts.  Servers manage their own configuration in the local dced by using the routines starting with dce_server, introduced in the dce_server_intro(3dce) reference page. 

The dced API Naming Conventions

All of the dced API routine names begin with the dced_ prefix.  This API contains some specialized routines that operate on services represented by the following keywords in the routine names:

hostdataThe host data management service stores host-specific data  such as the host name, the host’s cell name, and other data, and it provides access to these data items. 

serverThe server control service configures, starts, and stops servers, among other things.  Applications must distinguish two general states of server control: server configuration (srvrconf) and server execution (srvrexec). 

secvalThe security validation service maintains a host’s principal identity and ensures applications that the DCE security daemon is genuine. 

keytabThe key table management service remotely manages key tables. 

The dced also provides the endpoint mapper service which has its own API, described with the RPC API.  These routines begin with rpc_ep and rpc_mgmt_ep. 

Since some of the dced daemon’s services require the same operations (but on different data types), the dced API also contains generic routines that may operate on more than one of the preceding services.  For example, you use the routine dced_object_read() to read a data item (object) from the hostdata, srvrconf, srvrexec, or keytab services. 

dced Binding Routines

A binding must be established to a dced service on a particular host before you can use any other dced routines.  The resources of the dced binding should also be released when an application is finished with the service. 

dced_binding_create()
Establishes a dced binding to a host service. 

dced_binding_from_rpc_binding()
Establishes a dced binding to a dced service on the host specified in an already-established RPC binding handle to any server. 

dced_binding_set_auth_info()
Sets authentication, authorization, and protection level information for a dced binding handle. 

dced_binding_free()
Releases the resources of a dced binding handle. 

Generic Entry Routines

All data maintained by dced is managed as entries.  Most of the services of dced have lists of entries traversed with a cursor that describe where the actual data is maintained. 

dced_entry_add()
Adds a keytab or hostdata entry. 

dced_entry_remove()
Removes a hostdata or keytab data entry from dced. 

dced_initialize_cursor()
Obtains a list of data entries from dced and sets a cursor at the beginning of the list. 

dced_entry_get_next()
Obtains the next data entry from a list of entries.

dced_release_cursor()
Releases the resources associated with a cursor which traverses a service’s list of entries.

dced_list_get()
Returns the list of data entries maintained by a DCE host service.

dced_list_release()
Releases the resources of a list of entries.

dced_inq_id()
Obtains the UUID associated with an entry name.

dced_inq_name()
Obtains the name associated with an entry UUID.

Generic Routines to Read Data Objects

These routines obtain the actual data for items to which entries refer (objects). 

dced_object_read()
Reads one data item of a dced service, based on the entry UUID. 

dced_object_read_all()
Reads all the data of a dced service’s entry list. 

dced_objects_release()
Releases the resources allocated for data obtained.

Host Data Management Routines

dced_hostdata_create()
Creates a hostdata item and the associated entry. 

dced_hostdata_read()
Reads a hostdata item. 

dced_hostdata_write()
Replaces an existing hostdata item. 

dced_hostdata_delete()
Deletes a hostdata item from a specific host and removes the associated entry. 

Server Configuration Control Routines

dced_server_create()
Creates a DCE server’s configuration data.

dced_server_modify_attributes()
Modifies a DCE server’s configuration data.

dced_server_delete()
Deletes a DCE server’s configuration data.

dced_server_start()
Starts a DCE-configured server.

Server Execution Control Routines

dced_server_disable_if()
Disables a service provided by a server.

dced_server_enable_if()
Re-enables a service provided by a server.

dced_server_stop()
Stops a DCE-configured server.

Security Validation Routines

dced_secval_start()
Starts a host’s security validation service.

dced_secval_validate()
Validates that the DCE security daemon (secd) used by a specific host is legitimate. 

dced_secval_status()
Returns a status parameter of TRUE if the security validation service is activated and FALSE if not.

dced_secval_stop()
Stops a host’s security validation service.

Key Table Management Routines

dced_keytab_create()
Creates a key table with a list of keys in a new file.

dced_keytab_delete()
Deletes a key table file and removes the associated entry.

dced_keytab_initialize_cursor()
Obtains a list of keys from a key table and sets a cursor at the beginning of the list.

dced_keytab_get_next_key()
Returns a key from a cached list, and advances the cursor.

dced_keytab_release_cursor()
Releases the resources associated with a cursor that traverses a key table.

dced_keytab_add_key()
Adds a key to a key table.

dced_keytab_change_key()
Changes a key in both a key table and in the security registry.

dced_keytab_remove_key()
Removes a key from a key table.

Data Types and Structures

The following data types used with the dced API are defined in dce/dced_base.idl and are shown here in alphabetical order. 

dced_attr_list_t
This data structure specifies the configuration attributes to use when you start a server via dced.  The structure consists of the following:

countAn unsigned32 number representing the number of attributes in the list. 

listAn array of configuration attributes where each element is of type sec_attr_t.  This data type is described in the sec_intro(3sec) reference page.  For dced, the list[i].attr_id field can have values of either dced_g_uuid_fileattr specifying plain text or dced_g_uuid_binfileattr specifying binary data. 

dced_binding_handle_t
A dced binding handle is an opaque pointer that refers to information that includes  a dced service (hostdata, srvrconf, srvrexec, secval, or keytab) and RPC binding information for a specific DCE host daemon. 

dced_cursor_t
The entry list cursor is an opaque pointer used to keep track of a location in an entry list between calls that traverse the list.

dced_entry_t
An entry is the structure that contains information about a data item (or object) maintained by a dced service.  The actual data is maintained elsewhere.  Each entry consists of the following structure members:

idA unique identifer of type uuid_t that dced maintains for every data item it maintains

nameThe name for the data item.  The data type is dced_string_t . 

descriptionA brief description the data item (of type dced_string_t) for the convenience of human users. 

storage_tag
A string of type dced_string_t describing the location of the actual data.  This is implementation-specific and may be a file (with a pathname) on the host system or a storage identifier for the dced process. 

dced_entry_list_t
An entry list is a uniform way to list the data items a dced service maintains.  The entry list structure contains a list of all the entries for a given service.  For example, the complete list of all entries of hostdata, server configuration data,  server execution data, and keytab data are each maintained in separate entry lists.  The structure consists of the following:

countAn unsigned32 number representing the number of entries in the list. 

listAn array of entries where each element is of type dced_entry_t. 

dced_key_t
A key consists of the following structure members:

principalA dced_string_t type string representing the principal for the key. 

versionAn unsigned32 number representing the version number of the key. 

authn_service
An unsigned32 number representing the authentication service used. 

passwdA pointer to a password.  This is of type sec_passwd_rec_t . 

See also the security introduction reference page, sec_intro(3sec). 

dced_key_list_t
A key list contains all the keys for a given key table and consists of the following structure elements:

countAn unsigned32 number representing the number of keys in the list. 

listAn array of keys where each element is of type dced_key_t. 

dced_keytab_cursor_t
The keytab cursor is an opaque pointer used to keep track of a location in a key list between calls that traverse the list.

dced_opnum_list_t
A list of operation numbers is used in the service_t structure.  This structure consists of the following fields:

countAn unsigned32 number representing the number of operations in the list. 

listAn array of UUIDs where each element is of type uuid_t. 

dced_service_type_t
The dced service type distinguishes the services provided by dced.  It is an enumerated type used mainly in a parameter of the dced_binding_from_rpc_binding() routine.  It can have one of the following values:

dced_e_service_type_hostdata
The host data management service.

dced_e_service_type_srvrconf
The server configuration management service.

dced_e_service_type_srvrexec
The server execution management service.

dced_e_service_type_secval
The security validation service.

dced_e_service_type_keytab
The key table management service.

dced_e_service_type_null
A NULL service type used internally.

dced_string_t
This data type is a character string from the Portable Character Set (PCS).

dced_string_list_t
A list of strings with the following format:

countAn unsigned32 number representing the number of strings in the list. 

listAn array of strings where each element is of type dced_string_t. 

dced_tower_list_t
A list of protocol towers used in the service_t structure.  This structure consists of the following fields:

countAn unsigned32 number representing the number of protocol towers in the list. 

listAn array of pointers where each element is a pointer to a protocol tower of the type sec_attr_twr_set_p_t.  This data type is described in the sec_intro(3sec) reference page. 

server_fixedattr_t
This structure is a field in the server_t structure.  It contains the following fields:

startupflagsThis field is of type unsigned32 and can be any combination of the following bits:

server_c_startup_at_boot
This means that dced should start the server when dced is started. 

server_c_startup_auto
This means that the server can be started automatically if dced determines there is a need. 

server_c_startup_explicit
This means dced can start the server if it receives an explicit command to do so via dced_server_start() or the dcecp operation server start. 

server_c_startup_on_failure
This means that the server should be restarted by dced if it exits with an unsuccesful exit status. 

Several bits are also reserved for vendor-specific startup and include the following:

server_c_startup_vendor1

server_c_startup_vendor2

server_c_startup_vendor3

server_c_startup_vendor4

flagsThis represents the execution state of the server and is the unsigned32 type.  This field is maintained only by dced and should not be modified.  Valid values to check for are self-explanatory and include the following:

server_c_exec_notrunning

server_c_exec_running

Several bits are also reserved for vendor-specific execution states and include:

server_c_exec_vendor1

server_c_exec_vendor2

server_c_exec_vendor3

server_c_exec_vendor4

programThis is the full path name of the server and is of type dced_string_t. 

argumentsThis is a list of arguments for the server and is of type dced_string_list_t. 

prerequisites
This is an advisory field that means this server is a client of other prerequisite servers whose IDs are in a list of type uuid_list_t.  The UUIDs should be the id fields from the server_t structures of the relevent servers. 

keytablesThis is a list of keytab entry UUIDs representing the key tables for this server and is of type uuid_list_t. 

posix_uidThis is a POSIX execution attribute for the user ID.  It is of type unsigned32. 

posix_gidThis is a POSIX execution attribute for the group ID.  It is of type unsigned32. 

posix_dirThis is a POSIX execution attribute for the directory in which the server started when it is invoked.  It is of type dced_string_t. 

server_tThe DCE host daemon describes a server as follows:

idEach server has a unique ID of type uuid_t. 

nameEach server’s name is of type dced_string_t. 

entrynameThe server’s entry name is a hint as to where the server appears in the namespace.  This is of type dced_string_t. 

servicesEach server offers a list of services specified in a list of type service_list_t.  This structure has the following members:

countAn unsigned32 number representing the number of services in the list. 

listA pointer to an array of services where each element is of type service_t. 

fixedThis is a set of attributes common to all DCE implementations.  The data type is server_fixedattr_t. 

attributesThis field is of type dced_attr_list_t and contains a list of attributes representing the behavior specific to a particular server or host. 

prin_names
This field is a list of principal names for the server and is of type dced_string_list_t. 

exec_dataData about an executing server is maintained in a tagged union (named tagged_union) with a discriminator of type unsigned32 named execstate representing the server’s execution state.  The union has the following two execution states:

server_c_exec_notrunning
For the case where the server is not running, the union member has no value. For example:

if(server->exec_data.execstate == server_c_exec_notrunning)
    server->exec_data.tagged_union = NULL;

server_c_exec_running
For the case where the server is running, and the value of the union member is a srvrexec_data_t data type named  running_data.  A srvrexec_data_t structure contains the following members:

instanceEach instance of a server on a host is identified with a UUID (type uuid_t). 

posix_pidEach server has a POSIX process ID of type unsigned32. 

service_tThis structure describes each service offered by a server.  The server_t structure, described earlier, contains an array of these structures.  The service_t structure contains the following fields:

ifspecAn interface specification of type rpc_if_id_t, generated by an idl compilation of the interface definition representing the service.  This data type is described in the rpc_intro(3rpc) reference page. 

ifnameAn interface name of type dced_string_t. 

annotationAn annotation about the purpose of the interface (type dced_string_t).  This field is for user display purposes only. 

flagsThe flag field is of type unsigned32 and currently has only one bit field defined, service_c_disabled.  If this flag is set, it indicates that the service is not currently available for the server.  Also, the dced endpoint mapper will not map an endpoint to a disabled service.  Several values are also reserved for vendor-specific use:

service_c_vendor1

service_c_vendor2

service_c_vendor3

service_c_vendor4

entrynameThe entry name (type dced_string_t) is a hint as to where this service appears in the namespace.  If the value is NULL, the value in the entryname field of the server_t structure is used. 

objectsThis is a list of objects supported by the service.  The list is of type uuid_list_t. 

operationsThis is a list of operation numbers of type dced_opnum_list_t.  This field is not currently used. 

towersThis is a list of protocol towers of type dced_tower_list_t, specifying the endpoints where this server can be reached. 

srvrexec_stop_method_t
The server execution stop method is an enumerated type with one of the following values:

srvrexec_stop_rpc
Stops the running server gracefully by letting the server complete all outstanding remote procedure calls. This causes dced to invoke the rpc_mgmt_server_stop_listening() routine in that server. 

srvrexec_stop_soft
This uses a system-specific mechanism such as the SIGTERM signal.  It stops the running server with a mechanism that the server can ignore or intercept in order to do application-specific cleanup. 

srvrexec_stop_hard
This uses a system-specific mechanism such as the SIGKILL signal.  It stops the running server immediately with a mechanism that the server cannot intercept. 

srvrexec_stop_error
This uses a system-specific mechanism such as the SIGABRT signal.  The local operating system captures the server’s state before stopping it, and the server can also intercept it. 

uuid_list_t
A list of UUIDs in the following format:

countAn unsigned32 number representing the number of UUIDs in the list. 

listA pointer to an array of UUIDs where each element is of type uuid_t. 

Files

dce/dced_base.h

dce/dced.h

dce/dced_data.h

dce/rpctypes.idl

dce/passwd.idl

dce/sec_attr_base.idl

Related Information

Functions: dced_∗ API. 

Books: OSF DCE Application Development Guide