NAME

server - A dcecp object that manages DCE application servers

SYNOPSIS

server catalog [host_name_list] [-executing] [-simplename] [-local] server create server_name_list {-attribute attribute_list | -attribute value} [-local] server delete server_name_list [-local] server disable server_name_list [-interface interface_id_list] server enable server_name_list [-interface interface_id_list] server help [operation | -verbose] server modify server_name_list {-add  extended_rgy_attr_list | -remove extended_rgy_attr_list [-types] | -change attribute_list} [-local] server operations server ping server_name_list [-timeout timeout_method] server show server_name_list [-executing] [-local] server start server_name_list [-uuid uuid_list] server stop server_name_list [-method method]

ARGUMENTS

host_name_list
A list of one or more DCE host names specifying hosts for which to catalog servers.  Host names can be in any of the following forms:

/.:/hosts/hostname
 
/.../cell_name/hosts/hostname
 
hosts/hostname

server_name_list
A list of one or more names of servers to act on.  Server names have the following form:

/.../cell_name/hosts/host_name/config/service/name

where service is one of the following: srvrconf, srvrexec, or server.  The first two replacements for service uniquely identify the correct service as either the configuration service or the execution service.  The third is a simpler but ambiguous term; however, the ambiguity can usually be resolved by context.  For example, the stop operation only applies to a srvrexec object.  In cases where it is still ambiguous, a srvrconf object is assumed unless the ­-executing option is present.  Examples of server names are shown in the OPERATIONS sections of this reference page. 

operationThe name of the server operation for which to display help information. 

DESCRIPTION

The server object refers to servers residing on a host.  This one object can affect both the running daemons and the configuration information used by dced to start that daemon.  The distinction is usually obvious by the definition of the operation or by the name given as an argument.  When this is not the case, the ambiguity is resolved by a required option.  Almost all of these commands contact the dced on the target host to perform their operations.  Exceptions to this are noted below.  Some commands operate on a single server while other commands operate on more than one server.  See the ARGUMENTS section of this reference page for a description of how to specify server names.  Server configuration objects may contain application-specific extended registry attributes (ERAs).  Only the ERAs can be modified after creation, other attributes cannot.  When the dced on the local machine is in partial service mode, you must use the ­-local option to access the server object.  To access the server object when dced is in this mode, specify only the residual portion of the object name.  For example, specify server/server_name, not /.:/hosts/host_name/config/server/server_name. 

DATA STRUCTURES

interface_idThe interface identifier of an RPC interface.  The interface identifier takes the following form:

interface-uuid,major-version.minor-version

The version numbers are optional, but if you omit a version number, the value defaults to 0.  The UUID is a hexadecimal string and the version numbers are decimal strings.  For example:

-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11

Leading zeros in version numbers are ignored.  Alternatively, you can use dcecp string syntax in the following form:

{interface-UUID major-version.minor-version}

For example:

-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}

ATTRIBUTES

arguments  string_list
The command-line arguments passed to the program on startup.  Its value is a list of strings.  May not be modified after creation.

directory directory_name
The working directory that the server is started with.  May not be modified after creation.

gid group_idThe POSIX group identifier (gid) that the server is started with.  May not be modified after creation. 

keytabs keytab_list
A list of UUIDs of related keytab objects where the server stores its keys.  May not be modified after creation.

program program_name
The name of the server program to be run.  Its’ value is a string.  May not be modified after creation.

prerequesites uuid_list
A list of UUIDs of other server configuration objects that represents servers that must be running before this one is started.  In DCE Version 1.1, this information is not used to start the other servers; it is merely a note to the administrator.  Future versions of dced will probably take action based on this attribute.  May not be modified after creation.

principals principal_name_list
A list of principal names that the server runs as.  For example, secd runs as three different principals.  A fully qualified name is always returned on output.  On input a relative principal name represents a principal in the default cell of the dced.  May not be modified after creation.

services attribute_list
A list where each element is an attribute list of the following attributes:

annotation string
A human readable Portable Character Set (PCS) string describing the service.  (This is not an internationalized string, for compatibility with DCE Version 1.0 endpoint map annotation strings.)

bindings protocol_sequence_list
A list of string bindings identifying the service.

flags flag_name_list
The value is a list of key words to identify flags for the server. Currently only the following is supported:

disabledThe mapping has been marked as disabled in the endpoint map. 

ifname interface_name
The name of the interface of the service limited to PCS characters.

interface interface_id
The interface identifier (UUID and version) of the service.

entryname service_name
The name of the service (limited to PCS characters).

objects object_uuid_list
A list of object UUIDs supported by the service.

executing{ uuid pid}
A list of two elements, the UUID of the server instance and the pid (process ID) of the running server.  This attribute is only present if the server is running.  This attribute is multi-valued, one value for each instance of the server.

starton starting_condition_list
This attribute identifies when a server should be started.  The value is a list of one or more of the following, none of which can be modified after creation.

autoStart if a remote call that would be serviced by this server is received by dced.  Ignored for those servers that are repositories. 

bootStart at system startup. 

explicitStart if dced receives a command to start the server (such as the server start command in dcecp). 

failureStart if dced detects that the server exited with a nonsuccessful error code. 

Specifying a null value to this attribute means the server will not be started.  An example of a possible value is as follows:

{starton {boot explicit failure}}

uid user_idThe POSIX user identifier (uid) that the server is started with.  May not be modified after creation. 

uuid uuidThe internal identifier of the object.  It can be specified on creation, or automatically generated, but once created it may not be modified. 

Server configuration objects may also have ERAs attached to them.  ERAs may be manipulated by the modify operation.  See the OSF DCE Administration Guide for more information about server attributes. 

OPERATIONS

server catalog

Returns a list of the names of all server configuration objects on a specified host.  The syntax is as follows: server catalog [host_name_list] [-executing] [-simplename] [-local] Options

-executingReturns the name of all servers known by dced that are currently running on the specified host. 

-simplenameReturns names but removes the /.../cellname/hosts/hostname/config/service/ portion of the name. 

-localSpecifies that the command is to operate on the local dced object while the dced on the local machine is in partial service mode. 

The catalog operation returns a list of the names of all server configuration objects on a specified host.  If called with the ­-executing option, it returns the name of all server execution objects (running servers) known by dced that are currently executing on the specified host.  If called with no arguments, it returns information about the servers on the local host.  The optional host_name_list argument is a list of host names.  If more than one is specified then the information returned is concatenated together.  The order of information returned is arbitrary.  Fully qualified names are returned by default; use the ­-simplename option to return the names without prepending the cellname and the name of the server container.  Privileges Required You must have i (insert) permission to the applicable container (configuration or execution) object.  Examples

dcecp> server catalog /.:/hosts/foster/config
/.:/hosts/gumby/config/srvconf/try_tserver
dcecp>

server create

Creates a server configuration object.  The syntax is as follows: server create server_name_list {-attribute attribute_list | -attribute value} [-local] Options

-attribute attribute_list
Allows you to specify attributes by using an attribute list rather than using the -attribute value option. The format of an attribute list is as follows:

{{attribute value}...{attribute value}}

-attribute value
As an alternative to using the -attribute option with an attribute list, you can change individual attribute options by prepending a hyphen (-) to any attributes listed in the ATTRIBUTES section of this reference page. See ATTRIBUTES for descriptions of attributes.

-localSpecifies that the command is to operate on the local dced object while the dced on the local machine is in partial service mode. 

The create operation creates a server configuration object.  The server_name_list argument is a list of names of server configuration objects to be created.  An ­-attribute option with an argument list as a value is required to define attributes for the server to be created; the operation also accepts individual -attribute value.  It returns an empty string on success.  Privileges Required You must have i (insert) permission to the configuration container object.  Examples

dcecp> server create /.:/hosts/foster/config/srvrconf/try_tserver \
> -arguments /.:/hosts/foster/test_server \
> -program tserver \
> -entryname /.:/hosts/foster/test_server \
> -services {{ifname  {test server}}
>   {annotation {dcecp server test program}}
>   {interface {008bebed-c7c1-1ddc-9cb3-0000c0ba4944 1.0}}
>   {bindings {ncadg_ip_udp 130.105.5.50}}
>   {objects 0073f23a-2e1a-1ddd-b73a-0000c0ba4944}
>   {flags {}}
>   {entryname /.:/hosts/foster/test_server}}}
> -principals tserver \
> -starton boot auto explicit failure \
> -directory {/opt/tserver}
dcecp>

server delete

Deletes a server configuration object.  The syntax is as follows: server delete server_name_list [-local] The delete operation deletes a server configuration object.  The server_name_list argument is a list of names of server configuration objects to be deleted.  This operation returns an empty string on success.  An error is returned if any of the objects do not exist. Options

-localSpecifies that the command is to operate on the local dced object while the dced on the local machine is in partial service mode. 

Privileges Required You must have d (delete) permission to the server configuration object.  Examples

dcecp> server delete /.:/hosts/foster/config/srvrconf/try_tserver
dcecp>

server disable

Disables the specified server.  The syntax is as follows: server disable server_name_list [-interface interface_id_list] Options

-interface interface_id_list
Optionally specifies a list of one or more RPC interfaces to be disabled.  The interface identifier can be in string syntax or dcecp syntax. See DATA STRUCTURES for a description of string and dcecp syntaxes.

The disable operation disables the specified server.  It communicates with dced and removes the endpoints for all interfaces registered by the server (except the rpc_mgmt interface) from the endpoint map.  The server_name_list argument is a list of names of server execution objects.  The operation accepts an optional ­-interface option to specify a list of interfaces to be disabled.  It returns an empty string on success.  Privileges Required You must have w (write) permission to the server configuration object.  Examples

dcecp> server disable /.:/hosts/foster/config/srvrexec/try_tserver
dcecp>

server enable

Enables the specified server.  The syntax is as follows: server enable server_name_list [-interface interface_id_list] Options

-interface interface_id_list
Optionally specifies a list of one or more RPC interfaces to be disabled.  The interface identifier can be in string syntax or dcecp syntax. See DATA STRUCTURES for a description of string and dcecp syntax.

The enable operation enables the specified server.  It communicates with dced and enables any previously disabled endpoint mapping for all interfaces registered by the server in the endpoint map.  The argument server_name is a list of names of server execution objects.  This operation accepts an optional ­-interface option to specify a list of interfaces to be enabled and returns an empty string on success.  Privileges Required You must have w (write) permission to the server execution object.  Examples

dcecp> server enable /.:/hosts/foster/config/srvrexec/try_tserver
dcecp>

server help

Returns help information about the server object and its operations.  The syntax is as follows: server help [operation | -verbose] Options

-verboseDisplays information about the server object. 

Used without an argument or option, the server help command returns brief information about each server operation.  The optional operation argument is the name of an operation about which you want detailed information.  Alternatively, you can use the ­-verbose option for more detailed information about the server object itself.  Privileges Required No special privileges are needed to use the server help command.  Examples

dcecp> server help
catalog             Returns the list of srvrconf or srvrexec object names.
create              Creates a new server configuration (srvrconf) object.
delete              Deletes a server configuration (srvrconf) object.
disable             Disables interfaces of server execution (srvrexec) object.
enable              Enables interfaces of server execution (srvrexec) object.
modify              Modifies the srvrconf object’s variable attributes.
ping                Pings a server to see if it is receiving requests.
show                Returns the attributes of a srvrconf or srvrexec object.
start               Starts the specified server.
stop                Stops the specified running server.
help                Prints a summary of command-line options.
operations          Returns a list of the valid operations for this command.
dcecp>

server modify

Used to add or remove fixed attributes or ERAs and their values from the server configuration object.  The syntax is as follows: server modify server_name_list {-add extended_rgy_attr_list | -remove extended_rgy_attr_list [-types]  | -change attribute_list} [-local] Options

-add extended_rgy_attr_list
Allows you to add ERAs that may be defined for your environment.  You can specify the attributes to be added as a list. See the OSF DCE Administration Guide for more information about ERAs.

-remove extended_rgy_attr_list
Allows you to remove ERAs that may be defined for your environment.  You can specify the attributes to be removed as a list. See the OSF DCE Administration Guide and for more information about ERAs.

-typesSpecifies that a list of attribute names instead of names and values was given as the value of the ­-remove option, indicating that the entire attribute should be removed and not just specified values. 

-change attribute_list
Allows you to specify attributes by using an attribute list in the following format:

{{attribute value}...{attribute value}}

See ATTRIBUTES for more information about server attributes. 

-localSpecifies that the command is to operate on the local dced object while the dced on the local machine is in partial service mode. 

The modify operation changes fixed attributes or adds or removes ERAs and their values from the server object.  The server_name_list argument is a list of names of server objects to be modified.  The operation accepts the ­-change option which must have an attribute list as its value.  Attribute options are not supported for this command.  The name is always for a server configuration object; you may not modify a server execution object.  This operation returns an empty string on success.  Privileges Required You must have w (write) permission to the server configuration object.  Examples

dcecp> server modify /.:/hosts/foster/config/srvrconf/try_tserver \
> -add {data {second server list}}
dcecp>

server operations

Returns a list of the operations supported by the server object.  The syntax is as follows: server operations The list of available operations is in alphabetical order except for help and operations, which are listed last. Privileges Required No special privileges are needed to use the server operations command. Examples

dcecp> server operations
catalog create delete disable enable modify ping show start stop help operations
dcecp>

server ping

Checks whether a server is receiving client requests.  The syntax is as follows: server ping server_name_list [-timeout timeout_method] Options

-timeout timeout_method
Specifies the timeout method to use during communication with the server. Legal values are: min (the default), max or default.

The ping operation queries a server to see if it is receiving requests.  This operation communicates directly with the server.  The server_name_list argument is a list identifying the servers to ping.  The ­-timeout option controls the communication timeout used in contacting the server being pinged.  Use min for speed, max for accuracy, and default for a compromise between speed and accuracy.  This operation returns a list of values, one for each server specified in the argument, in the same order.  The values are 1 if the server is listening for RPC requests, 0 if it is not.  Each argument can be in one of the following formats:

•The name of a server entry in the namespace to be imported from.  For example:

/.../brain_cell/hosts/wallis/srvrexec/event_server

•A string binding with an object UUID specified.  For example:

{00337ea9-d979-1dd8-923f-0000c08adf56 ncacn_ip_tcp 15.121.12.72}

•A string binding with an endpoint specified.  For example:

{ncacn_ip_tcp 15.121.12.72 1075}

•An interface ID followed by a hostname, separated by commas.  For example:

{4885772c-c6d3-11ca-84c6-08002bic8fif,oddball}

•An interface ID followed by an object UUID and a hostname, separated by commas.  For example:

{4885772c-c6d3-11ca-84c6-08002bic8fif,
019ee420-682d-1109-a607-08002bodea7a,
oddball}

Privileges Required Often no special privileges are required, but this can vary depending on the individual server.  Examples

dcecp> server ping /.../brain_cell/hosts/wallis/srvrexec/event_server
1
dcecp>

server show

Returns information about servers.  The syntax is as follows: server show server_name_list [-executing] [-local] Options

-executingReturns an attribute list for a running server rather than its associated configuration object. 

-localSpecifies that the command is to operate on the local dced object while the dced on the local machine is in partial service mode. 

The show operation returns a list of both the fixed attributes and ERAs for the server entries specified in the argument.  The argument server_name_list is a list of names of server object entries.  If the names are ambiguous, server configuration objects are assumed unless the ­-executing option is present.  If the argument is a list the output is concatenated into a single list in the order specified.  Privileges Required You must have r (read) permission to the specified (configuration or execution) object.  Examples

dcecp> server show /.:/hosts/foster/config/srvrconf/try_tserver
{uuid 003b24d2-a196-1df3-915f-0000c0ba4944}
{program tserver}
{arguments /.:/hosts/foster/test_server}
{prerequisites {}}
{keytabs {}}
{entryname /.:/hosts/foster/test_server}
{services
 {{ifname  {test server}}
  {annotation {dcecp server test program}}
  {interface {008bebed-c7c1-1ddc-9cb3-0000c0ba4944 1.0}}
  {bindings {ncadg_ip_udp 130.105.5.50}}
  {objects 0073f23a-2e1a-1ddd-b73a-0000c0ba4944}
  {flags {}}
  {entryname /.:/hosts/foster/test_server}}}
{principals /.../foster_cell/tserver}
{starton boot auto explicit failure}
{uid 0}
{gid 0}
{dir /opt/tserver}
dcecp>

server start

Contacts a dced process to start a server based on a server configuration object.  The syntax is as follows: server start server_name_list [-uuid uuid_list] Options

-uuid uuid_list
A list of one or more UUIDs that identify the server to be started.

The start operation contacts a dced to start a server based on a server configuration object.  The server_name_list argument is a list of names of server configuration objects.  This operation returns the UUID of the started server on success.  This is the UUID found in the serverexec object for the server.  Privileges Required You must have x (execute) permission to the configuration object.  Examples

dcecp> server start /.:/hosts/foster/config/srvrconf/try_tserver
d90a0374-eb99-11cd-91b1-080009251352
dcecp>

server stop

Stops the specified running server processes.  The syntax is as follows: server stop server_name_list [-method method] Options

-method method
Optionally specifies how dced should stop the server.  The method must be one of the following:

rpcUse rpc_mgmt_server_stop_listening.  This is the default. 

softUse a soft local mechanism, such as SIGTERM. 

hardUse a hard local mechanism, such as SIGKILL. 

errorUse a state-preserving mechanism, such as SIGABRT. 

The stop operation stops the specified running server processes.  The server_name_list argument is a list of names of servers.  This operation returns an empty string on success.  It takes an optional ­-method option to specify how dced should stop the server.  The RPC runtime identifies servers not by name, but by interface, object UUID and endpoints.  You should be aware that if you use the rpc method, the command will be unable to distinguish between two or more server instances binding without endpoints to the same interface and using the same object UUID.  In this case, the command will stop a randomly selected server, not necessarily the one named in server_name_list.  Privileges Required You must have s (stop) permission on the execution object.  Examples

dcecp> server stop /.:/hosts/foster/config/srvrexec/try_tserver
dcecp>

RELATED INFORMATION

Commands:

dcecp(1m), dcecp_account(1m), dcecp_acl(1m), dcecp_keytab(1m), dced(1m). 
 

Hewlett-Packard Company  —  OSF DCE 1.1/HP DCE 1.5