Page History

...

export GSH_JVMARGS="-Dlibrary.jansi.path=/some/other/temp/path/with/exec"

Supported Commands

Grouper API methods

Any Grouper API method can be directly invoked just by referencing it, inclusive of the class in which it is defined. Methods return a java object which can be stored in a variable. For example, the following gsh session determines all of the groups to which a given subject belongs:

Environment variables that affect GSH startup:

• GROUPER_HOME: if set to a valid Grouper directory, it will use this directory. Otherwise, it will determine it based on the path to gsh
• GROUPER_CONF: if set to a valid conf directory, it will use this directory. Otherwise it will determine it based on GROUPER_HOME
• MEM_START: Override the default -Xms Java parameter (initial Java heap size)
• MEM_MAX: Override the default -Xmx Java parameter (maximum Java heap size)
• CLASSPATH: Will prepend to the constructed classpath
• GSH_JVMARGS: Additional arguments to pass to Java
• GSH_CYGWIN: (since 2.4.0 api patch 3) if set and not blank, the script will convert paths and the classpath to Windows-style, for use with Windows Java under Cygwin
• GSH_QUIET: (since 2.4.0 api patch 3) if set and not blank, will not output preliminary diagnostic information before starting Java, other than errors

Supported Commands

Grouper API methods

Any Grouper API method can be directly invoked just by referencing it, inclusive of the class in which it is defined. Methods return a java object which can be stored in a variable. For example, the following gsh session determines all of the groups to which a given subject belongs:

gsh 0% GrouperSession.startRootSession();
gsh 0% subj = findSubject("SD00125")
subject: id='SD00125' type='person' source='kitn-person' name='Barton, Tom'
gsh 1% sess = GrouperSession.start(subj)
edu.internet2.middleware.grouper.GrouperSession

gsh 0% GrouperSession.startRootSession();
gsh 0% subj = findSubject("SD00125")
subject: id='SD00125' type='person' source='kitn-person' name='Barton, Tom'
gsh 1% sess = GrouperSession.start(subj)
edu.internet2.middleware.grouper.GrouperSession: 29c40f97-9fb0-4e45-88bc-a14877a6c9b5,'SD00125','person'
gsh 2% member = MemberFinder.findBySubject(sess, subj)
member: id='SD00125' type='person' source='kitn-person' uuid='d0fa765e-1439-4701-89b1-9b08b4ce9daa'
gsh 3% member.getGroups()
group: name='etc:sysadmingroup' displayName='Grouper Administration:SysAdmin Group' uuid='6f77fb36-b466-481a-84a7-7af609f1ad09'

...

String principal = "someApp";
String email = null;

GrouperSession grouperSession = GrouperSession.startRootSession();


addSubject(principal, "application", principal);
HibernateSession.bySqlStatic().executeSql("insert into subjectattribute (subjectId, name, value, searchValue) values (?, ?, ?, ?)", GrouperUtil.toListObject(new Object[]{principal, "description", principal, principal.toLowerCase()}));
if (email != null){ HibernateSession.bySqlStatic().executeSql("insert into subjectattribute (subjectId, name, value, searchValue) values (?, ?, ?, ?)", GrouperUtil.toListObject(new Object[]{principal, "email", email, email.toLowerCase()}));}
HibernateSession.bySqlStatic().executeSql("insert into subjectattribute (subjectId, name, value, searchValue) values (?, ?, ?, ?)", GrouperUtil.toListObject(new Object[]{principal, "loginid", principal, principal}));
HibernateSession.bySqlStatic().executeSql("insert into subjectattribute (subjectId, name, value, searchValue) values (?, ?, ?, ?)", GrouperUtil.toListObject(new Object[]{principal, "name", principal, principal}));

String principal = "someApp";
String email = null;

GrouperSession grouperSession = GrouperSession.startRootSession();

HibernateSession.bySqlStatic().executeSql("delete from subjectattribute where subjectId = ?", GrouperUtil.toListObject(new Object[]{principal}));
HibernateSession.bySqlStatic().executeSql("delete from subject where subjectId = ?", GrouperUtil.toListObject(new Object[]{principal}));
HibernateSession.bySqlStatic().executeSql("delete from subject where subjectId = ?", GrouperUtil.toListObject(new Object[]{principal}));

System

...

Command

...

Description

...

sqlRun(file)

...

Execute each line of a sql file, just like ant would.  This can run the files generated by registryInitializeSchema()

...

sqlRun(string)

...

Executes a single sql statement

...

:exit

...

Terminate shell

...

help()

...

Display usage information

...

p(command)

...

Pretty print results.

...

:quit

...

Terminate shell

...

version()

...

Return version information

Unresolvable subject deletion utility (USDU)

usdu finds which memberships are with subjects which cannot be found in a subject source, and prints them on the screen
- if the usdu.DELETE option is passed in, then the memberships will be deleted
- a grouper session must be open when this command is run.

 For more information, see Unresolvable Subject Deletion Utility (USDU)

...

Command

...

Description

...

GrouperSession.startRootSession();
 usdu()

...

Sample call to find all unresolvable subjects in the registry and print details to the screen

...

usdu(usdu.DELETE)

...

Pass in that you want to delete memberships in the usdu call

...

usduBySource("schoolperson")

...

Work only in a specific subject source, pass in the sourceId from sources.xml

...

usduBySource("schoolperson", usdu.DELETE)

...

Work in a specific source and delete membeships

...

subject=SubjectFinder.findById("GrouperSystem")
 session=GrouperSession.start(subject)"
 memberSubject=SubjectFinder.findById("1234567")
 member=MemberFinder.findBySubject(session,memberSubject)
 usduByMember(member)

...

Work only with a specific member

...

usduByMember(member, usdu.DELETE)

...

usdu by member, and delete memberships

Find bad memberships

 This command will find membership records in the database which are invalid, and prints them on the screen, along with a GSH script that will fix the memberships.

 For more information, see Bad Membership Finder Utility

...

Command

...

Description

...

findBadMemberships()

...

complete findBadMemberships run

XML legacy

XML export legacy

There is an object: XmlExport which has various chaining methods, which should be ended with an exportTo() method.  You can export to file or string.

For more information, see Import-Export

...

Command

...

Description

...

XmlExport xmlExport.stem(stem)

...

The stem to export. Defaults to the ROOT stem.

...

XmlExport xmlExport.group(group)

...

The group to export

...

XmlExport xmlExport.relative(boolean)

...

If group or stem specified do not export parent Stems.

...

XmlExport xmlExport.includeParent(boolean)

...

If group specified, export from the parent stem

...

XmlExport xmlExport.childrenOnly(boolean)

...

If stem specified, export child stems and groups only - not the specified stem

...

XmlExport xmlExport.userProperties(file)

...

Properties file for extra settings for import

...

XmlExport xmlExport.grouperSession(grouperSession)

...

Operate within a certain grouper session (defaults to root session)

...

void xmlExport.exportToFile(file)

...

Export to an XML file

...

void xmlExport.exportToString(string)

...

Export to an XML string

 ?", GrouperUtil.toListObject(new Object[]{principal}));

System

Unresolvable subject deletion utility (USDU)

usdu finds which memberships are with subjects which cannot be found in a subject source, and prints them on the screen
- if the usdu.DELETE option is passed in, then the memberships will be deleted
- a grouper session must be open when this command is run.

 For more information, see Unresolvable Subject Deletion Utility (USDU)

Find bad memberships

 This command will find membership records in the database which are invalid, and prints them on the screen, along with a GSH script that will fix the memberships.

 For more information, see Bad Membership Finder Utility

XML legacy

XML export legacy

There is an object: XmlExport which has various chaining methods, which should be ended with an exportTo() method.  You can export to file or string.

For more information, see Import-Export

 Examples:

gsh 1% new XmlExport().exportToFile(new File("c:/temp/export.xml"))

gsh 1% grouperSession = GrouperSession.start(SubjectFinder.findById("mchyzer"));
gsh 2% stem = StemFinder.findByName(grouperSession, "aStem");
gsh 3% new XmlExport().stem(stem).relative(true).userProperties(new File("C:/temp/some.props")).grouperSession(grouperSession).exportToFile(new File("c:/temp/export.xml"));

 -or- (without chaining)

gsh 3% xmlExport = new XmlExport();
gsh 4% xmlExport.stem(stem);
gsh 5% xmlExport.grouperSession(grouperSession);
gsh 6% xmlExport.exportToFile(new File("c:/temp/export.xml"))

XML import legacy

There is an object: XmlImport which has various chaining methods, which should be ended with an importFrom() method.  You can import from file, string, or url.

For more information, see Import-Export

 Examples:

gsh 1% new XmlImport().importFromFile

 Examples:

gsh 1% new XmlExport().exportToFile(new File("c:/temp/export.xml"))

gsh 1% grouperSession = GrouperSession.start(SubjectFinder.findById("mchyzer"));
gsh 2% stem = StemFinder.findByName(grouperSession, "aStem");
gsh 3% new XmlExport().stem(stem).relative(true).userProperties(new File("C:/temp/some.props")).grouperSession(grouperSession).exportToFile(new File("c:/temp/export.xml"));

...

gsh 3%1% xmlExportgrouperSession = new XmlExport()GrouperSession.start(SubjectFinder.findById("mchyzer"));
gsh 4%2% xmlExport.stem(stem);
gsh 5%= xmlExportStemFinder.grouperSessionfindByName(grouperSession, "aStem");
gsh 6% xmlExport.exportToFile(new File("c:/temp/export.xml"))

XML import legacy

There is an object: XmlImport which has various chaining methods, which should be ended with an importFrom() method.  You can import from file, string, or url.

For more information, see Import-Export

...

Command

...

Description

...

3% new XmlImport().stem(stem

...

The Stem into which data will be imported. Defaults to the ROOT stem.

...

XmlImport xmlImport.updateList(boolean)

...

XML contains a flat list of Stems or Groups which may be updated.
Missing Stems and Groups are not created.

...

XmlImport xmlImport.userProperties(file)

...

Properties file for extra settings for import

...

XmlImport xmlImport.grouperSession(grouperSession)

...

Operate within a certain grouper session (defaults to root session)

...

XmlImport xmlImport.ignoreInternal(boolean)

...

Ignore internal attributes, including group and stem uuids.

...

void xmlImport.importFromFile(file)

...

Import from an XML file

...

void xmlImport.importFromString(string)

...

Import from an XML string

...

void xmlImport.importFromUrl(url)

...

Import XML from a URL

 Examples:

gsh 1% new XmlImport().importFromFile(new File("c:/temp/export.xml"))

gsh 1% grouperSession = GrouperSession.start(SubjectFinder.findById("mchyzer"));
gsh 2% stem = StemFinder.findByName(grouperSession, "aStem");
gsh 3% new XmlImport().stem(stem).updateList(true).userProperties(new File("C:/temp/some.props")).grouperSession(grouperSession).importFromUrl(new URL("http://whatever.xml"));

 -or- (without chaining)

gsh 3% xmlImport = new XmlImport();
gsh 4% xmlImport.stem(stem);
gsh 5% xmlImport.grouperSession(grouperSession);
gsh 6% xmlImport.importFromFile(new File("c:/temp/export.xml"))

Transactions

Transactions facilitate all commands succeeding or failing together, and perhaps some level of repeatable reads of the DB (depending on the DB).  If there is an open transaction and an exception is thrown in a command, GSH will shut down so that subsequent commands will not execute outside of a transaction.

Loader

Above, it describes how you can kick off the loader in daemon mode.  You can also execute one job with:

...

Command

...

Description

...

grouperSession = GrouperSession.startRootSession();
loaderGroup = GroupFinder.findByName(grouperSession, "stem:group");
loaderRunOneJob(loaderGroup);

...

Kick off the loader for one group (configured by group attributes)

...

loaderRunOneJob("MAINTENANCE_cleanLogs");

...

Kick off the loader by job name

...

loaderRunOneJob("CHANGE_LOG_changeLogTempToChangeLog");

...

Move change log entries from the temp table to the real table

...

loaderRunOneJob("CHANGE_LOG_consumer_grouperRules");
loaderRunOneJob("MAINTENANCE__rules");

...

Run the Grouper Rules daemon (the changelog or full version)

...

loaderRunOneJob("CHANGE_LOG_consumer_test");

...

Run a change log consumer

).updateList(true).userProperties(new File("C:/temp/some.props")).grouperSession(grouperSession).importFromUrl(new URL("http://whatever.xml"));

 -or- (without chaining)

gsh 3% xmlImport = new XmlImport();
gsh 4% xmlImport.stem(stem);
gsh 5% xmlImport.grouperSession(grouperSession);
gsh 6% xmlImport.importFromFile(new File("c:/temp/export.xml"))

Transactions

Transactions facilitate all commands succeeding or failing together, and perhaps some level of repeatable reads of the DB (depending on the DB).  If there is an open transaction and an exception is thrown in a command, GSH will shut down so that subsequent commands will not execute outside of a transaction.

Loader

Above, it describes how you can kick off the loader in daemon mode.  You can also execute one job with:

This query (in Oracle) will find jobs with no success in the last day and make a gsh script:

select distinct 'loaderRunOneJob("' || job_name || '");' as script 
from grouper_loader_log gll where started_time > sysdate-1 and status != 'SUCCESS'
and gll.job_name not like 'subjobFor%'
and not exists (select 1 from grouper_loader_log gll2 where gll2.started_time > sysdate-1
 and gll2.status = 'SUCCESS' and gll2.job_name = gll.job_name)

select distinct job_name from grouper_loader_log gll where started_time > CURRENT_DATE - 1 DAY and status != 'SUCCESS' and gll.job_name not like 'subjobFor%' 
AND NOT EXISTS (select job_name from grouper_loader_log gll2 where gll2.started_time > CURRENT_DATE - 1 DAY and gll2.status = 'SUCCESS' and gll2.job_name = gll.job_name)

v1.6+ loader

You can run the loader as a linux service

GrouperShell Variables (BeanShell only)

gsh has several variables that can be set to modify runtime behavior

    Example:

gsh 4% GSH_DEVEL = true
gsh 5% subj = findSubject("SD00125")
gsh 6% sess = GrouperSession.start(subj)
gsh 7% member = MemberFinder.findBySubject(sess, subj)
gsh 8% p(member.getGroups())
group: name='etc:sysadmingroup' displayName='Grouper Administration:SysAdmin Group' uuid='6f77fb36-b466-481a-84a7-7af609f1ad09'

Membership scripts

# (1) Print tab-separated summary of all group members, and flags for direct, indirect, or both
# Depending on the results, you could use the data to create a scrutinized list of Ids to delete, then import it and delete in a loop

me = SubjectFinder.findByIdentifierAndSource("my-username", "pid", true);
session = GrouperSession.start(me);
// OR: session = GrouperSession.startRootSession(True)

group = GroupFinder.findByName(session, "tmp:my:group", true);

effectiveMembers = group.getEffectiveMembers();
immediateMembers = group.getImmediateMembers();

System.out.println(String.join("\t", "id", "name", "Effective", "Immediate"));

for (Member m: group.getMembers()) {
    System.out.print(m.getSubject().getId() + "\t" + m.getSubject().getName() + "\t");
    System.out.print(effectiveMembers.contains(m).toString() + "\t");
    System.out.println(immediateMembers.contains(m).toString() + "\t");
}



# (2) Get the immediate and effective members for a specific source ("pid" in this example), intersect them to find the redundant ones
# This has a dryRun flag, so you can test first

sources = new HashSet<Source>()
sources.add(SourceManager.getInstance().getSource("pid"))

effectiveUsers = group.getEffectiveMembers(Group.getDefaultList(), sources, null)
immediateUsers = group.getImmediateMembers(Group.getDefaultList(), sources, null)

# use retainAll() to find the intersection; i.e., users both as effective and immediate member
immediateUsers.retainAll(effectiveUsers)

System.out.println("There are " + immediateUsers.size() + " users having both direct + indirect memberships");

dryRun = true

for (Member m: immediateUsers) {
    if (dryRun) {
        System.out.println("Ok to delete 

This query (in Oracle) will find jobs with no success in the last day and make a gsh script:

select distinct 'loaderRunOneJob("' || job_name || '");' as script 
from grouper_loader_log gll where started_time > sysdate-1 and status != 'SUCCESS'
and gll.job_name not like 'subjobFor%'
and not exists (select 1 from grouper_loader_log gll2 where gll2.started_time > sysdate-1
 and gll2.status = 'SUCCESS' and gll2.job_name = gll.job_name)

select distinct job_name from grouper_loader_log gll where started_time > CURRENT_DATE - 1 DAY and status != 'SUCCESS' and gll.job_name not like 'subjobFor%' 
AND NOT EXISTS (select job_name from grouper_loader_log gll2 where gll2.started_time > CURRENT_DATE - 1 DAY and gll2.status = 'SUCCESS' and gll2.job_name = gll.job_name)

v1.6+ loader

...

Command

...

Description

...

loaderRunOneJobAttr(attirbuteDef)

...

Run an attribute definition loader job

You can run the loader as a linux service

GrouperShell Variables (BeanShell only)

gsh has several variables that can be set to modify runtime behavior

...

Variable

...

Description

...

GSH_DEBUG

...

Stack traces will be printed upon failure if true

...

GSH_DEVEL

...

Summaries of returned objects are not automatically printed if true

...

GSH_TIMER

...

Prints time spent evaluating each command if true

    Example:

gsh 4% GSH_DEVEL = true
gsh 5% subj = findSubject("SD00125")
gsh 6% sess = GrouperSession.start(subj)
gsh 7% member = MemberFinder.findBySubject(sess, subj)
gsh 8% p(member.getGroups())
group: name='etc:sysadmingroup' displayName='Grouper Administration:SysAdmin Group' uuid='6f77fb36-b466-481a-84a7-7af609f1ad09'

Membership scripts

# (1) Print tab-separated summary of all group members, and flags for direct, indirect, or both
# Depending on the results, you could use the data to create a scrutinized list of Ids to delete, then import it and delete in a loop

me = SubjectFinder.findByIdentifierAndSource("my-username", "pid", true);
session = GrouperSession.start(me);
// OR: session = GrouperSession.startRootSession(True)

group = GroupFinder.findByName(session, "tmp:my:group", true);

effectiveMembers = group.getEffectiveMembers();
immediateMembers = group.getImmediateMembers();

System.out.println(String.join("\t", "id", "name", "Effective", "Immediate"));

for (Member m: group.getMembers()) {
    System.out.print(m.getSubject().getId() + "\t" + m.getSubject().getNamegetId() + "\t");
);
    } else {
        System.out.print(effectiveMembers.contains(m).toString() + "\t");
println("Deleting " + m.getSubject().getId());
        System.out.println(immediateMembers.contains(m).toString() + "\t");
}



# (2group.deleteMember(m, false);
    }
}

# (3) Get the immediate and effective members for groups this subject is a member of. Note that a specificgroup source ("pid" in this example), intersect them to find the redundant ones
# This has a dryRun flag, so you can test first

sourcesis a kind of subject, and has a toSubject() method to convert it.

import edu.internet2.middleware.grouper.membership.MembershipSubjectContainer

GrouperSession grouperSession = GrouperSession.startRootSession();

Group group = GroupFinder.findByName(grouperSession, "test:testGroup", true);
Subject subject = g.toSubject();

Set<MembershipSubjectContainer> msc = new HashSet<Source>MembershipFinder()
sources.addaddSubject(SourceManagersubject).getInstancefindMembershipResult().getSourcegetMembershipSubjectContainers("pid"));

effectiveUsersfor = group.getEffectiveMembers(Group.getDefaultList(), sources, null)
immediateUsers = group.getImmediateMembers(Group.getDefaultList(), sources, null)

# use retainAll() to find the intersection; i.e., users both as effective and immediate member
immediateUsers.retainAll(effectiveUsers)

System.out.println("There are " + immediateUsers.size() + " users having both direct + indirect memberships");

dryRun = true

for (Member m: immediateUsers) {
    if (dryRun) {
        System.out.println("Ok to delete " + m.getSubject().getId());
    } else {
        System.out.println("Deleting " + m.getSubject().getId());
        group.deleteMember(m, false);
    }
}

(MembershipSubjectContainer membershipSubjectContainer : msc) { println(membershipSubjectContainer.getGroupOwner().getName());}

//Note there are a few other options for the search. Add these to the MembershipFinder method chain before calling findMembershipResult():
//  - search immediate, effective, etc. (needs to import MembershipType)
import edu.internet2.middleware.grouper.membership.MembershipType
membershipFinder.assignMembershipType(MembershipType.IMMEDIATE) // options are IMMEDIATE|NONIMMEDIATE|EFFECTIVE|COMPOSITE
//  - retrieve specific groups based on pattern
membershipFinder.assignScope("%:test:%")
//  - Enabled status -- true means enabled only, false, means disabled only, and null means all
membershipFinder.assignEnabled(false)
// For other methods, refer to the Javadoc at http://internet2.github.io/grouper/master/grouper-parent/apidocs/edu/internet2/middleware/grouper/MembershipFinder.html

Misc

Note: you cannot encrypt passwords with GSH since the passwords end up in the GSH history.  To encrypt passwords, issue the command:

...