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
principal_name_list for the name format. A list of one or more names of principals to act on. Supply the names as follows: Fully quali-
fied principal names in the form /.:/principal_name, /.../cell_name/principal_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
contain 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 prin-
cipals 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,
depending 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 principal 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 sequential 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
specify 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 registry, 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 registry 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 principal. 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 principal 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/princi-
pal_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.goodcompany.com/daemon
/.../small_cell.goodcompany.com/sys /.../small_cell.goodcompany.com/bin /.../small_cell.goodcompany.com/uucp /.../small_cell.goodcom-
pany.com/who /.../small_cell.goodcompany.com/mail /.../small_cell.goodcompany.com/tcb /.../small_cell.goodcompany.com/dce-ptgt
/.../small_cell.goodcompany.com/dce-rgy /.../small_cell.goodcompany.com/cell_admin /.../small_cell.goodcompany.com/krbtgt/small_cell.good-
company.com /.../small_cell.goodcompany.com/hosts/pmin17/self /.../small_cell.goodcompany.com/hosts/pmin17/cds-server /.../small_cell.good-
company.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 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 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 principal 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: principal 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 target 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
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 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. modify Changes the information about a principal. rename
Renames the specified principal. show Returns the attributes of a principal. help Prints a summary of com-
mand-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 spec-
ify 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 Administration 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 modified in the order they are listed, and all modifications to an
individual 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 information.
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 command.
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 operation 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
operated on. If more than one principal is given, the attributes are concatenated 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 principal 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_organization(1m), dcecp_registry(1m), dcecp_xattrschema(1m).
principal(1m)