15577: Overhaul user and group management documentation

[arvados.git] / doc / admin / group-management.html.textile.liquid

diff --git a/doc/admin/group-management.html.textile.liquid b/doc/admin/group-management.html.textile.liquid
new file mode 100644 (file)
index 0000000..127b914
--- /dev/null
+++ b/doc/admin/group-management.html.textile.liquid
@@ -0,0 +1,104 @@
+---
+layout: default
+navsection: admin
+title: Group management
+...
+
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+This page describes how to manage groups at the command line.  You should be familiar with the "permission system":{{site.baseurl}}/api/permission-model.html .
+
+h2. Create a group
+
+User groups are entries in the "groups" table with @"group_class": "role"@.
+
+<pre>
+arv group create --group '{"name": "My new group", "group_class": "role"}'
+</pre>
+
+h2. Add a user to a group
+
+There are two separate permissions associated with group membership.  The first link grants the user @can_manage@ permission to manage things that the group can manage.  The second link grants permission for other users of the group to see that this user is part of the group.
+
+<pre>
+arv link create --link '{
+  "link_class": "permission",
+  "name": "can_manage",
+  "tail_uuid": "the_user_uuid",
+  "head_uuid": "the_group_uuid"}'
+
+arv link create --link '{
+  "link_class": "permission",
+  "name": "can_read",
+  "tail_uuid": "the_group_uuid",
+  "head_uuid": "the_user_uuid"}'
+</pre>
+
+A user can also be given read-only access to a group.  In that case, the first link should be created with @can_read@ instead of @can_manage@.
+
+h2. List groups
+
+<pre>
+arv group list --filters '[["group_class", "=", "role"]]'
+</pre>
+
+h2. List members of a group
+
+Use the command "jq":https://stedolan.github.io/jq/ to extract the tail_uuid of each permission link which has the user uuid.
+
+<pre>
+arv link list --filters '[["link_class", "=", "permission"],
+  ["head_uuid", "=", "the_group_uuid"]]' | jq .items[].tail_uuid
+</pre>
+
+h2. Share a project with a group
+
+This will give all members of the group @can_manage@ access.
+
+<pre>
+arv link create --link '{
+  "link_class": "permission",
+  "name": "can_manage",
+  "tail_uuid": "the_group_uuid",
+  "head_uuid": "the_project_uuid"}'
+</pre>
+
+A project can also be shared read-only.  In that case, the first link should be created with @can_read@ instead of @can_manage@.
+
+h2. List things shared with the group
+
+Use the command "jq":https://stedolan.github.io/jq/ to extract the head_uuid of each permission link which has the object uuid.
+
+<pre>
+arv link list --filters '[["link_class", "=", "permission"],
+  ["tail_uuid", "=", "the_group_uuid"]]' | jq .items[].head_uuid
+</pre>
+
+h2. Stop sharing a project with a group
+
+This will remove access for members of the group.
+
+The first step is to find the permission link objects.  The second step is to delete them.
+
+<pre>
+arv --format=uuid link list --filters '[["link_class", "=", "permission"],
+  ["tail_uuid", "=", "the_group_uuid"], ["head_uuid", "=", "the_project_uuid"]]'
+
+arv link delete --uuid each_link_uuid
+</pre>
+
+h2. Remove user from a group
+
+The first step is to find the permission link objects.  The second step is to delete them.
+
+<pre>
+arv --format=uuid link list --filters '[["link_class", "=", "permission"],
+  ["tail_uuid", "in", ["the_user_uuid", "the_group_uuid"]],
+  ["head_uuid", "in", ["the_user_uuid", "the_group_uuid"]]'
+
+arv link delete --uuid each_link_uuid
+</pre>