Debian Codegraph @

doc/passthrough.txt

raw
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.