Access Control - Configure - H2O - the optimized HTTP 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..