Re: Api idés

I think a binary, RLE API would be way over the top. This is in no way
performance critical. A text stream based API is way easier to develop
against, and debug.

Some rough notes on how that could look:

1) Overall structure of communication:

Transport over UNIX domain socket (no auth required by default), or TCP
(auth required).

Daemon never sends anything unless provoked (sent a command line). What the
daemon sends in response to a command, depends on the command. All sent
commands and replies are \n or \r\n terminated text lines (no fancy
encoding - or is there any need for that that I can't see?).

Command lines sent to the daemon are space separated token sequences. They
all start with a keyword, further tokens are interpreted accordingly.

Replies, when expected, all start with a keyword (indicating success,
failure, what it expected next for modal stuff), with the rest of the line
purely informational. These reply keywords are chosen to NEVER be valid
first keywords of configuration or status output lines (stuff that would
appear in show commands that we'd want to be easily copy+pasteable)

Any request or reply keyword is documented and interpreted case sensitive.
Programmers should not need to do case conversion to recognize stuff.

2) Authentication and Authorization

When required (*), the first thing a client MUST do is authenticate. If the
client thinks it does not need to authenticate, but it should, its first
command, unless it starts an authentication, elicits a response, e.g.
"AUTH-FAIL", and the daemon drops the connection immediately afterwards.

Authentication starts with a command "auth user <USERNAME>". That will
always elicit a response:
* "AUTHENTICATED <AUTHORIZATION-LIST*>" when no authentication is required.
Client may proceed, and use any of the commands covered by the
space-separated list of authorization tokens (may be stuff like CONFIG,
SHOW, SHUTDOWN, ... and all commands should clearly document which
authorization tokens are required to use them).  This kind of reply is also
used when a user that needs authentication, has successfully completed it.
* "AUTH-NEEDED <SCHEMES+>" when further authentication is needed; lists,
space separated, authentication schemes permitted. NOTE: this list MUST
reflect what configuration allows, and MUST NOT vary depending on the
<USERNAME> from the request.

When AUTH-NEEDED, client then sends "auth scheme <SCHEME> <CREDENTIALS*>".
For schemes that don't need further steps, an AUTHENTICATED reply (see
above) is sent when the credentials were good, or "AUTH-FAIL" and
connection close otherwise. For schemes that require further steps, a reply
of "AUTH-CHALLENGE <SCHEME> <whatever*>" is sent, and the client is
expected to send another "auth scheme <SCHEME> <CREDENTIALS*>" line to
complete.

Once the client successfully authenticated, it knows that it can do (via
the AUTHORIZATION-LIST from the AUTHENTICATED reply.) Maybe the client
further would like to authenticate the daemon - that could be requested
with an "auth yourself <...>" command, won't go into details now.

Auth _configuration_ should be only possible with suitable privilege, only
shown (when listing config) with suitable privilege; auth credentials
ALWAYS separate from online modifiable configuration (separate config file
- no need to be easy to change on the fly)

3) Command Discovery

For the benefit of CLI clients supporting autocompletion, it might be
interesting to implement a discovery mechanism regarding commands supported
by the daemon. Thinking along these lines:

* "info commands" would result in a multiline reply. Each line starts with
"COMMAND " followed by a single valid command syntax. Placeholders there,
e.g. <IP>, would indicate variable parts of the command. The list is
terminated by a line starting / reading "COMMAND-END".
* "info version" would result in a single line reply "VERSION
<daemon-version-number> <hash-of-valid-command-defining-config-parts>".
This would be good for the benefit of CLI clients to be able to cache "info
commands" replies - the CLI could keep the command list for the given
authenticated user for as long as the daemon-version-number and hash
doesn't change.

4) Configuration Changes

Using a "configure" command, the client indicates it wants to change
configuration. This mail is already too long, though, so I'll stop here :)

best regards
  Patrick

------------------------------------------------------------------------------
One dashboard for servers and applications across Physical-Virtual-Cloud 
Widest out-of-the-box monitoring support with 50+ applications
Performance metrics, stats and reports that give you Actionable Insights
Deep dive visibility with transaction tracing using APM Insight.
http://ad.doubleclick.net/ddm/clk/290420510;117567292;y

_______________________________________________
Keepalived-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/keepalived-devel