principal(1m)principal(1m)NAME
principal - A dcecp object that manages a principal in the DCE Security
Service
SYNOPSIS
principal catalog [cell_name] [-simplename]
principal create principal_name_list {-attribute extended_rgy_attr_list
| -attribute value}
principal delete principal_name_list
principal help [operation | -verbose]
principal modify principal_name_list {-add extended_rgy_attr_list |
-remove extended_rgy_attr_list [-types] | -change
extended_rgy_attr_list | -attribute value}
principal operations
principal rename principal_name -to new_principal_name
principal show principal_name_list [-all | -xattrs]
ARGUMENTS
The name of a cell to contact when processing the catalog operation.
The name must be a fully qualified cell name, such as /.: or
/.../cell_name The name of the principal operation for which to display
help information. The name of a single principal to act on. See prin‐
cipal_name_list for the name format. A list of one or more names of
principals to act on. Supply the names as follows: Fully qualified
principal names in the form /.:/principal_name, /.../cell_name/princi‐
pal_name, or principal_name@cell_name. Cell-relative principal names
in the form principal_name. These names refer to a principal in the
cell identified in the _s(sec) convenience variable, or if the _s(sec)
convenience variable is not set, in the local host's default cell.
Do not mix fully qualified names and cell-relative names in a list. In
addition, do not use the names of registry database objects that con‐
tain principal information; in other words, do not use names that begin
with /.:/sec/principal/.
DESCRIPTION
The principal object represents registry principals. Unless otherwise
noted, all of the operations of this object take the names of princi‐
pals to act on as an argument. These must be principal names, not the
names of the database objects that contain registry information about
principals (that is, the names must not begin with /.:/sec/principal).
When this command executes, it attempts to bind to the registry server
identified in the _s(sec) variable. If that server cannot process the
request or if the _s(sec) variable is not set, the command binds to
either an available slave server or the master registry server, depend‐
ing on the operation. Upon completion, the command sets the _b(sec)
convenience variable to the name of the registry server it bound to.
ATTRIBUTES
Used with the create and modify operations to specify whether the prin‐
cipal name is an alias. The value of this attribute is either yes (the
name is an alias) or no (the name is not an alias). The default in no.
Each principal can have only one primary name, but may have multiple
alias names. All of a principal's alias names refer to the same prin‐
cipal, and therefore share the same UUID and UNIX ID. While aliases
refer to the same principal, they are separate entries in the registry
database. Used with the create operation only for cell principals, to
specify the integer to use as user identifier, known as a Unix ID, for
the cell principals. No two principals can have the same UNIX ID.
However, aliases can share one.
If you do not enter this option for a cell principal, the next sequen‐
tial UNIX number is supplied as a default by the registry. For all
principals other than cell principals, the UNIX ID is extracted from
information embedded in the principal's UUID and cannot be specified
here. If this attribute is not supplied when a principal is created,
one is supplied automatically. Used with the create operation to spec‐
ify the internal identifier, known as a UUID, for the principal. No
two principals can have the same UUID, so do not use this option when
creating more than one principal with a single create command.
This option can also be used to adopt an orphaned UUID. Normally, the
UUID for a new principal is generated by the registry. When data is
tagged with a UUID of a principal that has been deleted from the reg‐
istry, this option can be used to specify the old UUID for a new prin‐
cipal. The UUID specified must be an orphan (a UUID for which no name
exists in the registry). An error occurs if you specify a name or UUID
that is already defined in the registry.
The -alias option cannot be used with this option. Both the -fullname
and the -quota options can.
Used with the create and modify operations to specify the full name of
the principal. This name is used for information purposes only. It
typically describes or expands a primary name to allow easy recognition
by users. For example, a principal could have a primary name of jsbach
and a full name of Johann S. Bach. The value is a string. If the
string contains spaces, you must surround them with quotation marks or
braces for entry. This option defaults to a null string (that is,
blank). Used with the create and modify operations to specify the
principal's object creation quota, which is the total number of reg‐
istry objects that can be created by the principal. It is either a
non-negative number or the string unlimited. A value of 0 prohibits
the principal from creating any registry objects. Each time a princi‐
pal creates a registry object, this value is decremented for that prin‐
cipal. Indicates whether the principal object is reserved or not. The
default is no. This attribute may not be set or modified by the user.
See the OSF DCE Administration Guide for more information about princi‐
pal attributes.
OPERATIONS
principal catalog
Returns a list of the names of all principals in the registry. The
syntax is as follows: principal catalog [cell_name] [-simplename]
Options Returns a list of principal names in the registry without
prepending the cell name.
The catalog operation returns a list of the names of all principals in
the local registry in lexical order. Use the cell_name argument to
return a list of principals in another cell's registry. By default,
fully qualified names are returned in the form cellname/principal_name.
Use the -simplename option to return them in the form principal_name.
Privileges Required
You must have r (read) permission to the /.:/sec/principal directory.
Examples
dcecp> principal catalog /.../small_cell.goodcompany.com/nobody
/.../small_cell.goodcompany.com/root /.../small_cell.goodcom‐
pany.com/daemon /.../small_cell.goodcompany.com/sys
/.../small_cell.goodcompany.com/bin /.../small_cell.goodcom‐
pany.com/uucp /.../small_cell.goodcompany.com/who /.../small_cell.good‐
company.com/mail /.../small_cell.goodcompany.com/tcb
/.../small_cell.goodcompany.com/dce-ptgt /.../small_cell.goodcom‐
pany.com/dce-rgy /.../small_cell.goodcompany.com/cell_admin
/.../small_cell.goodcompany.com/krbtgt/small_cell.goodcompany.com
/.../small_cell.goodcompany.com/hosts/pmin17/self /.../small_cell.good‐
company.com/hosts/pmin17/cds-server /.../small_cell.goodcom‐
pany.com/hosts/pmin17/gda /.../small_cell.goodcompany.com/William_Ward
/.../small_cell.goodcompany.com/John_Hunter dcecp>
principal create
Creates a new principal in the registry database. The syntax is as
follows: principal create principal_name_list {-attribute
extended_rgy_attr_list | -attribute value}
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 sec‐
tion of this reference page. You cannot use this format to specify
ERAs; it is only for the standard attributes described in ATTRIBUTES.
Allows you to specify attributes, including ERAs, by using an attribute
list rather than individual attribute options. The format of an
attribute list is as follows: {{extended_rgy_attr_list
value}...{extended_rgy_attr_list value}}
The create operation creates a new principal in the registry database.
The argument is a list of names of principals to be created. Options
are used to specify the attributes of the newly created principal. All
options are applied to all principals in the argument. This operation
returns an empty string on success.
Privileges Required
You must have i (insert) permission to the directory in which the prin‐
cipal is to be created.
Examples
The following command creates an alias postmaster for the principal
with UNIX ID 1234: dcecp> principal create postmaster -uid 1234 -alias
yes dcecp>
dcecp> principal create postmaster@gumby_cell dcecp>
principal delete
Deletes principals from the registry. The syntax is as follows: prin‐
cipal delete principal_name_list
The delete operation deletes principals from the registry. When a
principal is deleted, the principal's account is deleted as well. The
argument is a list of names of principals to be deleted. Note that
these names can be either primary or alias names. In either case, any
account associated with that name is deleted. If a named principal
does not exist, an error is generated. This operation returns an empty
string on success.
Privileges Required
You must have d (delete) permission to the directory in which the tar‐
get principal exists. You must have r (read) and D (Delete_object)
permissions on the principal to be deleted.
Examples
dcecp> principal delete /.:/William_Smith dcecp>
principal help
Returns help information about the principal object and its operations.
The syntax is as follows: principal help [operation | -verbose]
Options Displays information about the principal object.
Used without an argument or option, the principal help command returns
brief information about each principal operation. The optional opera‐
tion 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 principal object itself.
Privileges Required
No special privileges are needed to use the principal help command.
Examples
dcecp> principal help catalog Returns all the names of
principals in the registry. create Creates a DCE princi‐
pal. delete Deletes a principal from the registry. mod‐
ify Changes the information about a principal. rename
Renames the specified principal. show Returns the
attributes of a principal. help Prints a summary of
command-line options. operations Returns a list of the valid
operations for this command. dcecp>
principal modify
Changes attributes of principals. The syntax is as follows: principal
modify principal_name_list {-add extended_rgy_attr_list | -remove
extended_rgy_attr_list [-types] | -change extended_rgy_attr_list |
-attribute value}
Options As an alternative to using the -add, -change, or -remove
options with attribute lists, you can specify individual attribute
options by prepending a hyphen (-) to any attributes listed in the
ATTRIBUTES section of this reference page. You cannot use this format
to specify ERAs; it is only for the standard attributes described in
ATTRIBUTES. Allows you to modify attributes, including ERAs, by using
an attribute list rather than individual attribute options. The format
of an attribute list is as follows: {{extended_rgy_attr_list
value}...{extended_rgy_attr_list value}}
Allows you to modify attributes, including ERAs, by using an attribute
list rather than individual attribute options. See the -add option for
the attribute list format. Allows you to modify attributes, including
ERAs, by using an attribute list rather than individual attribute
options. See the -add option for the attribute list format.
Without the -types option, -remove deletes individual attribute
instances attached to the group. In this case, extended_rgy_attr_list
is a list of attribute-value pairs. With the -types option, -remove
deletes attribute types (and all instances of that type) attached to
the group. In this case, extended_rgy_attr_list is a list of attribute
types. Used with the -remove option to remove attribute types (and all
instances of that type) attached to the group. See the OSF DCE Admin‐
istration Guide for more information about ERAs.
The modify operation changes attributes of principals. The argument is
a list of names of principals to be operated on. All modifications are
applied to all principals named in the argument. Principals are modi‐
fied in the order they are listed, and all modifications to an individ‐
ual principal are atomic. Modifications to multiple principals are not
atomic. A failure for any one principal in a list generates an error
and cancels the operation. This operation returns an empty string on
success.
The -change option can be used to modify the value of any of the
attributes except for uid and uuid. The value of the -change option is
an attribute list describing the new values.
Privileges Required
You must have r (read) permission to the principal to be modified and f
(full name) permission to change the principal's fullname and/or m
(mgmt_info) permission to change the principal's management informa‐
tion.
Examples
dcecp> principal modify /.:/joe -fullname "Joe Long" dcecp> principal
show /.:/joe {name joe} {fullname {Joe Long}} {uid 30014} {uuid
0000753e-f51f-2e0e-b000-0000c08adf56} {alias no} {reserved no} {quota
unlimited} dcecp>
dcecp> principal modify joe -add {test_era 101} dcecp>
dcecp> principal show joe -all {name joe} {fullname {Joe Long}} {uid
30014} {uuid 0000753e-f51f-2e0e-b000-0000c08adf56} {alias no} {reserved
no} {quota unlimited} {test_era 101} dcecp>
principal operations
Returns a list of the operations supported by the principal object.
The syntax is as follows: principal 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 principal operations com‐
mand.
Examples
dcecp> principal operations catalog create delete modify rename show
help operations dcecp>
principal rename
This operation changes the name of a specified principal. The syntax
is as follows: principal rename principal_name -to new_principal_name
Options Specifies the new name of the principal.
The rename operation changes the name of a specified principal. The
argument is a single name of a principal to be renamed. The required
-to option specifies the new name, which cannot be a list. This opera‐
tion returns an empty string on success.
Privileges Required
You must have r (read) and n (name) permission to the registry object
for the specified principal.
Examples
dcecp> principal rename K_Doe -to K_Smith dcecp>
dcecp> principal show K_Doe Error: Registry object not found dcecp>
principal show
Shows registry information for the specified principals. The syntax is
as follows: principal show principal_name_list [-all | -xattrs]
Options Returns only the ERAs of the principal, with no other
attributes. Return the attributes followed by the ERAs.
The show operation returns an attribute list describing the specified
principals. The argument is a list of names of principals to be oper‐
ated on. If more than one principal is given, the attributes are con‐
catenated and a blank line inserted between principals. There is one
attribute in addition to fullname, uid, uuid, alias, and quota. It is
called groups and its value is a list of the group names that the prin‐
cipal is a member of. Attributes are returned in the following order:
fullname, uid, uuid, alias, and quota, followed by groups.
If called with the -xattrs option, then ERAs are returned instead of
the above attributes. If called with -all, both are returned.
Privileges Required
You must have r (read) permission to the specified principals.
Examples
dcecp> principal show /.:/joe {name joe} {fullname {Joe Long}} {uid
30014} {uuid 0000753e-f51f-2e0e-b000-0000c08adf56} {alias no} {reserved
no} {quota unlimited} {groups none gumby} dcecp>
RELATED INFORMATION
Commands: dcecp(1m), dcecp_account(1m), dcecp_group(1m), dcecp_organi‐
zation(1m), dcecp_registry(1m), dcecp_xattrschema(1m).
principal(1m)