[libvirt] [PATCH] Add info about access control checks into API reference

[Daniel P. Berrange]

On Wed, Aug 07, 2013 at 12:06:09PM -0600, Eric Blake wrote:
> On 08/07/2013 06:06 AM, Daniel P. Berrange wrote:
> > From: "Daniel P. Berrange" <berrange at redhat.com>
> > 
> > So that app developers / admins know what access control checks
> > are performed for each API, this patch extends the API docs
> > generator to include details of the ACLs for each.
> > 
> > The gendispatch.pl script is extended so that it generates
> > a simple XML describing ACL rules, eg.
> > 
> >   <aclinfo>
> >     ...
> >     <api name='virConnectNumOfDomains'>
> >       <check object='connect' perm='search_domains'/>
> >       <filter object='domain' perm='getattr'/>
> >     </api>
> >     <api name='virDomainAttachDeviceFlags'>
> >       <check object='domain' perm='write'/>
> >       <check object='domain' perm='save' flags='!VIR_DOMAIN_AFFECT_CONFIG|VIR_DOMAIN_AFFECT_LIVE'/>
> >       <check object='domain' perm='save' flags='VIR_DOMAIN_AFFECT_CONFIG'/>
> >     </api>
> >     ...
> >   </aclinfo>
> > 
> > The newapi.xsl template loads the XML files containing the ACL
> > rules and generates a short block of HTML for each API describing
> > the parameter checks and return value filters (if any).
> > 
> > Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> > ---
> >  docs/libvirt.css       | 14 +++++++++++
> >  docs/newapi.xsl        | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++
> >  src/Makefile.am        | 22 ++++++++++++++--
> >  src/rpc/gendispatch.pl | 59 ++++++++++++++++++++++++++++++++++++++++---
> >  4 files changed, 157 insertions(+), 6 deletions(-)
> 
> I'm no css or xsl expert, and perl is not my strongest language; but I
> can say that this patch applies and that the output looks like a useful
> and correct improvement.  (See the attached screenshot)

Hah, I'm sadly too familiar with  xsl from previous work writing
a content management system where the entire web UI was generated
with XSL transforms :-(


> > +} elsif ($mode eq "aclapi") {
> > +    print <<__EOF__;
> > +<!--
> > +  -  Automatically generated by gendispatch.pl.
> 
> This says WHO generated, but not WHICH file to edit if the generated
> file contains errors.  Can we add the source .x file as additional
> information (probably as a separate patch, since the other generated
> files likely have the same issue)?

I guess we could add that.


Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|