Modes on Xi-Batch Jobs and Variables

Understanding Modes

Modes control access to individual jobs and variables. Every job and every variable carries an owner, a group, and three sets of permissions.

Three permission sets:

User

Applied when you are the owner of the job or variable

Group

Applied when your primary group is the job's or variable's group. Only the primary group counts - a supplementary group membership does not.

Other

Applied to everybody

How a Permission Is Decided

This is where modes differ from Unix file permissions, and the difference matters. Unix picks one set and stops: if you own the file, the owner bits are the only ones that apply to you. Xi-Batch takes the union of every set that applies to you, and the other set applies to everyone.

You are permitted to do something if any of the following holds:

• You own the job or variable and the user set grants it
• Your primary group is its group and the group set grants it
• The other set grants it

So the other set is a floor rather than a fallback. Granting Delete to other grants it to everybody, the owner included, and clearing Read from the user set does nothing while other still has Read.

The three combine privileges - UG, UO and GO - merge two of the sets before this test is made, for the user who holds the privilege. They are described in Understanding User Privileges and Access Control.

The Eleven Modes

Eleven permissions exist for jobs. Variables have the same set except Kill, which is ten. Each appears in all three sets, so a job's mode is eleven permissions times three, and a variable's is ten times three.

The letters are what Xi-Batch prints and what you type. They are upper case only - a lower-case letter in a mode string is rejected with "Bad mode string".

Default Modes

A new job or variable takes the creating user's default modes. Those defaults, the values Xi-Batch ships with, and how to change them are covered in Configuring Default Job and Variable Modes for Users.

Viewing Modes

Seeing an object's modes requires the Display mode (M) permission on it.

For a job:

# In btq: move to the job and press M

# Command line
btjlist -H -F "%N %U %G %M" 15033

For a variable:

# In btq: press V for the variable list, move to the
# variable and press M

# Command line
btvlist -H -F "%N %U %G %M" project_status

The %M format prints the three sets as letter strings:

U:RWSMPUGDK,G:RSMG,O:SM

Read that as: the owner may read, write, reveal, display and set mode, give away owner and group, delete and kill; the group may read, reveal, display mode and give away group; everyone else may see it exists and read its mode. Where a set is empty the letters after its prefix are simply absent.

Changing Modes

Requires: Set mode (P) permission on the object

In btq:

1. Move to the job, or press V and move to the variable
2. Press M
3. Move down the permission list with j and k, and across the User, Group and Other columns with h and l - the arrow keys do the same
4. For each cell:
   • Y, y, T or t to set
   • N, n, F or f to unset
   • ~ or ! to invert
5. Press q to leave the screen and keep the change

Note that t sets, it does not toggle. Inverting is ~ or !.

From the command line:

# A job
btjchange -M "U:RWSMPD,G:RSM,O:S" 15033

# A variable
btvar -M "U:RWSMPD,G:RSM,O:S" project_status

# At submission time
btr -M "U:RWSMPDK,G:RSM,O:S" backup.sh

A mode string is a comma-separated list of clauses. Each clause is an optional set selector - any combination of U, G and O followed by a colon - then an optional operator, then the permission letters:

• = or nothing: set those sets to exactly these permissions
• +: add these permissions, leaving the rest alone
• -: remove these permissions

With no selector the clause applies to all three sets. The selector is matched without regard to case; the permission letters are not.

-M needs the change default modes (Cdft) privilege. Without it, a mode that does not come out exactly equal to the user's own default mode is refused with "Cannot respecify mode". Cdft is granted by default, so this normally passes unnoticed; a user who has had it taken away can change no modes from the command line at all.

# Give the group read access, change nothing else
btjchange -M "G:+RS" 15033

# Take write away from everybody
btjchange -M "-W" 15033

Coupled Permissions

Some permissions imply others, and Xi-Batch enforces the couplings as you edit, in the screens and in mode strings alike:

• Setting Read also sets Reveal
• Setting Write also sets Read and Reveal
• Setting Set mode also sets Display mode
• Clearing Reveal also clears Read and Write
• Clearing Read also clears Write
• Clearing Display mode also clears Set mode

A Mode Must Leave Somebody in Control

Xi-Batch refuses a mode that would orphan the object. At least one of the three sets must have Reveal, and that same set must also have Delete or Set mode. A mode failing this test is rejected when the job or variable is created and when its mode is changed, so there is no way to hide a job from everybody including yourself.

The practical consequence: you cannot clear Reveal in all three sets. To hide a job from other users, clear Reveal from the group and other sets and keep it in your own.

Common Mode Patterns

Private

btjchange -M "U:RWSMPDK,G:,O:" 15033

Only the owner can see or touch it. Nobody else knows it exists.

Shared read

btjchange -M "U:RWSMPDK,G:RSM,O:" 15033

The owner's group can read the job and see its permissions; the owner alone can change it. This is close to the shipped default, which additionally lets everyone see that the job exists.

Public read

btvar -M "U:RWSMPD,G:RSM,O:RSM" project_status

Everyone can read the variable. Useful for a status variable other people's jobs test in conditions.

Group managed

btjchange -M "U:RWSMPDK,G:RWSMPDK,O:" 15033

Anyone in the group has the owner's rights. The same effect for a whole group of users at once is the UG privilege, described in the privileges article.

Ownership Transfer

Changing the owner or the group of a job or variable takes two stages.

Stage 1 - give away. The current owner, or anyone with Give away owner (U) permission, nominates the new owner:

# In btq: move to the job, press O, enter the user name
# For the group: press G, enter the group name

The nominee is recorded. The owner has not changed.

Stage 2 - assume. The nominee, and only the nominee, accepts:

# In btq: the nominee moves to the job and presses O

This requires Assume ownership (V) permission - which is off in the shipped defaults, so a transfer usually needs the mode adjusted before it can complete. The group equivalents are Give away group (G) and Assume group ownership (H).

Administrators bypass both stages. A user with the write admin file (WA) privilege changes the owner or group in one step, provided the object grants either the give-away or the assume permission.

Why two stages? A job runs as its owner. A one-step transfer would let anyone push a job onto another account and have it run with that account's rights.

Troubleshooting

Cannot see a job or variable at all:

Reveal. Without it in any set that applies to you, the object does not exist as far as you are concerned. Ask the owner, or someone with RA privilege, to check.

Cannot see the permissions:

Display mode (M). %M prints nothing rather than reporting an error.

Cannot change a job or variable:

Write. Creating one in the first place also needs the create entry (CR) privilege.

Cannot delete:

Delete on that object. A variable also refuses to go while a job refers to it in a condition or an assignment.

Cannot kill a running job:

Kill (K), which is separate from Write and from Delete.

Cannot complete a transfer:

The giver needs Give away owner, the nominee needs Assume ownership, and the nominee must be the user who was actually nominated.

The mode change is refused outright:

The proposed mode leaves nobody able to see and manage the object. See the minimum-mode rule above.

Good Practice

Set the mode when you create the job. btr -M is one step and leaves no window in which the default applied.

Remember that other is a floor. Before granting anything to other, read it as "everybody, including people in no way connected with this work".

Reveal is the permission that hides things. Clearing Read still leaves the job listed.

Prefer group permissions to the UG privilege when only a few objects need sharing. UG applies to everything the group owns, permanently.

Check the result. btjlist -F "%M" after the change shows what the scheduler actually stored, couplings applied.