libvirt/docs/genaclperms.pl

#!/usr/bin/env perl
#
# Copyright (C) 2013 Red Hat, Inc.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library.  If not, see
# <http://www.gnu.org/licenses/>.
#

use strict;
use warnings;

my @objects = (
    "CONNECT", "DOMAIN", "INTERFACE",
    "NETWORK_PORT", "NETWORK", "NODE_DEVICE",
    "NWFILTER_BINDING", "NWFILTER",
     "SECRET", "STORAGE_POOL", "STORAGE_VOL",
    );

my %class;

foreach my $object (@objects) {
    my $class = lc $object;

    $class =~ s/(^\w|_\w)/uc $1/eg;
    $class =~ s/_//g;
    $class =~ s/Nwfilter/NWFilter/;
    $class = "vir" . $class . "Ptr";

    $class{$object} = $class;
}

my $objects = join ("|", @objects);

my %opts;
my $in_opts = 0;

my %perms;

while (<>) {
    if ($in_opts) {
        if (m,\*/,) {
            $in_opts = 0;
        } elsif (/\*\s*\@(\w+):\s*(.*?)\s*$/) {
            $opts{$1} = $2;
        }
    } elsif (m,/\*\*,) {
        $in_opts = 1;
    } elsif (/VIR_ACCESS_PERM_($objects)_((?:\w|_)+),/) {
        my $object = $1;
        my $perm = lc $2;
        next if $perm eq "last";

        $perm =~ s/_/-/g;

        $perms{$object} = {} unless exists $perms{$object};
        $perms{$object}->{$perm} = {
            desc => $opts{desc},
            message => $opts{message},
            anonymous => $opts{anonymous}
        };
        %opts = ();
    }
}

print <<EOF;
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
EOF

foreach my $object (sort { $a cmp $b } keys %perms) {
    my $class = $class{$object};
    my $olink = lc "object_" . $object;
    print <<EOF;
<h3><a id="$olink">$class</a></h3>
<table class="acl">
  <thead>
    <tr>
      <th>Permission</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
EOF

    foreach my $perm (sort { $a cmp $b } keys %{$perms{$object}}) {
        my $description = $perms{$object}->{$perm}->{desc};

        die "missing description for $object.$perm" unless
            defined $description;

        my $plink = lc "perm_" . $object . "_" . $perm;
        $plink =~ s/-/_/g;

        print <<EOF;
    <tr>
      <td><a id="$plink">$perm</a></td>
      <td>$description</td>
    </tr>
EOF

    }

    print <<EOF;
  </tbody>
</table>
EOF
}

print <<EOF;
  </body>
</html>
EOF
perl: Don't hardcode interpreter path This is particularly useful on operating systems that don't ship Perl as part of the base system (eg. FreeBSD) while still working just as well as it did before on Linux. In one case (src/rpc/genprotocol.pl) the interpreter path was missing altogether. Signed-off-by: Andrea Bolognani <abologna@redhat.com> 2017-09-18 15:35:50 +03:00			`#!/usr/bin/env perl`
Add documentation for access control system This adds two new pages to the website, acl.html describing the general access control framework and permissions models, and aclpolkit.html describing the use of polkit as an access control driver. page.xsl is modified to support a new syntax <div id="include" filename="somefile.htmlinc"/> which will cause the XSL transform to replace that <div> with the contents of 'somefile.htmlinc'. We use this in the acl.html.in file, to pull the table of permissions for each libvirt object. This table is autogenerated from the enums in src/access/viraccessperms.h by the genaclperms.pl script. newapi.xsl is modified so that the list of permissions checks shown against each API will link to the description of the permissions in acl.html Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2013-08-08 14:51:01 +04:00			`#`
			`# Copyright (C) 2013 Red Hat, Inc.`
			`#`
			`# This library is free software; you can redistribute it and/or`
			`# modify it under the terms of the GNU Lesser General Public`
			`# License as published by the Free Software Foundation; either`
			`# version 2.1 of the License, or (at your option) any later version.`
			`#`
			`# This library is distributed in the hope that it will be useful,`
			`# but WITHOUT ANY WARRANTY; without even the implied warranty of`
			`# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU`
			`# Lesser General Public License for more details.`
			`#`
			`# You should have received a copy of the GNU Lesser General Public`
			`# License along with this library. If not, see`
			`# <http://www.gnu.org/licenses/>.`
			`#`

			`use strict;`
			`use warnings;`

			`my @objects = (`
			`"CONNECT", "DOMAIN", "INTERFACE",`
docs: fix acl permission docs We have been grouping network-port and nwfilter-binding permissions under virNetworkPtr and virNWFilterPtr respectively. Add the two missing classes that were matched because they contain a substring of others. Signed-off-by: Ján Tomko <jtomko@redhat.com> Reviewed-by: Andrea Bolognani <abologna@redhat.com> 2019-06-27 18:39:50 +03:00			`"NETWORK_PORT", "NETWORK", "NODE_DEVICE",`
			`"NWFILTER_BINDING", "NWFILTER",`
Add documentation for access control system This adds two new pages to the website, acl.html describing the general access control framework and permissions models, and aclpolkit.html describing the use of polkit as an access control driver. page.xsl is modified to support a new syntax <div id="include" filename="somefile.htmlinc"/> which will cause the XSL transform to replace that <div> with the contents of 'somefile.htmlinc'. We use this in the acl.html.in file, to pull the table of permissions for each libvirt object. This table is autogenerated from the enums in src/access/viraccessperms.h by the genaclperms.pl script. newapi.xsl is modified so that the list of permissions checks shown against each API will link to the description of the permissions in acl.html Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2013-08-08 14:51:01 +04:00			`"SECRET", "STORAGE_POOL", "STORAGE_VOL",`
			`);`

			`my %class;`

			`foreach my $object (@objects) {`
			`my $class = lc $object;`

			`$class =~ s/(^\w\|_\w)/uc $1/eg;`
			`$class =~ s/_//g;`
			`$class =~ s/Nwfilter/NWFilter/;`
			`$class = "vir" . $class . "Ptr";`

			`$class{$object} = $class;`
			`}`

			`my $objects = join ("\|", @objects);`

			`my %opts;`
			`my $in_opts = 0;`

			`my %perms;`

			`while (<>) {`
			`if ($in_opts) {`
			`if (m,\*/,) {`
			`$in_opts = 0;`
			`} elsif (/\\s\@(\w+):\s(.?)\s*$/) {`
			`$opts{$1} = $2;`
			`}`
			`} elsif (m,/\\,) {`
			`$in_opts = 1;`
			`} elsif (/VIR_ACCESS_PERM_($objects)_((?:\w\|_)+),/) {`
			`my $object = $1;`
			`my $perm = lc $2;`
			`next if $perm eq "last";`

			`$perm =~ s/_/-/g;`

			`$perms{$object} = {} unless exists $perms{$object};`
			`$perms{$object}->{$perm} = {`
			`desc => $opts{desc},`
			`message => $opts{message},`
			`anonymous => $opts{anonymous}`
			`};`
			`%opts = ();`
			`}`
			`}`

			`print <<EOF;`
			`<?xml version="1.0" encoding="UTF-8"?>`
docs: switch to using HTML5 doctype declaration The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2017-07-26 20:01:25 +03:00			`<!DOCTYPE html>`
Add documentation for access control system This adds two new pages to the website, acl.html describing the general access control framework and permissions models, and aclpolkit.html describing the use of polkit as an access control driver. page.xsl is modified to support a new syntax <div id="include" filename="somefile.htmlinc"/> which will cause the XSL transform to replace that <div> with the contents of 'somefile.htmlinc'. We use this in the acl.html.in file, to pull the table of permissions for each libvirt object. This table is autogenerated from the enums in src/access/viraccessperms.h by the genaclperms.pl script. newapi.xsl is modified so that the list of permissions checks shown against each API will link to the description of the permissions in acl.html Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2013-08-08 14:51:01 +04:00			`<html xmlns="http://www.w3.org/1999/xhtml">`
			`<body>`
			`EOF`

			`foreach my $object (sort { $a cmp $b } keys %perms) {`
			`my $class = $class{$object};`
			`my $olink = lc "object_" . $object;`
			`print <<EOF;`
docs: Make anchors follow HTML5 According to HTML specification, <a name=''> works in HTML4, but <a id=''> works in both HTML4 and HTML5. This is followed even in docs/page.xsl where HTML bookmark links are generated only for those anchors which have @id attribute. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> 2019-08-27 18:21:32 +03:00			`<h3><a id="$olink">$class</a></h3>`
Add documentation for access control system This adds two new pages to the website, acl.html describing the general access control framework and permissions models, and aclpolkit.html describing the use of polkit as an access control driver. page.xsl is modified to support a new syntax <div id="include" filename="somefile.htmlinc"/> which will cause the XSL transform to replace that <div> with the contents of 'somefile.htmlinc'. We use this in the acl.html.in file, to pull the table of permissions for each libvirt object. This table is autogenerated from the enums in src/access/viraccessperms.h by the genaclperms.pl script. newapi.xsl is modified so that the list of permissions checks shown against each API will link to the description of the permissions in acl.html Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2013-08-08 14:51:01 +04:00			`<table class="acl">`
			`<thead>`
			`<tr>`
			`<th>Permission</th>`
			`<th>Description</th>`
			`</tr>`
			`</thead>`
			`<tbody>`
			`EOF`

			`foreach my $perm (sort { $a cmp $b } keys %{$perms{$object}}) {`
			`my $description = $perms{$object}->{$perm}->{desc};`

			`die "missing description for $object.$perm" unless`
			`defined $description;`

			`my $plink = lc "perm_" . $object . "_" . $perm;`
			`$plink =~ s/-/_/g;`

			`print <<EOF;`
			`<tr>`
docs: Make anchors follow HTML5 According to HTML specification, <a name=''> works in HTML4, but <a id=''> works in both HTML4 and HTML5. This is followed even in docs/page.xsl where HTML bookmark links are generated only for those anchors which have @id attribute. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> 2019-08-27 18:21:32 +03:00			`<td><a id="$plink">$perm</a></td>`
Add documentation for access control system This adds two new pages to the website, acl.html describing the general access control framework and permissions models, and aclpolkit.html describing the use of polkit as an access control driver. page.xsl is modified to support a new syntax <div id="include" filename="somefile.htmlinc"/> which will cause the XSL transform to replace that <div> with the contents of 'somefile.htmlinc'. We use this in the acl.html.in file, to pull the table of permissions for each libvirt object. This table is autogenerated from the enums in src/access/viraccessperms.h by the genaclperms.pl script. newapi.xsl is modified so that the list of permissions checks shown against each API will link to the description of the permissions in acl.html Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2013-08-08 14:51:01 +04:00			`<td>$description</td>`
			`</tr>`
			`EOF`

			`}`

			`print <<EOF;`
			`</tbody>`
			`</table>`
			`EOF`
			`}`

			`print <<EOF;`
			`</body>`
			`</html>`
			`EOF`