Title: managegroups.py - Remotely managing user groups
managegroups.py is a script for remotely managing VCL user groups. It uses
VCL's XML RPC API to provide an easy command line driven way of doing group
management.

{color:#ff0000}{*}NOTE: This script does not work with python 2.7. It
relies on the xmlrpclib module which changed from 2.6 to 2.7 in a way that
broke the script. You need to use python 2.6 for it to work.*{color}


<a name="managegroups.py-Remotelymanagingusergroups-Downloadinformation"></a>
## Download information

managegroups.py is not included in any official releases. You can download
it from our subversion repository.

[Download managegroups.py](https://svn.apache.org/repos/asf/vcl/sandbox/useful_scripts/managegroups.py)

<a name="managegroups.py-Remotelymanagingusergroups-AvailableCommands"></a>
## Available Commands

Running managegroups.py with no arguments provides help on how to use it.
It is used by specifying one of the following commands along with
parameters specific to each command.

* [#addUserGroup](#addusergroup.html)
 \- creates a new user group
* [#getUserGroupAttributes](#getusergroupattributes.html)
 \- gets information about a user group
* [#deleteUserGroup](#deleteusergroup.html)
 \- deletes a user group
* [#editUserGroup](#editusergroup.html)
 \- modifies attributes of a user group
* [#getUserGroupMembers](#getusergroupmembers.html)
 \- gets members of a user group
* [#addUsersToGroup](#adduserstogroup.html)
 \- adds users to a group
* [#removeUsersFromGroup](#removeusersfromgroup.html)
 \- removes users from a group
* [#emptyGroupMembership](#emptygroupmembership.html)
 \- removes all users currently in a group

<a name="managegroups.py-Remotelymanagingusergroups-ReturnStatus"></a>
## Return Status

These are the possible values of the return status:
* 0 - successful execution
* 1 - missing authentication information
* 2 - problem with command line parameters
* 3 - for commands that pass in a filename, problems encountered reading
the file
* 4 - no users specified to add to or remove from a group
* 5 - error encountered while performing XML RPC API call

<a name="managegroups.py-Remotelymanagingusergroups-ReturnOutput"></a>
## Return Output

The output of managegroups.py will always start with one of:
* SUCCESS: - indicates successful run of the command
* ERROR: - indicates a problem running the command
* WARNING: - indicates a no errors, but possibly unexpected results (i.e.
specifying a file when adding users to a group, but the file is empty)
There is one exception. If you specify a parameter, but omit the argument
for it, the option parser used in the script will generate an error.
However, in those cases, the return status of the command will always be 2.

<a name="managegroups.py-Remotelymanagingusergroups-Authentication"></a>
## Authentication

The script needs to know what userid/password to use and what URL to
access. These can either be defined as variables within the script (look at
the very top of the file) or specified as parameters on the command line,
before specifying which of managegroups's commands to use.

There are two ways to specify authentication information because some
people may prefer to have the password saved in the file, but not in a
command line history, while others may prefer to have the password saved in
command line history, but not in the file. Any of the authentication
options specified on the command line will override any defined in the
file.

The options for specifying authentication on the command line are
* \-u username - log in to VCL site with this user, must be in
username@affiliation form
* \-p "vclpass" - password used when logging in to VCL site, use quotes if
it contains spaces
* \-r vclurl - XMLRPC URL of VCL site (it will end with
index.php?mode=xmlrpccall - i.e. [https://vcl.ncsu.edu/scheduling/index.php?mode=xmlrpccall](https://vcl.ncsu.edu/scheduling/index.php?mode=xmlrpccall)
)

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:addUserGroup}addUserGroup"></a>
## {anchor:addUserGroup}addUserGroup

Use this command to create a new user group.

parameters:
* \-n name - name of new user group
* \-a affiliation - affiliation of new user group
* \-o owner - user that will be the owner of the group in
username@affiliation form
* \-m ManagingGroup - name of user group that can manage membership of the
new group
* \-i InitialMaxTime - (minutes) max initial time users in this group can
select for length of reservations
* \-t TotalMaxTime - (minutes) total length users in the group can have for
a reservation (including all extensions)
* \-x MaxExtendTime - (minutes) max length of time users can request as an
extension to a reservation at a time

on success, returns:
SUCCESS: User group sucessfully created


<a name="managegroups.py-Remotelymanagingusergroups-{anchor:getUserGroupAttributes}getUserGroupAttributes"></a>
## {anchor:getUserGroupAttributes}getUserGroupAttributes

Use this command to get existing information about a user group's
attributes (it does not include the current membership of the group).
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group

on success, returns:
SUCCESS: Attributes retreived
followed by:
owner: <user group owner>
managingGroup: <name of managing user group>
initialMaxTime: <max allowed initial reservation time>
totalMaxTime: <total allowed reservation time>
maxExtendTime: <make time allowed per extension>

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:deleteUserGroup}deleteUserGroup"></a>
## {anchor:deleteUserGroup}deleteUserGroup

Use this command to delete an existing user group.
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group

on success, returns:
SUCCESS: User group sucessfully deleted

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:editUserGroup}editUserGroup"></a>
## {anchor:editUserGroup}editUserGroup

Use this command to modify attributes of an existing user group (it is not
used for editing the membership of the group). You can specify any
combination of the parameters labeled as optional.
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group
* \-N NewName - (optional) new name for the user group
* \-A NewAffiliation - (optional) new affiliation for the user group
* \-O NewOwner - (optional) new owner for the user group in
username@affiliation form
* \-M NewManagingGroup - (optional) new user group that can manage
membership of the user group in group@affiliation form
* \-I NewInitialMaxTime - (optional) new max initial time users in the
group can select for length of reservations
* \-T NewTotalMaxTime - (optional) new total length users in the group can
have for a reservation (including all extensions)
* \-X NewMaxExtendTime - (optional) new max length of time users can
request as an extension to a reservation at a time

on success, returns:
SUCCESS: User group sucessfully updated

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:getUserGroupMembers}getUserGroupMembers"></a>
## {anchor:getUserGroupMembers}getUserGroupMembers

Use this command to get the current members of a group. Note that it is
possible for a group to have no members.
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group

on success, returns:
SUCCESS: Membership retrieved
followed by one user per line in username@affiliation form

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:addUsersToGroup}addUsersToGroup"></a>
## {anchor:addUsersToGroup}addUsersToGroup

Use this command to add users to an existing user group. *Note*: The users
will either need to already exist in VCL or be part of an affiliation that
is backed by LDAP so that the users can be verified.
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group

Additionally, at least one of these must be specified:
* \-l UserList - comma delimited list of users to add (no spaces) in
username@affiliation form
* \-f filename - name of file containing users to add (one user per line)
in username@affiliation form

on success, returns:
SUCCESS: Users sucessfully added to group

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:removeUsersFromGroup}removeUsersFromGroup"></a>
## {anchor:removeUsersFromGroup}removeUsersFromGroup

Use this command to remove users from an existing user group.
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group

Additionally, at least one of these must be specified:
* \-l UserList - comma delimited list of users to add (no spaces) in
username@affiliation form
* \-f filename - name of file containing users to add (one user per line)
in username@affiliation form

on success, returns:
SUCCESS: Users sucessfully removed from group

<a name="managegroups.py-Remotelymanagingusergroups-{anchor:emptyGroupMembership}emptyGroupMembership"></a>
## {anchor:emptyGroupMembership}emptyGroupMembership

Use this command to empty the membership of an existing user group.
parameters:
* \-n name - name of an existing user group
* \-a affiliation - affiliation of user group

on success, returns:
SUCCESS: Users sucessfully removed from group

<a name="managegroups.py-Remotelymanagingusergroups-Examples"></a>
## Examples

The last example includes the authentication information on the command
line. For the other examples, the authentication would have been specified
inline in the script. Authentication information was only included in one
example to make the others more readable.

Create a new user group with name FallUsers, affiliation Local, admin as
the owner, and adminUsers@Local as the managing group:

    managegroups.py addUserGroup -n FallUsers -a Local -o admin@Local -m
adminUsers@Local -i 240 -t 360 -x 30

Change the name of an existing user group named FallUsers, affiliation
Local to be SpringUsers:

    managegroups.py editUserGroup -n FallUsers -a Local -N SpringUsers

Add two users specified on the command line to a group:

    managegroups.py addUsersToGroup -n FallUsers -a Local -l
student1@Local,student2@Local

Add all users in a specified file to a group:

    managegroups.py addUsersToGroup -n FallUsers -a Local -f newusers.txt

The file would contain something like the following:

    userid1@Local
    userid2@Local
    userid3@Local

Remove all members of a group:

    managegroups.py emptyGroupMembership -n CS101 -a Local

Delete a user group:

    managegroups.py -u admin@Local -p passwordhere -r
'https://your.vcl.site/index.php?mode=xmlrpccall' deleteUserGroup -n CS101
-a Local