| 1 |
The Passthrough Frontend |
| 2 |
======================== |
| 3 |
|
| 4 |
The Passthrough frontend basically replays the ConfModule protocol over a |
| 5 |
Unix domain socket so that other programs can "listen" in and actually |
| 6 |
implement the user interface. With some minor additions, the protocol is |
| 7 |
designed to mirror the ConfModule protocol as closely as feasible. |
| 8 |
|
| 9 |
A typical session goes like this: (time moves downwards) |
| 10 |
In this diagram, and in the rest of this document, "Passthrough" denotes |
| 11 |
the Debconf passthrough frontend, Frontend represents a user-supplied |
| 12 |
program that understands this interface. |
| 13 |
|
| 14 |
|
| 15 |
Confmodule Passthrough Frontend |
| 16 |
--------------- -------------- ---------------------- |
| 17 |
CAPB backup -> |
| 18 |
CAPB backup -> |
| 19 |
<- 0 backup |
| 20 |
<- CAPB backup |
| 21 |
INPUT foo/bar -> (stored) |
| 22 |
<- 0 question will be asked |
| 23 |
INPUT foo/baz -> (stored) |
| 24 |
<- 0 question will be asked |
| 25 |
GO -> |
| 26 |
DATA foo/bar type boolean -> |
| 27 |
<- 0 OK |
| 28 |
DATA foo/bar description some description -> |
| 29 |
<- 0 OK |
| 30 |
DATA foo/bar extended_description etc -> |
| 31 |
<- 0 OK |
| 32 |
INPUT medium foo/bar -> |
| 33 |
<- 0 OK |
| 34 |
DATA foo/baz description some description -> |
| 35 |
<- 0 OK |
| 36 |
DATA foo/baz extended_description etc -> |
| 37 |
<- 0 OK |
| 38 |
INPUT low foo/baz -> |
| 39 |
<- 0 OK |
| 40 |
GO -> |
| 41 |
<- 0 OK (or 30 GOBACK) |
| 42 |
GET foo/bar -> |
| 43 |
(stored) <- 0 true |
| 44 |
GET foo/baz -> |
| 45 |
(stored) <- 0 my input |
| 46 |
<- 0 OK |
| 47 |
GET foo/bar -> |
| 48 |
<- true |
| 49 |
GET foo/baz -> |
| 50 |
<- my input |
| 51 |
STOP |
| 52 |
|
| 53 |
|
| 54 |
|
| 55 |
Each request from Passthrough will block until it receives a reply from |
| 56 |
the Frontend. |
| 57 |
|
| 58 |
Communications |
| 59 |
~~~~~~~~~~~~~~ |
| 60 |
Communication between the Passthrough module and the Frontend takes place |
| 61 |
over a Unix domain socket connection. The DEBCONF_PIPE environment variable |
| 62 |
must be set to the filename to use for the socket. |
| 63 |
|
| 64 |
When the Passthrough module starts up, it expects the socket to already |
| 65 |
exist. The Frontend is responsible for creating the socket and be ready |
| 66 |
to listen on it prior to invoking Debconf with the Passthrough module. |
| 67 |
|
| 68 |
The socket should be created with mode 0400, and owned by root:root |
| 69 |
It should be removed when the Frontend exits. |
| 70 |
|
| 71 |
All communication between the Passthrough module and the Frontend is defined |
| 72 |
to be encoded in UTF-8. Both sides are responsible for recoding between |
| 73 |
UTF-8 and whatever their internal character encoding may be. |
| 74 |
|
| 75 |
DATA/INPUT/GO/GET mechanism |
| 76 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 77 |
Unlike existing Debconf frontends, the Frontend does not have access |
| 78 |
to the template information directly. In order for it to have that |
| 79 |
information, the Passthrough module is responsible for sending it |
| 80 |
the information. This is done via the DATA mechanism, by sending |
| 81 |
commands like this: |
| 82 |
|
| 83 |
DATA <tag> <item> <value> |
| 84 |
|
| 85 |
where: |
| 86 |
<tag> is the name of the template, e.g. debconf/frontend |
| 87 |
<item> is one of {"type", "description", "extended_description", "choices"} |
| 88 |
<value> is the value of the <item>, with all newlines converted to |
| 89 |
"\\n" (i.e. 0x2F 0x6E) |
| 90 |
|
| 91 |
All DATA information will be sent to the Frontend prior to sending any |
| 92 |
INPUT commands with the same tag. |
| 93 |
|
| 94 |
After DATA commands for a <tag> is sent, a corresponding SET command may |
| 95 |
be sent to set the default value for that question, if a default was |
| 96 |
defined, viz: |
| 97 |
|
| 98 |
SET <tag> <value> |
| 99 |
where: |
| 100 |
<tag> is the name of the template |
| 101 |
<value> is the default value of the question |
| 102 |
|
| 103 |
If any substitution variables were set, corresponding SUBST commands may be |
| 104 |
sent: |
| 105 |
|
| 106 |
SUBST <tag> <key> <value> |
| 107 |
where: |
| 108 |
<tag> is the name of the template |
| 109 |
<key> is the name of the variable to substitute |
| 110 |
<value> is the value to substitute in place of the named variable |
| 111 |
|
| 112 |
Finally, a corresponding INPUT command will be sent as: |
| 113 |
|
| 114 |
INPUT <priority> <tag> |
| 115 |
where: |
| 116 |
<priority> is the priority of the question |
| 117 |
<tag> is the name of the template |
| 118 |
|
| 119 |
An INPUT command will be issued to the Frontend for each INPUT command |
| 120 |
received by the Passthrough module prior to a GO command. After all INPUT |
| 121 |
commands have been sent to the Frontend, a GO will be sent. At this point |
| 122 |
the Frontend should query the user for information, and return either: |
| 123 |
0 OK if everything is ok |
| 124 |
or: |
| 125 |
30 GOBACK if the user requested to go back to a previous question |
| 126 |
|
| 127 |
If a GOBACK request was received and the ConfModule supports the backup |
| 128 |
capability, the previous set of questions will be asked again, with all |
| 129 |
DATA commands reissued. |
| 130 |
|
| 131 |
Otherwise, if an OK condition was returned, the Passthrough module will issue |
| 132 |
the same number of GET commands as previously sent INPUT commands, in the |
| 133 |
form of: |
| 134 |
|
| 135 |
GET <tag> |
| 136 |
|
| 137 |
to which the Frontend should reply with: |
| 138 |
|
| 139 |
0 <value> |
| 140 |
where: |
| 141 |
<value> was the answer to the question of the given <tag> |
| 142 |
|
| 143 |
Shutdown |
| 144 |
~~~~~~~~ |
| 145 |
Whether the ConfModule explicitly requests a STOP, or when the ConfModule ends, |
| 146 |
the passthrough module will send a STOP command to the Frontend to inform it |
| 147 |
that the current configuration session has been completed. |
| 148 |
|
| 149 |
Error Handling |
| 150 |
~~~~~~~~~~~~~~ |
| 151 |
At any point in time, the Frontend may indicate an error condition by sending |
| 152 |
a response such as: |
| 153 |
100 <error message> |
| 154 |
|
| 155 |
This signals the Passthrough module that something is wrong. At the time of |
| 156 |
this writing, unfortunately, the Passthrough module does not handle errors |
| 157 |
very gracefully. |
| 158 |
|
| 159 |
Implementation Details/Hints for the Frontend |
| 160 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 161 |
The frontend needs to be careful about storing information across multiple |
| 162 |
DATA/INPUT/GO/GET requests. After any GET requests, the next DATA/INPUT |
| 163 |
request should cause any pending question/answer information at the Frontend |
| 164 |
side to be discarded. Similarly, when a Frontend sends back a "30 GOBACK" |
| 165 |
response to a GO command, it should take care to clear out previous |
| 166 |
question/answer information. |