varGroup.sh (Access Management Utility)
How to use the varGroup.sh Access Management Utility
Contents
About
varGroup.sh is a command line utility for managing groups in the Access Manager Database. The Access Manager Database contains information about groups that is used primarily to support authorization (checking who is allowed to access what).
Groups in the access manager are typically either:
- The students and faculty of a course, e.g., Music 101.
- People with the same job function, e.g., Catalogers.
The Access Manager database contains the following information about groups:
- descriptive information, for example, the instructor of a course
- a list of the members (users) of the group
- an optional list of reserves for the group (e.g., a list of digitized audio recordings)
A configuration file accessPolicy.xml is used to describe what groups have what permissions. Generally it would be set up to allow all the members of a group to access the reserves of the group.
varGroup.sh Command Syntax
The syntax for varGroup.sh is as follows:
varGroup.sh delete [-f] <group_name> | dump [-f] [-g <group_name>] <file_name> | -dir <dir_name> | list | load <file_name1> [<file_name2> ...]
The commands are described below:
- delete - This command deletes a group from the database. It will prompt the user to confirm that the group should be deleted unless the -f ("force") option is specified.
- dump - This command is used to dump groups to files in a tagged format that is the same format used by the load command. This command can be used for browsing and backing up the group information. The user will be prompted to confirm if an existing file should be overwritten, unless the -f ("force") option is specified. If the -g option is used to specify a group, only that group will be dumped. If the -g option is not used, all groups will be dumped. If a file name is specified, all groups that are dumped will be stored in that file. If a directory is specified, each group that is dumped will be stored in a separate file where the name of the file matches the name of the group (/'s in the group name are replaced with _'s in the file name).
- list - This command lists the group names in the Access Manager.
- load - This command is used to load group information from files that use a tagged data format. A file can contain multiple groups, and multiple files can be specified. If a group in the file doesn't exist when it is loaded, it will be created. If it does exist, its information will be replaced by the information in the file. So, for example, if a group in the database has 3 members, and a data file for that group is loaded that has one member, after the file is loaded the group will only have the one member from the file. If a group is updated and pre-existing "locked" members are not in the update group member list, the locked members will still exist for the group (preservation of locked members not implemented in 5.0.5 or earlier versions).
In addition, a -debug flag can optionally be used before each command, e.g., varGroup.sh -debug list. This feature will cause the underlying script used for executing Java programs (v2run.sh) to print some debugging information, and cause logging to go to the console.
varGroup.sh Examples
Example |
Description |
---|---|
|
Lists all the group names |
|
Loads the group data file VariationsGroups.txt into the |
|
Deletes the group MUSIC_101_SPRING_2007 (and prompts to confirm that |
|
Deletes the group MUSIC_101_SPRING_2007 (without prompting to confirm |
|
Dumps all the groups in the Access Manager database |
|
Dumps (only) the group MUSIC_101 to file |
|
Dumps all the groups to the directory variations_groups |
Group Data File Syntax
GroupName: <group-name> [GroupType: course | other ] [ClassNumber: <class-number>] [ClassTitle: <class-title>] [Instructor: <instructor>] [SectionNumber: <section-number>] [Department: <department>] [DepartmentCode: <departmentCode>] [Campus: <campus>] [Semester: <semester>] [Year: <year>] [ExpirationDate: <expiration-date> | never ] [Members: <user-name> [,<owner_flag> [,<locked_flag> [,<comments>]]] | <ip-address> ... EndMembers:] [ ReservesValidFrom: <date> ReservesValidUntil: <date> [ReservesCreatedBy: <user>] [Reserves: <container-id-1> <container-id-2> ... EndReserves:] ]
Notes:
- For each group in a file, a group name must be specified. The other fields are optional, however, if any reserve list information is specified, it must contain a valid from and valid until dates.
- If a group name is chosen that is not a legal file name, then the dump command will not work when a directory is specified. Slashes "/" in group names are replaced with underscores "_".
- The colons are considered part of the tag, and there must be no space between the last letter of the tag and the colon.
- For tags that can only have a single value, the value must be on the same line as the tag.
- For tags that can have multiple values, the values must be on different lines than the tags (between the start tag and end tag).
- Dates are in mm/dd/yyyy format, for example, 12/31/2007.
- The default value for group expiration date is "never" (which is the latest date allowed by the database).
- The default value for group type is "course", and the only allowed values are "course" and "other".
- The username specified in the Members list needs to be a valid RFC822 Name (e.g. user@example.edu). The username can optionally be followed by three other comma-separated attributes as follows (in order):
- flag indicating whether the member has update rights for that group (Y or N)
- flag indicating whether the member is "locked"; a locked user will not be removed by a subsequent load operation even if that member is not in the file being loaded (not implemented in 5.0.5 or earlier versions)
- a comment, perhaps describing a special reason the user is in the group, or giving the user's name, etc.
username examples
me@myuni.edu
me@myuni.edu,N,N,My name and or some kind of comment
Group Data File Tag Information
Tag |
Required |
Number |
Default Value |
Maximum Value Length |
---|---|---|---|---|
GroupName: |
Yes |
1 |
- |
128 |
GroupType: |
No |
1 |
"course" |
6 (must be either |
ClassNumber: |
No |
1 |
null |
5 |
ClassTitle: |
No |
1 |
null |
64 |
Instructor |
No |
1 |
null |
128 |
SectionNumber: |
No |
1 |
null |
32 |
Department: |
No |
1 |
null |
8 |
DepartmentCode: |
No |
1 |
null |
10 |
Campus: |
No |
1 |
null |
2 |
Semester: |
No |
1 |
null |
15 |
Year |
No |
1 |
null |
4-byte integer |
ExpirationDate: |
No |
1 |
"never" |
max. date of 12/31/2037 |
Members:/EndMembers: |
No |
multiple |
- |
128 |
Reserves:/EndReserves: |
No |
multiple |
- |
128 |
ReservesValidFrom: |
If any reserve tags used |
1 |
- |
max. date of 12/31/2037 |
ReservesValidUntil: |
If any reserve tags used |
1 |
- |
max. date of 12/31/2037 |
ReservesCreatedBy: |
No |
1 |
null |
128 |
Group Data File Example
# This is the catalogers group, its name must have the format <institution/library>/Group/Catalogers # Users in this group typically are allowed to access all media files and modify metadata GroupName: IU/Group/Catalogers GroupType: other ExpirationDate: never Members: mullen2@IU.EDU ys3@IU.EDU cjcolvar@IU.EDU, N, Y, Not group owner and not deleted by updates. mnotess@IU.EDU, Y, Y, The group owner and not deleted by updates. EndMembers: # This is the digitizers group, its name must have the format <institution/library>/Group/Digitizers # Users in this group typically are allowed to access all media files and modify metadata GroupName: IU/Group/Digitizers GroupType: other ExpirationDate: never Members: digitizer@IU.EDU audio@IU.EDU score@IU.EDU EndMembers: # This is an example of a course group. Typically, users in a course # cannot update metadata, and can only access media files that are # part of the course's reserve list. GroupName: MUSIC_101_Summer_2005 GroupType: course ClassNumber: Instructor: Smith, Andrew John SectionNumber: 20133 Department: MUS DepartmentCode: Campus: BL Semester: Summer Year: 2005 ExpirationDate: 8/31/2005 Members: joestudent@IU.EDU janestudent@IU.EDU liustudent@IU.EDU josestudent@IU.EDU zzstudent@IU.EDU ajsmith@IU.EDU, Y, Y, Owner and not deleted by updates. busyassistant@IU.EDU, N, Y, Assistant - can not make changes but not removed by updates. EndMembers: ReservesValidFrom: 5/1/2005 ReservesValidUntil: 8/31/2005 Reserves: IU/Container/114366 IU/Container/144603 IU/Container/125465 IU/Container/144648 IU/Container/144580 IU/Container/114379 EndReserves: