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

[Eric Blake]

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)

> +++ b/src/Makefile.am
> @@ -830,6 +830,11 @@ ACCESS_DRIVER_SYM_FILES = \
>  		libvirt_access_qemu.syms \
>  		libvirt_access_lxc.syms
>  
> +ACCESS_DRIVER_API_FILES = \
> +		libvirt_access.xml \
> +		libvirt_access_qemu.xml \
> +		libvirt_access_lxc.xml
> +

I also tested 'make distcheck' with this patch applied (which includes
VPATH testing and checks that the new files are appropriately generated
rather than included in the tarball).  I will note that 'make distcheck'
currently fails if 'make' was not run first; but that problem existed
before your patch, so even if you made it worse, it's not a
show-stopper.  And since 'make all distcheck' passes, it appears that
you got the makefile magic right.

ACK.

> +} 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)?

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screenshot from 2013-08-07 11:12:43.png
Type: image/png
Size: 41189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130807/603445ac/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130807/603445ac/attachment-0001.sig>