aboutsummaryrefslogtreecommitdiff
path: root/doc/ctl.texi
blob: 4c220ecceda4b021223835a8606e2a304baec09f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
@c This is part of the GNU Pies manual.
@c Copyright (C) 2009--2020 Sergey Poznyakoff
@c This file is distributed under GFDL 1.3 or any later version
@c published by the Free Software Foundation.

  This appendix describes @dfn{control API} used to communicate with the
running @command{pies} daemon via the control interface
(@pxref{control}).  This API is used by @command{piesctl} (@pxref{piesctl}).

The API is designed as a REST service and uses HTTP.  Queries are sent to
pies @dfn{endpoints}, each of which serves a distinct purpose.  Data
are serialized using the JSON format.

The sections below describe in detail each endpoint and associated
with it request types.

@node /instance
@appendixsec /instance
  This endpoint controls the state of the running @command{pies}
instance and accepts the following HTTP requests: @code{GET},
@code{DELETE}, @code{POST} (or @code{PUT}).

@deffn {Request} GET /instance
  Retrieves information about the current instance.  The response body
is a JSON object with the following attributes:

@table @samp
@item PID
PID of the running daemon.

@item argv
Array of the command line arguments.  @samp{argv[0]} is the program
name.

@item binary
Name of the @command{pies} binary.

@item instance
The instance name.  @xref{instances}.

@item package
Package name (the string @samp{GNU Pies}).

@item version
Package version
@end table

Any of these can be used in the URI to request the information about
that particular attribute, e.g.:

@example
GET /instance/argv @result{} @{"argv":["pies", "-x2"]@}
@end example
@end deffn

@deffn {Request} DELETE /instance/PID
Stops the current @command{pies} instance.
@end deffn

@deffn {Request} PUT /instance/PID
@deffnx {Request} POST /instance/PID
Restarts the current @command{pies} instance.
@end deffn

@node /conf
@appendixsec /conf

The @samp{/conf} endpoint allows the client to inspect and change the
configuration of the running @command{pies} instance.

@node /conf/files
@appendixsubsec /conf/files

@deffn {Request} GET /conf/files
Return list of configuration files.  On success, a JSON array is
returned.  Each array element is an object with two attributes:

@defvr {Attr} string file
Pathname of the configuration file.
@end defvr

@defvr {Attr} string syntax
Configuration file syntax (@pxref{Syntax}).
@end defvr

For example:

@example
GET /conf/files @result{}
[@{"file":"/etc/pies.conf", "syntax":"pies"@},
 @{"file":"/etc/inetd.conf", "syntax":"inetd"@}]
@end example
@end deffn

@deffn {Request} POST /conf/files
Adds a new configuration file.   The body must be a JSON object with
@samp{file} and @samp{syntax} attributes, as described above.  The
@samp{file} value must contain a pathname of a configuration file
written in a syntax supplied by the @samp{syntax} attribute
(@pxref{Syntax}).

This request returns 201 code on success.  To actually parse and load
the added configuration file, send a @samp{PUT} request to
@samp{/conf/runtime} (@pxref{/conf/runtime}).
@end deffn

@deffn {Request} DELETE /conf/files/true
Clears all previously configured configuration files.  Responds with:

@example
@{ "message":"file list cleared", "status":"OK" @}
@end example
@end deffn

@deffn {Request} DELETE /conf/files/[@var{list}]
Removes files named in the @var{list} from the list of configuration files.

The @samp{DELETE} response is 200 on success.  To actually update the
configuration of the running process, send a @samp{PUT} request to
@samp{/conf/runtime} (@pxref{/conf/runtime}).
@end deffn

@node /conf/runtime
@appendixsubsec /conf/runime

This is a write-only URI.  The only request supported is
@samp{PUT /conf/runtime}.  It initiates reloading of the
@command{pies} configuration.  Usually, this request is sent after one
or more @samp{POST} and/or @samp{DELETE} requests to
@samp{/conf/files}, in order to finalize the changes applied to the
configuration.

@node /programs
@appendixsec /programs

  A request sent to this URI selects one or more components and
applies operation defined by the request type to all of them.

  Components are selected using a query in the form of JSON object
(a @dfn{selector}).  Valid selectors are:  

@table @samp
@item null
@itemx false
Matches nothing.

@item true
Matches all components.

@item @{ "op": "component", "arg": @var{tag} @}
Matches component with the given @var{tag} (@pxref{tag}).

@item @{ "op": "type", "arg": "component" @}
Matches all components.

@item @{ "op": "type", "arg": "command" @}
Matches all commands.

@item @{ "op": "mode", "arg": @var{mode} @}
Matches all components with the given @var{mode}.  @xref{component
mode}.

@item @{ "op": "active" @}
Matches all active components.

@item @{ "op": "status", "arg": @var{status} @}
Matches all components with the given @var{status} (one of
@samp{stopped}, @samp{running}, @samp{listener}, @samp{sleeping},
@samp{stopping}, @samp{finished}).  @xref{component status} for a
discussion of these values.

@item @{ "op: "not", "arg": @var{condition} @}
Negates @var{condition}, which is any valid selector.

@item @{ "op": "and", "arg": @var{array} @}
Returns the result of logical conjunction on the @var{array} of selectors.

@item @{ "op": "or", "arg": @var{array} @}
Returns the result of logical disjunction on the @var{array} of selectors.
@end table

  For example, the following selector matches all components that are
in @samp{running} state, excepting components of @samp{inetd} mode:

@example
@{ "op": "and",
   "arg": [ @{ "op": "type", "arg": "component" @},
            @{ "op": "not", "arg": @{ "op": "mode", "arg": "inetd" @}
          ]
@}
@end example

The following requests are supported:

@deffn {Request} GET /programs?@var{selector}
@deffnx {Request} GET /programs/@var{tag}
  This request returns information about components matched by
@var{selector} (see below for the @samp{/programs/@var{tag} variant}.
The response is a JSON array of descriptions.  If no component matches
the @var{selector}, empty array is returned.  Each description is a
JSON object with the following attributes:

@deftypevr {Attr} string type
Type of the described entity: @samp{component} for an instance of a
configured component, and @samp{command} for a command run as a part
of exit action (@pxref{Exit Actions}), including mailer invocations
(@pxref{Notification}).
@end deftypevr

@deftypevr {Attr} string mode
Mode of the entity.  @xref{component mode}.
@end deftypevr

@anchor{component status}
@deftypevr {Attr} string status
Entity status.   Possible values are:

@table @code
@item finished
A @samp{once} or @samp{startup} component has finished.

@item listener
Component is an inetd listener.

@item running
Component is running.

@item sleeping
Component has been put to sleep because of excessive number of
failures (@pxref{respawn}).

@item stopped
Component is stopped.

@item stopping
Component is being stopped (a @code{SIGTERM} was sent).
@end table
@end deftypevr

@deftypevr {Attr} boolean active
Whether this component is active.  By default, all components are
active, unless marked with a @samp{disable} flag (@pxref{flags}) or
administratively stopped.
@end deftypevr

@deftypevr {Attr} integer PID
PID of the running process.
@end deftypevr

@deftypevr {Attr} string URL
(for @samp{inetd} components) URL of the socket the component is
listening on.
@end deftypevr

@deftypevr {Attr} string service
(for @samp{tcpmux} components) TCPMUX service name.  @xref{TCPMUX}.
@end deftypevr

@deftypevr {Attr} string master
(for @samp{tcpmux} components) Tag of master TCPMUX component.
@xref{TCPMUX}.
@end deftypevr

@deftypevr {Attr} string runlevels
For inittab components, the string of runlevels this component is
configured to run in.  @xref{Init Process}.
@end deftypevr

@deftypevr {Attr} integer wakeup-time
If component is in the @samp{sleeping} state, this attribute gives the
number of seconds after which an attempt will be made to restart it.
@end deftypevr

@deftypevr {Attr} array argv
Component command line split into words.
@end deftypevr

@deftypevr {Attr} string command
Component command.
@end deftypevr
@end deffn

@deffn {Request} DELETE /programs?@var{selector}
@deffnx {Request} DELETE /programs/@var{tag}
Stop components matched by the @var{selector}.  On success returns:

@example
@{ "status":"OK" @}
@end example

@noindent
On failure, returns

@example
@{ "status":"ER", "message": @var{text} @}
@end example

@noindent
where @var{text} is a textual human-readable description of the failure.
@end deffn

@deffn {Request} PUT /programs?@var{selector}
@deffnx {Request} PUT /programs/@var{tag}
Start components matched by @var{selector}.
@end deffn

@deffn {Request} POST /programs
Restart components.  The selector is supplied in the request content.
@end deffn

Wherever a selector is passed via query parameters, a simplified form
with component tag passed as query path is also allowed.  For example:

@example
 GET /programs/@var{tag}
@end example

@noindent
is a shortcut for:

@example
@{ "op":"and",
   "arg":[ @{"op":"type", "arg":"component"@},
           @{"op":"component", "arg":@var{tag} @} ] @}
@end example

@node /alive
@appendixsec /alive

  This entry point accepts only @samp{GET} requests.  The URI must not
be empty and must not include sub-directories (parts separated with
slashes).  It is treated as the name of the component to return the
status of.  E.g. querying @samp{/alive/foo} returns the status of the
component named @samp{foo}.  The status is returned as HTTP status
code:

@table @asis
@item 200
The component is up and running.  For regular components that means
that the corresponding program is running.  For @samp{inetd}
components that means that the listener is listening on the configured
socket.

@item 403
No component specified.

@item 404
There is no such component.

@item 503
The component is not running.  This means that it has failed, or has
been stopped administratively or (for @samp{once} and @samp{startup}
components) that it has run once and finished.

If the component has failed, the @samp{Retry-After:} HTTP header
contains the number of seconds after which @command{pies} will retry
starting this component.
@end table

@node /runlevel
@appendixsec /runlevel
  This URI is active when @command{pies} runs as init process
(@pxref{Init Process}).  It supports two requests:

@deffn {Request} GET /runlevel
Returns the current state of the program as a JSON object with the
following attributes:

@defvr {Attr} string runlevel
Current runlevel.  @xref{Runlevels}.
@end defvr

@defvr {Attr} string prevlevel
Previous runlevel (@samp{N} if none).
@end defvr

@defvr {Attr} string bootstate
Boot state.  @xref{startup states}.
@end defvr

@defvr {Attr} string initdefault
Default runlevel.
@end defvr
@end deffn

@deffn {Request} PUT /runlevel/@{"runlevel":@var{L}@}
Initiates transition from the current runlevel to runlevel @var{L}
(@pxref{Runlevels}).
@end deffn

@node /environ
@appendixsec /environ
    This URI is active when @command{pies} runs as init process
(@pxref{Init Process}).  It manipulates the program initial
environment, i.e. the environment that all programs inherit.
@xref{Init Environment}.

@deffn {Request} GET /environ/
Returns entire environment formatted as a JSON array of strings.  On
success, the 200 response is returned:

@example
["RUNLEVEL=3", "CONSOLE=/dev/tty", ...]  
@end example
@end deffn

@deffn {Request} GET /environ/@var{var}
Returns the value of the environment variable @var{var}, if such is
defined.  On success, the 200 response carries the object:

@example
@{ "status":"OK", "value":@var{string} @}
@end example

@noindent
If the variable @var{var} is not defined, a 404 response is returned.
On error, a 403 response is returned.  In both cases, the response
body is the usual @command{pies} diagnostics object:

@example
@{ "status":"ER", "message":@var{text} @}
@end example
@end deffn

@deffn {Request} DELETE /environ/@var{var}
Deletes from the environment the variable @var{var}.  On success,
responds with HTTP 200:

@example
@{ "status":"OK" @}
@end example

Error responses are the same as for @samp{GET}.
@end deffn

@deffn {Request} PUT /environ/@var{name}=@var{value}
Initializes environment variable @var{name} to @var{value}.  See
@samp{GET} for the possible responses.
@end deffn



Return to:

Send suggestions and report system problems to the System administrator.