Here we discuss what to do if a Researcher wishes to sponsor an account ("resources") for an ex-grad-student.


IncludeSponsorsDataPreamble

These notes relate to adding users to groups and servers using the Xhiered Accounts packages. This controls access to "xhiered" machines as well as those using the CS Active Directory for accounts management.

IncludeSponsorsDataRequiredAuthorization

Required authorization

  • Users who need to update accounts need to be in group "sponsor" and group "accounts" on cscf.cs.
  • Users who need to manipulate accounts, for example set passwords, in the core region to be in the "accounts" group on core.cs. Similarly for any other region.

IncludeSponsorsDataCreatingUserids

Creating Truly New Users (Userids)

Before you can use the sponsors data software to create new accounts for a userid, that userid must be present on cscf.cs.uwaterloo.ca in the file /software/accounts-userids/data/Userids on the machine cscf.cs.uwaterloo.ca. Often, but not always, that happens automatically.

If the userinfo command gives results for the userid, then the userid is appropriately present in this file, and you can proceed. (And use the Id Number: indicated by the output as the id number to associate with the userid). If userinfo gives no output for the particular user, more work is needed to get the userid into the file.

The Id Number: will be a student id, employee id, HR id, employee id, or WatIAM "P-number", in that order. In fact, you will see other obscure values listed too. But only the one shown can be used. Users with a lengthy history at UW sometimes have several other values shown as the Other Ids: value; you cannot use any of those values.

In most cases user names and identification numbers already exist, precreated in WatIAM. In other limited cases, the correct thing to do is create a userid which really should, for various reasons, not be put in WatIAM. And occasionally you need to do things to cause the WatIAM account creation.

WatIAM account creation (precreation) is discussed at this link which requires appropriate authentication.

After the WatIAM account has been created, you normally need to wait until the next business day for the new userid to be available for sponsors data. Various technical personnel, including Adrian Pepper, can accelerate that process, however.

If you need to do that yourself, perhaps see Discussion of the Userids File for Experts.

And bear in mind Information about Userids in the Sponsors Data.

IncludeSponsorsDataCreatingUserids

Creating Truly New Groups (gids)

If you are creating a new group to appear in the Active Directory (eg: users_researchgroup), you will need to follow the instructions in CreatingGroupAccounts

IncludeSponsorsDataLocation

Location of Accounts Sponsor files

The accounts files for CS are on the UNIX computer cscf.cs.uwaterloo.ca

cd /software/accounts-master/data/sponsors

IncludeSponsorsDataDirectoryTableStart

Directory/File NamePurpose
Research/
IncludeSponsorsDataDirectoryResearch
Research/ files under Research correspond to an individual researcher or research group. Here resources, or extra resources, for users specifically affiliated with particular researchers can be sponsored. These might be extra disk space (or theoretically printing) for a grad student, or entire accounts for associated or visiting researchers.
REGISTRAR-YYYYMM/
IncludeSponsorsDataDirectoryREGISTRARyy
REGISTRAR-YYYYMM/ Files under REGISTRAR-YYYYMM, e.g. REGISTRAR-201001 implement the predictable long-term expiry of sponsored resources by freezing the indicated previous terms class (program/year) memberships. Another file there ensures any account created stays until after the drop-add deadline. Occasionally (usually only in fall terms) you will see REGISTRAR-YYYYMMext directories. Read the file .README in such a directory for an explanation of its purpose and how it was created.

Graduate Students would previously have had resources allocated from files in the subdirectories named REGISTRAR-YYYYMMDD arising from previous allocations under REGISTRAR.

It will be necessary to add appropriate sponsorship information for them to the appropriate per-researcher file beneath /software/accounts-master/data/sponsors/Research.

For example, perhaps you received an email message like:

From wbcowan@cs.uwaterloo.ca Wed Jan 20 16:02:51 2010
Message-ID: <4B576F6A.1030300@bagend.uwaterloo.ca>
Date: Wed, 20 Jan 2010 13:02:34 -0800
From: William Cowan 
To: accounts@cs.uwaterloo.ca
Subject: Re: CS Grad computer account expiring

Please retain the account for Samwise Gamgee.

accounts@cs.uwaterloo.ca wrote:
> CS computing accounts for grad students who have left are
> sponsored by the School for a few terms.  After this time
> they are disabled unless the supervisor wishes to sponsor
> them.
>
> The accounts for:
>
>     Samwise Gamgee (sgamgee) 
>     Peregin Took (ptook) 
>     Meriadoc Brandibuck (mbrandibuck)
>
> on the core CS computing environment will be disabled in
> early February 2010 and the files removed shortly thereafter.
>
> Warning email has already been sent to the students at their
> @cs and @uwaterloo.ca addresses.
>
> If you have any questions please contact accounts@cs.uwaterloo.ca.

In this case you might first consider the file

/software/accounts-master/data/sponsors/Research/Cowan

but further inspection would reveal that, because of a surname conflict,

/software/accounts-master/data/sponsors/Research/WCowan

is the one to change. (Note that student names in this example are fictional, but we've used two real researcher names for a realistic example).

Making the changes

On cscf.cs.uwaterloo.ca use an appropriate text editor you are comfortable with.

A normal resource sponsorship to be added to the file (WCowan in our example), to extend resource sponsorship for a the named graduate student would look like

====
# Created January 2010 to perpetuate core.cs Grad account sgamgee
Computing: core.cs
SponsorshipEnds: 2015/Jan/21
Quota: 1G
AssignTo: sgamgee
====
Computing: serverus.cs
SponsorshipEnds: 2015/Jan/21
Groups: general_cs
AssignTo: sgamgee

But if you have lots of similar cases to handle, it can be more convenient to do them all together, perhaps even adding to previously existing sections, and ending up with something like:

====
# Perpetuate core.cs Grad accounts
Computing: core.cs
SponsorshipEnds: 2015/Jan/21
Quota: 1G
AssignTo: bbaggins sgamgee ptook mbrandybuck
====
Computing: serverus.cs
SponsorshipEnds: 2015/Jan/21
Groups: general_cs
AssignTo: bbaggins sgamgee ptook mbrandybuck

You can even do differing SponsorshipEnds dates (sometimes called "Expiry Dates"), as in.

====
# Perpetuate core.cs Grad accounts
Computing: core.cs
SponsorshipEnds: 2015/Jan/21
Quota: 1G
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook
SponsorshipEnds: 2012/Dec/25
AssignTo: mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins
====
Computing: serverus.cs
SponsorshipEnds: 2015/Jan/21
Groups: general_cs
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook
SponsorshipEnds: 2012/Dec/25
AssignTo: mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

If it was decided all such students should get more diskquota, there would be only one number to change.

And yet you could later add resources for only one.

====
# Perpetuate core.cs Grad accounts
Computing: core.cs
SponsorshipEnds: 2015/Jan/21
Quota: 1G
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook
SponsorshipEnds: 2012/Dec/25
AssignTo: mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins
====
Computing: serverus.cs
SponsorshipEnds: 2015/Jan/21
Groups: general_cs
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook
SponsorshipEnds: 2012/Dec/25
AssignTo: mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

====
# Samwise needs more room for mpegs
Computing: core.cs
SponsorshipEnds: 2015/Jan/21
Quota: 20G
AssignTo: sgamgee

For more of a tutorial about editing sponsors data files perhaps see SponsorsDataEditingTutorial .

Cautionary Notes About Editing the Sponsors Data

IncludeSponsorsDataEditingCaution
In general you should avoid making easy-to-make mistakes.

Nearly all files found in the directory

   /software/accounts-master/data/sponsors/
and all directories beneath it, will be processed by the sponsor_resources command. Exceptions are files whose name begins with . (dot/period) and files in sub-directories which sub-directories are named RCS. If a subdirectory name begins with . (dot/period) then everything beneath it will be ignored (unless referred to explicitly by other files).

The upshot of that is that you cannot place arbitrary files in these directories, or sponsor_resources will stop working correctly.

When editing the sponsors data files, it can often be convenient to copy and modify previously existing lines to create your new additions. If you do that, make sure you correctly change all relevant SponsorshipEnds dates, or remove them as appropriate. Also make sure you delete or change any comments which are irrelevant in the new context. It's better to leave no comments than leave confusing comments.

Consider that the files are intended to help later readers understand the sponsorship situation; use a few comment lines ("#"), and, in general, put a blank line before each ==== line.

Note that id numbers need to be associated with userids. This can be done directly in the AssignTo line as in

      AssignTo: sgamgee:02020202

Or it can be done in the Userids: section at the top of the file.

To help make sure we don't slip up and put a real userid:studentid in one of these pages, we by convention omit :studentid in all examples.

Finally, make sure you remember to use the co command so you leave the file editable by others.

IncludeSponsorResourcesAccountsClient

Run the sponsor_resources program to process the changes

IncludeSponsorsDataRunSponsorResources

sponsor_resources takes the data under /software/accounts-master/data/sponsors and produces per-user requirements in per-machine (actually per-region) files under /software/accounts-master/data/resources. Along the way, it might detect errors in the changes you made. Fix any problems that are reported and keep rerunning sponsor_resources until all errors have gone away.

Here is an example of a "bad run":

@cscf[140]% sponsor_resources
Error: /software/accounts-master/data/sponsors/Research/Terry line 63: Userid 'bjlafren'
 is not a standard userid
FYI:  78150(20697) computings, 1262(1180) printers, 300(0) aliases, 0(0) ppps
FYI:  1 error, 0 warnings, (0 notes)
FYI: expired sponsorship entries:  91 computings, 2 printers, 0 aliases, 0 ppps
@cscf[141]%
In this case, sponsor_resources complained because we used the short version of the userid ("bjlafren"), but it always requires the long version (ie: "bjlafreniere").

This is an example of a "good run":

@cscf[143]% sponsor_resources
FYI:  78151(20697) computings, 1262(1180) printers, 300(0) aliases, 0(0) ppps
FYI:  0 errors, 0 warnings, (0 notes)
FYI: expired sponsorship entries:  91 computings, 2 printers, 0 aliases, 0 ppps
@cscf[144]%

Path to the "sponsor_resources" command

If you don't happen to have the maintenance commands in your path, the path to the sponsor_resources command is:
/software/accounts-master/maintenance/sponsor_resources

Run the userinfo program to verify your changes

IncludeSponsorsDataRunUserinfo

Run the userinfo command before and after you make your changes to verify that its output reflects your intended changes. More details are here.

Run the accounts-client program

IncludeSponsorsDataRunAccountsClient

accounts-client {hostname, eg:core.cs} >& ~/hostname-date &

This will cause the desired changes to actually happen on the appropriate machine (hostname; what is described as "Computing:" in the sponsor file, which may in turn affect a region of machines). /etc/passwd and /etc/group file will be updated if necessary, as will system quota files, and home directories will be created for any newly-created users. The diagnostic output from the job will be written to the given filename in your home directory. eg:

   accounts-client softbase.cs >& ~/softbase-20100208 &
   
If your changes will cause changes on multiple regions, you will need to run the command for each. eg:
   accounts-client student.cs >& ~/student-20100208 &
   accounts-client core.cs >& ~/core-20100208 &
   
If you run accounts-client with no name, all known regions are updated. eg:
   accounts-client >& ~/ac-all-20100208 &
   
That can take a long time to finish.

Path to the "accounts-client" command

If you don't happen to have the maintenance commands in your path, the path to the accounts-client command is:
/software/accounts-master/maintenance/accounts-client

Documentation

IncludeSponsorsDataDocumentation

The following traditional UNIX man page documentation describes the sponsors data base in a technical fashion. As you become familiar with how things work in general, you might find this documentation good for checking specific details.

-- AdrianPepper - 15 Mar 2010

Topic revision: r10 - 2011-03-15 - AdrianPepper
Information in this area is meant for use by CSCF staff and is not official documentation, but anybody who is interested is welcome to use it if they find it useful.


Edit

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2014 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback