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 pathname 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 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 regardless of whether 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 subcommand, 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:

-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 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 the 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 subcommand is used primarily to facilitate copying ACLs to different cells.

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. A particular type only applies to components whose ACL Managers implement it. 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 authentication 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. Note that the unauthenticated type is not implemented in the DFS ACL Manager.

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_bytes.data where:

uuid
Identifies the type extended ACL entry. (This UUID can identify
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 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 documentation 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 /.../dresden.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 permissions will be rwx, not crwx. The l(ist) subcommand will show those permissions as follows:
```
user:mike:crwx  #effective -rwx---
```

The following 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/sailing/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
```