Access Control - Configure - H2O - the optimized HTTP/2 server

- -

-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. -

- -

`"allow"`

- -

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.. }

- -

`"redirect"`

- -

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

- -

`"respond"`

- -

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()

- -

`"method"`

- -

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.

- -

`"user_agent"`

- -

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.. -

- - - - -

-H2O -

-Configure > -Access Control -

Example

ACL Methods

`"allow"`

`"deny"`

`"redirect"`

`"respond"`

`"use"`

Matching Methods

`"addr"`

`"path"`

`"method"`

`"header"`

`"user_agent"`

Caution

How-To

Matching IP Address Blocks