acl_edit(1m)acl_edit(1m)NAMEacl_edit - Edits or lists an object's ACLs
SYNOPSISacl_edit {[-e] pathname | -addr string_binding component_name} [-ic |
-io] [-n | -c] [command_line_subcommands] [-ngui] [-v]
OPTIONS
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 pathname is specified, the -e
option directs acl_edit to the ACL on the Directory Service entry. 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 rela‐
tive 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. 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. For container objects only, specifies that the object's
Initial Object Creation ACL is to be edited. The Initial Object Cre‐
ation 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. 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 modi‐
fied.
If a modify operation creates a mask that unintentionally adds permis‐
sions to an existing acl entry, the modify causing the mask recalcula‐
tion will abort with an error unless you specify either the -c or -n
option. Creates or modifies the object's mask_obj type entry with per‐
missions 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 rec‐
ommended 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 permis‐
sions to an existing acl entry, the modify causing the mask recalcula‐
tion 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. 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 capa‐
ble of using the GUI, acl_edit comes up in command-line mode regardless
of wheter you supply this option or not. Run in verbose mode.
ARGUMENTS
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. 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. Adds a new ACL entry or changes the permis‐
sions of an existing entry. You can enter multiple entries, each sepa‐
rated by a space. Purges all masked permissions (before any other mod‐
ifications 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. Deletes an existing entry
from the ACL associated with the specified object. You can enter mul‐
tiple entries, each separated by a space. Replaces (substitutes) the
ACL information associated with this object with acl_entry. All exist‐
ing entries are removed and replaced by the newly specified entries.
If you specify the -s subcommand, you cannot specify the -f or -k sub‐
command. You can enter multiple entries, each separated by a space.
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 subcommand, you cannot specify the -s or -k sub‐
command. 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. Lists the entries in the object's ACL. The com‐
mand-line subcommands are evaluated in the following order: -p -s or -f
or -k -d -m -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 Develop‐
ment Reference.
The acl_edit command automatically binds to the server of the object
specified, and then communicates (through the standard DCE ACL inter‐
face) 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 subcom‐
mand on the line that invokes acl_edit. Only one command-line subcom‐
mand 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 with‐
out 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. Exits acl_edit without saving the
changes to the object's ACL. Applies the ACL entries in filename to
the specified object. This subcommand removes existing entries and
replaces them with the entries in the file. Sets the cell name to be
associated with the ACL. This subcommand is used primarily to facili‐
tate copying ACLs to different cells. The default cell name stays in
place until you run the subcommand again to change it. Saves all
changes to the ACL without exiting. Deletes the specified ACL entry.
Exits from acl_edit, saving any changes to the object's ACL. Displays
the permissions granted in the specified object's ACL to the principal
that invoked acl_edit. 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.
Removes all ACL entries except the user_obj entry if it exists. Lists
the entries in the object's ACL. 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] subcom‐
mand.
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 speci‐
fies 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 unauthenti‐
cated. The mask is calculated after the ACL is modified.
If you use the -c option, the new mask is set even if it grants permis‐
sions 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. Lists the available
permission tokens and explanations. 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. 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. Tests whether or not the permissions speci‐
fied in the command are granted to the principal under whose DCE iden‐
tity 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: Identifies the role of the ACL entry. Identifies the specific
principal or group to whom the entry applies. For an entry type of
extended, key contains the ACL data. 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. for‐
eign_user - Permissions for a specific, authenticated user in a for‐
eign cell. This type of ACL entry must include a key that identifies
the specific principal and the principal's cell. foreign_group - Per‐
missions 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 authenti‐
cated 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 - Permis‐
sions 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 pro‐
cedures. This entry is used for principals that have failed authenti‐
cation 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 ver‐
sion without losing any data. The extended entry allows the applica‐
tion 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: 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.) Up to three Network Data Representation (NDR) format
labels (in hexadecimal format and separated by periods) that identify
the encoding of data. A decimal number that specifies the total number
of bytes in 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 implement 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 doc‐
umentation for the DCE component you are using to obtain a more
detailed description of its specific permissions.
EXAMPLES
The following example uses the interactive interface to set permissions
for the unauthenticated and mask_obj entry type: sec_acl_edit> m
mask_obj:rwx sec_acl_edit> m unauthenticated:r The following example
uses the interactive interface to set permissions 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 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 /.../dres‐
den.com/fs/walden/progress_chart -m user:mike:crwx
Note that because this entry will be filtered through the object mask
(mask_obj), which specifies only rwx permissions, the actual permis‐
sions will be rwx, not crwx. The l(ist) subcommand will show those
permissions as follows: user:mike:crwx #effective -rwx--- The follow‐
ing example uses the interactive interface to set permissions 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/sail‐
ing/staff/burati:rwx The following example uses the non-interactive
command-line interface to invoke acl_edit 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
acl_edit(1m)
