--- /dev/null
+---
+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* effect 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) |
projects / thirdparty / systemd.git / commitdiff
