Query: dcecp_server
OS: hpux
Section: 1m
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
server(1m) server(1m)NAMEserver - A dcecp object that manages DCE application serversSYNOPSISserver 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 residual_server_name] server stop server_name_list [-method method] [-srname residual_server_name]ARGUMENTSA 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 This argument can also be a single string binding representing the host with which to communicate. See server_name_list for more informa- tion. 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 STRUCTURES 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 single 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.DESCRIPTIONThe 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 argu- ment. 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 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 server object name. For example, specify server/server_name, not /.:/hosts/host_name/config/server/server_name.DATA STRUCTURESThe interface identifier of an RPC interface. The interface identifier takes the following form: interface-uuid,major-version.minor-ver- sion The version numbers are optional, but if you omit one, the value defaults to 0. The UUID is a hexadecimal string, and the complete version number is a decimal string. For example: -interface ec1eeb60-5943-11c9-a309-08002b102989,3.11 Leading zeros in version numbers are ignored. Alternatively, you can use Tcl syntax in the following form: {interface-uuid major-version.minor-version} For example: -interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}ATTRIBUTESThe 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 cur- rent 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 interna- tionalized string, for compatibility with DCE Version 1.0 endpoint map annotation strings.) A list of string bindings identifying the ser- vice. 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 supports. 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. Cannot 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 running 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 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. 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 cell name and the name of the server container. Privileges Required You must have r (read) permission to the applicable container (configuration or execution) object. Examples dcecp> server catalog /.:/hosts/smith /.../gumby1/hosts/smith/config/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 cre- ated; 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}} > -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 [-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 specific 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 configuration 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 disable 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. Specifies 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. Specifies 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 Dis- ables 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} [-srname resid- ual_server_name | -local] Options 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. 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. 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 argu- ment 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 time- out_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 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: /.:/hosts/foster/test_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 fol- lowed 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 com- mand 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 identify 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 (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] [-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 success. 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 repre- senting 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 follows: 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 mecha- nism, 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 INFORMATIONCommands: dcecp(1m), dcecp_account(1m), dcecp_acl(1m), dcecp_hostdata(1m), dcecp_keytab(1m), dced(1m). server(1m)