server(1m)server(1m)NAMEserver - A dcecp object that manages DCE application servers
SYNOPSISserver catalog [host_name_list] [-executing] [-simplename] [-local]
server create server_name_list {-attribute attribute_list | -attribute
value} [-srname residual_server_name | -local]
server delete server_name_list [-srname residual_server_name | -local]
server disable server_name_list -interface interface_id_list [-srname
residual_server_name]
server enable server_name_list -interface interface_id_list [-srname
residual_server_name]
server help [operation | -verbose]
server modify server_name_list {-add extended_rgy_attr_list | -remove
extended_rgy_attr_list [-types] | -change attribute_list} [-srname
residual_server_name | -local]
server operations
server ping server_entryname_list [-timeout timeout_method]
server show server_name_list [-executing] [-srname residual_server_name
| -local]
server start server_name_list [-uuid uuid_list] [-srname resid‐
ual_server_name]
server stop server_name_list [-method method] [-srname resid‐
ual_server_name]
ARGUMENTS
A list of one or more DCE host names specifying hosts for which to cat‐
alog servers. Host names can be in any of the following forms:
/.:/hosts/hostname
/.../cell_name/hosts/hostname
hosts/hostname
This argument can also be a single string binding representing the host
with which to communicate. See server_name_list for more information.
The name of the server operation for which to display help information.
A list of one or more server entrynames to ping. See the DATA STRUC‐
TURES section of this reference page for more details. A list of one
or more names of servers to act on. Usually they are of the 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 applies only to a
srvrexec object. In cases where it is still ambiguous, a srvrconf
object is assumed unless the -executing option is present.
The name can also be a single string binding representing the host with
which to communicate. For example: {ncacn_ip_tcp 130.105.1.227}
A string binding is useful when the name service is not operating and
cannot translate the other forms of server names. If you supply a sin‐
gle string binding, you must use the -srname option to specify the
object's residual name.
Examples of server names are shown in the OPERATIONS section.
DESCRIPTION
The server object refers to servers residing on a host. This 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 are noted below.
Some commands operate on a single server while other commands operate
on more than one server. See the ARGUMENTS section 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 cre‐
ation; 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 por‐
tion of the server object name. For example, specify
server/server_name, not /.:/hosts/host_name/config/server/server_name.
DATA STRUCTURES
The 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 one, the value
defaults to 0. The UUID is a hexadecimal string, and the complete ver‐
sion number is a decimal string. For example: -interface
ec1eeb60-5943-11c9-a309-08002b102989,3.11 Leading zeros in version num‐
bers are ignored.
Alternatively, you can use Tcl syntax in the following form: {inter‐
face-uuid major-version.minor-version} For example: -interface
{458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}
ATTRIBUTES
The command-line arguments passed to the program on startup. Its value
is a list of strings. Cannot be modified after creation. The working
directory that the server is started with. Cannot be modified after
creation. The POSIX group identifier (gid) that the server is started
with. Cannot be modified after creation. A list of UUIDs of related
keytab objects in which the server stores its keys. Cannot be modified
after creation. The name of the server program to be run. Its value
is a string. Cannot not be modified after creation. A list of UUIDs
of other server configuration objects that represents servers that must
be running before this one is started. In the current version of DCE,
this information is not used to start the other servers; it is merely a
note to the administrator. Future versions of dced may take action
based on this attribute. Cannot be modified after creation. 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. Cannot be modified after creation. A
list where each element is an attribute list containing the following
attributes: 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.) A
list of string bindings identifying the service. A list of keywords to
identify flags for the server. Currently only one is supported: The
mapping has been marked as disabled in the endpoint map. The name of
the interface of the service limited to PCS characters. The interface
identifier (UUID and version) of the service. The name of the service
(limited to PCS characters). A list of object UUIDs the service sup‐
ports. 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. This attribute identifies when a
server should be started. The value is a list containing one or more
of the following, none of which can be modified after creation. Start
if dced receives a remote call that would be serviced by this server.
Ignored for those servers that are repositories. Start at system
startup. Start if dced receives a command to start the server (such as
the server start command in dcecp). Start 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}}
The POSIX user identifier (uid) that the server is started with. Can‐
not not be modified after creation. The internal identifier of the
object. It can be specified on creation, or automatically generated,
but once created it cannot 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.
OPERATIONSserver 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
Returns the name of all servers known by dced that are currently run‐
ning on the specified host. Returns names but removes the /.../cell‐
name/hosts/hostname/config/service/ portion of the name. Specifies
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 config‐
uration 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. The order of information returned is arbi‐
trary. Fully qualified names are returned by default; use the
-simplename option to return the names without prepending the cell name
and the name of the server container.
Privileges Required
You must have r (read) permission to the applicable container (configu‐
ration or execution) object.
Examples
dcecp> server catalog /.:/hosts/smith /.../gumby1/hosts/smith/con‐
fig/srvrconf/try_tserver dcecp>
dcecp> server catalog ncadg_ip_udp:15.22.24.244
/.../gumby1/hosts/smith/config/srvrconf/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} [-srname residual_server_name | -local]
Options
As an alternative to using the -attribute option with an attribute
list, you can specify individual attribute options by prepending a
hyphen (-) to any attributes listed in the ATTRIBUTES section of this
reference page. Allows you to specify attributes by using an attribute
list rather than individual attribute options. The format of an
attribute list is as follows: {{attribute value}...{attribute value}}
Specifies the server object to create. Specifies 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 pairs. The
-srname option is used to identify the specific server entry to create,
but only when the argument is a string binding representing a host, not
the fully qualified server name. This operation 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}} \ > -princi‐
pals 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 [-srname residual_server_name | -local]
Options
Specifies the server object to delete. Specifies that the command is
to operate on the local dced object while the dced on the local machine
is in partial service mode.
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. The -srname option is used to identify the spe‐
cific server entry to delete, but only when the argument is a string
binding representing a host, not the fully qualified server name. This
operation returns an empty string on success. An error is returned if
any of the objects do not exist.
Privileges Required
You must have d (delete) and r (read) permissions to the server config‐
uration object.
Examples
dcecp> server delete /.:/hosts/foster/config/srvrconf/try_tserver
dcecp>
dcecp> server delete ncacn_ip_tcp:15.22.24.145 -srname try_tserver
dcecp>
server disable
Disables the specified server. The syntax is as follows: server dis‐
able server_name_list -interface interface_id_list [-srname resid‐
ual_server_name]
Options
Specifies a list of one or more RPC interfaces to be disabled. The
interface identifier can be in string syntax or Tcl syntax.
See DATA STRUCTURES for the format of an interface identifier. Speci‐
fies the server object to disable.
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 requires the -interface option to specify a
list of interfaces to be disabled. The -srname option is used to iden‐
tify the specific server entry to disable, but only when the argument
is a string binding representing a host, not the fully qualified server
name. This operation returns an empty string on success.
Privileges Required
You must have w (write) permission to the server execution object.
Examples
dcecp> server disable /.:/hosts/foster/config/srvrexec/try_tserver \ >
-interface {bb8a80e2-dd2d-11cc-a842-080009353559 1.0} dcecp>
dcecp> server disable ncacn_ip_tcp:15.21.24.244 -srname try_tserver \ >
-interface {bb8a80e2-dd2d-11cc-a842-080009353559 1.0} dcecp>
server enable
Enables the specified server. The syntax is as follows: server enable
server_name_list -interface interface_id_list [-srname resid‐
ual_server_name]
Options
Specifies a list of one or more RPC interfaces to be enabled. The
interface identifier can be in string syntax or Tcl syntax.
See DATA STRUCTURES for the format of an interface identifier. Speci‐
fies the server object to enable.
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_list is a list of names of server execution objects. The
-srname option is used to identify the specific server entry to enable,
but only when the argument is a string binding representing a host, not
the fully qualified server name. This operation requires the
-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 \ >
-interface {bb8a80e2-dd2d-11cc-a842-080009353559 1.0} dcecp>
dcecp> server enable ncacn_ip_tcp:15.22.24.244 -srname try_tserver \ >
-interface {bb8a80e2-dd2d-11cc-a842-080009353559 1.0} dcecp>
server help
Returns help information about the server object and its operations.
The syntax is as follows: server help [operation | -verbose]
Options Displays 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 mod‐
ify server_name_list {-add extended_rgy_attr_list | -remove
extended_rgy_attr_list [-types] | -change attribute_list} [-srname
residual_server_name | -local]
Options Allows you to add ERAs that may be defined for your environ‐
ment. You can specify the attributes to be added as a list. See the
OSF DCE Administration Guide for more information about ERAs. 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 Admin‐
istration Guide and for more information about ERAs. Specifies 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. 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. Specifies
that the command is to operate on the local dced object while the dced
on the local machine is in partial service mode. Specifies the server
object to modify.
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. The -srname option is used to identify the
specific server entry to modify, but only when the argument is a string
binding representing a host, not the fully qualified server name. 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_entryname_list [-timeout timeout_method]
Options 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 whether it is receiving
requests. This operation communicates directly with the server. The
server_entryname_list argument is a list identifying the entrynames of
the servers to ping.
The -timeout option controls the communication timeout used in contact‐
ing 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:
/.:/hosts/foster/test_server A string binding with an object UUID spec‐
ified. For example: {00337ea9-d979-1dd8-923f-0000c08adf56 ncacn_ip_tcp
15.121.12.72} A string binding with an endpoint specified. For exam‐
ple: {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, gnat}
Privileges Required
Often no special privileges are required, but this can vary depending
on the individual server.
Examples
dcecp> server ping /.:/hosts/foster/test_server 1 dcecp>
server show
Returns information about servers. The syntax is as follows: server
show server_name_list [-executing] [-srname residual_server_name |
-local]
Options Returns an attribute list for an executing server object rather
than its associated configuration object. Specifies that the command
is to operate on the local dced object while the dced on the local
machine is in partial service mode. Specifies the server object to
show.
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. The -srname option is used to iden‐
tify the specific server entry to show, but only when the argument is a
string binding representing a host, not the fully qualified server
name. 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 applicable container (configu‐
ration 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 {}} {entry‐
name /.:/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 /.../fos‐
ter_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 configura‐
tion object. The syntax is as follows: server start server_name_list
[-uuid uuid_list] [-srname residual_server_name]
Options
A list of one or more UUIDs that identify the server to be started.
Specifies the server object to start. 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 suc‐
cess. This is the UUID found in the serverexec object for the server.
The -srname option is used to identify the specific server entry to
start, but only when the argument is a string binding representing a
host, not the fully qualified server name.
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>
dcecp> server start ncacn_ip_tcp:15.22.24.244 -srname try_tserver
d90a0374-eb99-11cd-91b1-080009251352 dcecp>
server stop
Stops the specified running server processes. The syntax is as fol‐
lows: server stop server_name_list [-method method] [-srname resid‐
ual_server_name]
Options
Optionally specifies how dced should stop the server. The method must
be one of the following: Use rpc_mgmt_server_stop_listening. This is
the default. Use a soft local mechanism, such as SIGTERM. Use a hard
local mechanism, such as SIGKILL. Use a state-preserving mechanism,
such as SIGABRT. Specifies the server object to stop.
The stop operation stops the specified running server processes. The
server_name_list argument is a list of names of servers. It takes an
optional -method option to specify how dced should stop the server.
The -srname option is used to identify the specific server entry to
stop, but only when the argument is a string binding representing a
host, not the fully qualified server name. This operation returns an
empty string on success.
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 cannot 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 stops 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 -method
soft dcecp>
RELATED INFORMATION
Commands: dcecp(1m), dcecp_account(1m), dcecp_acl(1m), dcecp_host‐
data(1m), dcecp_keytab(1m), dced(1m).
server(1m)
