a project

Every site on HTTPS

Caddy is an extensible server platform that uses TLS by default.

Caddy Forum
Caddy on Sourcegraph Cloudsmith

Releases · Documentation · Get Help


Powered by


  • Easy configuration with the Caddyfile
  • Powerful configuration with its native JSON config
  • Dynamic configuration with the JSON API
  • Config adapters if you don't like JSON
  • Automatic HTTPS by default
    • ZeroSSL and Let's Encrypt for public names
    • Fully-managed local CA for internal names & IPs
    • Can coordinate with other Caddy instances in a cluster
    • Multi-issuer fallback
  • Stays up when other servers go down due to TLS/OCSP/certificate-related issues
  • Production-ready after serving trillions of requests and managing millions of TLS certificates
  • Scales to tens of thousands of sites ... and probably more
  • HTTP/1.1, HTTP/2, and experimental HTTP/3 support
  • Highly extensible modular architecture lets Caddy do anything without bloat
  • Runs anywhere with no external dependencies (not even libc)
  • Written in Go, a language with higher memory safety guarantees than other servers
  • Actually fun to use
  • So, so much more to discover


The simplest, cross-platform way is to download from GitHub Releases and place the executable file in your PATH.

For other install options, see

Build from source


For development

Note: These steps will not embed proper version information. For that, please follow the instructions in the next section.

$ git clone ""
$ cd caddy/cmd/caddy/
$ go build

When you run Caddy, it may try to bind to low ports unless otherwise specified in your config. If your OS requires elevated privileges, you will need to give your new binary permission to do so. On Linux, this can be done easily with: sudo setcap cap_net_bind_service=+ep ./caddy

If you prefer to use go run which creates temporary binaries, you can still do this. Make an executable file called (or whatever you want) with these contents:

sudo setcap cap_net_bind_service=+ep "$1"

then you can use go run like so:

$ go run -exec ./ main.go

If you don't want to type your password for setcap, use sudo visudo to edit your sudoers file and allow your user account to run that command without a password, for example:

username ALL=(ALL:ALL) NOPASSWD: /usr/sbin/setcap

replacing username with your actual username. Please be careful and only do this if you know what you are doing! We are only qualified to document how to use Caddy, not Go tooling or your computer, and we are providing these instructions for convenience only; please learn how to use your own computer at your own risk and make any needful adjustments.

With version information and/or plugins

Using our builder tool, xcaddy...

$ xcaddy build

...the following steps are automated:

  1. Create a new folder: mkdir caddy
  2. Change into it: cd caddy
  3. Copy Caddy's main.go into the empty folder. Add imports for any custom plugins you want to add.
  4. Initialize a Go module: go mod init caddy
  5. (Optional) Pin Caddy version: go get replacing version with a git tag or commit.
  6. (Optional) Add plugins by adding their import: _ "import/path/here"
  7. Compile: go build

Quick start

The Caddy website has documentation that includes tutorials, quick-start guides, reference, and more.

We recommend that all users -- regardless of experience level -- do our Getting Started guide to become familiar with using Caddy.

If you've only got a minute, the website has several quick-start tutorials to choose from! However, after finishing a quick-start tutorial, please read more documentation to understand how the software works. 🙂


Caddy is most often used as an HTTPS server, but it is suitable for any long-running Go program. First and foremost, it is a platform to run Go applications. Caddy "apps" are just Go programs that are implemented as Caddy modules. Two apps -- tls and http -- ship standard with Caddy.

Caddy apps instantly benefit from automated documentation, graceful on-line config changes via API, and unification with other Caddy apps.

Although JSON is Caddy's native config language, Caddy can accept input from config adapters which can essentially convert any config format of your choice into JSON: Caddyfile, JSON 5, YAML, TOML, NGINX config, and more.

The primary way to configure Caddy is through its API, but if you prefer config files, the command-line interface supports those too.

Caddy exposes an unprecedented level of control compared to any web server in existence. In Caddy, you are usually setting the actual values of the initialized types in memory that power everything from your HTTP handlers and TLS handshakes to your storage medium. Caddy is also ridiculously extensible, with a powerful plugin system that makes vast improvements over other web servers.

To wield the power of this design, you need to know how the config document is structured. Please see our documentation site for details about Caddy's config structure.

Nearly all of Caddy's configuration is contained in a single config document, rather than being scattered across CLI flags and env variables and a configuration file as with other web servers. This makes managing your server config more straightforward and reduces hidden variables/factors.

Full documentation

Our website has complete documentation:

The docs are also open source. You can contribute to them here:

Getting help

  • We strongly recommend that all professionals or companies using Caddy get a support contract through Ardan Labs before help is needed.

  • A sponsorship goes a long way!

  • Individuals can exchange help for free on our community forum at Remember that people give help out of their spare time and good will. The best way to get help is to give it first!

Please use our issue tracker only for bug reports and feature requests, i.e. actionable development items (support questions will usually be referred to the forums).


The name "Caddy" is trademarked. The name of the software is "Caddy", not "Caddy Server" or "CaddyServer". Please call it "Caddy" or, if you wish to clarify, "the Caddy web server". Caddy is a registered trademark of apilayer GmbH.

Caddy is a project of ZeroSSL, an apilayer company.

Debian package repository hosting is graciously provided by Cloudsmith. Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that enables your organization to create, store and share packages in any format, to any place, with total confidence.

Expand ▾ Collapse ▴





View Source
const (
	ExitCodeSuccess = iota

    Exit codes. Generally, you should NOT automatically restart the process if the exit code is ExitCodeFailedStartup (1).

    View Source
    const ImportPath = ""

      ImportPath is the package import path for Caddy core.


      View Source
      var (
      	// DefaultAdminListen is the address for the admin
      	// listener, if none is specified at startup.
      	DefaultAdminListen = "localhost:2019"
      	// ErrInternalRedir indicates an internal redirect
      	// and is useful when admin API handlers rewrite
      	// the request; in that case, authentication and
      	// authorization needs to happen again for the
      	// rewritten request.
      	ErrInternalRedir = fmt.Errorf("internal redirect; re-authorization required")
      	// DefaultAdminConfig is the default configuration
      	// for the administration endpoint.
      	DefaultAdminConfig = &AdminConfig{
      		Listen: DefaultAdminListen,
      View Source
      var ConfigAutosavePath = filepath.Join(AppConfigDir(), "autosave.json")

        ConfigAutosavePath is the default path to which the last config will be persisted.

        View Source
        var DefaultStorage = &certmagic.FileStorage{Path: AppDataDir()}

          DefaultStorage is Caddy's default storage module.


          func AppConfigDir

          func AppConfigDir() string

            AppConfigDir returns the directory where to store user's config.

            If XDG_CONFIG_HOME is set, it returns: $XDG_CONFIG_HOME/caddy. Otherwise, os.UserConfigDir() is used; if successful, it appends "Caddy" (Windows & Mac) or "caddy" (every other OS) to the path. If it returns an error, the fallback path "./caddy" is returned.

            The config directory is not guaranteed to be different from AppDataDir().

            Unlike os.UserConfigDir(), this function prefers the XDG_CONFIG_HOME env var on all platforms, not just Unix.


            func AppDataDir

            func AppDataDir() string

              AppDataDir returns a directory path that is suitable for storing application data on disk. It uses the environment for finding the best place to store data, and appends a "caddy" or "Caddy" (depending on OS and environment) subdirectory.

              For a base directory path: If XDG_DATA_HOME is set, it returns: $XDG_DATA_HOME/caddy; otherwise, on Windows it returns: %AppData%/Caddy, on Mac: $HOME/Library/Application Support/Caddy, on Plan9: $home/lib/caddy, on Android: $HOME/caddy, and on everything else: $HOME/.local/share/caddy.

              If a data directory cannot be determined, it returns "./caddy" (this is not ideal, and the environment should be fixed).

              The data directory is not guaranteed to be different from AppConfigDir().


              func GetModuleID

              func GetModuleID(instance interface{}) string

                GetModuleID returns a module's ID from an instance of its value. If the value is not a module, an empty string will be returned.

                func GetModuleName

                func GetModuleName(instance interface{}) string

                  GetModuleName returns a module's name (the last label of its ID) from an instance of its value. If the value is not a module, an empty string will be returned.

                  func GoModule

                  func GoModule() *debug.Module

                    GoModule returns the build info of this Caddy build from debug.BuildInfo (requires Go modules). If no version information is available, a non-nil value will still be returned, but with an unknown version.

                    func HomeDir

                    func HomeDir() string

                      HomeDir returns the best guess of the current user's home directory from environment variables. If unknown, "." (the current directory) is returned instead, except GOOS=android, which returns "/sdcard".

                      func JoinNetworkAddress

                      func JoinNetworkAddress(network, host, port string) string

                        JoinNetworkAddress combines network, host, and port into a single address string of the form accepted by ParseNetworkAddress(). For unix sockets, the network should be "unix" (or "unixgram" or "unixpacket") and the path to the socket should be given as the host parameter.

                        func Listen

                        func Listen(network, addr string) (net.Listener, error)

                          Listen returns a listener suitable for use in a Caddy module. Always be sure to close listeners when you are done with them.

                          func ListenPacket

                          func ListenPacket(network, addr string) (net.PacketConn, error)

                            ListenPacket returns a net.PacketConn suitable for use in a Caddy module. Always be sure to close the PacketConn when you are done.

                            func Load

                            func Load(cfgJSON []byte, forceReload bool) error

                              Load loads the given config JSON and runs it only if it is different from the current config or forceReload is true.

                              func Log

                              func Log() *zap.Logger

                                Log returns the current default logger.

                                func Modules

                                func Modules() []string

                                  Modules returns the names of all registered modules in ascending lexicographical order.

                                  func PIDFile

                                  func PIDFile(filename string) error

                                    PIDFile writes a pidfile to the file at filename. It will get deleted before the process gracefully exits.

                                    func ParseDuration

                                    func ParseDuration(s string) (time.Duration, error)

                                      ParseDuration parses a duration string, adding support for the "d" unit meaning number of days, where a day is assumed to be 24h.

                                      func ParseStructTag

                                      func ParseStructTag(tag string) (map[string]string, error)

                                        ParseStructTag parses a caddy struct tag into its keys and values. It is very simple. The expected syntax is: `caddy:"key1=val1 key2=val2 ..."`

                                        func RegisterModule

                                        func RegisterModule(instance Module)

                                          RegisterModule registers a module by receiving a plain/empty value of the module. For registration to be properly recorded, this should be called in the init phase of runtime. Typically, the module package will do this as a side-effect of being imported. This function panics if the module's info is incomplete or invalid, or if the module is already registered.

                                          func RemoveMetaFields

                                          func RemoveMetaFields(rawJSON []byte) []byte

                                            RemoveMetaFields removes meta fields like "@id" from a JSON message by using a simple regular expression. (An alternate way to do this would be to delete them from the raw, map[string]interface{} representation as they are indexed, then iterate the index we made and add them back after encoding as JSON, but this is simpler.)

                                            func Run

                                            func Run(cfg *Config) error

                                              Run runs the given config, replacing any existing config.

                                              func SplitNetworkAddress

                                              func SplitNetworkAddress(a string) (network, host, port string, err error)

                                                SplitNetworkAddress splits a into its network, host, and port components. Note that port may be a port range (:X-Y), or omitted for unix sockets.

                                                func Stop

                                                func Stop() error

                                                  Stop stops running the current configuration. It is the antithesis of Run(). This function will log any errors that occur during the stopping of individual apps and continue to stop the others. Stop should only be called if not replacing with a new config.

                                                  func TrapSignals

                                                  func TrapSignals()

                                                    TrapSignals create signal/interrupt handlers as best it can for the current OS. This is a rather invasive function to call in a Go program that captures signals already, so in that case it would be better to implement these handlers yourself.

                                                    func Validate

                                                    func Validate(cfg *Config) error

                                                      Validate loads, provisions, and validates cfg, but does not start running it.


                                                      type APIError

                                                      type APIError struct {
                                                      	Code    int    `json:"-"`
                                                      	Err     error  `json:"-"`
                                                      	Message string `json:"error"`

                                                        APIError is a structured error that every API handler should return for consistency in logging and client responses. If Message is unset, then Err.Error() will be serialized in its place.

                                                        func (APIError) Error

                                                        func (e APIError) Error() string

                                                        type AdminConfig

                                                        type AdminConfig struct {
                                                        	// If true, the admin endpoint will be completely disabled.
                                                        	// Note that this makes any runtime changes to the config
                                                        	// impossible, since the interface to do so is through the
                                                        	// admin endpoint.
                                                        	Disabled bool `json:"disabled,omitempty"`
                                                        	// The address to which the admin endpoint's listener should
                                                        	// bind itself. Can be any single network address that can be
                                                        	// parsed by Caddy. Default: localhost:2019
                                                        	Listen string `json:"listen,omitempty"`
                                                        	// If true, CORS headers will be emitted, and requests to the
                                                        	// API will be rejected if their `Host` and `Origin` headers
                                                        	// do not match the expected value(s). Use `origins` to
                                                        	// customize which origins/hosts are allowed.If `origins` is
                                                        	// not set, the listen address is the only value allowed by
                                                        	// default.
                                                        	EnforceOrigin bool `json:"enforce_origin,omitempty"`
                                                        	// The list of allowed origins/hosts for API requests. Only needed
                                                        	// if accessing the admin endpoint from a host different from the
                                                        	// socket's network interface or if `enforce_origin` is true. If not
                                                        	// set, the listener address will be the default value. If set but
                                                        	// empty, no origins will be allowed.
                                                        	Origins []string `json:"origins,omitempty"`
                                                        	// Options related to configuration management.
                                                        	Config *ConfigSettings `json:"config,omitempty"`

                                                          AdminConfig configures Caddy's API endpoint, which is used to manage Caddy while it is running.

                                                          type AdminHandler

                                                          type AdminHandler interface {
                                                          	ServeHTTP(http.ResponseWriter, *http.Request) error

                                                            AdminHandler is like http.Handler except ServeHTTP may return an error.

                                                            If any handler encounters an error, it should be returned for proper handling.

                                                            type AdminHandlerFunc

                                                            type AdminHandlerFunc func(http.ResponseWriter, *http.Request) error

                                                              AdminHandlerFunc is a convenience type like http.HandlerFunc.

                                                              func (AdminHandlerFunc) ServeHTTP

                                                                ServeHTTP implements the Handler interface.

                                                                type AdminRoute

                                                                type AdminRoute struct {
                                                                	Pattern string
                                                                	Handler AdminHandler

                                                                  AdminRoute represents a route for the admin endpoint.

                                                                  type AdminRouter

                                                                  type AdminRouter interface {
                                                                  	Routes() []AdminRoute

                                                                    AdminRouter is a type which can return routes for the admin API.

                                                                    type App

                                                                    type App interface {
                                                                    	Start() error
                                                                    	Stop() error

                                                                      App is a thing that Caddy runs.

                                                                      type CleanerUpper

                                                                      type CleanerUpper interface {
                                                                      	Cleanup() error

                                                                        CleanerUpper is implemented by modules which may have side-effects such as opened files, spawned goroutines, or allocated some sort of non-stack state when they were provisioned. This method should deallocate/cleanup those resources to prevent memory leaks. Cleanup should be fast and efficient. Cleanup should work even if Provision returns an error, to allow cleaning up from partial provisionings.

                                                                        type Config

                                                                        type Config struct {
                                                                        	Admin   *AdminConfig `json:"admin,omitempty"`
                                                                        	Logging *Logging     `json:"logging,omitempty"`
                                                                        	// StorageRaw is a storage module that defines how/where Caddy
                                                                        	// stores assets (such as TLS certificates). The default storage
                                                                        	// module is `` (the local file system),
                                                                        	// and the default path
                                                                        	// [depends on the OS and environment](/docs/conventions#data-directory).
                                                                        	StorageRaw json.RawMessage `json:"storage,omitempty" caddy:" inline_key=module"`
                                                                        	// AppsRaw are the apps that Caddy will load and run. The
                                                                        	// app module name is the key, and the app's config is the
                                                                        	// associated value.
                                                                        	AppsRaw ModuleMap `json:"apps,omitempty" caddy:"namespace="`
                                                                        	// contains filtered or unexported fields

                                                                          Config is the top (or beginning) of the Caddy configuration structure. Caddy config is expressed natively as a JSON document. If you prefer not to work with JSON directly, there are [many config adapters](/docs/config-adapters) available that can convert various inputs into Caddy JSON.

                                                                          Many parts of this config are extensible through the use of Caddy modules. Fields which have a json.RawMessage type and which appear as dots (•••) in the online docs can be fulfilled by modules in a certain module namespace. The docs show which modules can be used in a given place.

                                                                          Whenever a module is used, its name must be given either inline as part of the module, or as the key to the module's value. The docs will make it clear which to use.

                                                                          Generally, all config settings are optional, as it is Caddy convention to have good, documented default values. If a parameter is required, the docs should say so.

                                                                          Go programs which are directly building a Config struct value should take care to populate the JSON-encodable fields of the struct (i.e. the fields with `json` struct tags) if employing the module lifecycle (e.g. Provision method calls).

                                                                          type ConfigSettings

                                                                          type ConfigSettings struct {
                                                                          	// Whether to keep a copy of the active config on disk. Default is true.
                                                                          	Persist *bool `json:"persist,omitempty"`

                                                                            ConfigSettings configures the, uh, configuration... and management thereof.

                                                                            type Constructor

                                                                            type Constructor func() (Destructor, error)

                                                                              Constructor is a function that returns a new value that can destruct itself when it is no longer needed.

                                                                              type Context

                                                                              type Context struct {
                                                                              	// contains filtered or unexported fields

                                                                                Context is a type which defines the lifetime of modules that are loaded and provides access to the parent configuration that spawned the modules which are loaded. It should be used with care and wrapped with derivation functions from the standard context package only if you don't need the Caddy specific features. These contexts are canceled when the lifetime of the modules loaded from it is over.

                                                                                Use NewContext() to get a valid value (but most modules will not actually need to do this).

                                                                                func NewContext

                                                                                func NewContext(ctx Context) (Context, context.CancelFunc)

                                                                                  NewContext provides a new context derived from the given context ctx. Normally, you will not need to call this function unless you are loading modules which have a different lifespan than the ones for the context the module was provisioned with. Be sure to call the cancel func when the context is to be cleaned up so that modules which are loaded will be properly unloaded. See standard library context package's documentation.

                                                                                  func (Context) App

                                                                                  func (ctx Context) App(name string) (interface{}, error)

                                                                                    App returns the configured app named name. If that app has not yet been loaded and provisioned, it will be immediately loaded and provisioned. If no app with that name is configured, a new empty one will be instantiated instead. (The app module must still be registered.) This must not be called during the Provision/Validate phase to reference a module's own host app (since the parent app module is still in the process of being provisioned, it is not yet ready).

                                                                                    func (Context) LoadModule

                                                                                    func (ctx Context) LoadModule(structPointer interface{}, fieldName string) (interface{}, error)

                                                                                      LoadModule loads the Caddy module(s) from the specified field of the parent struct pointer and returns the loaded module(s). The struct pointer and its field name as a string are necessary so that reflection can be used to read the struct tag on the field to get the module namespace and inline module name key (if specified).

                                                                                      The field can be any one of the supported raw module types: json.RawMessage, []json.RawMessage, map[string]json.RawMessage, or []map[string]json.RawMessage. ModuleMap may be used in place of map[string]json.RawMessage. The return value's underlying type mirrors the input field's type:

                                                                                      json.RawMessage              => interface{}
                                                                                      []json.RawMessage            => []interface{}
                                                                                      [][]json.RawMessage          => [][]interface{}
                                                                                      map[string]json.RawMessage   => map[string]interface{}
                                                                                      []map[string]json.RawMessage => []map[string]interface{}

                                                                                      The field must have a "caddy" struct tag in this format:

                                                                                      caddy:"key1=val1 key2=val2"

                                                                                      To load modules, a "namespace" key is required. For example, to load modules in the "http.handlers" namespace, you'd put: `namespace=http.handlers` in the Caddy struct tag.

                                                                                      The module name must also be available. If the field type is a map or slice of maps, then key is assumed to be the module name if an "inline_key" is NOT specified in the caddy struct tag. In this case, the module name does NOT need to be specified in-line with the module itself.

                                                                                      If not a map, or if inline_key is non-empty, then the module name must be embedded into the values, which must be objects; then there must be a key in those objects where its associated value is the module name. This is called the "inline key", meaning the key containing the module's name that is defined inline with the module itself. You must specify the inline key in a struct tag, along with the namespace:

                                                                                      caddy:"namespace=http.handlers inline_key=handler"

                                                                                      This will look for a key/value pair like `"handler": "..."` in the json.RawMessage in order to know the module name.

                                                                                      To make use of the loaded module(s) (the return value), you will probably want to type-assert each interface{} value(s) to the types that are useful to you and store them on the same struct. Storing them on the same struct makes for easy garbage collection when your host module is no longer needed.

                                                                                      Loaded modules have already been provisioned and validated. Upon returning successfully, this method clears the json.RawMessage(s) in the field since the raw JSON is no longer needed, and this allows the GC to free up memory.

                                                                                      Example (Array)
                                                                                      Example (Map)

                                                                                      func (Context) LoadModuleByID

                                                                                      func (ctx Context) LoadModuleByID(id string, rawMsg json.RawMessage) (interface{}, error)

                                                                                        LoadModuleByID decodes rawMsg into a new instance of mod and returns the value. If mod.New is nil, an error is returned. If the module implements Validator or Provisioner interfaces, those methods are invoked to ensure the module is fully configured and valid before being used.

                                                                                        This is a lower-level method and will usually not be called directly by most modules. However, this method is useful when dynamically loading/unloading modules in their own context, like from embedded scripts, etc.

                                                                                        func (Context) Logger

                                                                                        func (ctx Context) Logger(mod Module) *zap.Logger

                                                                                          Logger returns a logger that can be used by mod.

                                                                                          func (*Context) OnCancel

                                                                                          func (ctx *Context) OnCancel(f func())

                                                                                            OnCancel executes f when ctx is canceled.

                                                                                            func (Context) Storage

                                                                                            func (ctx Context) Storage() certmagic.Storage

                                                                                              Storage returns the configured Caddy storage implementation.

                                                                                              type CtxKey

                                                                                              type CtxKey string

                                                                                                CtxKey is a value type for use with context.WithValue.

                                                                                                const ReplacerCtxKey CtxKey = "replacer"

                                                                                                  ReplacerCtxKey is the context key for a replacer.

                                                                                                  type CustomLog

                                                                                                  type CustomLog struct {
                                                                                                  	// The writer defines where log entries are emitted.
                                                                                                  	WriterRaw json.RawMessage `json:"writer,omitempty" caddy:"namespace=caddy.logging.writers inline_key=output"`
                                                                                                  	// The encoder is how the log entries are formatted or encoded.
                                                                                                  	EncoderRaw json.RawMessage `json:"encoder,omitempty" caddy:"namespace=caddy.logging.encoders inline_key=format"`
                                                                                                  	// Level is the minimum level to emit, and is inclusive.
                                                                                                  	// Possible levels: DEBUG, INFO, WARN, ERROR, PANIC, and FATAL
                                                                                                  	Level string `json:"level,omitempty"`
                                                                                                  	// Sampling configures log entry sampling. If enabled,
                                                                                                  	// only some log entries will be emitted. This is useful
                                                                                                  	// for improving performance on extremely high-pressure
                                                                                                  	// servers.
                                                                                                  	Sampling *LogSampling `json:"sampling,omitempty"`
                                                                                                  	// Include defines the names of loggers to emit in this
                                                                                                  	// log. For example, to include only logs emitted by the
                                                                                                  	// admin API, you would include "admin.api".
                                                                                                  	Include []string `json:"include,omitempty"`
                                                                                                  	// Exclude defines the names of loggers that should be
                                                                                                  	// skipped by this log. For example, to exclude only
                                                                                                  	// HTTP access logs, you would exclude "http.log.access".
                                                                                                  	Exclude []string `json:"exclude,omitempty"`
                                                                                                  	// contains filtered or unexported fields

                                                                                                    CustomLog represents a custom logger configuration.

                                                                                                    By default, a log will emit all log entries. Some entries will be skipped if sampling is enabled. Further, the Include and Exclude parameters define which loggers (by name) are allowed or rejected from emitting in this log. If both Include and Exclude are populated, their values must be mutually exclusive, and longer namespaces have priority. If neither are populated, all logs are emitted.

                                                                                                    type Destructor

                                                                                                    type Destructor interface {
                                                                                                    	Destruct() error

                                                                                                      Destructor is a value that can clean itself up when it is deallocated.

                                                                                                      type DiscardWriter

                                                                                                      type DiscardWriter struct{}

                                                                                                        DiscardWriter discards all writes.

                                                                                                        func (DiscardWriter) CaddyModule

                                                                                                        func (DiscardWriter) CaddyModule() ModuleInfo

                                                                                                          CaddyModule returns the Caddy module information.

                                                                                                          func (DiscardWriter) OpenWriter

                                                                                                          func (DiscardWriter) OpenWriter() (io.WriteCloser, error)

                                                                                                            OpenWriter returns ioutil.Discard that can't be closed.

                                                                                                            func (DiscardWriter) String

                                                                                                            func (DiscardWriter) String() string

                                                                                                            func (DiscardWriter) WriterKey

                                                                                                            func (DiscardWriter) WriterKey() string

                                                                                                              WriterKey returns a unique key representing discard.

                                                                                                              type Duration

                                                                                                              type Duration time.Duration

                                                                                                                Duration can be an integer or a string. An integer is interpreted as nanoseconds. If a string, it is a Go time.Duration value such as `300ms`, `1.5h`, or `2h45m`; valid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.

                                                                                                                func (*Duration) UnmarshalJSON

                                                                                                                func (d *Duration) UnmarshalJSON(b []byte) error

                                                                                                                  UnmarshalJSON satisfies json.Unmarshaler.

                                                                                                                  type ListenerWrapper

                                                                                                                  type ListenerWrapper interface {
                                                                                                                  	WrapListener(net.Listener) net.Listener

                                                                                                                    ListenerWrapper is a type that wraps a listener so it can modify the input listener's methods. Modules that implement this interface are found in the caddy.listeners namespace. Usually, to wrap a listener, you will define your own struct type that embeds the input listener, then implement your own methods that you want to wrap, calling the underlying listener's methods where appropriate.

                                                                                                                    type LogSampling

                                                                                                                    type LogSampling struct {
                                                                                                                    	// The window over which to conduct sampling.
                                                                                                                    	Interval time.Duration `json:"interval,omitempty"`
                                                                                                                    	// Log this many entries within a given level and
                                                                                                                    	// message for each interval.
                                                                                                                    	First int `json:"first,omitempty"`
                                                                                                                    	// If more entries with the same level and message
                                                                                                                    	// are seen during the same interval, keep one in
                                                                                                                    	// this many entries until the end of the interval.
                                                                                                                    	Thereafter int `json:"thereafter,omitempty"`

                                                                                                                      LogSampling configures log entry sampling.

                                                                                                                      type Logging

                                                                                                                      type Logging struct {
                                                                                                                      	// Sink is the destination for all unstructured logs emitted
                                                                                                                      	// from Go's standard library logger. These logs are common
                                                                                                                      	// in dependencies that are not designed specifically for use
                                                                                                                      	// in Caddy. Because it is global and unstructured, the sink
                                                                                                                      	// lacks most advanced features and customizations.
                                                                                                                      	Sink *StandardLibLog `json:"sink,omitempty"`
                                                                                                                      	// Logs are your logs, keyed by an arbitrary name of your
                                                                                                                      	// choosing. The default log can be customized by defining
                                                                                                                      	// a log called "default". You can further define other logs
                                                                                                                      	// and filter what kinds of entries they accept.
                                                                                                                      	Logs map[string]*CustomLog `json:"logs,omitempty"`
                                                                                                                      	// contains filtered or unexported fields

                                                                                                                        Logging facilitates logging within Caddy. The default log is called "default" and you can customize it. You can also define additional logs.

                                                                                                                        By default, all logs at INFO level and higher are written to standard error ("stderr" writer) in a human-readable format ("console" encoder if stdout is an interactive terminal, "json" encoder otherwise).

                                                                                                                        All defined logs accept all log entries by default, but you can filter by level and module/logger names. A logger's name is the same as the module's name, but a module may append to logger names for more specificity. For example, you can filter logs emitted only by HTTP handlers using the name "http.handlers", because all HTTP handler module names have that prefix.

                                                                                                                        Caddy logs (except the sink) are zero-allocation, so they are very high-performing in terms of memory and CPU time. Enabling sampling can further increase throughput on extremely high-load servers.

                                                                                                                        func (*Logging) Logger

                                                                                                                        func (logging *Logging) Logger(mod Module) *zap.Logger

                                                                                                                          Logger returns a logger that is ready for the module to use.

                                                                                                                          type Module

                                                                                                                          type Module interface {
                                                                                                                          	// This method indicates that the type is a Caddy
                                                                                                                          	// module. The returned ModuleInfo must have both
                                                                                                                          	// a name and a constructor function. This method
                                                                                                                          	// must not have any side-effects.
                                                                                                                          	CaddyModule() ModuleInfo

                                                                                                                            Module is a type that is used as a Caddy module. In addition to this interface, most modules will implement some interface expected by their host module in order to be useful. To learn which interface(s) to implement, see the documentation for the host module. At a bare minimum, this interface, when implemented, only provides the module's ID and constructor function.

                                                                                                                            Modules will often implement additional interfaces including Provisioner, Validator, and CleanerUpper. If a module implements these interfaces, their methods are called during the module's lifespan.

                                                                                                                            When a module is loaded by a host module, the following happens: 1) ModuleInfo.New() is called to get a new instance of the module. 2) The module's configuration is unmarshaled into that instance. 3) If the module is a Provisioner, the Provision() method is called. 4) If the module is a Validator, the Validate() method is called. 5) The module will probably be type-asserted from interface{} to some other, more useful interface expected by the host module. For example, HTTP handler modules are type-asserted as caddyhttp.MiddlewareHandler values. 6) When a module's containing Context is canceled, if it is a CleanerUpper, its Cleanup() method is called.

                                                                                                                            type ModuleID

                                                                                                                            type ModuleID string

                                                                                                                              ModuleID is a string that uniquely identifies a Caddy module. A module ID is lightly structured. It consists of dot-separated labels which form a simple hierarchy from left to right. The last label is the module name, and the labels before that constitute the namespace (or scope).

                                                                                                                              Thus, a module ID has the form: <namespace>.<name>

                                                                                                                              An ID with no dot has the empty namespace, which is appropriate for app modules (these are "top-level" modules that Caddy core loads and runs).

                                                                                                                              Module IDs should be lowercase and use underscores (_) instead of spaces.

                                                                                                                              Examples of valid IDs: - http - http.handlers.file_server - caddy.logging.encoders.json

                                                                                                                              func (ModuleID) Name

                                                                                                                              func (id ModuleID) Name() string

                                                                                                                                Name returns the Name (last element) of a module ID.

                                                                                                                                func (ModuleID) Namespace

                                                                                                                                func (id ModuleID) Namespace() string

                                                                                                                                  Namespace returns the namespace (or scope) portion of a module ID, which is all but the last label of the ID. If the ID has only one label, then the namespace is empty.

                                                                                                                                  type ModuleInfo

                                                                                                                                  type ModuleInfo struct {
                                                                                                                                  	// ID is the "full name" of the module. It
                                                                                                                                  	// must be unique and properly namespaced.
                                                                                                                                  	ID ModuleID
                                                                                                                                  	// New returns a pointer to a new, empty
                                                                                                                                  	// instance of the module's type. This
                                                                                                                                  	// method must not have any side-effects,
                                                                                                                                  	// and no other initialization should
                                                                                                                                  	// occur within it. Any initialization
                                                                                                                                  	// of the returned value should be done
                                                                                                                                  	// in a Provision() method (see the
                                                                                                                                  	// Provisioner interface).
                                                                                                                                  	New func() Module

                                                                                                                                    ModuleInfo represents a registered Caddy module.

                                                                                                                                    func GetModule

                                                                                                                                    func GetModule(name string) (ModuleInfo, error)

                                                                                                                                      GetModule returns module information from its ID (full name).

                                                                                                                                      func GetModules

                                                                                                                                      func GetModules(scope string) []ModuleInfo

                                                                                                                                        GetModules returns all modules in the given scope/namespace. For example, a scope of "foo" returns modules named "", "foo.loo", but not "bar", "", etc. An empty scope returns top-level modules, for example "foo" or "bar". Partial scopes are not matched (i.e. scope "" does not match name "").

                                                                                                                                        Because modules are registered to a map under the hood, the returned slice will be sorted to keep it deterministic.

                                                                                                                                        func (ModuleInfo) String

                                                                                                                                        func (mi ModuleInfo) String() string

                                                                                                                                        type ModuleMap

                                                                                                                                        type ModuleMap map[string]json.RawMessage

                                                                                                                                          ModuleMap is a map that can contain multiple modules, where the map key is the module's name. (The namespace is usually read from an associated field's struct tag.) Because the module's name is given as the key in a module map, the name does not have to be given in the json.RawMessage.

                                                                                                                                          type NetworkAddress

                                                                                                                                          type NetworkAddress struct {
                                                                                                                                          	Network   string
                                                                                                                                          	Host      string
                                                                                                                                          	StartPort uint
                                                                                                                                          	EndPort   uint

                                                                                                                                            NetworkAddress contains the individual components for a parsed network address of the form accepted by ParseNetworkAddress(). Network should be a network value accepted by Go's net package. Port ranges are given by [StartPort, EndPort].

                                                                                                                                            func ParseNetworkAddress

                                                                                                                                            func ParseNetworkAddress(addr string) (NetworkAddress, error)

                                                                                                                                              ParseNetworkAddress parses addr into its individual components. The input string is expected to be of the form "network/host:port-range" where any part is optional. The default network, if unspecified, is tcp. Port ranges are inclusive.

                                                                                                                                              Network addresses are distinct from URLs and do not use URL syntax.

                                                                                                                                              func (NetworkAddress) IsUnixNetwork

                                                                                                                                              func (na NetworkAddress) IsUnixNetwork() bool

                                                                                                                                                IsUnixNetwork returns true if na.Network is unix, unixgram, or unixpacket.

                                                                                                                                                func (NetworkAddress) JoinHostPort

                                                                                                                                                func (na NetworkAddress) JoinHostPort(offset uint) string

                                                                                                                                                  JoinHostPort is like net.JoinHostPort, but where the port is StartPort + offset.

                                                                                                                                                  func (NetworkAddress) PortRangeSize

                                                                                                                                                  func (na NetworkAddress) PortRangeSize() uint

                                                                                                                                                    PortRangeSize returns how many ports are in pa's port range. Port ranges are inclusive, so the size is the difference of start and end ports plus one.

                                                                                                                                                    func (NetworkAddress) String

                                                                                                                                                    func (na NetworkAddress) String() string

                                                                                                                                                      String reconstructs the address string to the form expected by ParseNetworkAddress(). If the address is a unix socket, any non-zero port will be dropped.

                                                                                                                                                      type Provisioner

                                                                                                                                                      type Provisioner interface {
                                                                                                                                                      	Provision(Context) error

                                                                                                                                                        Provisioner is implemented by modules which may need to perform some additional "setup" steps immediately after being loaded. Provisioning should be fast (imperceptible running time). If any side-effects result in the execution of this function (e.g. creating global state, any other allocations which require garbage collection, opening files, starting goroutines etc.), be sure to clean up properly by implementing the CleanerUpper interface to avoid leaking resources.

                                                                                                                                                        type ReplacementFunc

                                                                                                                                                        type ReplacementFunc func(variable string, val interface{}) (interface{}, error)

                                                                                                                                                          ReplacementFunc is a function that is called when a replacement is being performed. It receives the variable (i.e. placeholder name) and the value that will be the replacement, and returns the value that will actually be the replacement, or an error. Note that errors are sometimes ignored by replacers.

                                                                                                                                                          type Replacer

                                                                                                                                                          type Replacer struct {
                                                                                                                                                          	// contains filtered or unexported fields

                                                                                                                                                            Replacer can replace values in strings. A default/empty Replacer is not valid; use NewReplacer to make one.

                                                                                                                                                            func NewReplacer

                                                                                                                                                            func NewReplacer() *Replacer

                                                                                                                                                              NewReplacer returns a new Replacer.

                                                                                                                                                              func (*Replacer) Delete

                                                                                                                                                              func (r *Replacer) Delete(variable string)

                                                                                                                                                                Delete removes a variable with a static value that was created using Set.

                                                                                                                                                                func (*Replacer) Get

                                                                                                                                                                func (r *Replacer) Get(variable string) (interface{}, bool)

                                                                                                                                                                  Get gets a value from the replacer. It returns the value and whether the variable was known.

                                                                                                                                                                  func (*Replacer) GetString

                                                                                                                                                                  func (r *Replacer) GetString(variable string) (string, bool)

                                                                                                                                                                    GetString is the same as Get, but coerces the value to a string representation.

                                                                                                                                                                    func (*Replacer) Map

                                                                                                                                                                    func (r *Replacer) Map(mapFunc ReplacerFunc)

                                                                                                                                                                      Map adds mapFunc to the list of value providers. mapFunc will be executed only at replace-time.

                                                                                                                                                                      func (*Replacer) ReplaceAll

                                                                                                                                                                      func (r *Replacer) ReplaceAll(input, empty string) string

                                                                                                                                                                        ReplaceAll efficiently replaces placeholders in input with their values. All placeholders are replaced in the output whether they are recognized or not. Values that are empty string will be substituted with empty.

                                                                                                                                                                        func (*Replacer) ReplaceFunc

                                                                                                                                                                        func (r *Replacer) ReplaceFunc(input string, f ReplacementFunc) (string, error)

                                                                                                                                                                          ReplaceFunc is the same as ReplaceAll, but calls f for every replacement to be made, in case f wants to change or inspect the replacement.

                                                                                                                                                                          func (*Replacer) ReplaceKnown

                                                                                                                                                                          func (r *Replacer) ReplaceKnown(input, empty string) string

                                                                                                                                                                            ReplaceKnown is like ReplaceAll but only replaces placeholders that are known (recognized). Unrecognized placeholders will remain in the output.

                                                                                                                                                                            func (*Replacer) ReplaceOrErr

                                                                                                                                                                            func (r *Replacer) ReplaceOrErr(input string, errOnEmpty, errOnUnknown bool) (string, error)

                                                                                                                                                                              ReplaceOrErr is like ReplaceAll, but any placeholders that are empty or not recognized will cause an error to be returned.

                                                                                                                                                                              func (*Replacer) Set

                                                                                                                                                                              func (r *Replacer) Set(variable string, value interface{})

                                                                                                                                                                                Set sets a custom variable to a static value.

                                                                                                                                                                                type ReplacerFunc

                                                                                                                                                                                type ReplacerFunc func(key string) (interface{}, bool)

                                                                                                                                                                                  ReplacerFunc is a function that returns a replacement for the given key along with true if the function is able to service that key (even if the value is blank). If the function does not recognize the key, false should be returned.

                                                                                                                                                                                  type StandardLibLog

                                                                                                                                                                                  type StandardLibLog struct {
                                                                                                                                                                                  	// The module that writes out log entries for the sink.
                                                                                                                                                                                  	WriterRaw json.RawMessage `json:"writer,omitempty" caddy:"namespace=caddy.logging.writers inline_key=output"`
                                                                                                                                                                                  	// contains filtered or unexported fields

                                                                                                                                                                                    StandardLibLog configures the default Go standard library global logger in the log package. This is necessary because module dependencies which are not built specifically for Caddy will use the standard logger. This is also known as the "sink" logger.

                                                                                                                                                                                    type StderrWriter

                                                                                                                                                                                    type StderrWriter struct{}

                                                                                                                                                                                      StderrWriter writes logs to standard error.

                                                                                                                                                                                      func (StderrWriter) CaddyModule

                                                                                                                                                                                      func (StderrWriter) CaddyModule() ModuleInfo

                                                                                                                                                                                        CaddyModule returns the Caddy module information.

                                                                                                                                                                                        func (StderrWriter) OpenWriter

                                                                                                                                                                                        func (StderrWriter) OpenWriter() (io.WriteCloser, error)

                                                                                                                                                                                          OpenWriter returns os.Stderr that can't be closed.

                                                                                                                                                                                          func (StderrWriter) String

                                                                                                                                                                                          func (StderrWriter) String() string

                                                                                                                                                                                          func (StderrWriter) WriterKey

                                                                                                                                                                                          func (StderrWriter) WriterKey() string

                                                                                                                                                                                            WriterKey returns a unique key representing stderr.

                                                                                                                                                                                            type StdoutWriter

                                                                                                                                                                                            type StdoutWriter struct{}

                                                                                                                                                                                              StdoutWriter writes logs to standard out.

                                                                                                                                                                                              func (StdoutWriter) CaddyModule

                                                                                                                                                                                              func (StdoutWriter) CaddyModule() ModuleInfo

                                                                                                                                                                                                CaddyModule returns the Caddy module information.

                                                                                                                                                                                                func (StdoutWriter) OpenWriter

                                                                                                                                                                                                func (StdoutWriter) OpenWriter() (io.WriteCloser, error)

                                                                                                                                                                                                  OpenWriter returns os.Stdout that can't be closed.

                                                                                                                                                                                                  func (StdoutWriter) String

                                                                                                                                                                                                  func (StdoutWriter) String() string

                                                                                                                                                                                                  func (StdoutWriter) WriterKey

                                                                                                                                                                                                  func (StdoutWriter) WriterKey() string

                                                                                                                                                                                                    WriterKey returns a unique key representing stdout.

                                                                                                                                                                                                    type StorageConverter

                                                                                                                                                                                                    type StorageConverter interface {
                                                                                                                                                                                                    	CertMagicStorage() (certmagic.Storage, error)

                                                                                                                                                                                                      StorageConverter is a type that can convert itself to a valid, usable certmagic.Storage value. (The value might be short-lived.) This interface allows us to adapt any CertMagic storage implementation into a consistent API for Caddy configuration.

                                                                                                                                                                                                      type UsagePool

                                                                                                                                                                                                      type UsagePool struct {
                                                                                                                                                                                                      	// contains filtered or unexported fields

                                                                                                                                                                                                        UsagePool is a thread-safe map that pools values based on usage (reference counting). Values are only inserted if they do not already exist. There are two ways to add values to the pool:

                                                                                                                                                                                                        1) LoadOrStore will increment usage and store the
                                                                                                                                                                                                           value immediately if it does not already exist.
                                                                                                                                                                                                        2) LoadOrNew will atomically check for existence
                                                                                                                                                                                                           and construct the value immediately if it does
                                                                                                                                                                                                           not already exist, or increment the usage
                                                                                                                                                                                                           otherwise, then store that value in the pool.
                                                                                                                                                                                                           When the constructed value is finally deleted
                                                                                                                                                                                                           from the pool (when its usage reaches 0), it
                                                                                                                                                                                                           will be cleaned up by calling Destruct().

                                                                                                                                                                                                        The use of LoadOrNew allows values to be created and reused and finally cleaned up only once, even though they may have many references throughout their lifespan. This is helpful, for example, when sharing thread-safe io.Writers that you only want to open and close once.

                                                                                                                                                                                                        There is no way to overwrite existing keys in the pool without first deleting it as many times as it was stored. Deleting too many times will panic.

                                                                                                                                                                                                        The implementation does not use a sync.Pool because UsagePool needs additional atomicity to run the constructor functions when creating a new value when LoadOrNew is used. (We could probably use sync.Pool but we'd still have to layer our own additional locks on top.)

                                                                                                                                                                                                        An empty UsagePool is NOT safe to use; always call NewUsagePool() to make a new one.

                                                                                                                                                                                                        func NewUsagePool

                                                                                                                                                                                                        func NewUsagePool() *UsagePool

                                                                                                                                                                                                          NewUsagePool returns a new usage pool that is ready to use.

                                                                                                                                                                                                          func (*UsagePool) Delete

                                                                                                                                                                                                          func (up *UsagePool) Delete(key interface{}) (deleted bool, err error)

                                                                                                                                                                                                            Delete decrements the usage count for key and removes the value from the underlying map if the usage is 0. It returns true if the usage count reached 0 and the value was deleted. It panics if the usage count drops below 0; always call Delete precisely as many times as LoadOrStore.

                                                                                                                                                                                                            func (*UsagePool) LoadOrNew

                                                                                                                                                                                                            func (up *UsagePool) LoadOrNew(key interface{}, construct Constructor) (value interface{}, loaded bool, err error)

                                                                                                                                                                                                              LoadOrNew loads the value associated with key from the pool if it already exists. If the key doesn't exist, it will call construct to create a new value and then stores that in the pool. An error is only returned if the constructor returns an error. The loaded or constructed value is returned. The loaded return value is true if the value already existed and was loaded, or false if it was newly constructed.

                                                                                                                                                                                                              func (*UsagePool) LoadOrStore

                                                                                                                                                                                                              func (up *UsagePool) LoadOrStore(key, val interface{}) (value interface{}, loaded bool)

                                                                                                                                                                                                                LoadOrStore loads the value associated with key from the pool if it already exists, or stores it if it does not exist. It returns the value that was either loaded or stored, and true if the value already existed and was

                                                                                                                                                                                                                func (*UsagePool) Range

                                                                                                                                                                                                                func (up *UsagePool) Range(f func(key, value interface{}) bool)

                                                                                                                                                                                                                  Range iterates the pool similarly to how sync.Map.Range() does: it calls f for every key in the pool, and if f returns false, iteration is stopped. Ranging does not affect usage counts.

                                                                                                                                                                                                                  This method is somewhat naive and acquires a read lock on the entire pool during iteration, so do your best to make f() really fast, m'kay?

                                                                                                                                                                                                                  type Validator

                                                                                                                                                                                                                  type Validator interface {
                                                                                                                                                                                                                  	Validate() error

                                                                                                                                                                                                                    Validator is implemented by modules which can verify that their configurations are valid. This method will be called after Provision() (if implemented). Validation should always be fast (imperceptible running time) and an error must be returned if the module's configuration is invalid.

                                                                                                                                                                                                                    type WriterOpener

                                                                                                                                                                                                                    type WriterOpener interface {
                                                                                                                                                                                                                    	// WriterKey is a string that uniquely identifies this
                                                                                                                                                                                                                    	// writer configuration. It is not shown to humans.
                                                                                                                                                                                                                    	WriterKey() string
                                                                                                                                                                                                                    	// OpenWriter opens a log for writing. The writer
                                                                                                                                                                                                                    	// should be safe for concurrent use but need not
                                                                                                                                                                                                                    	// be synchronous.
                                                                                                                                                                                                                    	OpenWriter() (io.WriteCloser, error)

                                                                                                                                                                                                                      WriterOpener is a module that can open a log writer. It can return a human-readable string representation of itself so that operators can understand where the logs are going.


                                                                                                                                                                                                                      Path Synopsis
                                                                                                                                                                                                                      Package main is the entry point of the Caddy application.
                                                                                                                                                                                                                      Package main is the entry point of the Caddy application.
                                                                                                                                                                                                                      Package encode implements an encoder middleware for Caddy.
                                                                                                                                                                                                                      Package encode implements an encoder middleware for Caddy.
                                                                                                                                                                                                                      Package distributedstek provides TLS session ticket ephemeral keys (STEKs) in a distributed fashion by utilizing configured storage for locking and key sharing.
                                                                                                                                                                                                                      Package distributedstek provides TLS session ticket ephemeral keys (STEKs) in a distributed fashion by utilizing configured storage for locking and key sharing.