NAME

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:

hostdata

The 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.

server

The 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).

secval

The security validation service maintains a host's principal identity and ensures applications that the DCE Security daemon is genuine.

keytab

The key table management service remotely manages key tables.

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 above 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.

2i

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:

count

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

list

An 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:

"id" A unique identifer of type uuid_t that dced maintains for every data item it maintains

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

description

A 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:

count

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

list

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

dced_key_t

A key consists of the following structure members:

principal

A dced_string_t type string representing the principal for the key.

version

An unsigned32 number representing the version number of the key.

authn_service

An unsigned32 number representing the authentication service used.

passwd

A 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:

count

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

list

An 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:

count

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

list

An 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:

count

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

list

An 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:

count

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

list

An 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:

startupflags

This 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 server_c_startup_vendor1, server_c_startup_vendor2, server_c_startup_vendor3, and server_c_startup_vendor4.

flags

This 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

program

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

arguments

This 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.

keytables

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

posix_uid

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

posix_gid

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

posix_dir

This 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_t

The DCE Host daemon describes a server as follows:

id

Each server has a unique ID of type uuid_t.

name

Each server's name is of type dced_string_t.

entryname

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

services

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

count

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

list

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

fixed

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

attributes

This 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_data

Data 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:

instance

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

posix_pid

Each server has a POSIX process ID of type unsigned32.

service_t

This 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:

ifspec

An 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.

ifname

An interface name of type dced_string_t.

annotation

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

flags

The 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 and include service_c_vendor1, service_c_vendor2, service_c_vendor3, and service_c_vendor4.

entryname

The 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.

objects

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

operations

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

towers

This 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_stop_server_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:

count

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

list

A 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

Routines: dced_* API.

Books: OSF DCE Application Development Guide