From be1c7e50e1e8809ea56f2c9d472eccd8ffd73a97 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 04:57:58 +0200 Subject: Adding upstream version 1.44.3. Signed-off-by: Daniel Baumann --- .../h2o/libh2o/doc/configure/access_control.html | 444 +++++++++++++++++++++ 1 file changed, 444 insertions(+) create mode 100644 web/server/h2o/libh2o/doc/configure/access_control.html (limited to 'web/server/h2o/libh2o/doc/configure/access_control.html') diff --git a/web/server/h2o/libh2o/doc/configure/access_control.html b/web/server/h2o/libh2o/doc/configure/access_control.html new file mode 100644 index 00000000..74f4ced6 --- /dev/null +++ b/web/server/h2o/libh2o/doc/configure/access_control.html @@ -0,0 +1,444 @@ + + + + + + + + + + + + + + + + +Access Control - Configure - H2O - the optimized HTTP/2 server + + +
+
+ +

+H2O +

+

the optimized HTTP/1.x, HTTP/2 server

+ + +
+ +
+ +
+
+
+Powered by Oktavia +
+
+ + +
+ + + + + + + + + + + + +
+ +

+Configure > +Access Control +

+ + +

+Starting from version 2.1, H2O comes with a DSL-like mruby library which makes it easy to write access control list (ACL). +

+ +

Example

+ +

+Below example uses this Access Control feature to write various access control. +

+ +
+
Example. Access Control
+
paths:
+  "/":
+    mruby.handler: |
+      acl {
+        allow { addr == "127.0.0.1" }
+        deny { user_agent.match(/curl/i) && ! addr.start_with?("192.168.") }
+        respond(503, {}, ["Service Unavailable"]) { addr == malicious_ip }
+        redirect("https://example.com/", 301) { path =~ /moved/ }
+        use Htpasswd.new("/path/to/.htpasswd", "realm") { path.start_with?("/admin") }
+      }
+    file.dir: /path/to/doc_root
+
+
+ + +

+In the example, the handler you get by calling acl method will do the following: +

    +
  • + if the remote IP address is exactly equal to "127.0.0.1", the request will be delegated to the next handler (i.e. serve files under /path/to/doc_root) and all following acl settings are ignored +
    • +
  • + otherwise, if the user agent string includes "curl" and the remote IP address doesn't start with "192.168.", this handler immediately returns 403 Forbidden response +
    • +
  • + otherwise, if the remote IP address is exactly equal to the malicious_ip variable, this handler immediately returns 503 Service Unavailable response +
    • +
  • + otherwise, if the request path matches with the pattern /moved/i, this handler immediately redirects the client to "https://example.com" with 301 status code +
    • +
  • + otherwise, if the request path starts with /admin, apply Basic Authentication to the request (for details of Basic Authentication, see here). +
    • +
  • + otherwise, the request will be delegated to the next handler (i.e. serve files under /path/to/doc_root) +
    • + +
+ +

ACL Methods

+ +

+An ACL handler is built by calling ACL methods, which can be used like directives. +ACL methods can only be used in acl block. +

+ +

+Each ACL method adds a filter to the handler, which checks whether the request matches the provided condition or not. +Every ACL method can be accompanied by a condition block, which should return boolean value. +

+ +

+The filter defined by the method that first matched the accompanying condition gets applied (e.g. response 403 Forbidden, redirect to somewhere). +If a condition block is omitted, all requests matches. +If none of the conditions matches the request, the handler returns 399 and the request will be delegated to the next handler. +

+ + + +
+
Description:
+
+

+ Adds a filter which delegates the request to the next handler if the request matches the provided condition. +

+ +
allow { ..condition.. }
+ +
+
+ +
+

"deny"

+
+ +
+
Description:
+
+

+ Adds a filter which returns 403 Forbidden if the request matches the provided condition. +

+ +
deny { ..condition.. }
+ +
+
+ + + +
+
Description:
+
+

+ Adds a filter which redirects the client if the request matches the provided condition. +

+ +
redirect(location, status) { ..condition.. }
+ +
+
Parameters:
+
+
+
location
+
Location to which the client will be redirected. Required.
+
status
+
Status code of the response. Default value: 302
+
+
+
+ + + +
+
Description:
+
+

+ Adds a filter which returns arbitrary response if the request matches the provided condition. +

+ +
respond(status, header, body) { ..condition.. }
+ +
+
Parameters:
+
+
+
status
+
Status code of the response. Required.
+
header
+
Header key-value pairs of the response. Default value: {}
+
body
+
Body array of the response. Default value: []
+
+
+
+ +
+

"use"

+
+ +
+
Description:
+
+

+ Adds a filter which applies the provided handler (callable object) if the request matches the provided condition. +

+ +
use(proc) { ..condition.. }
+ +
+
Parameters:
+
+
+
proc
+
Callable object that should be applied
+
+
+
+ +

Matching Methods

+ +

+In a condition block, you can use helpful methods which return particular properties of the request as string values. +Matching methods can only be used in a condition block of the ACL methods. +

+ +
+

"addr"

+
+ +
+
Description:
+
+

+ Returns the remote IP address of the request. +

+ +
addr(forwarded)
+ +
+
Parameters:
+
+
+
forwarded
+
If true, returns the value of X-Forwarded-For header if it exists. Default value: true
+
+
+
+ +
+

"path"

+
+ +
+
Description:
+
+

+ Returns the requested path string of the request. +

+ +
path()
+ +
+
+ + + +
+
Description:
+
+

+ Returns the HTTP method of the request. +

+ +
method()
+ +
+
+ + + +
+
Description:
+
+

+ Returns the header value of the request associated with the provided name. +

+ +
header(name)
+ +
+
Parameters:
+
+
+
name
+
Case-insensitive header name. Required.
+
+
+
+ + + +
+
Description:
+
+

+ Shortcut for header("user-agent"). +

+ +
user_agent()
+ +
+
+ +

Caution

+ +

+Several restrictions are introduced to avoid misconfiguration when using acl method. +

    +
  • acl method can be called only once in each handler configuration
    • +
  • If acl method is used, the handler returned by the configuration directive must be the one returned by the acl method
    • +
+If a configuration violates these restrictions, the server will detect it and refuse to launch with error message. +

+ +

+For example, both of the following examples violate the restrictions above, so the server will refuse to start up. +

+ +
+
Example. Misconfiguration Example 1
+
paths:
+  "/":
+    mruby.handler: |
+      acl {    # this block will be ignored!
+        allow { addr == "127.0.0.1" }
+      }
+      acl {
+        deny
+      }
+    file.dir: /path/to/doc_root
+
+
+ + +
+
Example. Misconfiguration Example 2
+
paths:
+  "/":
+    mruby.handler: |
+      acl {    # this block will be ignored!
+        allow { addr == "127.0.0.1" }
+        deny
+      }
+      proc {|env| [399, {}, []}
+    file.dir: /path/to/doc_root
+
+
+ + +

+You can correct these like the following: +

+ +
+
Example. Valid Configuration Example
+
paths:
+  "/":
+    mruby.handler: |
+      acl {
+        allow { addr == "127.0.0.1" }
+        deny
+      }
+    file.dir: /path/to/doc_root
+
+
+ + +

How-To

+ +

Matching IP Address Blocks

+ +

+You can match an IP address against predefined list of address blocks using a script named trie_addr.rb. +

+

+Below is an example. +

+ +
+
Example. Address Block Matching Example
+
paths:
+  "/":
+    mruby.handler: |
+      require "trie_addr.rb"
+      trie = TrieAddr.new.add(["192.168.0.0/16", "172.16.0.0/12"])
+      acl {
+        allow { trie.match?(addr) }
+        deny
+      }
+    file.dir: /path/to/doc_root
+
+
+ + +

+This library currently supports only IPv4 addresses. TrieAddr#match? returns false when it receives an invalid IPv4 address (including an IPv6 address) as an argument.. +

+ + + + +
+ + + -- cgit v1.2.3