19961: Clarify preemptionNotice significance.

[arvados.git] / doc / api / permission-model.html.textile.liquid

diff --git a/doc/api/permission-model.html.textile.liquid b/doc/api/permission-model.html.textile.liquid
index 4e04699fcd71bec937f989657e535f321819f759..2d589e2709e9b2fdd66e1fade52c747cc8752340 100644 (file)
--- a/doc/api/permission-model.html.textile.liquid
+++ b/doc/api/permission-model.html.textile.liquid
@@ -16,13 +16,17 @@ There are four levels of permission: *none*, *can_read*, *can_write*, and *can_m
 ** the object is not included in any list query response.
 ** direct queries of the object by uuid return 404 Not Found.
 ** Link objects require valid identifiers in @head_uuid@ and @tail_uuid@, so an attempt to create a Link that references an unreadable object will return an error indicating the object is not found.
 ** the object is not included in any list query response.
 ** direct queries of the object by uuid return 404 Not Found.
 ** Link objects require valid identifiers in @head_uuid@ and @tail_uuid@, so an attempt to create a Link that references an unreadable object will return an error indicating the object is not found.

-* *can_read* grants read-only access to the record.  Attempting to update or delete the record returns an error.  *can_read* does not allow a reader to see any permission grants on the object except the object's owner_uuid and the reader's own permissions.
-* *can_write* permits changes to the record (but not permission links).  *can_write* permits the user to delete the object.  *can_write* also implies *can_read*.
-* *can_manage* permits the user to read, create, update and delete permission links whose @head_uuid@ is this object's @uuid@.  *can_manage* also implies *can_write* and *can_read*.
+* *can_read* grants read-only access to the record.  Attempting to update or delete the record returns an error.
+** *can_read* does not allow a reader to see any permission grants on the object except the object's owner_uuid and the reader's own permissions.
+* *can_write* permits changes to the record, including changing ownership and deleting the object.
+** *can_write* cannot read, create, update or delete permission links associated with the object.
+** *can_write* also implies *can_read*.
+* *can_manage* permits the user to read, create, update and delete permission links whose @head_uuid@ is this object's @uuid@.
+** *can_manage* also implies *can_write* and *can_read*.

 
 h2. Ownership
 
 
 h2. Ownership
 

-All Arvados objects have an @owner_uuid@ field. Valid uuid types for @owner_uuid@ are "User" and "Group".  For Group, the @group_class@ must be a "project".
+All Arvados objects have an @owner_uuid@ field. Valid uuid types for @owner_uuid@ are "User" and "Group".  In the case of a Group, the @group_class@ must be "project".

 
 The User or Group specified by @owner_uuid@ has *can_manage* permission on the object.  This permission is one way: an object that is owned does not get any special permissions on the User or Group that owns it.
 
 
 The User or Group specified by @owner_uuid@ has *can_manage* permission on the object.  This permission is one way: an object that is owned does not get any special permissions on the User or Group that owns it.
 


@@ -33,37 +37,48 @@ h2(#links). Permission links
 A permission link is a link object with:
 
 * @owner_uuid@ of the system user.
 A permission link is a link object with:
 
 * @owner_uuid@ of the system user.

-* @link_class@ *permission*
-* @name@ one of *can_read*, *can_write* or *can_manage*
+* @link_class@ "permission"
+* @name@ one of *can_read*, *can_write*, *can_manage* or *can_login*

 * @head_uuid@ of some Arvados object
 * @head_uuid@ of some Arvados object

-* @tail_uuid@ of a User or Group
+* @tail_uuid@ of a User or Group.  For Group, the @group_class@ must be a "role".

 
 This grants the permission in @name@ for @tail_uuid@ accessing @head_uuid@.
 
 
 This grants the permission in @name@ for @tail_uuid@ accessing @head_uuid@.
 

-If a User has *can_manage* permission on some object, the user has the ability to read, create, update and delete permission links with @head_uuid@ of the managed object (i.e. permission grants on the object).
+If a User has *can_manage* permission on some object, the user has the ability to read, create, update and delete permission links with @head_uuid@ of the managed object.  In other words, the user has the ability to modify the permission grants on the object.
+
+The *can_login* @name@ is only meaningful on a permission link with with @tail_uuid@ a user UUID and @head_uuid@ a Virtual Machine UUID. A permission link of this type gives the user UUID permission to log into the Virtual Machine UUID. The username for the VM is specified in the @properties@ field. Group membership can be specified that way as well, optionally. See the "VM login section on the 'User management at the CLI' page":{{ site.baseurl }}/admin/user-management-cli.html#vm-login for an example.

 
 h3. Transitive permissions
 
 
 h3. Transitive permissions
 

-Permissions can be obtained indirectly by following multiple permission links or nested ownership.
+Permissions can be obtained indirectly through nested ownership (*can_manage*) or by following multiple permission links.

 
 

-* If a User X *can_read* Group A, and Group A *can_read* Object B, then User X *can_read* Object B.
+* If a User X owns project A, and project A owns project B, then User X *can_manage* project B.
+* If a User X *can_read* role A, and role A *can_read* Object B, then User X *can_read* Object B.

 * Permissions are narrowed to the least powerful permission on the path.
 * Permissions are narrowed to the least powerful permission on the path.

-** If User X *can_write* Group A, and Group A *can_read* Object B, then User X *can_read* Object B.
-** If User X *can_read* Group A, and Group A *can_write* Object B, then User X *can_read* Object B.
+** If User X *can_write* role A, and role A *can_read* Object B, then User X *can_read* Object B.
+** If User X *can_read* role A, and role A *can_write* Object B, then User X *can_read* Object B.

 
 h2. Projects and Roles
 
 A "project" is a subtype of Group that is displayed as a "Project" in Workbench, and as a directory by @arv-mount@.
 * A project can own things (appear in @owner_uuid@)
 * A project can be owned by a user or another project.
 
 h2. Projects and Roles
 
 A "project" is a subtype of Group that is displayed as a "Project" in Workbench, and as a directory by @arv-mount@.
 * A project can own things (appear in @owner_uuid@)
 * A project can be owned by a user or another project.

-* The name of a project is unique only among projects with the same owner_uuid.
-* Projects can be the target (@head_uuid@) of a permission link, but not the origin (@tail_uuid@).  Putting a project in a @tail_uuid@ field is an error.
+* The name of a project is unique only among projects and filters with the same owner_uuid.
+* Projects can be targets (@head_uuid@) of permission links, but not origins (@tail_uuid@).  Putting a project in a @tail_uuid@ field is an error.
+
+A "filter" is a subtype of Group that is displayed as a "Project" in Workbench, and as a directory by @arv-mount@. See "the groups API documentation":{{ site.baseurl }}/api/methods/groups.html for more information.
+* A filter group cannot own things (cannot appear in @owner_uuid@).  Putting a filter group in an @owner_uuid@ field is an error.
+* A filter group can be owned by a user or a project.
+* The name of a filter is unique only among projects and filters with the same owner_uuid.
+* Filters can be targets (@head_uuid@) of permission links, but not origins (@tail_uuid@).  Putting a filter in a @tail_uuid@ field is an error.

 
 A "role" is a subtype of Group that is treated in Workbench as a group of users who have permissions in common (typically an organizational group).
 * A role cannot own things (cannot appear in @owner_uuid@).  Putting a role in an @owner_uuid@ field is an error.
 * All roles are owned by the system user.
 
 A "role" is a subtype of Group that is treated in Workbench as a group of users who have permissions in common (typically an organizational group).
 * A role cannot own things (cannot appear in @owner_uuid@).  Putting a role in an @owner_uuid@ field is an error.
 * All roles are owned by the system user.

-* The name of a role is unique across an instance.
-* A role can be both the target (head_uuid) and origin (tail_uuid) of a permission link.
+* The name of a role is unique across a single Arvados cluster.
+* Roles can be both targets (@head_uuid@) and origins (@tail_uuid@) of permission links.
+* By default, all roles are visible to all active users. However, if the configuration entry @Users.RoleGroupsVisibleToAll@ is @false@, visibility is determined by normal permission rules, _i.e._, a role is only visible to users who have that role, and to admins.
+* By default, any user can create a new role. However, if the configuration entry @Users.CanCreateRoleGroups@ is @false@, only admins can create roles.

 
 h3. Access through Roles
 
 
 h3. Access through Roles
 


@@ -79,15 +94,17 @@ h2. Special cases
 
 Log table objects are additionally readable based on whether the User has *can_read* permission on @object_uuid@ (User can access log history about objects it can read).  To retain the integrity of the log, the log table denies all update or delete operations.
 
 
 Log table objects are additionally readable based on whether the User has *can_read* permission on @object_uuid@ (User can access log history about objects it can read).  To retain the integrity of the log, the log table denies all update or delete operations.
 

-Permission links where @tail_uuid@ is a User allow @can_read@ on the link record by that user.  (User can discover her own permission grants.)
+Permission links where @tail_uuid@ is a User allow *can_read* on the link record by that user (User can discover her own permission grants.)

 
 At least *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).
 
 A user can only read a container record if the user has read permission to a container_request with that container_uuid.
 
 *can_read* and *can_write* access on a user grants access to the user record, but not anything owned by the user.
 
 At least *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).
 
 A user can only read a container record if the user has read permission to a container_request with that container_uuid.
 
 *can_read* and *can_write* access on a user grants access to the user record, but not anything owned by the user.

-*can_manage* access to a user grants can_manage access to the user, _and everything owned by that user_.
-If a user A *can_read* role R, and role R *can_manage* user B, then user A *can_read* user B _and everything owned by that user_.
+*can_manage* access to a user grants can_manage access to the user, _and everything owned by that user_ .
+If a user A *can_read* role R, and role R *can_manage* user B, then user A *can_read* user B _and everything owned by that user_ .
+
+Modifying a role group requires *can_manage* permission (by contrast, *can_write* is sufficient to modify project groups and other object types).

 
 h2(#system). System user and group
 
 
 h2(#system). System user and group
 


@@ -95,7 +112,9 @@ A privileged user account exists for the use by internal Arvados components.  Th
 
 h2. Anoymous user and group
 
 
 h2. Anoymous user and group
 

-An Arvados site may be configured to allow users to browse resources without requiring a login.  In this case, permissions for non-logged-in users are associated with the "anonymous" user.  To make objects visible to the public, they can be shared with the "anonymous" role.  The anonymous user uuid is @{siteprefix}-tpzed-anonymouspublic@.  The anonymous group uuid is @{siteprefix}-j7d0g-anonymouspublic@.
+An Arvados site may be configured to allow users to browse resources without requiring a login.  In this case, permissions for non-logged-in users are associated with the "anonymous" user.  To make objects visible to anyone (both logged-in and non-logged-in users), they can be shared with the "anonymous" role.  Note that objects shared with the "anonymous" user will only be visible to non-logged-in users!
+
+The anonymous user uuid is @{siteprefix}-tpzed-anonymouspublic@.  The anonymous group uuid is @{siteprefix}-j7d0g-anonymouspublic@.

 
 h2. Example
 
 
 h2. Example