openresty ssl certificate routines for peter_sslers SSL Certificate manager


Lua support for Certificate Manager in OpenResty


This package is almost production-ready.


one line...

    sudo opm install aptise/peter_sslers-lua-resty


lua-resty-peter_sslers is a library that can be used in an openresty/nginx environment to dynamically serve the correct SSL certificate for a given domain.

It supports both the prime cache types 1 & 2 of peter_sslers

It is implemented as a library with some example scripts to invoke it.

  • core library

    • ssl_certhandler.lua

  • examples

    • ssl_certhandler-lookup.lua

    • ssl_certhandler-expire.lua

    • ssl_certhandler-status.lua

The -lookup.lua, -expire.lua, -status.lua scripts can be copied into a block.

The library is hardcoded to use db9 in redis. if you want another option, edit or PR a fix on the line that looks like:

ngx.log(ngx.ERR, "changing to db 9: ", times) redcon:select(9)

Redis is NOT required, but recommended. Instead you can failover to directly query a peter_sslers pyramid instance.

To use the Peter SSlers Pyramid fallback, the following library is used:

  • lua-resty-http

Hits and misses from the fallback API will be cached in the shared cache dict. If you need to remove values, you will need to restart the server OR use one of the nginx/lua examples for cache clearing. Fallback API requests will notify the Pyramid app that the request should have write-through cache behavior.

Caching Note

In order to maximize performance there are 2 layers of caching WITHIN nginx/openresty:

  • certificates are cached in a LRU cache within a given worker in the native cdata format for ssl_certhandler.lru_cache_duration seconds (default 60)

  • certificates are cached across all workers in PEM format for ssl_certhandler.cert_cache_duration seconds (default 600)

These values can be adjusted.


The nginx shared dict can easily have values queried flushed/expired/overwritten, however it can only store PEM certificates (not the cdata pointers), so the certificates need to be repeatedly parsed.

The LRU cache can hold the cdata pointers, but implementation details of nginx/openresty do not allow easy query & manipulation of the cache. Messaging between all the workers for overwriting/expiry would be a large task too.

An easy way to handle deployment concerns is to use a timeout on the LRU cache that is long-enough to perform well under load, but short-enough to allow for changes in the shared-dict to propagate.


Make sure your nginx contains:

`` server { init_by_lua_block { require "resty.core" local ssl_certhandler = require "peter_sslers.ssl_certhandler" ssl_certhandler.initialize() } init_worker_by_lua_block { require "resty.core" local ssl_certhandler = require "peter_sslers.ssl_certhandler" -- cert_cache_duration, lru_cache_duration, lru_maxitems ssl_certhandler.initialize_worker(90, 30, 200) } } ``

  • initialize currently does nothing.

  • initialize_worker accepts three arguments:

    • cert_cache_duration seconds for PEM cache in ngx.shared.DICT

    • lru_cache_duration seconds for LRU cache of cdata pointer in worker

    • lru_maxitems max number of items for LRU cache of cdata pointer in worker

Then implement the examples routes

Due to an implementation detail of lua/luajit, the examples below must be implemented in a block/file and can not be "require(/path/to/example)". This is because of how the redis connection is instantiated. (see )


Core library. Exposes several functions.


This is very simple, it merely specfies a cache, duration, and prime_version

invoked within nginx...

`` server { listen 443 default_server; ... // nginx must have a default configured ssl_certificate /path/to/default/fullchain.pem; ssl_certificate_key /path/to/default/privkey.pem; ssl_certificate_by_lua_block { } ``


The nginx shared memory cache persists across configuration reloads. Servers must be fully restarted to clear memory.

The workaround? API endpoints to "flush" the cache or expire certain keys(domains).

A simple example is provided with peter_sslers.ssl_certhandler-expire, which can be invoked within nginx as-is rather easily:

`` server { listen 443 default_server; ... location /.peter_sslers { auth_basic "peter_sslers-nginx"; auth_basic_user_file /path/to/peter_sslers-nginx.htpasswd; location /.peter_sslers/nginx/shared_cache/expire { content_by_lua_block { -- requirements local ssl_certhandler = require "peter_sslers.ssl_certhandler"

                                        -- alias functions
                                        local ssl_certhandler_expire = ssl_certhandler.expire_ssl_certs

This expire tool creates the following routes:

  • /peter_sslers/nginx/shared_cache/expire/all Flushes the entire nginx certificate cache

  • /peter_sslers/nginx/shared_cache/expire/domain/{DOMAIN} Flushes the domain's pkey & chain entires in the certificate cache

On success, these routes return JSON in a HTTP-200-OK document.

  • {"result": "success", "expired": "all"}

  • {"result": "success", "expired": "domain", "domain": "{DOMAIN}"}

  • {"result": "error", "expired": "None", "reason": "Unknown URI"}

On error, these routes should generate a bad status code.

The Pyramid component can query these endpoints automatically for you.


The status route shows some info about the system

`` server { listen 443 default_server; ... location /.peter_sslers/nginx { auth_basic "peter_sslers-nginx"; auth_basic_user_file /path/to/peter_sslers-nginx.htpasswd; location /.peter_sslers/nginx/shared_cache/status { content_by_lua_block { -- requirements local ssl_certhandler = require "peter_sslers.ssl_certhandler"

                                        -- alias functions
                                        local ssl_certhandler_status = ssl_certhandler.status_ssl_certs


This the core work:

`` ssl_certificate_by_lua_block { -- requirements local ssl_certhandler = require "peter_sslers.ssl_certhandler"

            -- alias functions
            local ssl_certhandler_set = ssl_certhandler.set_ssl_certificate

            local prime_version = 1
            local fallback_server = ''
            ssl_certhandler_set(prime_version, fallback_server)

fully configured example

a fully configured example is available in the main peter_sslers repo:


This approach makes aggressive use of caching in the nginx workers (via worker lru and a shared dict) and Redis; caching both hits and misses.

The nginx worker dicts are shared across reloads (kill -HUP {PID}); so if a bad value gets in there you must restart or wait for the timeout.

The logic in pseudocode:

`` cert_cdata = lru_cache.get(domain) # check worker cache if hit(cert_cdata): if invalid(cert_cdata): return else: cert_pem = cert_cache.get(domain) # check shared cache if hit(cert_pem): if invalid(cert_pem): lru_cache.set(domain, invalid) return else: cert_pem = redis.get(domain) if hit(cert_pem): if invalid(cert_pem): lru_cache.set(domain, invalid) cert_cache.set(domain, invalid) return else: cert_pem = upstream_https.get(domain) if hit(cert_pem): if invalid(cert_pem): lru_cache.set(domain, invalid) cert_cache.set(domain, invalid) return if valid(cert_pem) lru_cache.set(domain, cert_cdata) cert_cache.set(domain, cert_pem) cert_cdata = parse(cert_pem) if valid(cert_cdata): set_ssl_certificate(cert_cdata) ``

Integration/Debugging HowTo

Various levels of information are sent to the following debug levels of nginx. Changing the nginx debug level will expose more data

  • ERR



Notice how a worker is initialized:

-- cert_cache_duration, lru_cache_duration, lru_maxitems ssl_certhandler.initialize_worker(90, 30, 100)

For debugging you may want to lower these to shorten the LRU cache to a negligible number

ssl_certhandler.initialize_worker(5, 1, 100)

The "/status" and "/expire" routes only show information in the shared cache -- information is cached into each worker's own LRU cache and is not available to these routes. If "/expire" is used, a domain will be removed from the shared cache and "/status" route... but may still be in a worker's LRU.

Check the status:

curl -k https://peter:sslers@

expire curl -k https://peter:sslers@

Known problems


Jonathan Vanasco <>

Originally started in


This module is licensed under the MIT License. See LICENSE.txt


Jonathan Vanasco (