Get Started

Installation

The policy engine runs from a single binary. For convenience it is distributed in deb and rpm packages.

Red Hat-based distributions

$ sudo yum install policy-engine
$ sudo systemctl start policy-engine

Debian-based distributions

$ sudo apt-get install policy-engine
$ sudo systemctl start policy-engine

Verify the installation

The service will, by default, listen to the following ports when it has been started.

Daemon configuration

The policy engine daemon is configured using command line arguments set in the systemd service file:

$ cat /usr/lib/systemd/system/policy-engine.service

If might not be necessary to change the default configuration, but if it is - follow this procedure. First make a copy of the service file:

$ sudo cp /usr/lib/systemd/system/policy-engine.service \
        /etc/systemd/system/policy-engine.service

Then make any modifications to /etc/systemd/system/policy-engine.service, reload systemd and restart policy-engine:

$ sudo systemctl daemon-reload
$ sudo systemctl restart policy-engine

Some of the available command line arguments are:

The command /usr/sbin/policy-engine --help shows the complete set of arguments available.

Define an endpoint

Endpoints can be defined using the management API or using the file system directly. Both methods are shown below.

Define an endpoint using the management API

Create the endpoint by specifying its name, together with the public request host and request path in an HTTP POST request to the administration API.

$ curl http://localhost:8089/endpoints -i -X POST -d '{
             "name": "example",
             "host": "example.com",
             "path": "/*"
         }'

HTTP/1.1 201 Created
Date: Mon, 19 Sep 2016 11:46:46 GMT
Content-Length: 50
Content-Type: text/plain; charset=utf-8

{
    "host": "example.com",
    "name": "example",
    "path": "/*"
}

The 201 response code indicates that the endpoint example was successfully created. The endpoint configuration is persisted to the file /var/lib/policy-engine/endpoints/example.json.

No modules have been enabled yet, so any request to the endpoint will get a response code 200 and a small set of default response headers.

Enable request rate limiting

Request rate limiting can be enabled per endpoint using the Rate Limit module. First the module has to be enabled for the example endpoint:

$ curl http://localhost:8089/endpoints/example/modules -i -X POST -d '{
             "name": "rate-limit"
         }'

When the module is enabled, the number of requests allowed can be specified. The following will allow 200 requests per minute or 5000 requests per hour. The first limit to exceed will apply.

$ curl http://localhost:8089/endpoints/example/modules/rate-limit/default -i -X PUT -d '{
             "minute": 200,
             "hour": 5000
         }'

Policy requests to our example endpoint will now be rate limited. Since authentication is not yet enabled the rate limit will apply to the X-Forwarded-For request header or, if it does not exist, the source IP address of the request.

$ curl -i -H "host: example.com" http://localhost:8088/

HTTP/1.1 200 OK
X-Endpoint: example
X-Ratelimit-Limit: 200 5000
X-Ratelimit-Remaining: 199 4999
X-Ratelimit-Reset: 59 3599
Date: Mon, 12 Sep 2016 08:44:26 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8

The response status will be 429 Too Many Requests if the rate limit is exceeded.

Specify upstream resource URL

The Upstream Simple module is used to point to the upstream resource for a request. First the module has to be enabled.

$ curl http://localhost:8089/endpoints/example/modules -i -X POST -d '{
             "name": "upstream-simple"
         }'

When the module is enabled, it can be configured by specifying the upstream URL for the endpoint.

$ curl http://localhost:8089/endpoints/example/modules/upstream-simple/default -i -X PUT -d '{
             "url": "https://upstream.example.com"
         }'

Policy responses will now contain information about the upstream service.

$ curl -i -H "host: example.com" http://localhost:8088/

HTTP/1.1 200 OK
X-Endpoint: example
X-Ratelimit-Limit: 200 5000
X-Ratelimit-Remaining: 199 4999
X-Ratelimit-Reset: 59 3599
X-Upstream-Host: upstream.example.com
X-Upstream-Path: /
X-Upstream-Port: 443
X-Upstream-Preserve-Host: false
X-Upstream-Proto: https
X-Upstream-Url: https://upstream.example.com:443/
Date: Mon, 12 Sep 2016 08:44:26 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8

The X-Upstream response headers may be useful for a proxy that needs to fetch resources from some upstream service.

Define an endpoint using the file system

The policy engine reads endpoint definitions from the file system. The directory that is used for this is /var/lib/policy-engine/ by default. An endpoint definition can be defined by creating a file /var/lib/policy-engine/endpoints/example.json with the following example content:

{
   "path": "/*",
   "host": "example.com",
   "name": "example",
   "modules": [
      {
         "order": 0,
         "name": "rate-limit",
         "default": {
            "hour": 5000,
            "minute": 200
         }
      },
      {
         "order": 1,
         "name": "upstream-simple",
         "default": {
            "url": "https://upstream.example.com"
         }
      }
   ]
}

Validate that the configuration is valid:

$ sudo policy-engine --config-check --log-level debug

Load the updated configuration by restarting the service:

$ sudo systemctl restart policy-engine

A less disruptive alternative to restarting the service is to refresh the endpoint configurations using the management API while the service is running:

$ curl -X REFRESH http://localhost:8089/endpoints

Next steps

Now it is time to read up on Modules and Integration with other services.