----
-title: OSC 3008: Hierarchical Context Signalling
-category: Interfaces
-layout: default
-SPDX-License-Identifier: LGPL-2.1-or-later
----
-
-# OSC 3008: Hierarchical Context Signalling
-
-A terminal connects a user with programs. Control of the program side of
-terminals is typically passed around to various different components while the
-user is active: a shell might pass control to a process it invokes. If that
-process is `run0` then primary control is passed to the privileged session of
-the target user. If `systemd-nspawn` is invoked to start a container, primary
-control is passed to that container, and so on.
-
-A terminal emulator might be interested to know which component is currently in
-primary control of the program side of a terminal. OSC 3008 is a mechanism to
-inform it about such contexts. Each component taking over control can inform
-the terminal emulators that a new context begins now, and then use the terminal
-or pass control down to further apps, which can introduce contexts. Each
-context may carry various descriptive metadata fields.
-
-## Status
-
-This OSC sequence has been invented by the systemd project and is generated by
-systemd. Currently, no terminal application is known that consumes these
-sequences.
-
-## Use Cases
-
-Terminal emulators can use hierarchical context information:
-
-1. To introduce markers/bookmarks in the output that the user can jump between.
-
-2. To visually identify output from different contexts. For example the
- background of the associated output can be tinted in a reddish tone when
- privileges are acquired, and similar.
-
-3. Meta information on specific output can be shown in a tooltip or similar
-
-4. Programs (and all subcontexts) can be killed via a right-click menu on the
- output they generate.
-
-5. Similar, a right-click menu might offer an item to offer opening a new
- interactive shell in the same working directory that was current on the
- selected context.
-
-6. Failed commands or aborted sessions can be marked requesting user attention.
-
-## Context Types
-
-There are various types of contexts defined by this specification:
-
-1. `boot` → a booted system initiates this context early at boot. (systemd's
- PID 1 generates this on `/dev/console`.)
-
-2. `container` → a container manager initialized an interactive connection to a
- container. (`systemd-nspawn` generates this when interactively invoking a
- container. `machinectl login`, `machinectl shell` do this too.)
-
-3. `vm` → a VM manager initialized a terminal connection to a
- VM. (`systemd-vmspawn` generates this when interactively invoking a VM, as
- one example.)
-
-4. `elevate` → when the user interactively acquired higher privileges. (`run0`
- initiates a context of this type whenever the user invokes it to acquire
- root privileges.)
-
-5. `chpriv` → similar, but when the user acquired *different* privileges, not
- necessarily higher ones. (`run0` initiates a context of this type whenever
- the user invokes it to acquire non-root privileges of another user.)
-
-5. `subcontext` → similar, but the source and target privileges where
- identical. (`run0` initiates a context of this type whenever the user
- invokes it to acquire privileges of the user itself.)
-
-6. `remote` → a user invoked a tool such as `ssh` to connect to a remote
- system.
-
-7. `shell` → an interactive terminal shell initiates this context
-
-8. `command` → a shell interactively invokes a new program.
-
-9. `app` → an interactive program may initiate this context.
-
-10. `service` → the service manager invokes an interactive service on the terminal
-
-11. `session` → a login session of the user is initialized.
-
-## Semantics
-
-Contexts in the sense of OSC 3008 are hierarchical, and describe a tree
-structure: whenever a new context is opened it becomes the new active context,
-and the previously active context becomes its parent (if there is one). Only
-one context is currently active, but previously opened contexts remain valid in
-the background. Any other data written or read should be considered associated
-with the currently active context.
-
-Each context carries an identifier, chosen by the component opening the
-context. The identifier can chosen freely, but must not be longer than 64
-characters. The characters may be in the 32…126 byte range. Identifiers should
-be universally unique, for example randomly generated. A freshly generated UUID
-would work well for this, but this could also be something like the Linux boot
-ID combined with the 64bit inode number of Linux pidfds, or something hashed
-from it.
-
-Fundamentally, there are two OSC 3008 commands defined:
-
-1. OSC "`3008;start=`" … (the *start sequence*) → this initiates, updates or
- indicates a return to a context. It carries a context identifier, and
- typically some metadata. This may be sent to first initiate a context. If
- sent again for the same context ID that was initiated already this indicates
- an update of the existing context. In this case, *any* previously set
- metadata fields for the context are flushed out, reset to their defaults,
- and then reinitialized from the newly supplied data. Also, in this case any
- subcontexts of the contexts are implicitly terminated.
-
-2. OSC "`3008;end=`" … (the *end sequence*) → this terminates a context. It
- carries a context identifier to close, initiated before with OSC
- "`3008;start=`". It may also carry additional metadata.
-
-## General Syntax
-
-This builds on ECMA-48, and reuses the OSC and ST concepts introduced there.
-
-For sequences following this specification it is recommended to encode OSC as
-0x1B 0x5D, and ST as 0x1B 0x5C.
-
-ECMA-48 only allows characters from the range 0x20…0x7e (i.e. 32…126) inside
-OSC sequences. However, most terminal emulators nowadays allow the ASCII byte
-range > 0x7f in the OSC sequences they process, and so does this
-specification. Control characters (< 0x20 and 0x7f) are not allowed. The
-semicolon character ("`;`") – which is used as field separator by this
-specification – shall be replaced by "`\x3b`" and the backslash character
-("`\`") shall be replaced by "`\x5c`". All textual fields must be encoded in
-UTF-8, and then escaped with these two replacements.
-
-The start sequence begins with OSC, followed by the string `3008;start=`,
-followed by the context ID. This is then followed by any number of metadata
-fields, including none. Metadata fields begin with a semicolon (`;`) followed
-by in a string identifying the type of field, followed by an equal sign (`=`),
-and the field value. The sequence ends in ST.
-
-The end sequence begins with OSC, followed by the string `3008;end=`, followed
-by the context ID, and a series of metadata fields in the same syntax as for
-the start sequence. The sequence ends in ST.
-
-## Metadata Fields
-
-The following fields are currently defined for the start sequence:
-
-| Field | Context Types | Description |
-|---------------|---------------|-------------------------------------------------------------------------------------------------------------|
-| `type=` | *all* | Declares the context type, one of the types described above |
-| `user=` | *all* | UNIX user name the process issuing the sequence runs as |
-| `hostname=` | *all* | UNIX host name of the system the process issuing the sequence runs on |
-| `machineid=` | *all* | The machine ID (i.e. `/etc/machine-id`) of the system the process issuing the sequence runs on |
-| `bootid=` | *all* | The boot ID (i.e. `/proc/sys/kernel/random/boot_id`) of the system the process issuing the sequence runs on |
-| `pid=` | *all* | The numeric PID of the process issuing the sequence, in decimal notation |
-| `pidfdid=` | *all* | The 64bit inode number of the pidfd of the process issuing the sequence, in decimal notation |
-| `comm=` | *all* | The process name (i.e. `/proc/$PID/comm`, `PR_GET_NAME`) of the process issuing the sequence |
-| `cwd=` | `shell`, `command` | The current working directory |
-| `cmdline=` | `command` | The full command line of the invoked command |
-| `vm=` | `vm` | The name of the VM being invoked |
-| `container=` | `container` | The name of the container being invoked |
-| `targetuser=` | `elevate`, `chpriv`, `vm`, `container`, `remote`, `session` | Target UNIX user name |
-| `targethost=` | `remote` | Target UNIX, DNS host name, or IP address |
-| `sessionid=` | `session` | New allocated session ID |
-
-The following fields are currently defined for the end sequence:
-
-| Field | Context Types | Description |
-|---------------|---------------|-------------------------------------------------------------------------------------------------------------|
-| `exit=` | `command` | One of `success`, `failure`, `crash`, `interrupt`, indicating how the program terminated |
-| `status=` | `command` | The command's numeric exit status, i.e. the 0…255 value a program returns |
-| `signal=` | `command` | The termination signal of the command, if it died abnormally. A symbolic signal name. (`SIGKILL`, …) |
-
-All fields are optional, including the context type. However, it is generally
-recommended to always include the first 7 fields listed above, to make it easy
-to pinpoint the origin of a context in a race-free fashion, without any
-ambiguities.
-
-The order of the metadata fields is undefined, they may appear in any order
-(including that `type=` is specified at the very end or in the middle!). Note
-that `start=` and `end=` are not considered metadata fields but part of the
-start sequence, and hence must always appear right after OSC.
-
-## Processing, Limits, Security
-
-All context information provided like this should be considered auxiliary and –
-to some degree – redundant information. Hence, it would be wise for a terminal
-to enforce limits on various resources, dropping additional data once these
-limits are hit. Most importantly, a maximum stacking depth should probably
-enforced: any attempts to initiate further contexts should be ignored once the
-stack limit is hit (i.e. the earlier contexts should be kept, the later
-contexts be discarded, not the opposite). Overly long fields should be
-discarded (or potentially truncated, depending on the field type). This
-specification does not recommend any specific stack or string limits for now.
-
-The usual terminal reset sequences should *not* affect the stack of contexts
-(this is a safety feature: a program down the stack should not be able to
-affect the stack further up, possibly hiding relevant information). A temporary
-TTY hangup (`vhangup()`) should result in a full reset of the stack.
-
-All provided data should be processed in a lenient, graceful fashion: if a
-sequence contains invalid fields, those fields should be ignored, but the rest
-of the fields should still be used. In particular, unknown fields should be
-ignored.
-
-The fields provided in these sequences should not contain sensitive
-information. Context IDs should not be considered confidential, but it is
-strongly recommended to generate them in a fashion that guarantees their
-sufficient uniqueness and avoids accidental or intended clashes with other
-contents.
-
-## Examples
-
-1. A new container `foobar` has been invoked by user `lennart` on host `zeta`:
- `OSC "3008;start=bed86fab93af4328bbed0a1224af6d40;type=container;user=lennart;hostname=zeta;machineid=3deb5353d3ba43d08201c136a47ead7b;bootid=d4a3d0fdf2e24fdea6d971ce73f4fbf2;pid=1062862;pidfdid=1063162;comm=systemd-nspawn;container=foobar" ST`
-
-2. This context ends: `OSC "3008;end=bed86fab93af4328bbed0a1224af6d40" ST`
-
-## Syntax in ABNF
-
-```abnf
-OSC = %x1B %x5D
-ST = %x1B %x5C
-
-DECIMAL = "0"-"9"
-HEX = "0"-"9" / "A"-"F" / "a-f"
-ID128 = 32*36(HEX / "-")
-UINT64 = 1*20DECIMAL
-ESCSEMICOLON = "\x3b"
-ESCBACKSLASH = "\x5c"
-SAFE = %x20-3a / %x3c-5b / %x5d-7e / ESCSEMICOLON / ESCBACKSLASH
-
-CTXID = 1*64SAFE
-TYPEENUM = "service" / "session" / "shell" / "command" / "vm" / "container" / "elevate" / "chpriv" / "subcontext" / "remote" / "boot" / "app"
-
-TYPE = "type=" TYPEENUM
-USER = "user=" 1*255SAFE
-HOSTNAME = "hostname=" 1*255SAFE
-MACHINEID = "machineid=" 1D128
-BOOTID = "bootid=" ID128
-PID = "pid=" UINT64
-PIDFDID = "pidfdid=" UINT64
-COMM = "comm=" 1*255SAFE
-CWD = "cwd=" 1*255SAFE
-CMDLINE = "cmdline=" *255SAFE
-VM = "vm=" 1*255SAFE
-CONTAINER = "container=" 1*255SAFE
-TARGETUSER = "targetuser=" 1*255SAFE
-TARGETHOST = "targethost=" 1*255SAFE
-SESSIONID = "sessionid=" 1*255SAFE
-
-STARTFIELD = TYPE / USER / HOSTNAME / MACHINEID / BOOTID / PID / PIDFDID / COMM / CWD / CMDLINE / VM / CONTAINER / TARGETUSER / TARGETHOST / SESSIONID
-STARTSEQ = OSC "3008;start=" CTXID *(";" STARTFIELD) ST
-
-EXITENUM = "success" / "failure" / "crash" / "interrupt"
-SIGNALENUM = "SIGBUS" / "SIGTRAP" / "SIGABRT" / "SIGSEGV" / …
-
-EXIT = "exit=" EXITENUM
-STATUS = "status=" UINT64
-SIGNAL = "signal=" SIGNALENUM
-
-ENDFIELD = EXIT / STATUS / SIGNAL
-ENDSEQ = OSC "3008;end=" CTXID *(";" ENDFIELD) ST
-```
-
-## Known OSC Prefixes
-
-Here's a list of OSC prefixes used by the various sequences currently in public
-use in various terminal emulators. It's not going to be complete, but I tried
-to do some reasonably thorough research to avoid conflicts with the new OSC
-sequence defined above.
-
-| OSC Prefix | Purpose |
-|----------------:|------------------------------------------------------------|
-| `OSC "0;…"` | Icon name + window title |
-| `OSC "1;…"` | Icon name |
-| `OSC "2;…"` | Window title |
-| `OSC "3;…"` | X11 property |
-| `OSC "4;…"` | Palette |
-| `OSC "5;…"` | Special palette |
-| `OSC "6;…"` | Disable special color |
-| `OSC "7;…"` | Report cwd |
-| `OSC "8;…"` | Hyperlink |
-| `OSC "9;…"` | Progress bar (conemu) [conflict: also growl notifications] |
-| `OSC "10;…"` | Change colors |
-| `OSC "11;…"` | " |
-| `OSC "12;…"` | " |
-| `OSC "13;…"` | " |
-| `OSC "14;…"` | " |
-| `OSC "15;…"` | " |
-| `OSC "16;…"` | " |
-| `OSC "17;…"` | " |
-| `OSC "18;…"` | " |
-| `OSC "19;…"` | " |
-| `OSC "21;…"` | Query colors (kitty) |
-| `OSC "22;…"` | Cursor shape |
-| `OSC "46;…"` | Log file |
-| `OSC "50;…"` | Set font |
-| `OSC "51;…"` | Emacs shell |
-| `OSC "52;…"` | Manipulate selection data (aka clipboard) |
-| `OSC "60;…"` | Query allowed |
-| `OSC "61;…"` | Query disallowed |
-| `OSC "99;…"` | Notifications (kitty) |
-| `OSC "104;…"` | Reset color |
-| `OSC "105;…"` | Enable/disable special color |
-| `OSC "110;…"` | Reset colors |
-| `OSC "111;…"` | " |
-| `OSC "112;…"` | " |
-| `OSC "113;…"` | " |
-| `OSC "114;…"` | " |
-| `OSC "115;…"` | " |
-| `OSC "116;…"` | " |
-| `OSC "117;…"` | " |
-| `OSC "118;…"` | " |
-| `OSC "119;…"` | " |
-| `OSC "133;…"` | Prompt/command begin/command end (finalterm/iterm2) |
-| `OSC "440;…"` | Audio (mintty) |
-| `OSC "633;…"` | vscode action (Windows Terminal) |
-| `OSC "666;…"` | "termprop" (vte) |
-| `OSC "701;…"` | Locale (mintty) |
-| `OSC "777;…"` | Notification (rxvt) |
-| `OSC "3008;…"` | This specification |
-| `OSC "7704;…"` | ANSI colors (mintty) |
-| `OSC "7750;…"` | Emoji style (mintty) |
-| `OSC "7770;…"` | Font size (mintty) |
-| `OSC "7771;…"` | Glyph coverage (mintty) |
-| `OSC "7721:…"` | Copy window title (mintty) |
-| `OSC "7777;…"` | Window size (mintty) |
-| `OSC "9001;…"` | Action (Windows Terminal) |
-| `OSC "1337;…"` | iterm2 multiplex seeuqnece |
-| `OSC "5522;…"` | Clipboard (kitty) |
-| `OSC "30001;…"` | Push color onto stack (kitty) |
-| `OSC "30101;…"` | Pop color from stack (kitty) |
-| `OSC "77119;…"` | Wide chars (mintty) |
+[This content has moved to the UAPI group website](https://uapi-group.org/specifications/specs/osc_context/)
projects / thirdparty / systemd.git / commitdiff
