Re: Api idés

2015-05-07 08:16 skrev Patrick Schaaf:
> 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.

Binary is for one reason speed, think if you get data for graphic 
purpose
for every interface, it will be a hug overload to send that in ascii 
format.

Updates every 1/10 seconds, packet p/s for tx / rx and actual size.

10 interface and 10 graph it would not be optimal to send in ascii.

For a CLI applications it's overkill you don't need that performance.

Programmer to develop a cli or other tools need a library to encapsulate
low level RLE to "high level ascii land" and developer never need to
care about any RLE stuff at all, use command/tokens in ascii format as 
normal to
library routines instead.

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

Agree

> 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 rn terminated text
> lines (no fancy encoding - or is there any need for that that I can't
> see?).

But if you wont to monitor something like logfile you should get
that with a single command, not repeted (like polled),send until "stop 
send log file"
or socket close for any reason.

should work like "tail -f /var/log/keepalved.log"

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

Agree if its a CLI application,
You need /keyword/next_token ... or /keyword next_token ...

If you are in interface level and want to do "/ip ro sh"
to display all routes without to be in top level.


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

Agree

> 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)

Need only 3 level: write access, read access, both read/write
in low level api.

Always send salt value in reply cmd with a plain login

Login with name and password a second time and you have access 
read/write/both


> 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:

Agree

CLI program should ask all cmds and argument from low level api in
initialization task.


> * "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

-- 

best regarding

/Jan Holmberg

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