rpccp(1m)rpccp(1m)NAMErpccp - Starts the RPC control program
SYNOPSISrpccp [rpccp-command]
ARGUMENTS
Specifies one of the following control program commands: Adds an ele‐
ment to a profile in a name service entry; if the specified entry does
not exist, creates the entry. Adds an entry to the name service data‐
base. Adds or replaces server address information in the local end‐
point map. Adds a member to a group in a name service entry; if the
specified entry does not exist, creates the entry. Leaves the RPC con‐
trol program. Exports binding information for an interface identifier,
object UUIDs, or both to a server entry; if the specified entry does
not exist, creates the entry. Displays a list of commands or the pos‐
sible options of a specified command. Imports binding information and
an object UUID from a server entry. Leaves the RPC control program.
Removes selected elements from a profile. Removes an entry from the
name service database. Removes all group members and the group from
the specified entry. Removes specified elements from the local end‐
point map or from the endpoint map of a specified remote host. Removes
a selected member from a group. Removes all profile elements and the
profile from the specified entry. Shows the NSI attributes of an
entry. Shows the members of a group. Shows the elements of the local
endpoint map. Shows the elements of a profile. Shows the binding
information, interface identifier, and object UUIDs in a server entry.
Removes binding information, interface identifiers, and object UUIDs
from a server entry.
NOTES
This facility is superceded by the DCE control program (dcecp) for OSF
DCE version 1.1.
A server entry equates to an NSI binding attribute and, optionally, an
object attribute; a group equates to an NSI group attribute; and a pro‐
file equates to an NSI profile attribute. Typically, each server's
entries, groups, and profiles reside in distinct name service entries.
NOTES
With the exception of the rpccp_help subcommand, this command is
replaced at Revision 1.1 by the dcecp command. This command may be
fully replaced by the dcecp command in a future release of DCE, and may
no longer be supported at that time.
DESCRIPTION
The RPC control program (RPCCP) provides a set of commands for managing
name service use for RPC applications and for managing the endpoint
map.
You can use control program commands from within the control program or
from the system prompt (represented here as a $).
To use the control program commands from inside the control program,
Start and enter the control program using the rpccp command alone,
without any argument. The control program then displays the control
program prompt (rpccp>), as follows: $ rpccp rpccp> You can then enter
any control program command, for example: rpccp> show entry
/.:/LandS/anthro/pr_server_node3 You leave the control program and
return to the system prompt using the exit or quit command.
If you enter invalid input, the control program displays the valid com‐
mands.
To use the control program commands from the system prompt, enter the
rpccp command with an internal command of the control program as the
first argument. You can do this either interactively or in a command
procedure. For example, you can enter the show entry command as fol‐
lows: $ rpccp show entry /.:/LandS/anthro/pr_server_node3
Arguments and Options
Except for the exit and quit commands, rpccp commands have one or more
options. Each option is identified by a - (dash) followed by a letter;
for example, -s. Some options require arguments.
Commands that access NSI operations also require the name of a name
service entry as an argument. The order of arguments and the entry-
name option is arbitrary; for example, the following placements of
arguments and options are equivalent: rpccp> add element
/.:/LandS/anthro/mis_node_2 \ > -i
ec1eeb60-5943-11c9-a309-08002b102989,1.0
rpccp> add element -i ec1eeb60-5943-11c9-a309-08002b102989,1.0 \ >
/.:/LandS/anthro/mis_node_2
Environmental Influences on Command Syntax
There are variations in the action of the control program, depending on
whether commands are entered from the system prompt or from within the
control program. For example, entering the annotation field of profile
elements from the system prompt allows you to include internal spaces
in an annotation.
┌────────────────────┬──────────────────┬────────────────────────┐
│Function │ At System Prompt │ Inside Control Program │
├────────────────────┼──────────────────┼────────────────────────┤
│Strings within quo‐ │ Supported │ Not required │
│tation marks │ │ │
│Wildcard substitu‐ │ Supported │ Unsupported │
│tion │ │ │
├────────────────────┼──────────────────┼────────────────────────┤
└────────────────────┴──────────────────┴────────────────────────┘
Some UNIX systems require that you place an escape symbol (\) before
string binding delimiters such as brackets ([ ]) or that you place the
delimiters within quotation marks (' ' or '' '') at the system prompt.
The following table describes the scope of the RPC control program com‐
mands.
┌─────────────┬────────────────┐
│Scope │ Command │
├─────────────┼────────────────┤
│ │ │
│All entries │ add entry │
│ │ remove entry │
│ │ show entry │
│ │ │
│Server entry │ export │
│ │ import │
│ │ show server │
│ │ unexport │
│ │ │
│Group │ add member │
│ │ remove group │
│ │ remove member │
│ │ show group │
│ │ │
│Profile │ add element │
│ │ remove element │
│ │ remove profile │
│ │ show profile │
│ │ │
│Endpoint map │ add mapping │
│ │ remove mapping │
│ │ show mapping │
├─────────────┼────────────────┤
└─────────────┴────────────────┘
Environment Variables
The control program supports environment variables. Using environment
variables facilitates interactive use of the control program.
To distinguish environment variables, rpccp*(1m) reference pages follow
the convention of using all uppercase letters for examples of environ‐
ment variables. Note that UNIX environment variables are case sensi‐
tive. You can set an environment variable to represent values to
rpccp. Using an environment variable is helpful for specifying a long
string such as the following: A string representation of binding infor‐
mation (binding string) A string representation of an object or inter‐
face UUID (string UUID) An interface identifier (the interface UUID and
version numbers) The name of a name service entry
For example, in the following example, the environment variable
JANE_CAL represents an object UUID; the target name service entry,
/.:/LandS/anthro/Cal_host_2, is in the local cell: $
JANE_CAL=47f40d10-e2e0-11c9-bb29-08002b0f4528 $ export JANE_CAL
$ rpccp rpccp> export -o JANE_CAL /.:/LandS/anthro/Cal_host_2 The
environment variable NLSPATH must point to the location of dcerpc.cat
and dcedcs.cat. Otherwise, any run-time status codes returned by the
control program will be hexadecimal, rather than textual. form. The
value of this variable must include both the pathname of the directory
where the .cat files reside and the string %N. The dce name syntax is
the only syntax currently supported by the DCE Cell Directory Service
(CDS). However, the Name Service Interface (NSI) is independent of any
specific name service and, in the future, may support name services
that use other name syntaxes. When alternative name syntaxes are sup‐
ported, you can override the standard default with a process-specific
default by setting the RPC_DEFAULT_ENTRY_SYNTAX environment variable.
When this variable is set for a process, the control program uses it to
find out the default syntax for the process. You can override this
default in any NSI command of the control program by using the -s
option to specify an alternative entry syntax. Setting
RPC_DEFAULT_ENTRY_SYNTAX requires specifying the integer 3 to indicate
the dce syntax. To set RPC_DEFAULT_ENTRY_SYNTAX, use the name=value
command to define an environment variable. The following command spec‐
ifies dce as the default name syntax in a login command file: # .login
command file # setting dce as default name syntax,
RPC_DEFAULT_ENTRY_SYNTAX=3 For the import command, you can use this
environment variable to indicate the entry where the search operation
starts. Usually, the starting entry is a profile.
The Name Service Interface
The remainder of this description contains information to help you use
commands that call the name service interface to access name service
entries (NSI commands).
The DCE RPC name service interface (NSI) is independent of any particu‐
lar name service. CDS, however, is the only name service available for
DCE RPC Version 1.0 applications. For more details on the name service
interface, see the . For a description of the DCE Cell Directory Ser‐
vice, see the .
Name Service Entries
To store information about RPC servers, interfaces, and objects, the
NSI defines the following name service entries: Stores binding informa‐
tion, interface identifiers, and object UUIDs for an RPC server Corre‐
sponds to one or more RPC servers that offer a common RPC interface,
type of RPC object, or both Defines search paths for looking in a name
service database for a server that offers a particular RPC interface
and object
Note that when the NSI is used with the Cell Directory Service, the
name service entries are CDS object entries
Structure of Entry Names
Each entry in a name service database is identified by a unique global
name made up of a cell name and a cell-relative name.
A cell is a group of users, systems, and resources that share common
DCE services. A cell configuration includes at least one cell directory
server, one security server, and one time server. A cell's size can
range from one system to thousands of systems. For information on
cells, see the CDS portion of this book.
The following is an example of a global name: /.../C=US/O=uw/OU=MadC‐
ity/LandS/anthro/Stats_host_2 The parts of a global name are as fol‐
lows: For example: /.../C=US/O=uw/OU=MadCity The symbol /... begins a
cell name. The letters before the equal signs (=) are abbreviations
for country (C), organization (O), and organization unit (OU).
For entries in the local cell, the cell name can be represented by a
/.: prefix, in place of the actual cell name; for example,
/.:/LandS/anthro/Stats_host_2 For NSI operations on entries in the
local cell you can omit the cell name.
Each name service entry requires a cell-relative name, which contains a
directory pathname and a leaf name. Follows the cell name and indi‐
cates the hierarchical relationship of the entry to the cell root.
The directory pathname is the middle portion of the global name. The
cell name is to the left of the directory pathname, and the leaf name
is to the right, as follows:
cell-name + directory-pathname + leaf-name
The directory pathname contains the names of any subdirectories in the
path; each subdirectory name begins with a slash (/), as follows:
/sub-dir-a-name/sub-dir-b-name/sub-dir-c-name
Directory paths are created by name service administrators. If an
appropriate directory path does not exist, ask your name service admin‐
istrator to extend an existing path or create a new path. In a direc‐
tory path, the name of a subdirectory should reflect its relationship
to its parent directory (the directory that contains the subdirectory).
Identifies the specific entry. The leaf name is the right-hand part of
global name beginning with the rightmost slash.
In the following example, /.../C=US/O=uw/OU=MadCity is the cell name,
/LandS/anthro is the directory pathname, and /Cal_host_4 is the leaf
name. /.../C=US/O=uw/OU=MadCity/LandS/anthro/Cal_host_4,
If a name service entry is located at the cell root, the leaf name
directly follows the cell name; for example, /.:/cell-profile.
Note that when the NSI is used with CDS, the cell-relative name is a
CDS name.
Guidelines for Constructing Names of Name Service Entries
A global name includes both a cell name and a cell-relative name com‐
posed of a directory pathname and a leaf name. The cell name is
assigned to a cell root at its creation. When you specify only a cell-
relative name to an NSI command, the NSI automatically expands the name
into a global name by inserting the local cell name. When returning the
name of a name service entry, a group member, or member in a profile
element, NSI operations return global names.
The directory pathname and leaf name uniquely identify a name service
entry. The leaf name should somehow describe the entry; for example, by
identifying its owner or its contents. The remainder of this section
contains guidelines for choosing leaf names. Note that directory path‐
names and leaf names are case sensitive.
For a server entry that advertises an RPC interface or service offered
by a server, the leaf name must distinguish the entry from the equiva‐
lent entries of other servers. When a single server instance runs on a
host, you can ensure a unique name by combining the name of the ser‐
vice, interface (from the interface definition), or the system name for
the server's host system.
For example, consider two servers, one offering a calendar service on
host JULES and one, on host VERNE.
The server on JULES uses the following leaf name: calendar_JULES The
server on VERNE uses the following leaf name: calendar_VERNE For
servers that perform tasks on or for a specific system, an alternative
approach is to create server entries in a system-specific host direc‐
tory within the name service database. Each host directory takes the
name of the host to which it corresponds. Because the directory name
identifies the system, the leaf name of the server entry name need not
include the host name, for example:
/.:/LandS/host_1/Process_control
To construct names for the server entries used by distinctive server
instances on a single host, you can construct unique server entry names
by combining the following information: the name of the server's ser‐
vice, interface, or object; the system name of the server's host sys‐
tem, and a reusable instance identifier, such as an integer.
For example, the following leaf names distinguish two instances of a
calendar service on the JULES system: calendar_JULES_01
calendar_JULES_02
Avoid automatically generating entry names for the server entries of
server instances, for example, by using unique data such as a time
stamp (calendar_verne_15OCT91_21:25:32) or a process identifier (calen‐
dar_jules_208004D6). When a server incorporates such unique data into
its server entry names, each server instance creates a separate server
entry, causing many server entries. When a server instance stops run‐
ning, it leaves an obsolete server entry that is not reused. The cre‐
ation of a new entry whenever a server instance starts may impair per‐
formance.
A server can use multiple server entries to advertise different combi‐
nations of interfaces and objects. For example, a server can create a
separate server entry for a specific object (and the associated inter‐
faces). The name of such a server entry should correspond to a well-
known name for the object. For example, consider a server that offers a
horticulture bulletin board known to users as horticulture_bb. The
server exports the horticulture_bb object, binding information, and
the associated bulletin-board interface to a server entry whose leaf
name identifies the object, as follows: horticulture_bb Note that an
RPC server that uses RPC authentication can choose identical names for
its principal name and its server entry. Use of identical names permits
a client that calls the rpc_binding_set_auth_info routine to automati‐
cally determine a server's principal name (the client will assume the
principal name to be the same as the server's entry name). If a server
uses different principal and server entry names, users must explicitly
supply the principal name. For an explanation of principal names, see
the DCE Security Service part of the DCE Application Development Guide.
The leaf name of a group should indicate the interface, service, or
object that determines membership in the group. For example, for a
group whose members are selected because they advertise an interface
named Statistics, the following is an effective leaf name: Statistics
For a group whose members advertise laser-printer print queues as
objects, the following is an effective leaf name: laser-printer
The leaf name of a profile should indicate the profile users; for exam‐
ple, for a profile that serves the members of an accounting department,
the following is an effective leaf name: accounting_profile
Privilege Required
To use the NSI commands to access entries in a CDS database, you need
access control list (ACL) permissions. Depending on the NSI operation,
you need ACL permissions to the parent directory or the CDS object
entry (the name service entry) or both. The ACL permissions are as
follows: To create an entry, you need insert permission to the parent
directory. To read an entry, you need read permission to the CDS
object entry. To write to an entry, you need write permission to the
CDS object entry. To delete an entry, you need delete permission
either to the CDS object entry or to the parent directory.
Note that write permission does not imply read permission.
ACL permissions for the NSI commands of the control program are
described in the reference pages.
EXAMPLES
The following command starts the RPC control program: $ rpccp rpccp>
The following command at the system prompt removes the entry
/.:/LandS/anthro/Cal_host_2: $ rpccp remove entry \ >
/.:/LandS/anthro/Cal_host_2
RELATED INFORMATION
Commands: dcecp, add element(1m), add entry(1m), add mapping(1m), add
member(1m), export(1m), import(1m), remove element(1m), remove
entry(1m), remove group(1m), remove mapping(1m), remove member(1m),
remove profile(1m), show entry(1m), show group(1m), show mapping(1m),
show profile(1m), show server(1m), unexport(1m)rpccp(1m)
