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 tries to describe in general what changes can be made once the appropriate file has been located.

Reference is made to the sponsor_resources command. Running that command processes the data described here, and informs you of mistakes you may have made.

I have recently realized that a good practice is to run it before you begin making your new changes, so you can see if there are currently any persistently unavoidable non-fatal errors. That will allow you to distinguish between those and errors you may introduce.

Use RCS co command to prepare file for editing

IncludeSponsorsDataEditingRCSout

All files in the sponsor data are now maintained using the RCS set of utilities.

Before using your favourite appropriate text editor to make changes to the file, you must do the following

   cs-xh-admin% rcsdiff _filename_
   cs-xh-admin% co -l _filename_

The rcsdiff is not strictly-speaking necessary, but it is a good habit to get into. It should return no output, meaning that you will not obliterate anyone else's changes. Somewhat similarly, if the co command fails, it may be because another person already has the file locked; you may need to talk to them to resolve that.

Note that before you do the above, the file filename should not be writeable by you; this process modifies the file so you are able to make changes working as your own personal userid (without using super-user). The file might or might not be owned by your personal userid, depending upon who last did make a change to the file.

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.

Use RCS ci command to unlock the file so others can edit it

IncludeSponsorsDataEditingRCSin

At this point you must use the RCS utility ci to save a record of your changes, and unlock the file so others can make changes, as follows.

   cs-xh-admin% ci -u _filename_

You will be prompted for a description of your changes. Make it reasonably brief, but meaningingful. A reference to an ST number is often appropriate.

More explicit descriptions of explicit change types are (will appear) in CF.SponsorsDataEditingTutorial.

-- AdrianPepper - 04 Dec 2012

---

IncludeAdrianReferers

Referers

This topic IncludeSponsorsDataEditingTutorial is referred to by...

• IncludeSponsorsDataIdNumber
• SponsorsDataEditingTutorial
• SponsorsDataEditingUserids
• TemplateSponsorDataAccountsCollapsed