From: Willy Tarreau Date: Tue, 8 May 2007 23:31:45 +0000 (+0200) Subject: [DOC] add some documentation about ACLs X-Git-Tag: v1.3.10~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=726c2bf6453325e6aa3ac07bbf6bf48c52cd868c;p=thirdparty%2Fhaproxy.git [DOC] add some documentation about ACLs Minimal documentation about ACLs --- diff --git a/doc/haproxy-en.txt b/doc/haproxy-en.txt index 1341aea539..865bf8e41f 100644 --- a/doc/haproxy-en.txt +++ b/doc/haproxy-en.txt @@ -2525,6 +2525,80 @@ Notes : forwarded unmodified to the server as if the option was not set. +5) Access lists +=============== + +With version 1.3.10, a new concept of access lists (acl) was born. As it was +not necesary to reinvent the wheel, and because even long thoughts lead to +unsatisfying proposals, it was finally decided that something close to what +Squid provides would be a good compromise between features and ease of use. + +The principle is very simple : acls are declared with a name, a test and a list +of valid values to check against during the test. Conditions are applied on +various actions, and those conditions apply a logical AND between acls. The +condition is then only met if all acls are true. + +It is possible to use the reserved keyword "OR" in conditions, and it is +possible for an acl to be specified multiple times, even with various tests, in +which case the first one which returns true validates the ACL. + +As of 1.3.10, only the following tests have been implemented : + + Layer 3/4 : + src [/mask] ... : match IPv4 source address + dst [/mask] ... : match IPv4 destination address + src_port [:] ... : match source port range + dst_port [:] ... : match destination port range + dst_limit : true if frontend has less than connections + + Layer 7 : + method ... : match HTTP method + req_ver <1.0|1.1> ... : match HTTP request version + resp_ver <1.0|1.1> ... : match HTTP response version + status [:] ... : match HTTP response status code in range + url ... : exact string match on URI + url_reg ... : regex string match on URI + url_beg ... : true if URI begins with + url_end ... : true if URI ends with + url_sub ... : true if URI contains + url_dir ... : true if URI contains between slashes + url_dom ... : true if URI contains between slashes or dots + +Other ones are coming (headers, cookies, time, auth), it's just a matter of +time. It is also planned to be able to read the patterns from a file, as well +as to ignore the case for some of them. + +The only command supporting a condition right now is the "block" command, which +blocks a request and returns a 403 if its condition is true (with the "if" +keyword), or if it is false (with the "unless" keyword). + +Example : +--------- + + acl options_uris url * + acl meth_option method OPTIONS + acl http_1.1 req_ver 1.1 + acl allowed_meth method GET HEAD POST OPTIONS CONNECT + acl connect_meth method CONNECT + acl proxy_url url_beg http:// + + # block if reserved URI "*" used with a method other than "OPTIONS" + block if options_uris !meth_option + + # block if the OPTIONS method is used with HTTP 1.0 + block if meth_option !http_1.1 + + # allow non-proxy url with anything but the CONNECT method + block if !connect_meth !proxy_url + + # block all unknown methods + block unless allowed_meth + +Note: this documentation is very light but should permit one to start and above +all it should permit to work on the project without being slowed down too much +with the doc. + + ========================= | System-specific setup | ========================= diff --git a/doc/haproxy-fr.txt b/doc/haproxy-fr.txt index 795b67b3c8..63ac9a4514 100644 --- a/doc/haproxy-fr.txt +++ b/doc/haproxy-fr.txt @@ -2624,6 +2624,81 @@ Notes : pas précisée. +5) Listes d'accès +================= + +Avec la version 1.3.10, un nouveau concept de listes d'accès (ACL) a vu le +jour. Comme il n'était pas nécessaire de réinventer la roue, et du fait que +toutes les réflexions passées aboutissaient à des propositions non +satisfaisantes, il a finalement été décidé que quelque chose de proche de ce +que Squid offre serait un bon compromis entre une richesse fonctionnelle et une +facilité d'utilisation + +Le principe est très simple : les ACLs sont déclarées avec un nom, un test et +une liste de valeurs valides à tester. Des conditions sont appliquées sur +diverses actions, et ces conditions effectuent un ET logique entre les ACLs. La +condition n'est donc validée que si toutes les ACLs sont vraies. + +Il est également possible d'utiliser le mot réservé "OR" dans les conditions, +et il est possible pour une ACL d'être spécifiée plusieurs fois, même avec des +tests différents, auquel cas le premier test réussi validera l'ACL. + +Au stade de la version 1.3.10, seuls les tests suivants ont été implémentés : + + Niveaux 3/4 : + src [/mask] ... : match IPv4 source address + dst [/mask] ... : match IPv4 destination address + src_port [:] ... : match source port range + dst_port [:] ... : match destination port range + dst_limit : true if frontend has less than connections + + Niveau 7 : + method ... : match HTTP method + req_ver <1.0|1.1> ... : match HTTP request version + resp_ver <1.0|1.1> ... : match HTTP response version + status [:] ... : match HTTP response status code in range + url ... : exact string match on URI + url_reg ... : regex string match on URI + url_beg ... : true if URI begins with + url_end ... : true if URI ends with + url_sub ... : true if URI contains + url_dir ... : true if URI contains between slashes + url_dom ... : true if URI contains between slashes or dots + +D'autres tests arrivent (entêtes, cookies, heure, authentification), c'est +juste une question de temps. Il est aussi prévu de permettre de lire les +valeurs depuis un fichier, ainsi que d'ignorer la casse pour certains tests. + +La seule commande supportant les conditions d'ACL à ce jour est la nouvelle +commande "block" qui bloque une requête et retourne un statut 403 si sa +condition est validée (cas du "if") ou invalidée (cas du "unless"). + +Exemple : +--------- + + acl options_uris url * + acl meth_option method OPTIONS + acl http_1.1 req_ver 1.1 + acl allowed_meth method GET HEAD POST OPTIONS CONNECT + acl connect_meth method CONNECT + acl proxy_url url_beg http:// + + # block if reserved URI "*" used with a method other than "OPTIONS" + block if options_uris !meth_option + + # block if the OPTIONS method is used with HTTP 1.0 + block if meth_option !http_1.1 + + # allow non-proxy url with anything but the CONNECT method + block if !connect_meth !proxy_url + + # block all unknown methods + block unless allowed_meth + +Note: Cette documentation est embryonnaire mais doit permettre de démarrer et +surtout d'avancer sur le projet sans être trop ralenti par la documentation. + + ======================= | Paramétrage système | =======================