7.1 Scope and Roles
This chapter defines the jobs channel: the interface by which a process asks a Peios service manager to run an arbitrary program under its supervision, with an identity the requester is entitled to confer, and to manage that program afterwards.
A job submitted this way is a job in the sense of §4.2 — one process execution, supervised by the manager — whose parent is the process that asked for it rather than a service definition. The manager forks it, installs its token, contains it, records it and reaps it exactly as it does a service's process. What differs is where the definition came from and who is entitled to manage the result.
Two shapes of use are intended, and the chapter is written so that one primitive serves both:
- A task: a program that runs to completion and reports progress on the way — a backup, a transfer, a migration — submitted by a broker on behalf of the principal it is acting for.
- A session: a long-lived program managed from outside — a per-logon host process for an interactive session — submitted with a freshly issued logon token and one end of a channel back to its submitter.
Nothing in the protocol distinguishes the two. They are the same message with different field values.
7.1.1 The roles #
The manager is the process that supervises services and listens on the control and notification channels of §4. It listens on the jobs channel too. On Peios this is peinit.
A submitter connects to the jobs channel, submits a job, and MAY manage the jobs it submitted. A submitter is any process the socket's descriptor admits; it holds no relationship with the manager beyond the one its token establishes.
A job is the process the manager started on a submitter's behalf. It speaks the notification channel of §4 about itself, in the same way a service does, and this chapter adds nothing to that role beyond the progress fields defined in §4.19.
A client of the control channel (§4) MAY observe and stop jobs it is entitled to, alongside services. That role is unchanged here; §4.14 defines the commands.
Requirements are stated against the role, not the program. A service that submits jobs is a submitter when it does so; a job that submits jobs of its own is a submitter too.
7.1.2 What this chapter covers #
- the jobs socket, how it is reached, and who may reach it
- message framing on it, and how a message carries a token and descriptors alongside its content
- how the identity a job runs as is established, and the rule that the manager never installs an identity the submitter could not already act as
- the job definition a submitter sends, and what the manager validates
- the job view the manager reports, its states and its causes
- the commands a submitter may issue about its own jobs, and the Security Descriptor that decides who else may
- passing descriptors into a job, and receiving its output
- the error vocabulary, the extension rules and the conformance requirements
7.1.3 What this chapter does not cover #
- The notification channel, including the progress fields a job sends. A job reports on itself exactly as a service does. §4.16–§4.19.
- Observing and stopping jobs from the control channel. The
job-list,job-statusandjob-stopcommands are part of the control channel's command set and are defined in §4.14, using the job view this chapter defines. - How the manager supervises the job once it is running — cgroup containment, output capture, reaping, the child setup sequence. That is the manager's own design, documented in its reference manual.
- How a token is conveyed on a socket, and what the kernel checks
when it is. Peer-token capture,
KACS_SCM_TOKEN, the impersonation gates and the impersonation-level ratchet are kernel operations, documented in the Peios Kernel TRM §3.5. - How a submitter obtained the token it attaches. From a peer it is serving, from a logon it originated (PGSS §2), or from anywhere else — the manager does not ask, because the kernel has already decided whether the submitter may convey it.