ia64/xen-unstable

view docs/misc/xenstore.txt @ 16609:a4fadcab5cb0

docs/misc/xenstore.txt minor fixes
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Fri Dec 14 10:12:15 2007 +0000 (2007-12-14)
parents 671ef298d491
children 95bb6485d29d
line source
1 Xenstore protocol specification
2 -------------------------------
4 Xenstore implements a database which maps filename-like pathnames
5 (also known as `keys') to values. Clients may read and write values,
6 watch for changes, and set permissions to allow or deny access. There
7 is a rudimentary transaction system.
9 While xenstore and most tools and APIs are capable of dealing with
10 arbitrary binary data as values, this should generally be avoided.
11 Data should generally be human-readable for ease of management and
12 debugging; xenstore is not a high-performance facility and should be
13 used only for small amounts of control plane data. Therefore xenstore
14 values should normally be 7-bit ASCII text strings containing bytes
15 0x20..0x7f only, and should not contain a trailing nul byte. (The
16 APIs used for accessing xenstore generally add a nul when reading, for
17 the caller's convenience.)
19 A separate specification will detail the keys and values which are
20 used in the Xen system and what their meanings are. (Sadly that
21 specification currently exists only in multiple out-of-date versions.)
24 Paths are /-separated and start with a /, just as Unix filenames.
26 We can speak of two paths being <child> and <parent>, which is the
27 case if they're identical, or if <parent> is /, or if <parent>/ is an
28 initial substring of <child>. (This includes <path> being a child of
29 itself.)
31 If a particular path exists, all of its parents do too. Every
32 existing path maps to a possibly empty value, and may also have zero
33 or more immediate children. There is thus no particular distinction
34 between directories and leaf nodes. However, it is conventional not
35 to store nonempty values at nodes which also have children.
37 The permitted character for paths set is ASCII alphanumerics and plus
38 the four punctuation characters -/_@ (hyphen slash underscore atsign).
39 @ should be avoided except to specify special watches (see below).
40 Doubled slashes and trailing slashes (except to specify the root) are
41 forbidden. The empty path is also forbidden.
44 Communication with xenstore is via either sockets, or event channel
45 and shared memory, as specified in io/xs_wire.h: each message in
46 either direction is a header formatted as a struct xsd_sockmsg
47 followed by xsd_sockmsg.len bytes of payload.
49 The payload syntax varies according to the type field. Generally
50 requests each generate a reply with an identical type, req_id and
51 tx_id. However, if an error occurs, a reply will be returned with
52 type ERROR, and only req_id and tx_id copied from the request.
54 A caller who sends several requests may receive the replies in any
55 order and must use req_id (and tx_id, if applicable) to match up
56 replies to requests. (The current implementation always replies to
57 requests in the order received but this should not be relied on.)
60 ---------- Xenstore protocol details - introduction ----------
62 The payload syntax and semantics of the requests and replies are
63 described below. In the payload syntax specifications we use the
64 following notations:
66 | A nul (zero) byte.
67 <foo> A string guaranteed not to contain any nul bytes.
68 <foo|> Binary data (which may contain zero or more nul bytes)
69 <foo>|* Zero or more strings each followed by a trailing nul
70 <foo>|+ One or more strings each followed by a trailing nul
71 ? Reserved value (may not contain nuls)
72 ?? Reserved value (may contain nuls)
74 Except as otherwise noted, reserved values are believed to be sent as
75 empty strings by all current clients. Clients should not send
76 nonempty strings for reserved values; those parts of the protocol may
77 be used for extension in the future.
80 Error replies are as follows:
82 ERROR E<something>|
83 Where E<something> is the name of an errno value
84 listed in io/xs_wire.h. Note that the string name
85 is transmitted, not a numeric value.
88 Where no reply payload format is specified below, success responses
89 have the following payload:
90 OK|
92 Values commonly included in payloads include:
94 <path>
95 Specifies a path in the hierarchical key structure.
96 If <path> starts with a / it simply represents that path.
98 <path> is allowed not to start with /, in which case the
99 caller must be a domain (rather than connected via a socket)
100 and the path is taken to be relative to /local/domain/<domid>
101 (eg, `x/y' sent by domain 3 would mean `/local/domain/3/x/y').
103 <domid>
104 Integer domid, represented as decimal number 0..65535.
105 Parsing errors and values out of range generally go
106 undetected. The special DOMID_... values (see xen.h) are
107 represented as integers; unless otherwise specified it
108 is an error not to specify a real domain id.
112 The following are the actual type values, including the request and
113 reply payloads as applicable:
116 ---------- Database read, write and permissions operatons ----------
118 READ <path>| <value|>
119 WRITE <path>|<value|>
120 Store and read the octet string <value> at <path>.
121 WRITE creates any missing parent paths, with empty values.
123 MKDIR <path>|
124 Ensures that the <path> exists, by necessary by creating
125 it and any missing parents with empty values. If <path>
126 or any parent already exists, its value is left unchanged.
128 RM <path>|
129 Ensures that the <path> does not exist, by deleting
130 it and all of its children. It is not an error if <path> does
131 not exist, but it _is_ an error if <path>'s immediate parent
132 does not exist either.
134 DIRECTORY <path>| <child-leaf-name>|*
135 Gives a list of the immediate children of <path>, as only the
136 leafnames. The resulting children are each named
137 <path>/<child-leaf-name>.
139 GET_PERMS <path>| <perm-as-string>|+
140 SET_PERMS <path>|<perm-as-string>|+?
141 <perm-as-string> is one of the following
142 w<domid> write only
143 r<domid> read only
144 b<domid> both read and write
145 n<domid> no access
146 See http://wiki.xensource.com/xenwiki/XenBus section
147 `Permissions' for details of the permissions system.
149 ---------- Watches ----------
151 WATCH <wpath>|<token>|?
152 Adds a watch.
154 When a <path> is modified (including path creation, removal,
155 contents change or permissions change) this generates an event
156 on the changed <path>. Changes made in transactions cause an
157 event only if and when committed. Each occurring event is
158 matched against all the watches currently set up, and each
159 matching watch results in a WATCH_EVENT message (see below).
161 The event's path matches the watch's <wpath> if it is an child
162 of <wpath>.
164 <wpath> can be a <path> to watch or @<wspecial>. In the
165 latter case <wspecial> may have any syntax but it matches
166 (according to the rules above) only the following special
167 events which are invented by xenstored:
168 @introduceDomain occurs on INTRODUCE
169 @releaseDomain occurs on any domain crash or
170 shutdown, and also on RELEASE
171 and domain destruction
173 When a watch is first set up it is triggered once straight
174 away, with <path> equal to <wpath>. Watches may be triggered
175 spuriously. The tx_id in a WATCH request is ignored.
177 Watches are supposed to be restricted by the permissions
178 system but in practice the implementation is imperfect.
179 Applications should not rely on being sent a notification for
180 paths that they cannot read; however, an application may rely
181 on being sent a watch when a path which it _is_ able to read
182 is deleted even if that leaves only a nonexistent unreadable
183 parent. A notification may omitted if a node's permissions
184 are changed so as to make it unreadable, in which case future
185 notifications may be suppressed (and if the node is later made
186 readable, some notifications may have been lost).
188 WATCH_EVENT <epath>|<token>|
189 Unsolicited `reply' generated for matching modfication events
190 as described above. req_id and tx_id are both 0.
192 <epath> is the event's path, ie the actual path that was
193 modifed; however if the event was the recursive removal of an
194 parent of <wpath>, <epath> is just
195 <wpath> (rather than the actual path which was removed). So
196 <epath> is a child of <wpath>, regardless.
198 Iff <wpath> for the watch was specified as a relative pathname,
199 the <epath> path will also be relative (with the same base,
200 obviously).
202 UNWATCH <wpath>|<token>|?
204 ---------- Transactions ----------
206 TRANSACTION_START | <transid>|
207 <transid> is an opaque uint32_t allocated by xenstored
208 represented as unsigned decimal. After this, transaction may
209 be referenced by using <transid> (as 32-bit binary) in the
210 tx_id request header field. When transaction is started whole
211 db is copied; reads and writes happen on the copy.
212 It is not legal to send non-0 tx_id in TRANSACTION_START.
213 Currently xenstored has the bug that after 2^32 transactions
214 it will allocate the transid 0 for an actual transaction.
216 TRANSACTION_END T|
217 TRANSACTION_END F|
218 tx_id must refer to existing transaction. After this
219 request the tx_id is no longer valid and may be reused by
220 xenstore. If F, the transaction is discarded. If T,
221 it is committed: if there were any other intervening writes
222 then our END gets get EAGAIN.
224 The plan is that in the future only intervening `conflicting'
225 writes cause EAGAIN, meaning only writes or other commits
226 which changed paths which were read or written in the
227 transaction at hand.
229 ---------- Domain management and xenstored communications ----------
231 INTRODUCE <domid>|<mfn>|<evtchn>|?
232 Notifies xenstored to communicate with this domain.
234 INTRODUCE is currently only used by xend (during domain
235 startup and various forms of restore and resume), and
236 xenstored prevents its use other than by dom0.
238 <domid> must be a real domain id (not 0 and not a special
239 DOMID_... value). <mfn> must be a machine page in that domain
240 represented in signed decimal (!). <evtchn> must be event
241 channel is an unbound event channel in <domid> (likewise in
242 decimal), on which xenstored will call bind_interdomain.
243 Violations of these rules may result in undefined behaviour;
244 for example passing a high-bit-set 32-bit mfn as an unsigned
245 decimal will attempt to use 0x7fffffff instead (!).
247 RELEASE <domid>|
248 Manually requests that xenstored disconnect from the domain.
249 The event channel is unbound at the xenstored end and the page
250 unmapped. If the domain is still running it won't be able to
251 communicate with xenstored. NB that xenstored will in any
252 case detect domain destruction and disconnect by itself.
253 xenstored prevents the use of RELEASE other than by dom0.
255 GET_DOMAIN_PATH <domid>| <path>|
256 Returns the domain's base path, as is used for relative
257 transactions: ie, /local/domain/<domid> (with <domid>
258 normalised). The answer will be useless unless <domid> is a
259 real domain id.
261 IS_DOMAIN_INTRODUCED <domid>| T| or F|
262 Returns T if xenstored is in communication with the domain:
263 ie, if INTRODUCE for the domain has not yet been followed by
264 domain destruction or explicit RELEASE.
266 RESUME <domid>|
268 Arranges that @releaseDomain events will once more be
269 generated when the domain becomes shut down. This might have
270 to be used if a domain were to be shut down (generating one
271 @releaseDomain) and then subsequently restarted, since the
272 state-sensitive algorithm in xenstored will not otherwise send
273 further watch event notifications if the domain were to be
274 shut down again.
276 It is not clear whether this is possible since one would
277 normally expect a domain not to be restarted after being shut
278 down without being destroyed in the meantime. There are
279 currently no users of this request in xen-unstable.
281 xenstored prevents the use of RESUME other than by dom0.
283 ---------- Miscellaneous ----------
285 DEBUG print|<string>|?? sends <string> to debug log
286 DEBUG print|<thing-with-no-nul> EINVAL
287 DEBUG check|?? checks xenstored innards
288 DEBUG <anything-else|> no-op (future extension)
290 These requests should not generally be used and may be
291 withdrawn in the future.