From: Lennart Poettering Date: Thu, 18 Dec 2025 09:12:19 +0000 (+0100) Subject: docs: add redirection of the osc context to uapi website X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d91aed3b55f01707c02e72b61734df009eb9c08a;p=thirdparty%2Fsystemd.git docs: add redirection of the osc context to uapi website --- diff --git a/docs/OSC_CONTEXT.md b/docs/OSC_CONTEXT.md index db06458f10d..56a3f499c5a 100644 --- a/docs/OSC_CONTEXT.md +++ b/docs/OSC_CONTEXT.md @@ -1,339 +1 @@ ---- -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/)