Sponsors Data Editing Tutorial

The central aspect of making any particular resource changes for any particular set of users defined by any criteria, is the editing of files in the sponsors data data base.

Details of required changes may differ according to other specific details, but this attempted tutorial attempts to describe in general what changes can be made once the appropriate file has been located.

File Format By Fictional Example

Sponsors files format; how to make changes

IncludeSponsorsDataEditingTutorial

The sponsors files are divided into sections, delimited by 8 equal-signs, ie: "========" Following that is typically a "Class:" entry which then lists a billing or sponsorship code. These will appear, for instance, in the inventory under the "Sponsorship Code" drop box.

Here's a fictional section of account sponsorship. (actually real region names, but fictional userids and extra group name).

========
Class:  Rmg002
Description: sponsored accounts

====
# Basic accounts with varying SponsorshipEnds ("expiry")
Computing: cs-general.cs.private
Quota: 0G
SponsorshipEnds: 2017/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2015/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins
====
# For cs-general.cs.private, parallel accounts are needed on serverus.cs
Computing: serverus.cs
Groups: general_cs
SponsorshipEnds: 2017/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2015/Oct/31
AssignTo:
        ptook
     mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

====
# Extra quota
# Samwise needs more room for mpegs
Computing: cs-general.cs.private
SponsorshipEnds: 2017/Jan/21
Quota: 20G 
AssignTo: sgamgee

====
# Extra groups
# bbaggins and ptook belong in group heroes
Computing: cs-general.cs.private
Groups: heroes
SponsorshipEnds: 2017/Jan/21
AssignTo: ptook
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

Note that lines beginning with "#" are comments which the programs (sponsor_resources) ignore; the comment lines are intended to explain things to people reading the sponsorship files. The "====" lines are required, and reset all resource parameters. After that, "Computing: " must appear, specifying an appropriate hostname. The other lines change resource parameters, causing the resources defined when "AssignTo: " is encountered to be assigned to the indicated userids. The examples here are designed to act as a template to explain some possibilities. For a reasonably complete explanation, see the sponsors man page.

If the userids actually existed, and sponsor_resources were run on the above sometime after 2010/Jan/10 but before 2015/Oct/31, the above would result in resource allocation (as indicated by userinfo command) of...

cs-xh-admin% userinfo mbrandybuck
...
Sponsored: computing cs-general.cs.private:  Rmg002(0)
Sponsored: computing serverus.cs:  Rmg002(0;general_cs)
...

cs-xh-admin% userinfo ptook
...
Sponsored: computing cs-general.cs.private:  Rmg002(0;heroes),Rmg002(0)
Sponsored: computing serverus.cs:  Rmg002(0;general_cs)
...

cs-xh-admin% userinfo sgamgee
...
Sponsored: computing cs-general.cs.private:  Rmg002(0),Rmg002(20000000)
Sponsored: computing serverus.cs:  Rmg002(0;general_cs)
...

Note that resources would not be allocated for bbaggins because his SponsorshipEnds date has passed in all cases.

Note that when you specify the userid you should, as described in more detail in SponsorsDataEditingUserids, follow it with a colon, and an appropriate extra id number for redundancy. The userinfo command can be used to determine that id number.

The id will be a student id, employee id, HR id, employee id, or WatIAM "P-number". It may be added once to a Userids: keyword near the beginning of the file, or it may be added to each use in an AssignTo:. For more details see SponsorsDataEditingUserids.

If you omit that id, however, the sponsor_resources command will actually tell you what value to use, and in fact the resources will be allocated. If you use an incorrect value (for example an employee id for a user who has a student id), you will be told what the correct value is, and an error will be generated and the resources will NOT be allocated.

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

Note that logical lines can be extended by beginning following lines with spaces, as was done with.

AssignTo:
        ptook
     mbrandybuck

That's deliberately sloppy, to indicate the flexibility of the input format. Normally it's nice to line things up.

Note the common resources for all others, but with additional disk quota for sgamgee and group membership for ptook.

There are a number of common changes one might want to make (usually to fulfill a request from a user or their sponsor).

You could add a new AssignTo: userid in appropriate places to cause new resources to be allocated for that userid on the indicated Computing environments. If one of the existing SponsorshipEnds date is appropriate, you could add the new userid to an existing AssignTo: line. Otherwise you could add new SponsorshipEnds lines as well as new AssignTo lines for the new userid.

You could change the 0G to something else to change quota for all the associated users at once. For example, you could change it to 5G which would give each of them an extra 5G (5 gigabyte) of disk quota.

Aside: After the time this tutorial was first written, base quotas in many regions have been increased to the point that nearly all accounts now are given (extra) quota of 0G.

You could change the date after a SponsorshipEnds to change when the resource sponsorship, and likely whole account(s), expires.

You could add another section like #Extra quota or #Extra groups to add more quota or groups for existing accounts.

Allocating standard resources to another userid

Suppose fbaggins is entitled to an account sponsored here.

We could add him to the lines with sgamgee as in:

========
Class:  Rmg002
Description: sponsored accounts

====
# Basic accounts with varying SponsorshipEnds ("expiry")
Computing: cs-general.cs.private
Quota: 1G
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee fbaggins
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins
====
# For cs-general.cs.private, parallel accounts are needed on serverus.cs
Computing: serverus.cs
SponsorshipEnds: 2015/Jan/21
Groups: general_cs
AssignTo: sgamgee fbaggins
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

# Extra quota and # Extra groups sections would remain the same.

That's assuming he won't have the requirements for the extra 20G which sgamgee has.

If it would be better to give fbaggins his own SponsorshipEnds date, then...

========
Class:  Rmg002
Description: sponsored accounts

====
# Basic accounts with varying SponsorshipEnds ("expiry")
Computing: cs-general.cs.private
Quota: 1G
SponsorshipEnds: 2020/Jan/21
AssignTo: fbaggins
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins
====
# For cs-general.cs.private, parallel accounts are needed on serverus.cs
Computing: serverus.cs
Groups: general_cs
SponsorshipEnds: 2020/Jan/21
AssignTo: fbaggins
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

# Extra quota and # Extra groups sections would remain the same.

Changing disk quota or group memberships for the standard set of users

The disk quota for all sponsored accounts can be changed by first Quota line. A Groups line could be added to make them all members of a UNIX group.

========
Class:  Rmg002
Description: sponsored accounts

====
# Basic accounts with varying SponsorshipEnds ("expiry")
Computing: cs-general.cs.private
Quota: 5G
Groups: hobbits
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins
====
# For cs-general.cs.private, parallel accounts are needed on serverus.cs
Computing: serverus.cs
Groups: general_cs
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

# Extra quota and # Extra groups sections would remain the same.

Changing =SponsorshipEnds

Perhaps it was decided bbaggins should have the sponsored resources after all. That could be made to happen by changing (all) his relevant SponsorshipEnds dates.

========
Class:  Rmg002
Description: sponsored accounts

====
# Basic accounts with varying SponsorshipEnds ("expiry")
Computing: cs-general.cs.private
Quota: 1G
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2014/Jan/10
AssignTo: bbaggins
====
# For cs-general.cs.private, parallel accounts are needed on serverus.cs
Computing: serverus.cs
Groups: general_cs
SponsorshipEnds: 2015/Jan/21
AssignTo: sgamgee
SponsorshipEnds: 2013/Oct/31
AssignTo: ptook mbrandybuck
SponsorshipEnds: 2014/Jan/10
AssignTo: bbaggins

====
# Extra quota
# Samwise needs more room for mpegs
Computing: cs-general.cs.private
SponsorshipEnds: 2015/Jan/21
Quota: 20G 
AssignTo: sgamgee

====
# Extra groups
# bbaggins and ptook belong in group heroes
Computing: cs-general.cs.private
Groups: heroes
SponsorshipEnds: 2015/Jan/21
AssignTo: ptook
SponsorshipEnds: 2014/Jan/10
AssignTo: bbaggins

Extra Sections for Special Cases

This section has not been written yet. It would describe how to add more extra sections as in the original example. Perhaps that's obvious and little more needs to be said than that you can.

Reorganizing to Use Membership

Assuming the end of sponsorship is the same for all resources for a given user, the Members and MembershipEnds facilities can be used to avoid the need to enter and/or update the same date multiple times.

========
Class:  Rmg002
Description: sponsored accounts

MembershipEnds: 2015/Jan/21
Members: sgamgee
MembershipEnds: 2013/Oct/31
Members: ptook mbrandybuck
MembershipEnds: 2010/Jan/10
Members: bbaggins

====
# Basic accounts with varying SponsorshipEnds ("expiry")
Computing: cs-general.cs.private
Quota: 1G
AssignTo: *MEMBERS*
====
# For cs-general.cs.private, parallel accounts are needed on serverus.cs
Computing: serverus.cs
Groups: general_cs
AssignTo: *MEMBERS*

====
# Extra quota
# Samwise needs more room for mpegs
Computing: cs-general.cs.private
SponsorshipEnds: 2015/Jan/21
Quota: 20G 
AssignTo: sgamgee

====
# Extra groups
# bbaggins and ptook belong in group heroes
Computing: cs-general.cs.private
Groups: heroes
SponsorshipEnds: 2015/Jan/21
AssignTo: ptook
SponsorshipEnds: 2010/Jan/10
AssignTo: bbaggins

Note that there's no way to avoid giving extra SponsorshipEnds for the extra resources which are not allocated to all active *MEMBERS*. That is, there's no way to specify that those allocations should be cutoff when the MembershipEnds takes effect.

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. Only one specific id number can be used for a particular userid. See IncludeSponsorsDataIdNumbers for details.

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 ci -u command so you leave the file editable by others.

---

I anticipate writing a SponsorsDataEditingTutorialAdvanced. I anticipate covering MailAliases there, but perhaps it should be introduced sooner. The problems with printing could be discussed, and perhaps approaches to using the sponsors data as a tool to help keep track of intended printer usage. The Members mechanism definitely should be left to be discussed there. As should input redirection ("<").

Hmm. I added mention of Members here, and it's not clear it doesn't fit. Perhaps MailAliases could be a section here too. Or added to the overall example.

It might be a good idea to have SponsorsDataEditingTutorialAdvanced handle questions about how to determine where changes need to be made. How to make somewhat arbitrary decisions about, for instance, sponsoring all members of a group in one place, or scattering the sponsorship of those group memberships around several different sponsors as appropriate for each individual.

-- AdrianPepper - 14 Aug 2014