NAME
acl_edit - Edits or lists an object's ACLs
SYNOPSIS
acl_edit {[-e] pathname | -addr string_binding component_name}
[-ic | -io] [-n | -c] [command_line_subcommands] [-ngui]
[-v]
OPTIONS
-e pathname Specifies that the ACL on the Directory Service
entry is to be edited. You must specify the
pathname argument if you use the -e option. The
-e option is especially useful in case of an
ambiguous pathname. The pathname argument can be
interpreted in two ways if it is the name of a
leaf object in the Directory Service (that is, if
it is not the name of a directory). It can be
interpreted as the Directory Service entry itself,
or as the object (whatever it is) referenced by
that Directory Service entry. When such a path-
name is specified, the -e option directs acl_edit
to the ACL on the Directory Service entry.
-addr string_binding component_name
The -addr option lets you identify the object
whose ACLs you want to edit by supplying the RPC
binding handle of the ACL Manager that controls
access to the object (with the string_binding
argument) and the relative pathname of the object
(with the component_name argument). Because you
have identified the RPC binding handle, you can
specify only the object's relative pathname for
component_name. The most common way to identify
the object whose ACLs you want to manipulate
is through the pathname argument,described below.
The -addr option is used primarily by applications
that do not use the Directory Service, but do use
the generic ACL Manager. It can also be used if
the Directory Service is unavailable.
-ic For container objects only, specifies that the
object's Initial Container Creation ACL is to be
edited. The Initial Container Creation ACL is
applied by default to any containers created
within the ACL'd container. If this option is
specified and the object named in pathname is not
a container, an error is returned.
-io For container objects only, specifies that the
object's Initial Object Creation ACL is to be
edited. The Initial Object Creation ACL is applied
by default to any simple objects (that is, objects
that are not containers) created within the ACL'd
container. If this option is specified and the
object is not a container, an error is returned.
-n Specifies that a new mask should not be calculated.
This option is useful only for objects that
support the mask_obj entry type and that are
required to recalculate a new mask after they are
modified. If a modify operation creates a mask
that unintentionally adds permissions to an
existing acl entry, the modify causing the mask
recalculation will abort with an error unless you
specify either the -c or -n option.
-c Creates or modifies the object's mask_obj type
entry with permissions equal to the union of all
entries other than type user_obj, other_obj, and
unauthenticated. This creation or modification is
done after all other modifications to the ACL are
performed. The new mask is set even if it grants
permissions previously masked out. It is
recommended that you use this option only if not
specifying it results in an error. This option is
useful only for objects that support the mask_obj
entry type and are required to recalculate a new
mask after they are modified. If a modify
operation creates a mask that unintentionally adds
permissions to an existing acl entry, the modify
causing the mask recalculation will abort with an
error unless you specify either the -c or -n option.
If you specify the -c option for an ACL that does
not support mask_obj entry type, acl_edit returns
an error when it attempts to save the ACL, aborting
all subcommands supplied on the command line.
-ngui Specifies that a Graphical User Interface (GUI)
should not be used even if a GUI is available.
If your version of acl_edit supports a GUI and
your terminal is capable of using it, invoking
acl_edit without this option will bring up the GUI
mode. Use the -ngui option to bring up command-
line mode. However, if a GUI is not available, or
the terminal is not capable of using the GUI,
acl_edit comes up in command-line mode regardles
of wheter you supply this option or not.
-v Run in verbose mode.
ARGUMENTS
pathname The full pathname of the object whose ACL is to be
viewed or edited. If the object is in another
cell, pathname must be fully qualified to include
the cell identifier.
command_line_subcommands
The command-line subcommands, which act on the
object specified by pathname, are entered as part
of the command string that invokes acl_edit. Only
one command-line subcommand can be specified per
invocation. The commands follow. See the
description of the equivalent interactive
subcommand for a more detailed description of the
command functions.
-m [acl_entry] acl_entry...
Adds a new ACL entry or changes the
permissions of an existing entry. You
can enter multiple entries, each
separated by a space.
-p Purges all masked permissions (before
any other modifications are made). This
option is useful only for ACLs that
contain an entry of type mask_obj. Use it
to prevent unintentionally granting
permissions to an existing entry when a
new mask is calculated as a result of
adding or modifying an ACL entry.
-d [acl_entry] acl_entry...
Deletes an existing entry from the ACL
associated with the specified object.
You can enter multiple entries, each
separated by a space.
-s [acl_entry] acl_entry...
Replaces (substitutes) the ACL information
associated with this object with
acl_entry. All existing entries are
removed and replaced by the newly
specified entries. If you specify the -s
subcommand, you cannot specify the -f or
-k subcommand. You can enter multiple
entries, each separated by a space.
-f file Assigns the ACL information contained
in file to the object. All existing entries
are removed and replaced by the entries
in the file. If you specify the -f sub-
command, you cannot specify the -s or -k
subcommand.
-k Removes all entries, except entries of
type user_obj (if they are present).
If you specify the -k subcommand, you
cannot specify the -f or -s subcommand.
-l Lists the entries in the object's ACL.
The command-line subcommands are evaluated in the following order:
1.
-p
2.
-s or -f or -k
3.
-d
4.
-m
5.
-l
NOTES
With the exception of the following subcommands, 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.
+ abort
+ commit
+ exit
+ help
+ test access
DESCRIPTION
The acl_edit command is a client program that, when invoked, binds to
the specified object's ACL Manager (which is implemented in the object's
server), and allows the user to manipulate the object's ACL through the
standard DCE ACL interface. This interface is the sec_acl_...()
interface documented in the OSF DCE Application Development Reference.
The acl_edit command automatically binds to the server of the object
specified, and then communicates (through the standard DCE ACL
interface) with that server's ACL manager in response to user input.
Exactly what the object "specified" is depends partly on whether or not
the -e option is specified. Specifying -e means that you want to operate
on the Directory Service ACL - in other words, you want acl_edit to bind
to the CDS server and allow you to operate on the ACL maintained by that
server on the object's directory entry. If, on the the ACL on the object
to which the directory entry refers - then you simply omit the -e
option. The result will be that acl_edit will bind to that object's
server (the server must, of course, implement an ACL manager), giving
you access to the object's ACL.
All acl_edit subcommands act on the object specified by pathname when
you invoked acl_edit. You can invoke acl_edit in either command-line or
interactive mode:
+ To invoke acl_edit in command-line mode, enter the command, the
object's pathname, options, and the command-line subcommand on th
line that invokes acl_edit. Only one command-line subcommand can be
entered per acl_edit invocation.
+ To invoke acl_edit in interactive mode, enter only acl_edit, the
object's pathname, and options. The acl_edit prompt is then
displayed. In this mode, you enter interactive subcommands that
let you edit and view entries in the object's ACL and view help
information about the acl_edit command itself.
Changes you make in command-line mode are saved when you enter the
command.
In interactive mode, you must explicitly save your changes. To do so,
use the commit subcommand to save the changes without exiting acl_edit
or the exit subcommand to save the changes and exit acl_edit. Use the
abort subcommand to exit acl_edit and save none of the changes you have
made. When you invoke acl_edit for a specific object's ACL, that ACL is
not locked. This means that it is possible for multiple users to edit
the ACL simultaneously, with each change overwriting the previous
changes. For this reason, the number of users assigned rights to change
a particular ACL should be tightly controlled and limited to one user
if possible.
INTERACTIVE SUBCOMMANDS
The following subcommands are available when acl_edit is invoked in
interactive mode. All of the commands act on the ACL associated with the
object specified by pathname when acl_edit was invoked.
? Displays the available acl_edit subcommands.
ab[ort] Exits acl_edit without saving the changes to the object's ACL.
as[sign] filename
Applies the ACL entries in filename to the specified object.
This subcommand removes existing entries and replaces them
with the entries in the file.
c[ell] name
Sets the cell name to be associated with the ACL. This sub-
command is used primarily to facilitate copying ACLs to
different cells. The default cell name stays in place until
you run the subcommand again to change it.
co[mmit] Saves all changes to the ACL without exiting.
d[elete] acl_entry
Deletes the specified ACL entry.
e[xit] Exits from acl_edit, saving any changes to the object's ACL.
g[et_access]
Displays the permissions granted in the specified object's ACL
to the principal that invoked acl_edit.
h[elp] [command ...]
Initiates the help facility. If you enter only the command
help, acl_edit displays a list of all commands and their
functions. If you enter help and a command (or commands
separated by a space), acl_edit displays help information on
the specified commands. Entering help sec_acl_entry displays
information about ACL entries.
k[ill_entries]
Removes all ACL entries except the user_obj entry if it
exists.
l[ist] Lists the entries in the object's ACL.
m[odify] acl_entry [-n | -c]
Adds a new ACL entry or replaces an existing ACL entry. This
command affects a single ACL entry. To add or replace all of
an object's ACL entries, see the su[bstitute] subcommand. For
objects that support the mask_obj entry type and are required
to calculate a new mask when their ACLs are modified, the -n
option specifies that a new mask should not be calculated; the
-c option specifies that the object's mask_obj entry should
have permissions equal to the union of all entries other than
user_obj, other_obj, and unauthenticated. The mask is
calculated after the ACL is modified.
If you use the -c option, the new mask is set even if it
grants permissions previously masked out. It is recommended
that you use the -c option only if not specifying it results
in an error. If the new mask unintentionally grants
permissions to an existing entry, the modify operation
causing the mask recalculation will abort with an error
unless you specify either the -c or -n option.
p[ermissions]
Lists the available permission tokens and explanations.
pu[rge] Purges all masked permissions. This option is useful only
for ACLs that contain an entry of type mask_obj. Use it to
prevent unintentionally granting permissions to an existing
entry when a new mask is calculated as a result of adding or
modifying an ACL entry.
su[bstitute] acl_entry [acl_entry ...]
Replaces all ACL entries with the one or ones specified. This
subcommand removes all existing entries and adds the ones
specified by acl_entry. To replace only a single ACL entry,
see the m[odify] subcommand.
t[est_access] [permissions ...]
Tests whether or not the permissions specified in the command
are granted to the principal under whose DCE identity the
acl_edit command was invoked. The option returns Granted if
the permissions are granted or Denied if they are not.
ACL ENTRIES
An ACL entry has the following syntax:
type[:key]:permissions
where:
type Identifies the role of the ACL entry.
key Identifies the specific principal or group to whom
the entry applies. For an entry type of extended,
key contains the ACL data.
permissions The ACL permissions.
A thorough description of each syntax component follows.
Type The type tag identifies the role of the ACL entry.
Valid types are the following:
+ user_obj - Permissions for the object's real or
effective user.
+ group_obj - Permissions for the object's real or
effective group.
+ other_obj - Permissions for others in the local cell
who are not otherwise named by a more
specific entry type.
+ user - Permissions for a specific principal
user in the ACL's cell. This type of
ACL entry must include a key that
identifies the specific principal.
+ group - Permissions for a specific group in the
ACL's cell. This type of ACL entry must
include a key that identifies the
specific group.
+ foreign_user
Permissions for a specific, authenticated
user in a foreign cell. This type of ACL
entry must include a key that identifies
the specific principal and the principal's
cell.
+ foreign_group
Permissions for a specific, authenticated
group in a foreign cell. This type of ACL
entry must include a key that identifies
the specific group and the group's cell.
+ foreign_other
Permissions for all authenticated
principals in a specific foreign cell,
unless those principals are specifically
named in an ACL entry of type foreign_user
or members in a group named in an entry of
type foreign_group. This type of ACL
entry must include a key that identifies
the specific foreign cell.
+ any_other - Permissions for all authenticated
principals unless those principals match
a more specific entry in the ACL.
+ mask_obj - Permissions for the object mask that is
applied to all entry types except
user_obj, other_obj, and unauthenticated.
+ unauthenticated
Maximum permissions applied when the
accessor does not pass authentication
procedures. This entry is used for
principals that have failed authentica-
tion due to bad keys, principals who
are entirely outside of any authentication
cell, and principals who choose not to use
authenticated access. Permissions granted
to an unauthenticated principal are masked
with this entry, if it exists. If this
entry does not exist, access to
unauthenticated principals is always
denied.
+ extended - A special entry that allows client
applications running at earlier DCE
versions to copy ACLs to and from ACL
Managers running at the current DCE
version without losing any data. The
extended entry allows the application
running at the lower version to obtain a
printable form of the ACL. The extended
ACL entry has the following form:
extended:uuid.ndr.ndr.ndr.ndr.number_of_byte.data
where:
uuid Identifies the type extended ACL
entry. (This UUID can identify
one of the ACL entry types
described here or an as-yet-
undefined ACL entry type.)
ndr.ndr.ndr.ndr
Up to three Network Data
Representation (NDR) format labels
(in hexadecimal format and
separated by periods) that
identify the encoding of data.
number_of_bytes
A decimal number that specifies
the total number of bytes in data.
data The ACL data in hexadecimal form.
(Each byte of ACL data is two
hexadecimal digits.) The ACL data
includes all of the ACL entry
specifications except the
permissions (described later) that
are entered separately. The data
is not interpreted; it is assumed
that the ACL Manager to which the
data is being passed can understand
that data.
Key
The key identifier (principal or group name) specifies the principal or
group to which the ACL entry applies. For entries of entry type
extended, key is the data passed from one ACL Manager to another. A key
is required for the following types of ACL entries:
+ user - Requires a principal name only.
+ group - Requires a group name only.
+ foreign_user - Requires a fully qualified cell name in addition
to the principal name.
+ foreign_group - Requires a fully qualified cell name in addition
to the group name.
+ foreign_other - Requires a fully qualified cell name.
Permissions
The permissions argument specifies the set of permissions that defines
the access rights conferred by the entry. Since each ACL Manager defines
the permission tokens and meanings appropriate for the objects it
controls, the actual tokens and their meanings vary. For example, the
Distributed File Service, the Directory Service, and the Security
Registry Service each implemhent a separate ACL Manager, and each can
use a different set of tokens and permissions. This means that file
system objects, objects in the namespace, and registry objects could
each use different permissions. Use the p[ermissions] subcommand to
display the currently available tokens and their meanings. See the
documentation for the DCE component you are using to obtain a more
detailed description of its specific permissions.
EXAMPLES
1. The following example uses the interactive interface to set permis-
sions for the unauthenticated and mask_obj entry type:
sec_acl_edit> m mask_obj:rwx
sec_acl_edit> m unauthenticated:r
2. The following example uses the interactive interface to set permis-
sions for the effective user, group, and others in the ACL's cell:
sec_acl_edit> m user_obj:crwx
sec_acl_edit> m group_obj:rwx
sec_acl_edit> m other_obj:rwx
3. The following example uses the command-line interface to invoke
acl_edit and assign permissions for the file progress_chart to the
authenticated user mike in the local cell:
% acl_edit /.../dresden.com/fs/walden/progress_chart -m user:mike:cx
Note that because this entry will be filtered through the object
mask (mask_obj), which specifies only rwx permissions, the actual
permissions will be rwx, not crwx. The l(ist) subcommand will show
those permissions as follows:
user:mike:crwx #effective -rwx---
4. The following example uses the interactive interface to set permis-
sions for the authenticated foreign user named burati in the cell
named /.../usc-cs.uscal.edu:
sec_acl_edit> m foreign_user:/.../usc-cs.uscal.edu/sailing/staff/bux
5. The following example uses the non-interactive command-line inter-
face to invoke and set the Initial Container Creation
permissions for the directory that is named walden:
% acl_edit /.../dresden.com/fs/walden -ic -m /user:walden:crwxid