Writing a Plugin: Server Type

Join the Caddy Community Forum to chat with other Caddy developers!

Caddy ships with an HTTP server, but you can implement other server types and plug them into Caddy. Other server types could be mail, DNS, TCP, something else used internally, etc.

To Caddy, the notion of a server is anything that can Listen() and Serve(). What that means and how that works is up to you. Feel free to be creative and liberal with this idea.

If your server type can use TLS, it should take advantage of Caddy's magic TLS features. We describe how to do that at the end of this guide.

At a high level, plugging in a server type is very easy, using the caddy.RegisterServerType() function. You pass in the name of the server type and a caddy.ServerType struct describing it.

Here's a (somewhat simplified) example of how the HTTP server does it:

import "github.com/mholt/caddy"

func init() {
	caddy.RegisterServerType("http", caddy.ServerType{
		Directives: directives,
		DefaultInput: func() caddy.Input {
			return caddy.CaddyfileInput{
				Contents:       []byte(fmt.Sprintf("%s:%s\nroot %s", Host, Port, Root)),
				ServerTypeName: "http",
			}
		},
		NewContext: newContext,
	})
}

As you can see, server types consist of a name ("http"), a list of directives, a default Caddyfile input (optional, but recommended), and a context. We'll talk about each of these now.

Directives

Each server type gets to define which directives it recognizes and in what order they should be executed. This is simply a list of strings, where each string is the name of a directive:

var directives = []string{
	"dir1",
	"dir2",
	"etc",
}

In most server types, the execution order matters significantly, so directives will not be executed if they are not in this list.

Default Caddyfile Input

This is optional, but highly recommended in case you would rather not default to a blank Caddyfile. What this means for your server type is up to you. But you can return an instance of caddy.CaddyfileInput to satisfy this function. Caddy will call your function only if it is needed.

Context

Caddy tries to avoid as much global state as possible. When Caddy loads, parses, and executes a Caddyfile, it does so in a scope called an Instance so that a group of servers can be managed individually and multiple server types can be started in the same process.

Each time Caddy goes through this startup phase, it will create a new caddy.Instance and Caddy will ask your server type for a new caddy.Context value so that it can execute your server's directives without sharing global state. Read the godoc for caddy.Context for more information.

You should not store a a list of contexts with your server type; they will be stored with the Instance and are accessible from Controllers. Keeping references to contexts lying around will prevent them from being garbage collected if the server is stopped later, which is likely a memory leak.

Ultimately, your goal is to make it so that MakeServers() returns a list of caddy.Server values that Caddy can use. How you do that is entirely up to you.

For example: the HTTP server uses its context type to keep a map of site configs. The package also has an exported function, GetConfig(c Controller) that gets a config for a certain site, designated by the caddy.Controller that is passed in. The config, in turn, stores the list of middleware, etc -- all the information needed to set up a site. Each directive's action calls the GetConfig function so they can help set up the site properly. By the time MakeServers() is called, all it has to do is combine those site configs into server instances and return them. (Server instances implement caddy.Server.)

Server

The caddy.Server interface considers both TCP and non-TCP servers. It has four methods; two are for TCP, two are for UDP or other:

type Server interface {
    TCPServer // Required if using TCP
    UDPServer // Required if using UDP or other
}

type TCPServer interface {
    Listen() (net.Listener, error)
    Serve(net.Listener) error
}

type UDPServer interface {
    ListenPacket() (net.PacketConn, error)
    ServePacket(net.PacketConn) error
}

If your server only uses TCP, the *Packet() methods may be no-ops (i.e. they return nil). The inverse is true for non-TCP servers. A server may also use both TCP and UDP, and implement all four methods.

Once this interface is implemented and configuration is properly applied from Caddyfile directives, your server type is ready to roll.

Automatic TLS

Server types that can use TLS should enable TLS automatically before we add it to the Caddy download page. Import the caddytls package to use Caddy's magic TLS features. This can seem a little confusing to integrate at first, but once it's working you'll love it and realize it's soooo worth it.

• You will need a way to store Caddy TLS configurations for your server instances. Typically this just means adding a field to your server's config struct.
• That same server config struct type should implement the caddytls.ConfigHolder interface. This is just a few getter methods.
• Call RegisterConfigGetter() in your package's init() so that the caddytls package knows how to ask for a config when it is parsing the Caddyfile for your server type. (Your "config getter" will have to make a new caddytls.Config if one does not already exist for the given Controller.)
• Add the tls directive to your server type's list of directives. Usually it goes near the front of the list.

When you are instantiating your actual server value and need a tls.Config, you can call caddytls.MakeTLSConfig(tlsConfigs) where tlsConfigs is a []caddytls.Config. This function will convert a list of Caddy TLS configs to a single standard library tls.Config for you. You can then use this in a call to tls.NewListener().

Finally, you typically want to enable TLS while the Caddyfile is being parsed. For example, the HTTP server configures HTTPS right after the tls directive is executed. You should use your package's init() function to register a parsing callback that goes through the configurations and configures TLS:

// replace "http" with your own server type name
caddy.RegisterParsingCallback("http", "tls", activateHTTPS)

This code executes the activateHTTPS() function after the tls directive is finished setting up. Your server type should have a similar function that enables TLS in a way that makes sense to it. To give you an idea, the HTTP server's activateHTTPS function does the following:

1. Prints a message to stdout, "Activating privacy features..." (if the operator is present; i.e. caddy.Started() == false) because the process can take a few seconds
2. Sets the Managed field to true on all configs that should be fully managed
3. Calls ObtainCert() for each config (this method only obtains certificates if the config qualifies and has its Managed field set to true).
4. Configures the server struct to use the newly-obtained certificates by setting the Enabled field of the TLS config to true and calling caddytls.CacheManagedCertificate() which actually loads the cert into memory for use
5. Calls caddytls.SetDefaultTLSParams() to make sure all the necessary fields have a value
6. Calls caddytls.RenewManagedCertificates(true) to ensure that all certificates that were loaded into memory have been renewed if necessary

That's a lot to do, but you can also look at how the HTTP server does it (<-- this is a permalink, so the latest code may be better) for guidance.

To help preserve perfect forward secrecy, you should call caddytls.RotateSessionTicketKeys() when instantiating your server value, passing in the TLS config. Be sure to close the channel it returns when your server is stopped.

Everything else about TLS: renewals, OCSP, and other maintenance, happen for you, since those are the same for all server types. All these steps simply hook your server type up to Caddy's TLS package so that it knows how to do its job.

Test your integration of the caddytls package thoroughly. Once it's working well, let's add your server type to the download page!