HTTP Restrictions

Virtuoso Restriction Hook

Virtuoso provides a hook procedure called DB.DBA.DBEV_RESTRICTIONS which, given a map of restriction names to their requested value ("min" or "max"), will return a set of mappings from restriction name to a vector containing the restriction type ("min" or "max"), the restriction value, and the optional service ID which triggered the restriction. If the latter is null then the restriction was triggered by the client IP address.

Since March 19th, 2014 Virtuoso provides a second restrictions hook DB.DBA.DBEV_GET_CONNECTION_RESTRICTION which supports restriction parameters. Restriction parameters simply allow to divide one restricted resource into several restrictions. This is very useful in terms of HTTP as it allows to define different restrictions for different urls or virtual dirs.

This hook is implemented in VAL and uses the ACL restriction system by prefixing every restriction name with urn:virtuoso:restrictions:.

VAL's implementation will always choose the least restrictive value. That means given two max values, one via the IP address and one via the authenticated user, VAL will choose the higher value.

The Restrictions can be controlled via the VAL ACL RESTful API or the Internal VAL API. Alternatively one can directly add the restrictions to the private graph matching the realm in which the restrictions should apply. Given the default realm http://www.openlinksw.com/ontology/acl#DefaultRealm and default hostname "HOST" the graph IRI would be http://HOST/acl/graph/restrictions/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm and the groups will be stored in named graph http://HOST/acl/graph/groups/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm. Be aware that these graphs can be customized for better readability.

HTTP Restriction Names

Virtuoso uses two restrictions which can be controlled on an IP address level or via service IDs. These restrictions define "global" limits on all virtual dirs.

1. urn:virtuoso:restrictions:http-request-rate restricts the maximum request rate per second.
2. urn:virtuoso:restrictions:http-content-size restricts the maximum content size for requests

If one wants to define restrictions only for a specific virtual dir or a specific URL then the above URNs need to be used as restriction parameters in restrictions on the url in question. See below for examples.

HTTP Restriction Examples

Global Http Restrictions

Restrict the requests per second to 10 for everyone for every http request

SPARQL

PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

WITH GRAPH <http://{HOST-CNAME}/acl/restrictions/groups/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>

INSERT {
  <{REST-IRI}> a oplres:Restriction ;
    foaf:maker <{PERSON-WEBID}> ; 
    foaf:name "Base line is 10 requests per second" ;
    oplres:hasMaxValue "10"^^xsd:decimal ;
    oplres:hasRestrictedResource <urn:virtuoso:restrictions:http-request-rate> ;
    oplres:hasAgentClass foaf:Agent ;
    oplres:hasRealm oplacl:DefaultRealm .
};

Restrict the requests per second to 1000 for the intranet for every http request

IP Address ranges are defined via conditional groups. Thus, we first define the conditional group which includes all IP addresses with a certain pattern:

SPARQL

PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

WITH GRAPH <http://{HOST-CNAME}/acl/restrictions/groups/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>

INSERT {
  <{GROUP-IRI}> a oplacl:ConditionalGroup ;
    foaf:maker <{PERSON-WEBID}> ; 
    foaf:name "Internal Network" ;
    oplacl:hasCondition [
      a oplacl:IPAddressCondition ;
      oplacl:hasIPAddressPattern "198.168..*"
    ] .
};

And then we use this group in our restriction:

SPARQL

PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

WITH GRAPH <http://{HOST-CNAME}/acl/restrictions/groups/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>

INSERT {
  <{REST-IRI}> a oplres:Restriction ;
    foaf:maker <{PERSON-WEBID}> ; 
    foaf:name "Intranet HTTP requests per second" ;
    oplres:hasMaxValue "1000"^^xsd:decimal ;
    oplres:hasRestrictedResource <urn:virtuoso:restrictions:http-request-rate> ;
    oplres:hasAgent <{GROUP-IRI}> ;
    oplres:hasRealm oplacl:DefaultRealm .
};

Virtual-Dir or URL-specific Http Restrictions

Restrict the requests per second to 10 for everyone on one virtual dir

The following restriction is scoped to all http requests on one virtual dir, i.e. /sparql. This means any request to pages in that virtual dir will be subject to the same restriction. This means that one client can make 10 requests in total on that virtual dir.

SPARQL

PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

WITH GRAPH <http://{HOST-CNAME}/acl/restrictions/groups/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>

INSERT {
  <{REST-IRI}> a oplres:Restriction ;
    foaf:maker <{PERSON-WEBID}> ; 
    foaf:name "Base line is 10 requests per second" ;
    oplres:hasMaxValue "10"^^xsd:decimal ;
    oplres:hasRestrictedResource <http://linkeddata.uriburner.com/sparql> ;
    oplres:hasRestrictedParameter <urn:virtuoso:restrictions:http-request-rate> ;
    oplres:hasAgentClass foaf:Agent ;
    oplres:hasRealm oplacl:DefaultRealm .
};

Restrict the requests per second on one specific URL

The following restriction allows 1000 requests per second on one specific URL (given that there is no virtual dir which matches that URL). It uses the same conditional group as above. So in practice this restriction limits the rate on one specific ODS API call:

SPARQL

PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

WITH GRAPH <http://{HOST-CNAME}/acl/restrictions/groups/http%3A%2F%2Fwww.openlinksw.com%2Fontology%2Facl%23DefaultRealm>

INSERT {
  <{REST-IRI}> a oplres:Restriction ;
    foaf:maker <{PERSON-WEBID}> ; 
    foaf:name "Intranet HTTP requests per second" ;
    oplres:hasMaxValue "1000"^^xsd:decimal ;
    oplres:hasRestrictedResource <http://web.ods.openlinksw.com/ods/api/user.info> ;
    oplres:hasRestrictedParameter <urn:virtuoso:restrictions:http-request-rate> ;
    oplres:hasAgent <{GROUP-IRI}> ;
    oplres:hasRealm oplacl:DefaultRealm .
};