9f38844cbad638ea787e51e80dd44aec08550aea
[netconf/netconf.git] / doc / control_socket.txt
1 netconf control socket
2 ======================
3 martin f. krafft <madduck@debian.org>
4 2007.06.11.1649, © martin f. krafft
5
6 Basics
7 ------
8 netconfd provides a control socket at /var/run/netconf/netconfd-ctl.sock with
9 mode 666. Clients can connect to this socket and are authenticated by
10 SO_PEERCRED, which lets netconfd know their PID and effective UID/GID at the
11 time of the connect.
12
13 The following is the initial idea for a protocol, which is more or less
14 currently implemented, but does not meet the needs. See below for more
15 discussion:
16
17   The protocol spoken over the socket shall be a simple request-response
18   protocol. Requests commence with a command taking a set of mandatory arguments
19   depending on the command.
20
21   An arbitrary number of optional parameters may follow the command line, one
22   parameter per line. The RFC 822 format shall be used. Parameters are stored in
23   a dictionary, so parameters on later lines will override earlier lines.
24
25   The request ends with EOF.
26
27   The response shall be at least one line, formatted similar to HTTP responses
28   and re-using the HTTP status codes. An empty request will thus receive a 400
29   status code while a successful request will be answered with 200.
30
31   Additional parameters/response headers may be returned in RFC 822 format.
32   An empty line ends the headers and may be followed by arbitrary text, such as
33   the output of a daemon (dhclient), which netconfd invoked on behalf of the
34   requesting client.
35
36   An EOF terminates the response and indicates that the daemon is done
37   processing the request.
38
39 This protocol does not allow for chatting between client and daemon, for
40 instance when a passphrase is needed. Also, it might make sense to simply
41 use SOAP for the communication. Thus this is will likely have to be
42 reimplemented soon.
43
44 <fast-forward 2 hours> After a talk with Enrico, SOAP is out of the question
45 because it's not real-time. Instead, the protocol will simply be "as much info
46 as possible, let the client filter", and each line shall be prefixed to allow
47 the client to handle it properly, e.g. I/E/C/R for stdIn, stdErr, returnCode
48 and Request respectively.
49
50 Remember that by our (current) design, we have a direct, one-way communication
51 channel between the daemon or whatever module it currently delegated to and
52 the client via a write-only file descriptor. The client waits on the file
53 descriptor and processes all data until EOF. It may decide to close the
54 connection earlier if it's happy and does not care about the future, or it may
55 keep listening forever. The daemon of course must be able to handle BROKEN
56 PIPE in that case.
57
58 Instead of implementing a chat protocol, why not let the daemon create a named
59 pipe if necessary and tell the client something like
60
61   NEED PASSPHRASE /lib/rw/netconf.T3Mpf1I3
62
63 and then listen on the pipe until timeout. Just a thought.
64
65 Commands
66 --------
67
68 IFUP <iface>
69   request that netconfd bring up the interface.
70
71
72 IFDOWN <iface>
73   request that netconfd bring down the interface.
74
75
76 IFSTATUS <iface>
77   request status information about the interface.
78
79
80 GETCONF <iface>
81   return the configuration that would be used for the interface without
82   actually doing anything.
83
84
85 QUIT
86   asks the daemon to quit.
87
88 This is all WIP.
89
90 // vim: ft=asciidoc