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

### `"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()

### `"header"`

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