From: Lucas Di Pentima Date: Mon, 4 Jul 2022 16:39:46 +0000 (-0300) Subject: 18858: Expands documentation to include the new tool. X-Git-Tag: 2.5.0~124^2~2 X-Git-Url: https://git.arvados.org/arvados.git/commitdiff_plain/48495e8ed3c15aefa94561ecf7caedc6ad716514 18858: Expands documentation to include the new tool. Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima --- diff --git a/doc/_config.yml b/doc/_config.yml index 7c5e6d986e..d2bb7e7975 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -177,7 +177,7 @@ navbar: - admin/federation.html.textile.liquid - admin/merge-remote-account.html.textile.liquid - admin/migrating-providers.html.textile.liquid - - user/topics/arvados-sync-groups.html.textile.liquid + - user/topics/arvados-sync-external-sources.html.textile.liquid - admin/scoped-tokens.html.textile.liquid - admin/token-expiration-policy.html.textile.liquid - admin/user-activity.html.textile.liquid diff --git a/doc/user/topics/arvados-sync-groups.html.textile.liquid b/doc/user/topics/arvados-sync-external-sources.html.textile.liquid similarity index 51% rename from doc/user/topics/arvados-sync-groups.html.textile.liquid rename to doc/user/topics/arvados-sync-external-sources.html.textile.liquid index 1f7eede4bb..0ec0098f05 100644 --- a/doc/user/topics/arvados-sync-groups.html.textile.liquid +++ b/doc/user/topics/arvados-sync-external-sources.html.textile.liquid @@ -1,7 +1,7 @@ --- layout: default navsection: admin -title: "Synchronizing external groups" +title: "Synchronizing from external sources" ... {% comment %} Copyright (C) The Arvados Authors. All rights reserved. @@ -9,7 +9,51 @@ Copyright (C) The Arvados Authors. All rights reserved. SPDX-License-Identifier: CC-BY-SA-3.0 {% endcomment %} -The @arvados-sync-groups@ tool allows to synchronize groups in Arvados from an external source. +The @arvados-sync-users@ and @arvados-sync-groups@ tools allow to manage Arvados users & groups from external sources. + +These tools are designed to be run periodically reading a file created by a remote auth system (ie: LDAP) dump script, applying what's included on the file as the source of truth. + +bq. NOTE: Both tools need to perform several administrative tasks on Arvados, so must be run using a superuser token via @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ environment variables or @~/.config/arvados/settings.conf@ file. + +h1. Using arvados-sync-users + +This tool reads a CSV (comma-separated values) file having information about user accounts and their expected state on Arvados. + +Every line on the file should have 5 fields: + +# A user identifier: it could be an email address (default) or a username. +# The user's first name. +# The user's last name. +# The intended user's active state. +# The intended user's admin state: will always be read as @false@ when @active=false@. + +The last 2 fields should be represented as @true@/@false@, @yes@/@no@, or @1@/@0@ values. + +h2. Options + +The following command line options are supported: + +table(table table-bordered table-condensed). +|_. Option |_. Description | +|==--help==|This list of options| +|==--case-insensitive==|Uses case-insensitive username matching| +|==--deactivate-unlisted==|Deactivate users that aren't listed on the input file. (Current & system users won't be affected)| +|==--user-id==|Identifier to use in looking up user. One of 'email' or 'username' (Default: 'email')| +|==--verbose==|Log informational messages| +|==--version==|Print version and exit| + +The tool will create users when needed, and update those existing records to match the desired state described by the fields on the CSV file. +System users like the root and anonymous are unaffected by this tool. +In the case of a @LoginCluster@ federation, this tool should be run on the cluster that manages the user accounts, and will fail otherwise. + +h2. Example + +To sync users using the username to identify every account, reading from some @external_users.csv@ file and deactivating existing users that aren't included in it, the command should be called as follows: + + +
~$ arvados-sync-users --deactivate-unlisted --user-id username /path/to/external_users.csv 
+
+ h1. Using arvados-sync-groups @@ -21,11 +65,6 @@ Users can be identified by their email address or username: the tool will check Permission level can be one of the following: @can_read@, @can_write@ or @can_manage@, giving the group member read, read/write or managing privileges on the group. For backwards compatibility purposes, if any record omits the third (permission) field, it will default to @can_write@ permission. You can read more about permissions on the "group management admin guide":{{ site.baseurl }}/admin/group-management.html. -This tool is designed to be run periodically reading a file created by a remote auth system (ie: LDAP) dump script, applying what's included on the file as the source of truth. - - -bq. NOTE: @arvados-sync-groups@ needs to perform several administrative tasks on Arvados, so must be run using a superuser token - h2. Options The following command line options are supported: