SGE_SHEPHERD(8)

🐑 NAME 🐑

sge_shepherd — the Grid Engine single job-controlling agent 💅 (yes, that's the whole NAME section, and yes, it's section 8 of the manual, iykyk)

📜 SYNOPSIS 📜

sge_shepherd

✨ DESCRIPTION ✨

Okay so bestie, sge_shepherd is the one holding down the parent process role for a single Grid Engine job. Why does a job even need a parent, you ask? Because on UNIX systems you literally cannot retrieve resource usage information (see getrusage(2)) after a job has finished without somebody hanging around to collect it. That somebody is the shepherd 🫶. On top of that, sge_shepherd forwards signals to the job — the suspension, enabling, termination kind, plus the Grid Engine checkpointing signal (see sge_ckpt(1) and queue_conf(5) for the full deets).

The shepherd gets all its info about the job it's about to start from sge_execd(8). And during the execution of that job it actually spins up up to 5 child processes, in this exact order:

1. a prolog script, run first — but only if this feature is enabled by the prolog parameter in the cluster configuration (see sge_conf(5))
2. a parallel environment startup procedure — but only if the job is a parallel job (see sge_pe(5) for more)
3. the job itself 👑
4. a parallel environment shutdown procedure, for parallel jobs
5. an epilog script, last — but only if requested by the epilog parameter in the cluster configuration

The prolog and epilog scripts, plus the parallel environment startup and shutdown procedures, are provided by the Grid Engine administrator, and they're intended for site-specific actions taken before and after execution of the actual user job. Not yours to write, but iconic of them to exist 😌.

Once the job has finished and the epilog script is processed, sge_shepherd retrieves resource usage statistics about the job, places them in a job-specific subdirectory of the sge_execd(8) spool directory for reporting through sge_execd(8), and finishes. Clean exit, no drama ✨.

The shepherd also places an exit status file in the spool directory. You can view this exit status with qacct -j JobId (see qacct(1)). But heads up bestie — it is not the exit status of sge_shepherd itself, it's the exit status of one of the methods executed by sge_shepherd. And its meaning shifts depending on which method an error occurred in (if any). The possible methods are: prolog, parallel start, job, parallel stop, epilog, suspend, restart, terminate, clean, migrate, and checkpoint.

The following exit values are returned:

• 0 — All methods: the operation was executed successfully. slay 💅
• 99 — Job script, prolog and epilog: when FORBID_RESCHEDULE is not set in the configuration (see sge_conf(5)), the job gets re-queued. Otherwise see "Other".
• 100 — Job script, prolog and epilog: when FORBID_APPERROR is not set in the configuration (see sge_conf(5)), the job gets re-queued. Otherwise see "Other".
• Other — and this is where it gets spicy 🌶️:
  • Job script: this is the exit status of the job itself. No action is taken upon this exit status because the meaning of this exit status is not known.
  • Prolog, epilog and parallel start: the queue is set to error state and the job is re-queued.
  • Parallel stop: the queue is set to error state, but the job is not re-queued. It is assumed that the job itself ran successfully and only the clean up script failed.
  • Suspend, restart, terminate, clean, and migrate: always successful.
  • Checkpoint: success, except for kernel checkpointing: checkpoint was not successful, did not happen (but migration will happen).

For the meaning of the return codes of the shepherd itself (which are interpreted by qacct(1)), go read sge_status(5).

---

🚫 RESTRICTIONS 🚫

sge_shepherd should not be invoked manually, bestie. Only by sge_execd(8). Hands off, this one is not for you 🙈

---

🌈 ENVIRONMENT VARIABLES 🌈

• SGE_ROOT — Specifies the location of the Grid Engine standard configuration files.
• SGE_CELL — If set, specifies the default Grid Engine cell. To address a Grid Engine cell sge_execd uses (in the order of precedence):
  1. The name of the cell specified in the environment variable SGE_CELL, if it is set.
  2. The name of the default cell, i.e. default.
• SGE_ENABLE_COREDUMP — If set, enable core dumps on Linux when the admin_user is not root. Linux normally disables core dumps when the daemon has changed uid or gid. Setting SGE_ENABLE_COREDUMP in sge_execd's environment defeats that to enable core dumps for debugging if they are otherwise allowed. This is typically not a big hazard with SGE, since most information is exposed in the spool area anyhow. Dumps will appear in the qmaster spool directory, which need not be world-readable. On Solaris, coreadm(1) may be used to enable such dumps.
• SGE_CGROUP_DIR — If Linux cgroups handling is enabled, this variable names a directory under the cgroup mount point in which to create job-specific directories. The default is sge.SGE_CELL so, for instance, the cpuset cgroup for a job might be /sys/fs/cgroup/cpuset/sge.default/123.

---

📁 FILES 📁

sgepasswd contains a list of user names and their corresponding encrypted passwords. If available, the password file will be used by sge_shepherd. To change the contents of this file please use the sgepasswd command. It is not advised to change that file manually. fr fr, don't.

• <execd_spool>/job_dir/<job_id> — job specific directory
• <sge_root>/<cell>/common/sgepasswd — Password information used on Microsoft Windows hosts. See sgepasswd(5).

---

👀 SEE ALSO 👀

sge_intro(1), sge_conf(5), sge_status(5), remote_startup(5), sgepasswd(5), sge_execd(8).

---

©️ COPYRIGHT ©️

See sge_intro(1) for a full statement of rights and permissions.

---

and that's the whole vibe check, bestie 💖 this page lives in SGE 8.1.3pre, stamped $Date: 2007-07-19 09:04:33 $ — go forth and let sge_execd(8) do the calling, mwah 💋🎀