varGroup.sh (Access Management Utility)

How to use the varGroup.sh Access Management Utility

Contents

• About
• varGroup.sh Command Syntax
• varGroup.sh Examples
• Group Data File Example

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

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

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: