"description":": object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Config\nConfig is the top (or beginning) of the Caddy configuration structure.\nCaddy config is expressed natively as a JSON document. If you prefer\nnot to work with JSON directly, there are [many config adapters](/docs/config-adapters)\navailable that can convert various inputs into Caddy JSON.\n\nMany parts of this config are extensible through the use of Caddy modules.\nFields which have a json.RawMessage type and which appear as dots (•••) in\nthe online docs can be fulfilled by modules in a certain module\nnamespace. The docs show which modules can be used in a given place.\n\nWhenever a module is used, its name must be given either inline as part of\nthe module, or as the key to the module's value. The docs will make it clear\nwhich to use.\n\nGenerally, all config settings are optional, as it is Caddy convention to\nhave good, documented default values. If a parameter is required, the docs\nshould say so.\n\nGo programs which are directly building a Config struct value should take\ncare to populate the JSON-encodable fields of the struct (i.e. the fields\nwith `json` struct tags) if employing the module lifecycle (e.g. Provision\nmethod calls).\n\n",
"markdownDescription":": `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Config) \nConfig is the top (or beginning) of the Caddy configuration structure.\nCaddy config is expressed natively as a JSON document. If you prefer\nnot to work with JSON directly, there are [many config adapters](/docs/config-adapters)\navailable that can convert various inputs into Caddy JSON.\n\nMany parts of this config are extensible through the use of Caddy modules.\nFields which have a json.RawMessage type and which appear as dots (•••) in\nthe online docs can be fulfilled by modules in a certain module\nnamespace. The docs show which modules can be used in a given place.\n\nWhenever a module is used, its name must be given either inline as part of\nthe module, or as the key to the module's value. The docs will make it clear\nwhich to use.\n\nGenerally, all config settings are optional, as it is Caddy convention to\nhave good, documented default values. If a parameter is required, the docs\nshould say so.\n\nGo programs which are directly building a Config struct value should take\ncare to populate the JSON-encodable fields of the struct (i.e. the fields\nwith `json` struct tags) if employing the module lifecycle (e.g. Provision\nmethod calls).\n \n",
"description":"http: object\nModule: caddy.config_loaders.http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/caddyconfig#HTTPLoader\nHTTPLoader can load Caddy configs over HTTP(S). It can adapt the config\nbased on the Content-Type header of the HTTP response.\n\n",
"markdownDescription":"http: `object` \nModule: `caddy.config_loaders.http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/caddyconfig#HTTPLoader) \nHTTPLoader can load Caddy configs over HTTP(S). It can adapt the config\nbased on the Content-Type header of the HTTP response.\n \n",
"type":"object",
"properties":{
"header":{
"description":"header: object\nModule: caddy.config_loaders.http\nHTTP headers to add to the request.\n",
"markdownDescription":"header: `object` \nModule: `caddy.config_loaders.http` \nHTTP headers to add to the request. \n",
"type":"object",
"additionalProperties":{
"description":"HTTP headers to add to the request.\n",
"markdownDescription":"HTTP headers to add to the request. \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"method":{
"description":"method: string\nModule: caddy.config_loaders.http\nThe method for the request. Default: GET\n",
"markdownDescription":"method: `string` \nModule: `caddy.config_loaders.http` \nThe method for the request. Default: GET \n",
"type":"string"
},
"timeout":{
"description":"timeout: number\nModule: caddy.config_loaders.http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nMaximum time allowed for a complete connection and request.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"timeout: `number` \nModule: `caddy.config_loaders.http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nMaximum time allowed for a complete connection and request.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"url: string\nModule: caddy.config_loaders.http\nThe URL of the request.\n",
"markdownDescription":"url: `string` \nModule: `caddy.config_loaders.http` \nThe URL of the request. \n",
"type":"string"
}
}
},
"caddy.listeners.http_redirect":{
"description":"http_redirect: object\nModule: caddy.listeners.http_redirect\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#HTTPRedirectListenerWrapper\nHTTPRedirectListenerWrapper provides HTTP-\u003eHTTPS redirects for\nconnections that come on the TLS port as an HTTP request,\nby detecting using the first few bytes that it's not a TLS\nhandshake, but instead an HTTP request.\n\nThis is especially useful when using a non-standard HTTPS port.\nA user may simply type the address in their browser without the\nhttps:// scheme, which would cause the browser to attempt the\nconnection over HTTP, but this would cause a \"Client sent an\nHTTP request to an HTTPS server\" error response.\n\nThis listener wrapper must be placed BEFORE the \"tls\" listener\nwrapper, for it to work properly.\n\n",
"markdownDescription":"http_redirect: `object` \nModule: `caddy.listeners.http_redirect` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#HTTPRedirectListenerWrapper) \nHTTPRedirectListenerWrapper provides HTTP-\u003eHTTPS redirects for\nconnections that come on the TLS port as an HTTP request,\nby detecting using the first few bytes that it's not a TLS\nhandshake, but instead an HTTP request.\n\nThis is especially useful when using a non-standard HTTPS port.\nA user may simply type the address in their browser without the\nhttps:// scheme, which would cause the browser to attempt the\nconnection over HTTP, but this would cause a \"Client sent an\nHTTP request to an HTTPS server\" error response.\n\nThis listener wrapper must be placed BEFORE the \"tls\" listener\nwrapper, for it to work properly.\n \n",
"type":"object"
},
"caddy.listeners.tls":{
"description":"tls: object\nModule: caddy.listeners.tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#tlsPlaceholderWrapper\ntlsPlaceholderWrapper is a no-op listener wrapper that marks\nwhere the TLS listener should be in a chain of listener wrappers.\nIt should only be used if another listener wrapper must be placed\nin front of the TLS handshake.\n\n",
"markdownDescription":"tls: `object` \nModule: `caddy.listeners.tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#tlsPlaceholderWrapper) \ntlsPlaceholderWrapper is a no-op listener wrapper that marks\nwhere the TLS listener should be in a chain of listener wrappers.\nIt should only be used if another listener wrapper must be placed\nin front of the TLS handshake.\n \n",
"type":"object"
},
"caddy.logging.encoders.console":{
"description":"console: object\nModule: caddy.logging.encoders.console\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#ConsoleEncoder\nConsoleEncoder encodes log entries that are mostly human-readable.\n\n",
"markdownDescription":"console: `object` \nModule: `caddy.logging.encoders.console` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#ConsoleEncoder) \nConsoleEncoder encodes log entries that are mostly human-readable.\n \n",
"description":"filter: object\nModule: caddy.logging.encoders.filter\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#FilterEncoder\nFilterEncoder can filter (manipulate) fields on\nlog entries before they are actually encoded by\nan underlying encoder.\n\n",
"markdownDescription":"filter: `object` \nModule: `caddy.logging.encoders.filter` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#FilterEncoder) \nFilterEncoder can filter (manipulate) fields on\nlog entries before they are actually encoded by\nan underlying encoder.\n \n",
"type":"object",
"properties":{
"fields":{
"description":"fields: object\nModule: caddy.logging.encoders.filter\nA map of field names to their filters. Note that this\nis not a module map; the keys are field names.\n\nNested fields can be referenced by representing a\nlayer of nesting with `\u003e`. In other words, for an\nobject like `{\"a\":{\"b\":0}}`, the inner field can\nbe referenced as `a\u003eb`.\n\nThe following fields are fundamental to the log and\ncannot be filtered because they are added by the\nunderlying logging library as special cases: ts,\nlevel, logger, and msg.\n",
"markdownDescription":"fields: `object` \nModule: `caddy.logging.encoders.filter` \nA map of field names to their filters. Note that this\nis not a module map; the keys are field names.\n\nNested fields can be referenced by representing a\nlayer of nesting with `\u003e`. In other words, for an\nobject like `{\"a\":{\"b\":0}}`, the inner field can\nbe referenced as `a\u003eb`.\n\nThe following fields are fundamental to the log and\ncannot be filtered because they are added by the\nunderlying logging library as special cases: ts,\nlevel, logger, and msg. \n",
"description":"discard: object\nModule: caddy.logging.writers.discard\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#DiscardWriter\nDiscardWriter discards all writes.\n\n",
"markdownDescription":"discard: `object` \nModule: `caddy.logging.writers.discard` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#DiscardWriter) \nDiscardWriter discards all writes.\n \n",
"type":"object"
},
"caddy.logging.writers.file":{
"description":"file: object\nModule: caddy.logging.writers.file\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#FileWriter\nFileWriter can write logs to files. By default, log files\nare rotated (\"rolled\") when they get large, and old log\nfiles get deleted, to ensure that the process does not\nexhaust disk space.\n\n",
"markdownDescription":"file: `object` \nModule: `caddy.logging.writers.file` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#FileWriter) \nFileWriter can write logs to files. By default, log files\nare rotated (\"rolled\") when they get large, and old log\nfiles get deleted, to ensure that the process does not\nexhaust disk space.\n \n",
"type":"object",
"properties":{
"filename":{
"description":"filename: string\nModule: caddy.logging.writers.file\nFilename is the name of the file to write.\n",
"markdownDescription":"filename: `string` \nModule: `caddy.logging.writers.file` \nFilename is the name of the file to write. \n",
"type":"string"
},
"roll":{
"description":"roll: boolean\nModule: caddy.logging.writers.file\nRoll toggles log rolling or rotation, which is\nenabled by default.\n",
"markdownDescription":"roll: `boolean` \nModule: `caddy.logging.writers.file` \nRoll toggles log rolling or rotation, which is\nenabled by default. \n",
"type":"boolean"
},
"roll_gzip":{
"description":"roll_gzip: boolean\nModule: caddy.logging.writers.file\nWhether to compress rolled files. Default: true\n",
"description":"roll_keep: number\nModule: caddy.logging.writers.file\nThe maximum number of rolled log files to keep.\nDefault: 10\n",
"markdownDescription":"roll_keep: `number` \nModule: `caddy.logging.writers.file` \nThe maximum number of rolled log files to keep.\nDefault: 10 \n",
"type":"number"
},
"roll_keep_days":{
"description":"roll_keep_days: number\nModule: caddy.logging.writers.file\nHow many days to keep rolled log files. Default: 90\n",
"markdownDescription":"roll_keep_days: `number` \nModule: `caddy.logging.writers.file` \nHow many days to keep rolled log files. Default: 90 \n",
"type":"number"
},
"roll_local_time":{
"description":"roll_local_time: boolean\nModule: caddy.logging.writers.file\nWhether to use local timestamps in rolled filenames.\nDefault: false\n",
"markdownDescription":"roll_local_time: `boolean` \nModule: `caddy.logging.writers.file` \nWhether to use local timestamps in rolled filenames.\nDefault: false \n",
"type":"boolean"
},
"roll_size_mb":{
"description":"roll_size_mb: number\nModule: caddy.logging.writers.file\nWhen a log file reaches approximately this size,\nit will be rotated.\n",
"markdownDescription":"roll_size_mb: `number` \nModule: `caddy.logging.writers.file` \nWhen a log file reaches approximately this size,\nit will be rotated. \n",
"type":"number"
}
}
},
"caddy.logging.writers.net":{
"description":"net: object\nModule: caddy.logging.writers.net\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#NetWriter\nNetWriter implements a log writer that outputs to a network socket. If\nthe socket goes down, it will dump logs to stderr while it attempts to\nreconnect.\n\n",
"markdownDescription":"net: `object` \nModule: `caddy.logging.writers.net` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging#NetWriter) \nNetWriter implements a log writer that outputs to a network socket. If\nthe socket goes down, it will dump logs to stderr while it attempts to\nreconnect.\n \n",
"type":"object",
"properties":{
"address":{
"description":"address: string\nModule: caddy.logging.writers.net\nThe address of the network socket to which to connect.\n",
"markdownDescription":"address: `string` \nModule: `caddy.logging.writers.net` \nThe address of the network socket to which to connect. \n",
"type":"string"
},
"dial_timeout":{
"description":"dial_timeout: number\nModule: caddy.logging.writers.net\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nThe timeout to wait while connecting to the socket.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"dial_timeout: `number` \nModule: `caddy.logging.writers.net` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nThe timeout to wait while connecting to the socket.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
},
"caddy.logging.writers.stderr":{
"description":"stderr: object\nModule: caddy.logging.writers.stderr\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#StderrWriter\nStderrWriter writes logs to standard error.\n\n",
"markdownDescription":"stderr: `object` \nModule: `caddy.logging.writers.stderr` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#StderrWriter) \nStderrWriter writes logs to standard error.\n \n",
"type":"object"
},
"caddy.logging.writers.stdout":{
"description":"stdout: object\nModule: caddy.logging.writers.stdout\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#StdoutWriter\nStdoutWriter writes logs to standard out.\n\n",
"markdownDescription":"stdout: `object` \nModule: `caddy.logging.writers.stdout` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#StdoutWriter) \nStdoutWriter writes logs to standard out.\n \n",
"type":"object"
},
"caddy.storage.consul":{
"description":"consul: object\nModule: caddy.storage.consul\nhttps://pkg.go.dev/github.com/pteich/caddy-tlsconsul#ConsulStorage\nConsulStorage allows to store certificates and other TLS resources\nin a shared cluster environment using Consul's key/value-store.\nIt uses distributed locks to ensure consistency.\n\n",
"markdownDescription":"consul: `object` \nModule: `caddy.storage.consul` \n[godoc](https://pkg.go.dev/github.com/pteich/caddy-tlsconsul#ConsulStorage) \nConsulStorage allows to store certificates and other TLS resources\nin a shared cluster environment using Consul's key/value-store.\nIt uses distributed locks to ensure consistency.\n \n",
"description":"file_system: object\nModule: caddy.storage.file_system\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/filestorage#FileStorage\nFileStorage is a certmagic.Storage wrapper for certmagic.FileStorage.\n\n",
"markdownDescription":"file_system: `object` \nModule: `caddy.storage.file_system` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/filestorage#FileStorage) \nFileStorage is a certmagic.Storage wrapper for certmagic.FileStorage.\n \n",
"type":"object",
"properties":{
"root":{
"description":"root: string\nModule: caddy.storage.file_system\nThe base path to the folder used for storage.\n",
"markdownDescription":"root: `string` \nModule: `caddy.storage.file_system` \nThe base path to the folder used for storage. \n",
"description":"events: object\nModule: events\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#App\nApp implements a global eventing system within Caddy.\nModules can emit and subscribe to events, providing\nhooks into deep parts of the code base that aren't\notherwise accessible. Events provide information about\nwhat and when things are happening, and this facility\nallows handlers to take action when events occur,\nadd information to the event's metadata, and even\ncontrol program flow in some cases.\n\nEvents are propagated in a DOM-like fashion. An event\nemitted from module `a.b.c` (the \"origin\") will first\ninvoke handlers listening to `a.b.c`, then `a.b`,\nthen `a`, then those listening regardless of origin.\nIf a handler returns the special error Aborted, then\npropagation immediately stops and the event is marked\nas aborted. Emitters may optionally choose to adjust\nprogram flow based on an abort.\n\nModules can subscribe to events by origin and/or name.\nA handler is invoked only if it is subscribed to the\nevent by name and origin. Subscriptions should be\nregistered during the provisioning phase, before apps\nare started.\n\nEvent handlers are fired synchronously as part of the\nregular flow of the program. This allows event handlers\nto control the flow of the program if the origin permits\nit and also allows handlers to convey new information\nback into the origin module before it continues.\nIn essence, event handlers are similar to HTTP\nmiddleware handlers.\n\nEvent bindings/subscribers are unordered; i.e.\nevent handlers are invoked in an arbitrary order.\nEvent handlers should not rely on the logic of other\nhandlers to succeed.\n\nThe entirety of this app module is EXPERIMENTAL and\nsubject to change. Pay attention to release notes.\n\n",
"markdownDescription":"events: `object` \nModule: `events` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#App) \nApp implements a global eventing system within Caddy.\nModules can emit and subscribe to events, providing\nhooks into deep parts of the code base that aren't\notherwise accessible. Events provide information about\nwhat and when things are happening, and this facility\nallows handlers to take action when events occur,\nadd information to the event's metadata, and even\ncontrol program flow in some cases.\n\nEvents are propagated in a DOM-like fashion. An event\nemitted from module `a.b.c` (the \"origin\") will first\ninvoke handlers listening to `a.b.c`, then `a.b`,\nthen `a`, then those listening regardless of origin.\nIf a handler returns the special error Aborted, then\npropagation immediately stops and the event is marked\nas aborted. Emitters may optionally choose to adjust\nprogram flow based on an abort.\n\nModules can subscribe to events by origin and/or name.\nA handler is invoked only if it is subscribed to the\nevent by name and origin. Subscriptions should be\nregistered during the provisioning phase, before apps\nare started.\n\nEvent handlers are fired synchronously as part of the\nregular flow of the program. This allows event handlers\nto control the flow of the program if the origin permits\nit and also allows handlers to convey new information\nback into the origin module before it continues.\nIn essence, event handlers are similar to HTTP\nmiddleware handlers.\n\nEvent bindings/subscribers are unordered; i.e.\nevent handlers are invoked in an arbitrary order.\nEvent handlers should not rely on the logic of other\nhandlers to succeed.\n\nThe entirety of this app module is EXPERIMENTAL and\nsubject to change. Pay attention to release notes.\n \n",
"type":"object",
"properties":{
"subscriptions":{
"description":"subscriptions: array\nModule: events\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#Subscription\nSubscriptions bind handlers to one or more events\neither globally or scoped to specific modules or module\nnamespaces.\n\n\nSubscription represents binding of one or more handlers to\none or more events.\n",
"markdownDescription":"subscriptions: `array` \nModule: `events` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#Subscription) \nSubscriptions bind handlers to one or more events\neither globally or scoped to specific modules or module\nnamespaces.\n\n\nSubscription represents binding of one or more handlers to\none or more events. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#Subscription\nSubscriptions bind handlers to one or more events\neither globally or scoped to specific modules or module\nnamespaces.\n\n\nSubscription represents binding of one or more handlers to\none or more events.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#Subscription) \nSubscriptions bind handlers to one or more events\neither globally or scoped to specific modules or module\nnamespaces.\n\n\nSubscription represents binding of one or more handlers to\none or more events. \n",
"type":"object",
"properties":{
"events":{
"description":"events: array\nModule: events\nThe name(s) of the event(s) to bind to. Default: all events.\n",
"markdownDescription":"events: `array` \nModule: `events` \nThe name(s) of the event(s) to bind to. Default: all events. \n",
"type":"array",
"items":{
"description":"The name(s) of the event(s) to bind to. Default: all events.\n",
"markdownDescription":"The name(s) of the event(s) to bind to. Default: all events. \n",
"type":"string"
}
},
"handlers":{
"description":"handlers: any\nModule: events.handlers\nThe event handler modules. These implement the actual\nbehavior to invoke when an event occurs. At least one\nhandler is required.\n",
"markdownDescription":"handlers: `any` \nModule: `events.handlers` \nThe event handler modules. These implement the actual\nbehavior to invoke when an event occurs. At least one\nhandler is required. \n"
},
"modules":{
"description":"modules: array\nModule: events\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleID\nThe ID or namespace of the module(s) from which events\noriginate to listen to for events. Default: all modules.\n\nEvents propagate up, so events emitted by module \"a.b.c\"\nwill also trigger the event for \"a.b\" and \"a\". Thus, to\nreceive all events from \"a.b.c\" and \"a.b.d\", for example,\none can subscribe to either \"a.b\" or all of \"a\" entirely.\n\n\nModuleID is a string that uniquely identifies a Caddy module. A\nmodule ID is lightly structured. It consists of dot-separated\nlabels which form a simple hierarchy from left to right. The last\nlabel is the module name, and the labels before that constitute\nthe namespace (or scope).\n\nThus, a module ID has the form: \u003cnamespace\u003e.\u003cname\u003e\n\nAn ID with no dot has the empty namespace, which is appropriate\nfor app modules (these are \"top-level\" modules that Caddy core\nloads and runs).\n\nModule IDs should be lowercase and use underscores (_) instead of\nspaces.\n\nExamples of valid IDs:\n- http\n- http.handlers.file_server\n- caddy.logging.encoders.json\n",
"markdownDescription":"modules: `array` \nModule: `events` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleID) \nThe ID or namespace of the module(s) from which events\noriginate to listen to for events. Default: all modules.\n\nEvents propagate up, so events emitted by module \"a.b.c\"\nwill also trigger the event for \"a.b\" and \"a\". Thus, to\nreceive all events from \"a.b.c\" and \"a.b.d\", for example,\none can subscribe to either \"a.b\" or all of \"a\" entirely.\n\n\nModuleID is a string that uniquely identifies a Caddy module. A\nmodule ID is lightly structured. It consists of dot-separated\nlabels which form a simple hierarchy from left to right. The last\nlabel is the module name, and the labels before that constitute\nthe namespace (or scope).\n\nThus, a module ID has the form: \u003cnamespace\u003e.\u003cname\u003e\n\nAn ID with no dot has the empty namespace, which is appropriate\nfor app modules (these are \"top-level\" modules that Caddy core\nloads and runs).\n\nModule IDs should be lowercase and use underscores (_) instead of\nspaces.\n\nExamples of valid IDs:\n- http\n- http.handlers.file_server\n- caddy.logging.encoders.json \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleID\nThe ID or namespace of the module(s) from which events\noriginate to listen to for events. Default: all modules.\n\nEvents propagate up, so events emitted by module \"a.b.c\"\nwill also trigger the event for \"a.b\" and \"a\". Thus, to\nreceive all events from \"a.b.c\" and \"a.b.d\", for example,\none can subscribe to either \"a.b\" or all of \"a\" entirely.\n\n\nModuleID is a string that uniquely identifies a Caddy module. A\nmodule ID is lightly structured. It consists of dot-separated\nlabels which form a simple hierarchy from left to right. The last\nlabel is the module name, and the labels before that constitute\nthe namespace (or scope).\n\nThus, a module ID has the form: \u003cnamespace\u003e.\u003cname\u003e\n\nAn ID with no dot has the empty namespace, which is appropriate\nfor app modules (these are \"top-level\" modules that Caddy core\nloads and runs).\n\nModule IDs should be lowercase and use underscores (_) instead of\nspaces.\n\nExamples of valid IDs:\n- http\n- http.handlers.file_server\n- caddy.logging.encoders.json\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleID) \nThe ID or namespace of the module(s) from which events\noriginate to listen to for events. Default: all modules.\n\nEvents propagate up, so events emitted by module \"a.b.c\"\nwill also trigger the event for \"a.b\" and \"a\". Thus, to\nreceive all events from \"a.b.c\" and \"a.b.d\", for example,\none can subscribe to either \"a.b\" or all of \"a\" entirely.\n\n\nModuleID is a string that uniquely identifies a Caddy module. A\nmodule ID is lightly structured. It consists of dot-separated\nlabels which form a simple hierarchy from left to right. The last\nlabel is the module name, and the labels before that constitute\nthe namespace (or scope).\n\nThus, a module ID has the form: \u003cnamespace\u003e.\u003cname\u003e\n\nAn ID with no dot has the empty namespace, which is appropriate\nfor app modules (these are \"top-level\" modules that Caddy core\nloads and runs).\n\nModule IDs should be lowercase and use underscores (_) instead of\nspaces.\n\nExamples of valid IDs:\n- http\n- http.handlers.file_server\n- caddy.logging.encoders.json \n",
"description":"http:object\nModule:http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#App\nApp is a robust, production-ready HTTP server.\n\nHTTPS is enabled by default if host matchers with qualifying names are used\nin any of routes; certificates are automatically provisioned and renewed.\nAdditionally, automatic HTTPS will also enable HTTPS for servers that listen\nonly on the HTTPS port but which do not have any TLS connection policies\ndefined by adding a good, default TLS connection policy.\n\nIn HTTP routes, additional placeholders are available (replace any `*`):\n\nPlaceholder | Description\n------------|---------------\n`{http.request.body}` | The request body (⚠️ inefficient; use only for debugging)\n`{http.request.cookie.*}` | HTTP request cookie\n`{http.request.duration}` | Time up to now spent handling the request (after decoding headers from client)\n`{http.request.duration_ms}` | Same as 'duration', but in milliseconds.\n`{http.request.uuid}` | The request unique identifier\n`{http.request.header.*}` | Specific request header field\n`{http.request.host.labels.*}` | Request host labels (0-based from right); e.g. for foo.example.com: 0=com, 1=example, 2=foo\n`{http.request.host}` | The host part of the request's Host header\n`{http.request.hostport}` | The host and port from the request's Host header\n`{http.request.method}` | The request method\n`{http.request.orig_method}` | The request's original method\n`{http.request.orig_uri.path.dir}` | The request's original directory\n`{http.request.orig_uri.path.file}` | The request's original filename\n`{http.request.orig_uri.path}` | The request's original path\n`{http.request.orig_uri.query}` | The request's original query string (without `?`)\n`{http.request.orig_uri}` | The request's original URI\n`{http.request.port}` | The port part of the request's Host header\n`{http.request.proto}` | The protocol of the request\n`{http.request.remote.host}` | The host part of the remote client's address\n`{http.request.remote.port}` | The port part of the remote client's address\n`{http.request.remote}` | The address of the remote client\n`{http.request.scheme}` | The request scheme\n`{http.request.tls.version}` | The TLS version name\n`{http.request.tls.cipher_suite}` | The TLS cipher suite\n`{http.request.tls.resumed}` | The TLS connection resumed a previous connection\n`{http.request.tls.proto}` | The negotiated next protocol\n`{http.request.tls.proto_mutual}` | The negotiated next protocol was advertised by the server\n`{http.request.tls.server_name}` | The server name requested by the client, if any\n`{http.request.tls.client.fingerprint}` | The SHA256 checksum of the client certificate\n`{http.request.tls.client.public_key}` | The public key of the client certificate.\n`{http.request.tls.client.public_key_sha256}` | The SHA256 checksum of the client's public key.\n`{http.request.tls.client.certificate_pem}` | The PEM-encoded value of the certificate.\n`{http.request.tls.client.certificate_der_base64}` | The base64-encoded value of the certificate.\n`{http.request.tls.client.issuer}` | The issuer DN of the client certificate\n`{http.request.tls.client.serial}` | The serial number of the client certificate\n`{http.request.tls.client.subject}` | The subject DN of the client certificate\n`{http.request.tls.client.san.dns_names.*}` | SAN DNS names(index optional)\n`{http.request.tls.client.san.emails.*}` | SAN email addresses (index optional)\n`{http.request.tls.client.san.ips.*}` | SAN IP addresses (index optional)\n`{http.request.tls.client.san.uris.*}` | SAN URIs (index optional)\n`{http.request.uri.path.*}` | Parts of the path, split by `/` (0-based from left)\n`{http.request.uri.path.dir}` | The directory, excluding leaf filename\n`{http.request.uri.path.file}` | The filename of the path, excluding directory\n`{http.request.uri.path}` | The path component of the request URI\n`{http.request.uri.query.*}` | Individual query string value\n`{http.request.uri.query}` | The query string (without `?`)\n`{http.request.uri}` | The full
"markdownDescription":"http:`object`\nModule:`http`\n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#App) \nApp is a robust, production-ready HTTP server.\n\nHTTPS is enabled by default if host matchers with qualifying names are used\nin any of routes; certificates are automatically provisioned and renewed.\nAdditionally, automatic HTTPS will also enable HTTPS for servers that listen\nonly on the HTTPS port but which do not have any TLS connection policies\ndefined by adding a good, default TLS connection policy.\n\nIn HTTP routes, additional placeholders are available (replace any `*`):\n\nPlaceholder | Description\n------------|---------------\n`{http.request.body}` | The request body (⚠️ inefficient; use only for debugging)\n`{http.request.cookie.*}` | HTTP request cookie\n`{http.request.duration}` | Time up to now spent handling the request (after decoding headers from client)\n`{http.request.duration_ms}` | Same as 'duration', but in milliseconds.\n`{http.request.uuid}` | The request unique identifier\n`{http.request.header.*}` | Specific request header field\n`{http.request.host.labels.*}` | Request host labels (0-based from right); e.g. for foo.example.com: 0=com, 1=example, 2=foo\n`{http.request.host}` | The host part of the request's Host header\n`{http.request.hostport}` | The host and port from the request's Host header\n`{http.request.method}` | The request method\n`{http.request.orig_method}` | The request's original method\n`{http.request.orig_uri.path.dir}` | The request's original directory\n`{http.request.orig_uri.path.file}` | The request's original filename\n`{http.request.orig_uri.path}` | The request's original path\n`{http.request.orig_uri.query}` | The request's original query string (without `?`)\n`{http.request.orig_uri}` | The request's original URI\n`{http.request.port}` | The port part of the request's Host header\n`{http.request.proto}` | The protocol of the request\n`{http.request.remote.host}` | The host part of the remote client's address\n`{http.request.remote.port}` | The port part of the remote client's address\n`{http.request.remote}` | The address of the remote client\n`{http.request.scheme}` | The request scheme\n`{http.request.tls.version}` | The TLS version name\n`{http.request.tls.cipher_suite}` | The TLS cipher suite\n`{http.request.tls.resumed}` | The TLS connection resumed a previous connection\n`{http.request.tls.proto}` | The negotiated next protocol\n`{http.request.tls.proto_mutual}` | The negotiated next protocol was advertised by the server\n`{http.request.tls.server_name}` | The server name requested by the client, if any\n`{http.request.tls.client.fingerprint}` | The SHA256 checksum of the client certificate\n`{http.request.tls.client.public_key}` | The public key of the client certificate.\n`{http.request.tls.client.public_key_sha256}` | The SHA256 checksum of the client's public key.\n`{http.request.tls.client.certificate_pem}` | The PEM-encoded value of the certificate.\n`{http.request.tls.client.certificate_der_base64}` | The base64-encoded value of the certificate.\n`{http.request.tls.client.issuer}` | The issuer DN of the client certificate\n`{http.request.tls.client.serial}` | The serial number of the client certificate\n`{http.request.tls.client.subject}` | The subject DN of the client certificate\n`{http.request.tls.client.san.dns_names.*}` | SAN DNS names(index optional)\n`{http.request.tls.client.san.emails.*}` | SAN email addresses (index optional)\n`{http.request.tls.client.san.ips.*}` | SAN IP addresses (index optional)\n`{http.request.tls.client.san.uris.*}` | SAN URIs (index optional)\n`{http.request.uri.path.*}` | Parts of the path, split by `/` (0-based from left)\n`{http.request.uri.path.dir}` | The directory, excluding leaf filename\n`{http.request.uri.path.file}` | The filename of the path, excluding directory\n`{http.request.uri.path}` | The path component of the request URI\n`{http.request.uri.query.*}` | Individual query string value\n`{http.request.uri.query}` | The query string (without `?`)\n`{htt
"description":"grace_period: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nGracePeriod is how long to wait for active connections when shutting\ndown the servers. During the grace period, no new connections are\naccepted, idle connections are closed, and active connections will\nbe given the full length of time to become idle and close.\nOnce the grace period is over, connections will be forcefully closed.\nIf zero, the grace period is eternal. Default: 0.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"grace_period: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nGracePeriod is how long to wait for active connections when shutting\ndown the servers. During the grace period, no new connections are\naccepted, idle connections are closed, and active connections will\nbe given the full length of time to become idle and close.\nOnce the grace period is over, connections will be forcefully closed.\nIf zero, the grace period is eternal. Default: 0.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"http_port: number\nModule: http\nHTTPPort specifies the port to use for HTTP (as opposed to HTTPS),\nwhich is used when setting up HTTP-\u003eHTTPS redirects or ACME HTTP\nchallenge solvers. Default: 80.\n",
"markdownDescription":"http_port: `number` \nModule: `http` \nHTTPPort specifies the port to use for HTTP (as opposed to HTTPS),\nwhich is used when setting up HTTP-\u003eHTTPS redirects or ACME HTTP\nchallenge solvers. Default: 80. \n",
"type":"number"
},
"https_port":{
"description":"https_port: number\nModule: http\nHTTPSPort specifies the port to use for HTTPS, which is used when\nsolving the ACME TLS-ALPN challenges, or whenever HTTPS is needed\nbut no specific port number is given. Default: 443.\n",
"markdownDescription":"https_port: `number` \nModule: `http` \nHTTPSPort specifies the port to use for HTTPS, which is used when\nsolving the ACME TLS-ALPN challenges, or whenever HTTPS is needed\nbut no specific port number is given. Default: 443. \n",
"type":"number"
},
"servers":{
"description":"servers: object\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Server\nServers is the list of servers, keyed by arbitrary names chosen\nat your discretion for your own convenience; the keys do not\naffect functionality.\n\n\nServer describes an HTTP server.\n",
"markdownDescription":"servers: `object` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Server) \nServers is the list of servers, keyed by arbitrary names chosen\nat your discretion for your own convenience; the keys do not\naffect functionality.\n\n\nServer describes an HTTP server. \n",
"type":"object",
"additionalProperties":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Server\nServers is the list of servers, keyed by arbitrary names chosen\nat your discretion for your own convenience; the keys do not\naffect functionality.\n\n\nServer describes an HTTP server.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Server) \nServers is the list of servers, keyed by arbitrary names chosen\nat your discretion for your own convenience; the keys do not\naffect functionality.\n\n\nServer describes an HTTP server. \n",
"properties":{
"automatic_https":{
"description":"automatic_https: object\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#AutoHTTPSConfig\nAutoHTTPS configures or disables automatic HTTPS within this server.\nHTTPS is enabled automatically and by default when qualifying names\nare present in a Host matcher and/or when the server is listening\nonly on the HTTPS port.\n\n\nAutoHTTPSConfig is used to disable automatic HTTPS\nor certain aspects of it for a specific server.\nHTTPS is enabled automatically and by default when\nqualifying hostnames are available from the config.\n",
"markdownDescription":"automatic_https: `object` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#AutoHTTPSConfig) \nAutoHTTPS configures or disables automatic HTTPS within this server.\nHTTPS is enabled automatically and by default when qualifying names\nare present in a Host matcher and/or when the server is listening\nonly on the HTTPS port.\n\n\nAutoHTTPSConfig is used to disable automatic HTTPS\nor certain aspects of it for a specific server.\nHTTPS is enabled automatically and by default when\nqualifying hostnames are available from the config. \n",
"type":"object",
"properties":{
"disable":{
"description":"disable: boolean\nModule: http\nIf true, automatic HTTPS will be entirely disabled,\nincluding certificate management and redirects.\n",
"markdownDescription":"disable: `boolean` \nModule: `http` \nIf true, automatic HTTPS will be entirely disabled,\nincluding certificate management and redirects. \n",
"type":"boolean"
},
"disable_certificates":{
"description":"disable_certificates: boolean\nModule: http\nIf true, automatic certificate management will be\ndisabled, but other auto-HTTPS features will\nremain enabled.\n",
"markdownDescription":"disable_certificates: `boolean` \nModule: `http` \nIf true, automatic certificate management will be\ndisabled, but other auto-HTTPS features will\nremain enabled. \n",
"type":"boolean"
},
"disable_redirects":{
"description":"disable_redirects: boolean\nModule: http\nIf true, only automatic HTTP-\u003eHTTPS redirects will\nbe disabled, but other auto-HTTPS features will\nremain enabled.\n",
"markdownDescription":"disable_redirects: `boolean` \nModule: `http` \nIf true, only automatic HTTP-\u003eHTTPS redirects will\nbe disabled, but other auto-HTTPS features will\nremain enabled. \n",
"type":"boolean"
},
"ignore_loaded_certificates":{
"description":"ignore_loaded_certificates: boolean\nModule: http\nBy default, automatic HTTPS will obtain and renew\ncertificates for qualifying hostnames. However, if\na certificate with a matching SAN is already loaded\ninto the cache, certificate management will not be\nenabled. To force automated certificate management\nregardless of loaded certificates, set this to true.\n",
"markdownDescription":"ignore_loaded_certificates: `boolean` \nModule: `http` \nBy default, automatic HTTPS will obtain and renew\ncertificates for qualifying hostnames. However, if\na certificate with a matching SAN is already loaded\ninto the cache, certificate management will not be\nenabled. To force automated certificate management\nregardless of loaded certificates, set this to true. \n",
"type":"boolean"
},
"skip":{
"description":"skip: array\nModule: http\nHosts/domain names listed here will not be included\nin automatic HTTPS (they will not have certificates\nloaded nor redirects applied).\n",
"markdownDescription":"skip: `array` \nModule: `http` \nHosts/domain names listed here will not be included\nin automatic HTTPS (they will not have certificates\nloaded nor redirects applied). \n",
"type":"array",
"items":{
"description":"Hosts/domain names listed here will not be included\nin automatic HTTPS (they will not have certificates\nloaded nor redirects applied).\n",
"markdownDescription":"Hosts/domain names listed here will not be included\nin automatic HTTPS (they will not have certificates\nloaded nor redirects applied). \n",
"type":"string"
}
},
"skip_certificates":{
"description":"skip_certificates: array\nModule: http\nHosts/domain names listed here will still be enabled\nfor automatic HTTPS (unless in the Skip list), except\nthat certificates will not be provisioned and managed\nfor these names.\n",
"markdownDescription":"skip_certificates: `array` \nModule: `http` \nHosts/domain names listed here will still be enabled\nfor automatic HTTPS (unless in the Skip list), except\nthat certificates will not be provisioned and managed\nfor these names. \n",
"type":"array",
"items":{
"description":"Hosts/domain names listed here will still be enabled\nfor automatic HTTPS (unless in the Skip list), except\nthat certificates will not be provisioned and managed\nfor these names.\n",
"markdownDescription":"Hosts/domain names listed here will still be enabled\nfor automatic HTTPS (unless in the Skip list), except\nthat certificates will not be provisioned and managed\nfor these names. \n",
"type":"string"
}
}
}
},
"errors":{
"description":"errors: object\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#HTTPErrorConfig\nErrors is how this server will handle errors returned from any\nof the handlers in the primary routes. If the primary handler\nchain returns an error, the error along with its recommended\nstatus code are bubbled back up to the HTTP server which\nexecutes a separate error route, specified using this property.\nThe error routes work exactly like the normal routes.\n\n\nHTTPErrorConfig determines how to handle errors\nfrom the HTTP handlers.\n",
"markdownDescription":"errors: `object` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#HTTPErrorConfig) \nErrors is how this server will handle errors returned from any\nof the handlers in the primary routes. If the primary handler\nchain returns an error, the error along with its recommended\nstatus code are bubbled back up to the HTTP server which\nexecutes a separate error route, specified using this property.\nThe error routes work exactly like the normal routes.\n\n\nHTTPErrorConfig determines how to handle errors\nfrom the HTTP handlers. \n",
"type":"object",
"properties":{
"routes":{
"description":"routes: array\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"routes: `array` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"object",
"properties":{
"group":{
"description":"group: string\nModule: http\nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed.\n",
"markdownDescription":"group: `string` \nModule: `http` \nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed. \n",
"type":"string"
},
"handle":{
"description":"handle: array\nModule: http.handlers\nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"handle: `array` \nModule: `http.handlers` \nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"type":"array",
"items":{
"description":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"description":"match: array\nModule: http.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `array` \nModule: `http.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"terminal: boolean\nModule: http\nIf true, no more routes will be executed after this one.\n",
"markdownDescription":"terminal: `boolean` \nModule: `http` \nIf true, no more routes will be executed after this one. \n",
"type":"boolean"
}
}
}
}
}
},
"idle_timeout":{
"description":"idle_timeout: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nIdleTimeout is the maximum time to wait for the next request\nwhen keep-alives are enabled. If zero, a default timeout of\n5m is applied to help avoid resource exhaustion.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"idle_timeout: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nIdleTimeout is the maximum time to wait for the next request\nwhen keep-alives are enabled. If zero, a default timeout of\n5m is applied to help avoid resource exhaustion.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"keepalive_interval: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nKeepAliveInterval is the interval at which TCP keepalive packets\nare sent to keep the connection alive at the TCP layer when no other\ndata is being transmitted. The default is 15s.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"keepalive_interval: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nKeepAliveInterval is the interval at which TCP keepalive packets\nare sent to keep the connection alive at the TCP layer when no other\ndata is being transmitted. The default is 15s.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"listen: array\nModule: http\nSocket addresses to which to bind listeners. Accepts\n[network addresses](/docs/conventions#network-addresses)\nthat may include port ranges. Listener addresses must\nbe unique; they cannot be repeated across all defined\nservers.\n",
"markdownDescription":"listen: `array` \nModule: `http` \nSocket addresses to which to bind listeners. Accepts\n[network addresses](/docs/conventions#network-addresses)\nthat may include port ranges. Listener addresses must\nbe unique; they cannot be repeated across all defined\nservers. \n",
"type":"array",
"items":{
"description":"Socket addresses to which to bind listeners. Accepts\n[network addresses](/docs/conventions#network-addresses)\nthat may include port ranges. Listener addresses must\nbe unique; they cannot be repeated across all defined\nservers.\n",
"markdownDescription":"Socket addresses to which to bind listeners. Accepts\n[network addresses](/docs/conventions#network-addresses)\nthat may include port ranges. Listener addresses must\nbe unique; they cannot be repeated across all defined\nservers. \n",
"type":"string"
}
},
"listener_wrappers":{
"description":"listener_wrappers: array\nModule: caddy.listeners\nA list of listener wrapper modules, which can modify the behavior\nof the base listener. They are applied in the given order.\n",
"markdownDescription":"listener_wrappers: `array` \nModule: `caddy.listeners` \nA list of listener wrapper modules, which can modify the behavior\nof the base listener. They are applied in the given order. \n",
"type":"array",
"items":{
"description":"A list of listener wrapper modules, which can modify the behavior\nof the base listener. They are applied in the given order.\n",
"markdownDescription":"A list of listener wrapper modules, which can modify the behavior\nof the base listener. They are applied in the given order. \n",
"description":"key to identify listener_wrappers module.\nwrapper: string\nModule: caddy.listeners",
"markdownDescription":"key to identify `listener_wrappers` module. \nwrapper: `string` \nModule: `caddy.listeners`",
"type":"string",
"enum":[
"http_redirect",
"tls"
]
}
}
}
]
}
},
"logs":{
"description":"logs: object\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ServerLogConfig\nEnables access logging and configures how access logs are handled\nin this server. To minimally enable access logs, simply set this\nto a non-null, empty struct.\n\n\nServerLogConfig describes a server's logging configuration. If\nenabled without customization, all requests to this server are\nlogged to the default logger; logger destinations may be\ncustomized per-request-host.\n",
"markdownDescription":"logs: `object` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ServerLogConfig) \nEnables access logging and configures how access logs are handled\nin this server. To minimally enable access logs, simply set this\nto a non-null, empty struct.\n\n\nServerLogConfig describes a server's logging configuration. If\nenabled without customization, all requests to this server are\nlogged to the default logger; logger destinations may be\ncustomized per-request-host. \n",
"type":"object",
"properties":{
"default_logger_name":{
"description":"default_logger_name: string\nModule: http\nThe default logger name for all logs emitted by this server for\nhostnames that are not in the LoggerNames (logger_names) map.\n",
"markdownDescription":"default_logger_name: `string` \nModule: `http` \nThe default logger name for all logs emitted by this server for\nhostnames that are not in the LoggerNames (logger_names) map. \n",
"type":"string"
},
"logger_names":{
"description":"logger_names: object\nModule: http\nLoggerNames maps request hostnames to a custom logger name.\nFor example, a mapping of \"example.com\" to \"example\" would\ncause access logs from requests with a Host of example.com\nto be emitted by a logger named \"http.log.access.example\".\n",
"markdownDescription":"logger_names: `object` \nModule: `http` \nLoggerNames maps request hostnames to a custom logger name.\nFor example, a mapping of \"example.com\" to \"example\" would\ncause access logs from requests with a Host of example.com\nto be emitted by a logger named \"http.log.access.example\". \n",
"type":"object",
"additionalProperties":{
"description":"LoggerNames maps request hostnames to a custom logger name.\nFor example, a mapping of \"example.com\" to \"example\" would\ncause access logs from requests with a Host of example.com\nto be emitted by a logger named \"http.log.access.example\".\n",
"markdownDescription":"LoggerNames maps request hostnames to a custom logger name.\nFor example, a mapping of \"example.com\" to \"example\" would\ncause access logs from requests with a Host of example.com\nto be emitted by a logger named \"http.log.access.example\". \n"
}
},
"should_log_credentials":{
"description":"should_log_credentials: boolean\nModule: http\nIf true, credentials that are otherwise omitted, will be logged.\nThe definition of credentials is defined by https://fetch.spec.whatwg.org/#credentials,\nand this includes some request and response headers, i.e `Cookie`,\n`Set-Cookie`, `Authorization`, and `Proxy-Authorization`.\n",
"markdownDescription":"should_log_credentials: `boolean` \nModule: `http` \nIf true, credentials that are otherwise omitted, will be logged.\nThe definition of credentials is defined by https://fetch.spec.whatwg.org/#credentials,\nand this includes some request and response headers, i.e `Cookie`,\n`Set-Cookie`, `Authorization`, and `Proxy-Authorization`. \n",
"type":"boolean"
},
"skip_hosts":{
"description":"skip_hosts: array\nModule: http\nBy default, all requests to this server will be logged if\naccess logging is enabled. This field lists the request\nhosts for which access logging should be disabled.\n",
"markdownDescription":"skip_hosts: `array` \nModule: `http` \nBy default, all requests to this server will be logged if\naccess logging is enabled. This field lists the request\nhosts for which access logging should be disabled. \n",
"type":"array",
"items":{
"description":"By default, all requests to this server will be logged if\naccess logging is enabled. This field lists the request\nhosts for which access logging should be disabled.\n",
"markdownDescription":"By default, all requests to this server will be logged if\naccess logging is enabled. This field lists the request\nhosts for which access logging should be disabled. \n",
"type":"string"
}
},
"skip_unmapped_hosts":{
"description":"skip_unmapped_hosts: boolean\nModule: http\nIf true, requests to any host not appearing in the\nLoggerNames (logger_names) map will not be logged.\n",
"markdownDescription":"skip_unmapped_hosts: `boolean` \nModule: `http` \nIf true, requests to any host not appearing in the\nLoggerNames (logger_names) map will not be logged. \n",
"type":"boolean"
}
}
},
"max_header_bytes":{
"description":"max_header_bytes: number\nModule: http\nMaxHeaderBytes is the maximum size to parse from a client's\nHTTP request headers.\n",
"markdownDescription":"max_header_bytes: `number` \nModule: `http` \nMaxHeaderBytes is the maximum size to parse from a client's\nHTTP request headers. \n",
"description":"metrics: object\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Metrics\nIf set, metrics observations will be enabled.\nThis setting is EXPERIMENTAL and subject to change.\n\n\nMetrics configures metrics observations.\nEXPERIMENTAL and subject to change or removal.\n",
"markdownDescription":"metrics: `object` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Metrics) \nIf set, metrics observations will be enabled.\nThis setting is EXPERIMENTAL and subject to change.\n\n\nMetrics configures metrics observations.\nEXPERIMENTAL and subject to change or removal. \n",
"type":"object"
},
"protocols":{
"description":"protocols: array\nModule: http\nProtocols specifies which HTTP protocols to enable.\nSupported values are:\n\n- `h1` (HTTP/1.1)\n- `h2` (HTTP/2)\n- `h2c` (cleartext HTTP/2)\n- `h3` (HTTP/3)\n\nIf enabling `h2` or `h2c`, `h1` must also be enabled;\nthis is due to current limitations in the Go standard\nlibrary.\n\nHTTP/2 operates only over TLS (HTTPS). HTTP/3 opens\na UDP socket to serve QUIC connections.\n\nH2C operates over plain TCP if the client supports it;\nhowever, because this is not implemented by the Go\nstandard library, other server options are not compatible\nand will not be applied to H2C requests. Do not enable this\nonly to achieve maximum client compatibility. In practice,\nvery few clients implement H2C, and even fewer require it.\nEnabling H2C can be useful for serving/proxying gRPC\nif encryption is not possible or desired.\n\nWe recommend for most users to simply let Caddy use the\ndefault settings.\n\nDefault: `[h1 h2 h3]`\n",
"markdownDescription":"protocols: `array` \nModule: `http` \nProtocols specifies which HTTP protocols to enable.\nSupported values are:\n\n- `h1` (HTTP/1.1)\n- `h2` (HTTP/2)\n- `h2c` (cleartext HTTP/2)\n- `h3` (HTTP/3)\n\nIf enabling `h2` or `h2c`, `h1` must also be enabled;\nthis is due to current limitations in the Go standard\nlibrary.\n\nHTTP/2 operates only over TLS (HTTPS). HTTP/3 opens\na UDP socket to serve QUIC connections.\n\nH2C operates over plain TCP if the client supports it;\nhowever, because this is not implemented by the Go\nstandard library, other server options are not compatible\nand will not be applied to H2C requests. Do not enable this\nonly to achieve maximum client compatibility. In practice,\nvery few clients implement H2C, and even fewer require it.\nEnabling H2C can be useful for serving/proxying gRPC\nif encryption is not possible or desired.\n\nWe recommend for most users to simply let Caddy use the\ndefault settings.\n\nDefault: `[h1 h2 h3]` \n",
"type":"array",
"items":{
"description":"Protocols specifies which HTTP protocols to enable.\nSupported values are:\n\n- `h1` (HTTP/1.1)\n- `h2` (HTTP/2)\n- `h2c` (cleartext HTTP/2)\n- `h3` (HTTP/3)\n\nIf enabling `h2` or `h2c`, `h1` must also be enabled;\nthis is due to current limitations in the Go standard\nlibrary.\n\nHTTP/2 operates only over TLS (HTTPS). HTTP/3 opens\na UDP socket to serve QUIC connections.\n\nH2C operates over plain TCP if the client supports it;\nhowever, because this is not implemented by the Go\nstandard library, other server options are not compatible\nand will not be applied to H2C requests. Do not enable this\nonly to achieve maximum client compatibility. In practice,\nvery few clients implement H2C, and even fewer require it.\nEnabling H2C can be useful for serving/proxying gRPC\nif encryption is not possible or desired.\n\nWe recommend for most users to simply let Caddy use the\ndefault settings.\n\nDefault: `[h1 h2 h3]`\n",
"markdownDescription":"Protocols specifies which HTTP protocols to enable.\nSupported values are:\n\n- `h1` (HTTP/1.1)\n- `h2` (HTTP/2)\n- `h2c` (cleartext HTTP/2)\n- `h3` (HTTP/3)\n\nIf enabling `h2` or `h2c`, `h1` must also be enabled;\nthis is due to current limitations in the Go standard\nlibrary.\n\nHTTP/2 operates only over TLS (HTTPS). HTTP/3 opens\na UDP socket to serve QUIC connections.\n\nH2C operates over plain TCP if the client supports it;\nhowever, because this is not implemented by the Go\nstandard library, other server options are not compatible\nand will not be applied to H2C requests. Do not enable this\nonly to achieve maximum client compatibility. In practice,\nvery few clients implement H2C, and even fewer require it.\nEnabling H2C can be useful for serving/proxying gRPC\nif encryption is not possible or desired.\n\nWe recommend for most users to simply let Caddy use the\ndefault settings.\n\nDefault: `[h1 h2 h3]` \n",
"description":"read_header_timeout: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nReadHeaderTimeout is like ReadTimeout but for request headers.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"read_header_timeout: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nReadHeaderTimeout is like ReadTimeout but for request headers.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"read_timeout":{
"description":"read_timeout: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to allow a read from a client's upload. Setting this\nto a short, non-zero value can mitigate slowloris attacks, but\nmay also affect legitimately slow clients.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"read_timeout: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to allow a read from a client's upload. Setting this\nto a short, non-zero value can mitigate slowloris attacks, but\nmay also affect legitimately slow clients.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"routes":{
"description":"routes: array\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nRoutes describes how this server will handle requests.\nRoutes are executed sequentially. First a route's matchers\nare evaluated, then its grouping. If it matches and has\nnot been mutually-excluded by its grouping, then its\nhandlers are executed sequentially. The sequence of invoked\nhandlers comprises a compiled middleware chain that flows\nfrom each matching route and its handlers to the next.\n\nBy default, all unrouted requests receive a 200 OK response\nto indicate the server is working.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"routes: `array` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nRoutes describes how this server will handle requests.\nRoutes are executed sequentially. First a route's matchers\nare evaluated, then its grouping. If it matches and has\nnot been mutually-excluded by its grouping, then its\nhandlers are executed sequentially. The sequence of invoked\nhandlers comprises a compiled middleware chain that flows\nfrom each matching route and its handlers to the next.\n\nBy default, all unrouted requests receive a 200 OK response\nto indicate the server is working.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nRoutes describes how this server will handle requests.\nRoutes are executed sequentially. First a route's matchers\nare evaluated, then its grouping. If it matches and has\nnot been mutually-excluded by its grouping, then its\nhandlers are executed sequentially. The sequence of invoked\nhandlers comprises a compiled middleware chain that flows\nfrom each matching route and its handlers to the next.\n\nBy default, all unrouted requests receive a 200 OK response\nto indicate the server is working.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nRoutes describes how this server will handle requests.\nRoutes are executed sequentially. First a route's matchers\nare evaluated, then its grouping. If it matches and has\nnot been mutually-excluded by its grouping, then its\nhandlers are executed sequentially. The sequence of invoked\nhandlers comprises a compiled middleware chain that flows\nfrom each matching route and its handlers to the next.\n\nBy default, all unrouted requests receive a 200 OK response\nto indicate the server is working.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"object",
"properties":{
"group":{
"description":"group: string\nModule: http\nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed.\n",
"markdownDescription":"group: `string` \nModule: `http` \nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed. \n",
"type":"string"
},
"handle":{
"description":"handle: array\nModule: http.handlers\nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"handle: `array` \nModule: `http.handlers` \nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"type":"array",
"items":{
"description":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"description":"match: array\nModule: http.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `array` \nModule: `http.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"terminal: boolean\nModule: http\nIf true, no more routes will be executed after this one.\n",
"markdownDescription":"terminal: `boolean` \nModule: `http` \nIf true, no more routes will be executed after this one. \n",
"type":"boolean"
}
}
}
},
"strict_sni_host":{
"description":"strict_sni_host: boolean\nModule: http\nIf true, will require that a request's Host header match\nthe value of the ServerName sent by the client's TLS\nClientHello; often a necessary safeguard when using TLS\nclient authentication.\n",
"markdownDescription":"strict_sni_host: `boolean` \nModule: `http` \nIf true, will require that a request's Host header match\nthe value of the ServerName sent by the client's TLS\nClientHello; often a necessary safeguard when using TLS\nclient authentication. \n",
"type":"boolean"
},
"tls_connection_policies":{
"description":"tls_connection_policies: array\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy\nHow to handle TLS connections. At least one policy is\nrequired to enable HTTPS on this server if automatic\nHTTPS is disabled or does not apply.\n\n\nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used.\n",
"markdownDescription":"tls_connection_policies: `array` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy) \nHow to handle TLS connections. At least one policy is\nrequired to enable HTTPS on this server if automatic\nHTTPS is disabled or does not apply.\n\n\nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy\nHow to handle TLS connections. At least one policy is\nrequired to enable HTTPS on this server if automatic\nHTTPS is disabled or does not apply.\n\n\nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy) \nHow to handle TLS connections. At least one policy is\nrequired to enable HTTPS on this server if automatic\nHTTPS is disabled or does not apply.\n\n\nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used. \n",
"type":"object",
"properties":{
"alpn":{
"description":"alpn: array\nModule: http\nProtocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake.\n",
"markdownDescription":"alpn: `array` \nModule: `http` \nProtocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake. \n",
"type":"array",
"items":{
"description":"Protocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake.\n",
"markdownDescription":"Protocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake. \n",
"type":"string"
}
},
"certificate_selection":{
"description":"certificate_selection: object\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CustomCertSelectionPolicy\nHow to choose a certificate if more than one matched\nthe given ServerName (SNI) value.\n\n\nCustomCertSelectionPolicy represents a policy for selecting the certificate\nused to complete a handshake when there may be multiple options. All fields\nspecified must match the candidate certificate for it to be chosen.\nThis was needed to solve https://github.com/caddyserver/caddy/issues/2588.\n",
"markdownDescription":"certificate_selection: `object` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CustomCertSelectionPolicy) \nHow to choose a certificate if more than one matched\nthe given ServerName (SNI) value.\n\n\nCustomCertSelectionPolicy represents a policy for selecting the certificate\nused to complete a handshake when there may be multiple options. All fields\nspecified must match the candidate certificate for it to be chosen.\nThis was needed to solve https://github.com/caddyserver/caddy/issues/2588. \n",
"type":"object",
"properties":{
"all_tags":{
"description":"all_tags: array\nModule: http\nThe certificate must have all of the tags in the list.\n",
"markdownDescription":"all_tags: `array` \nModule: `http` \nThe certificate must have all of the tags in the list. \n",
"type":"array",
"items":{
"description":"The certificate must have all of the tags in the list.\n",
"markdownDescription":"The certificate must have all of the tags in the list. \n",
"type":"string"
}
},
"any_tag":{
"description":"any_tag: array\nModule: http\nThe certificate must have at least one of the tags in the list.\n",
"markdownDescription":"any_tag: `array` \nModule: `http` \nThe certificate must have at least one of the tags in the list. \n",
"type":"array",
"items":{
"description":"The certificate must have at least one of the tags in the list.\n",
"markdownDescription":"The certificate must have at least one of the tags in the list. \n",
"type":"string"
}
},
"public_key_algorithm":{
"description":"public_key_algorithm: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#PublicKeyAlgorithm\nThe certificate must use this public key algorithm.\n\n\nPublicKeyAlgorithm is a JSON-unmarshalable wrapper type.\n",
"markdownDescription":"public_key_algorithm: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#PublicKeyAlgorithm) \nThe certificate must use this public key algorithm.\n\n\nPublicKeyAlgorithm is a JSON-unmarshalable wrapper type. \n",
"type":"number"
},
"serial_number":{
"description":"serial_number: array\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt\nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string.\n",
"markdownDescription":"serial_number: `array` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt) \nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt\nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt) \nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string. \n",
"type":"object"
}
},
"subject_organization":{
"description":"subject_organization: array\nModule: http\nThe certificate must have one of these organization names.\n",
"markdownDescription":"subject_organization: `array` \nModule: `http` \nThe certificate must have one of these organization names. \n",
"type":"array",
"items":{
"description":"The certificate must have one of these organization names.\n",
"markdownDescription":"The certificate must have one of these organization names. \n",
"type":"string"
}
}
}
},
"cipher_suites":{
"description":"cipher_suites: array\nModule: http\nThe list of cipher suites to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"cipher_suites: `array` \nModule: `http` \nThe list of cipher suites to support. Caddy's\ndefaults are modern and secure. \n",
"type":"array",
"items":{
"description":"The list of cipher suites to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"The list of cipher suites to support. Caddy's\ndefaults are modern and secure. \n",
"description":"mode: string\nModule: http\nThe mode for authenticating the client. Allowed values are:\n\nMode | Description\n-----|---------------\n`request` | Ask clients for a certificate, but allow even if there isn't one; do not verify it\n`require` | Require clients to present a certificate, but do not verify it\n`verify_if_given` | Ask clients for a certificate; allow even if there isn't one, but verify it if there is\n`require_and_verify` | Require clients to present a valid certificate that is verified\n\nThe default mode is `require_and_verify` if any\nTrustedCACerts or TrustedCACertPEMFiles or TrustedLeafCerts\nare provided; otherwise, the default mode is `require`.\n",
"markdownDescription":"mode: `string` \nModule: `http` \nThe mode for authenticating the client. Allowed values are:\n\nMode | Description\n-----|---------------\n`request` | Ask clients for a certificate, but allow even if there isn't one; do not verify it\n`require` | Require clients to present a certificate, but do not verify it\n`verify_if_given` | Ask clients for a certificate; allow even if there isn't one, but verify it if there is\n`require_and_verify` | Require clients to present a valid certificate that is verified\n\nThe default mode is `require_and_verify` if any\nTrustedCACerts or TrustedCACertPEMFiles or TrustedLeafCerts\nare provided; otherwise, the default mode is `require`. \n",
"type":"string"
},
"trusted_ca_certs":{
"description":"trusted_ca_certs: array\nModule: http\nA list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected.\n",
"markdownDescription":"trusted_ca_certs: `array` \nModule: `http` \nA list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected. \n",
"type":"array",
"items":{
"description":"A list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected.\n",
"markdownDescription":"A list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected. \n",
"type":"string"
}
},
"trusted_ca_certs_pem_files":{
"description":"trusted_ca_certs_pem_files: array\nModule: http\nTrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected.\n",
"markdownDescription":"trusted_ca_certs_pem_files: `array` \nModule: `http` \nTrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected. \n",
"type":"array",
"items":{
"description":"TrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected.\n",
"markdownDescription":"TrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected. \n",
"description":"trusted_leaf_certs: array\nModule: http\nDEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected.\n",
"markdownDescription":"trusted_leaf_certs: `array` \nModule: `http` \nDEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected. \n",
"description":"DEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected.\n",
"markdownDescription":"DEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected. \n",
"description":"verifiers: array\nModule: tls.client_auth\nClient certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked.\n",
"markdownDescription":"verifiers: `array` \nModule: `tls.client_auth` \nClient certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked. \n",
"description":"Client certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked.\n",
"markdownDescription":"Client certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked. \n",
"description":"key to identify verifiers module.\nverifier: string\nModule: tls.client_auth",
"markdownDescription":"key to identify `verifiers` module. \nverifier: `string` \nModule: `tls.client_auth`",
"type":"string",
"enum":[
"leaf"
]
}
}
}
]
}
}
}
},
"curves":{
"description":"curves: array\nModule: http\nThe list of elliptic curves to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"curves: `array` \nModule: `http` \nThe list of elliptic curves to support. Caddy's\ndefaults are modern and secure. \n",
"type":"array",
"items":{
"description":"The list of elliptic curves to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"The list of elliptic curves to support. Caddy's\ndefaults are modern and secure. \n",
"type":"string"
}
},
"default_sni":{
"description":"default_sni: string\nModule: http\nDefaultSNI becomes the ServerName in a ClientHello if there\nis no policy configured for the empty SNI value.\n",
"markdownDescription":"default_sni: `string` \nModule: `http` \nDefaultSNI becomes the ServerName in a ClientHello if there\nis no policy configured for the empty SNI value. \n",
"description":"insecure_secrets_log: string\nModule: http\nAlso known as \"SSLKEYLOGFILE\", TLS secrets will be written to\nthis file in NSS key log format which can then be parsed by\nWireshark and other tools. This is INSECURE as it allows other\nprograms or tools to decrypt TLS connections. However, this\ncapability can be useful for debugging and troubleshooting.\n**ENABLING THIS LOG COMPROMISES SECURITY!**\n\nThis feature is EXPERIMENTAL and subject to change or removal.\n",
"markdownDescription":"insecure_secrets_log: `string` \nModule: `http` \nAlso known as \"SSLKEYLOGFILE\", TLS secrets will be written to\nthis file in NSS key log format which can then be parsed by\nWireshark and other tools. This is INSECURE as it allows other\nprograms or tools to decrypt TLS connections. However, this\ncapability can be useful for debugging and troubleshooting.\n**ENABLING THIS LOG COMPROMISES SECURITY!**\n\nThis feature is EXPERIMENTAL and subject to change or removal. \n",
"description":"match: object\nModule: tls.handshake_match\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nHow to match this policy with a TLS ClientHello. If\nthis policy is the first to match, it will be used.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `object` \nModule: `tls.handshake_match` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nHow to match this policy with a TLS ClientHello. If\nthis policy is the first to match, it will be used.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"protocol_max: string\nModule: http\nMaximum TLS protocol version to allow. Default: `tls1.3`\n",
"markdownDescription":"protocol_max: `string` \nModule: `http` \nMaximum TLS protocol version to allow. Default: `tls1.3` \n",
"type":"string"
},
"protocol_min":{
"description":"protocol_min: string\nModule: http\nMinimum TLS protocol version to allow. Default: `tls1.2`\n",
"markdownDescription":"protocol_min: `string` \nModule: `http` \nMinimum TLS protocol version to allow. Default: `tls1.2` \n",
"type":"string"
}
}
}
},
"write_timeout":{
"description":"write_timeout: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nWriteTimeout is how long to allow a write to a client. Note\nthat setting this to a small value when serving large files\nmay negatively affect legitimately slow clients.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"write_timeout: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nWriteTimeout is how long to allow a write to a client. Note\nthat setting this to a small value when serving large files\nmay negatively affect legitimately slow clients.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"shutdown_delay: number\nModule: http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nShutdownDelay is how long to wait before initiating the grace\nperiod. When this app is stopping (e.g. during a config reload or\nprocess exit), all servers will be shut down. Normally this immediately\ninitiates the grace period. However, if this delay is configured, servers\nwill not be shut down until the delay is over. During this time, servers\ncontinue to function normally and allow new connections. At the end, the\ngrace period will begin. This can be useful to allow downstream load\nbalancers time to move this instance out of the rotation without hiccups.\n\nWhen shutdown has been scheduled, placeholders {http.shutting_down} (bool)\nand {http.time_until_shutdown} (duration) may be useful for health checks.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"shutdown_delay: `number` \nModule: `http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nShutdownDelay is how long to wait before initiating the grace\nperiod. When this app is stopping (e.g. during a config reload or\nprocess exit), all servers will be shut down. Normally this immediately\ninitiates the grace period. However, if this delay is configured, servers\nwill not be shut down until the delay is over. During this time, servers\ncontinue to function normally and allow new connections. At the end, the\ngrace period will begin. This can be useful to allow downstream load\nbalancers time to move this instance out of the rotation without hiccups.\n\nWhen shutdown has been scheduled, placeholders {http.shutting_down} (bool)\nand {http.time_until_shutdown} (duration) may be useful for health checks.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"acme_server: object\nModule: http.handlers.acme_server\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki/acmeserver#Handler\nHandler is an ACME server handler.\n\n",
"markdownDescription":"acme_server: `object` \nModule: `http.handlers.acme_server` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki/acmeserver#Handler) \nHandler is an ACME server handler.\n \n",
"type":"object",
"properties":{
"ca":{
"description":"ca: string\nModule: http.handlers.acme_server\nThe ID of the CA to use for signing. This refers to\nthe ID given to the CA in the `pki` app. If omitted,\nthe default ID is \"local\".\n",
"markdownDescription":"ca: `string` \nModule: `http.handlers.acme_server` \nThe ID of the CA to use for signing. This refers to\nthe ID given to the CA in the `pki` app. If omitted,\nthe default ID is \"local\". \n",
"type":"string"
},
"host":{
"description":"host: string\nModule: http.handlers.acme_server\nThe hostname or IP address by which ACME clients\nwill access the server. This is used to populate\nthe ACME directory endpoint. If not set, the Host\nheader of the request will be used.\nCOMPATIBILITY NOTE / TODO: This property may go away in the\nfuture. Do not rely on this property long-term; check release notes.\n",
"markdownDescription":"host: `string` \nModule: `http.handlers.acme_server` \nThe hostname or IP address by which ACME clients\nwill access the server. This is used to populate\nthe ACME directory endpoint. If not set, the Host\nheader of the request will be used.\nCOMPATIBILITY NOTE / TODO: This property may go away in the\nfuture. Do not rely on this property long-term; check release notes. \n",
"type":"string"
},
"path_prefix":{
"description":"path_prefix: string\nModule: http.handlers.acme_server\nThe path prefix under which to serve all ACME\nendpoints. All other requests will not be served\nby this handler and will be passed through to\nthe next one. Default: \"/acme/\".\nCOMPATIBILITY NOTE / TODO: This property may go away in the\nfuture, as it is currently only required due to\nlimitations in the underlying library. Do not rely\non this property long-term; check release notes.\n",
"markdownDescription":"path_prefix: `string` \nModule: `http.handlers.acme_server` \nThe path prefix under which to serve all ACME\nendpoints. All other requests will not be served\nby this handler and will be passed through to\nthe next one. Default: \"/acme/\".\nCOMPATIBILITY NOTE / TODO: This property may go away in the\nfuture, as it is currently only required due to\nlimitations in the underlying library. Do not rely\non this property long-term; check release notes. \n",
"type":"string"
},
"sign_with_root":{
"description":"sign_with_root: boolean\nModule: http.handlers.acme_server\nIf true, the CA's root will be the issuer instead of\nthe intermediate. This is NOT recommended and should\nonly be used when devices/clients do not properly\nvalidate certificate chains. EXPERIMENTAL: Might be\nchanged or removed in the future.\n",
"markdownDescription":"sign_with_root: `boolean` \nModule: `http.handlers.acme_server` \nIf true, the CA's root will be the issuer instead of\nthe intermediate. This is NOT recommended and should\nonly be used when devices/clients do not properly\nvalidate certificate chains. EXPERIMENTAL: Might be\nchanged or removed in the future. \n",
"type":"boolean"
}
}
},
"http.handlers.authentication":{
"description":"authentication: object\nModule: http.handlers.authentication\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth#Authentication\nAuthentication is a middleware which provides user authentication.\nRejects requests with HTTP 401 if the request is not authenticated.\n\nAfter a successful authentication, the placeholder\n`{http.auth.user.id}` will be set to the username, and also\n`{http.auth.user.*}` placeholders may be set for any authentication\nmodules that provide user metadata.\n\nIts API is still experimental and may be subject to change.\n\n",
"markdownDescription":"authentication: `object` \nModule: `http.handlers.authentication` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth#Authentication) \nAuthentication is a middleware which provides user authentication.\nRejects requests with HTTP 401 if the request is not authenticated.\n\nAfter a successful authentication, the placeholder\n`{http.auth.user.id}` will be set to the username, and also\n`{http.auth.user.*}` placeholders may be set for any authentication\nmodules that provide user metadata.\n\nIts API is still experimental and may be subject to change.\n \n",
"type":"object",
"properties":{
"providers":{
"description":"providers: object\nModule: http.authentication.providers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nA set of authentication providers. If none are specified,\nall requests will always be unauthenticated.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"providers: `object` \nModule: `http.authentication.providers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nA set of authentication providers. If none are specified,\nall requests will always be unauthenticated.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"ttl: object\nModule: http.handlers.cache\nhttps://pkg.go.dev/github.com/darkweak/souin/configurationtypes#Duration\nDuration is the super object to wrap the duration and be able to parse it from the configuration\n\n",
"markdownDescription":"ttl: `object` \nModule: `http.handlers.cache` \n[godoc](https://pkg.go.dev/github.com/darkweak/souin/configurationtypes#Duration) \nDuration is the super object to wrap the duration and be able to parse it from the configuration\n \n",
"type":"object"
}
}
},
"http.handlers.copy_response":{
"description":"copy_response: object\nModule: http.handlers.copy_response\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#CopyResponseHandler\nCopyResponseHandler is a special HTTP handler which may\nonly be used within reverse_proxy's handle_response routes,\nto copy the proxy response. EXPERIMENTAL, subject to change.\n\n",
"markdownDescription":"copy_response: `object` \nModule: `http.handlers.copy_response` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#CopyResponseHandler) \nCopyResponseHandler is a special HTTP handler which may\nonly be used within reverse_proxy's handle_response routes,\nto copy the proxy response. EXPERIMENTAL, subject to change.\n \n",
"type":"object",
"properties":{
"status_code":{
"description":"status_code: string\nModule: http.handlers.copy_response\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString\nTo write the upstream response's body but with a different\nstatus code, set this field to the desired status code.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned.\n",
"markdownDescription":"status_code: `string` \nModule: `http.handlers.copy_response` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString) \nTo write the upstream response's body but with a different\nstatus code, set this field to the desired status code.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned. \n",
"type":"string"
}
}
},
"http.handlers.copy_response_headers":{
"description":"copy_response_headers: object\nModule: http.handlers.copy_response_headers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#CopyResponseHeadersHandler\nCopyResponseHeadersHandler is a special HTTP handler which may\nonly be used within reverse_proxy's handle_response routes,\nto copy headers from the proxy response. EXPERIMENTAL;\nsubject to change.\n\n",
"markdownDescription":"copy_response_headers: `object` \nModule: `http.handlers.copy_response_headers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#CopyResponseHeadersHandler) \nCopyResponseHeadersHandler is a special HTTP handler which may\nonly be used within reverse_proxy's handle_response routes,\nto copy headers from the proxy response. EXPERIMENTAL;\nsubject to change.\n \n",
"type":"object",
"properties":{
"exclude":{
"description":"exclude: array\nModule: http.handlers.copy_response_headers\nA list of header fields to skip copying from the response.\nCannot be defined at the same time as Include.\n",
"markdownDescription":"exclude: `array` \nModule: `http.handlers.copy_response_headers` \nA list of header fields to skip copying from the response.\nCannot be defined at the same time as Include. \n",
"type":"array",
"items":{
"description":"A list of header fields to skip copying from the response.\nCannot be defined at the same time as Include.\n",
"markdownDescription":"A list of header fields to skip copying from the response.\nCannot be defined at the same time as Include. \n",
"type":"string"
}
},
"include":{
"description":"include: array\nModule: http.handlers.copy_response_headers\nA list of header fields to copy from the response.\nCannot be defined at the same time as Exclude.\n",
"markdownDescription":"include: `array` \nModule: `http.handlers.copy_response_headers` \nA list of header fields to copy from the response.\nCannot be defined at the same time as Exclude. \n",
"description":"A list of header fields to copy from the response.\nCannot be defined at the same time as Exclude.\n",
"markdownDescription":"A list of header fields to copy from the response.\nCannot be defined at the same time as Exclude. \n",
"type":"string"
}
}
}
},
"http.handlers.encode":{
"description":"encode: object\nModule: http.handlers.encode\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/encode#Encode\nEncode is a middleware which can encode responses.\n\n",
"markdownDescription":"encode: `object` \nModule: `http.handlers.encode` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/encode#Encode) \nEncode is a middleware which can encode responses.\n \n",
"type":"object",
"properties":{
"encodings":{
"description":"encodings: object\nModule: http.encoders\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nSelection of compression algorithms to choose from. The best one\nwill be chosen based on the client's Accept-Encoding header.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"encodings: `object` \nModule: `http.encoders` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nSelection of compression algorithms to choose from. The best one\nwill be chosen based on the client's Accept-Encoding header.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"object",
"properties":{
"gzip":{
"$ref":"#/definitions/http.encoders.gzip"
},
"zstd":{
"$ref":"#/definitions/http.encoders.zstd"
}
}
},
"match":{
"description":"match: object\nModule: http.handlers.encode\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher\nOnly encode responses that match against this ResponseMmatcher.\nThe default is a collection of text-based Content-Type headers.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria.\n",
"markdownDescription":"match: `object` \nModule: `http.handlers.encode` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher) \nOnly encode responses that match against this ResponseMmatcher.\nThe default is a collection of text-based Content-Type headers.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria. \n",
"type":"object",
"properties":{
"headers":{
"description":"headers: object\nModule: http.handlers.encode\nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.encode` \nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"object",
"additionalProperties":{
"description":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"status_code":{
"description":"status_code: array\nModule: http.handlers.encode\nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"status_code: `array` \nModule: `http.handlers.encode` \nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"type":"array",
"items":{
"description":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"type":"number"
}
}
}
},
"minimum_length":{
"description":"minimum_length: number\nModule: http.handlers.encode\nOnly encode responses that are at least this many bytes long.\n",
"markdownDescription":"minimum_length: `number` \nModule: `http.handlers.encode` \nOnly encode responses that are at least this many bytes long. \n",
"type":"number"
},
"prefer":{
"description":"prefer: array\nModule: http.handlers.encode\nIf the client has no strong preference, choose these encodings in order.\n",
"markdownDescription":"prefer: `array` \nModule: `http.handlers.encode` \nIf the client has no strong preference, choose these encodings in order. \n",
"type":"array",
"items":{
"description":"If the client has no strong preference, choose these encodings in order.\n",
"markdownDescription":"If the client has no strong preference, choose these encodings in order. \n",
"type":"string"
}
}
}
},
"http.handlers.error":{
"description":"error: object\nModule: http.handlers.error\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#StaticError\nStaticError implements a simple handler that returns an error.\nThis handler returns an error value, but does not write a response.\nThis is useful when you want the server to act as if an error\noccurred; for example, to invoke your custom error handling logic.\n\nSince this handler does not write a response, the error information\nis for use by the server to know how to handle the error.\n\n",
"markdownDescription":"error: `object` \nModule: `http.handlers.error` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#StaticError) \nStaticError implements a simple handler that returns an error.\nThis handler returns an error value, but does not write a response.\nThis is useful when you want the server to act as if an error\noccurred; for example, to invoke your custom error handling logic.\n\nSince this handler does not write a response, the error information\nis for use by the server to know how to handle the error.\n \n",
"type":"object",
"properties":{
"error":{
"description":"error: string\nModule: http.handlers.error\nThe error message. Optional. Default is no error message.\n",
"markdownDescription":"error: `string` \nModule: `http.handlers.error` \nThe error message. Optional. Default is no error message. \n",
"type":"string"
},
"status_code":{
"description":"status_code: string\nModule: http.handlers.error\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString\nThe recommended HTTP status code. Can be either an integer or a\nstring if placeholders are needed. Optional. Default is 500.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned.\n",
"markdownDescription":"status_code: `string` \nModule: `http.handlers.error` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString) \nThe recommended HTTP status code. Can be either an integer or a\nstring if placeholders are needed. Optional. Default is 500.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned. \n",
"description":"file_server: object\nModule: http.handlers.file_server\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/fileserver#FileServer\nFileServer implements a handler that serves static files.\n\nThe path of the file to serve is constructed by joining the site root\nand the sanitized request path. Any and all files within the root and\nlinks with targets outside the site root may therefore be accessed.\nFor example, with a site root of `/www`, requests to `/foo/bar.txt`\nwill serve the file at `/www/foo/bar.txt`.\n\nThe request path is sanitized using the Go standard library's\npath.Clean() function (https://pkg.go.dev/path#Clean) before being\njoined to the root. Request paths must be valid and well-formed.\n\nFor requests that access directories instead of regular files,\nCaddy will attempt to serve an index file if present. For example,\na request to `/dir/` will attempt to serve `/dir/index.html` if\nit exists. The index file names to try are configurable. If a\nrequested directory does not have an index file, Caddy writes a\n404 response. Alternatively, file browsing can be enabled with\nthe \"browse\" parameter which shows a list of files when directories\nare requested if no index file is present.\n\nBy default, this handler will canonicalize URIs so that requests to\ndirectories end with a slash, but requests to regular files do not.\nThis is enforced with HTTP redirects automatically and can be disabled.\nCanonicalization redirects are not issued, however, if a URI rewrite\nmodified the last component of the path (the filename).\n\nThis handler sets the Etag and Last-Modified headers for static files.\nIt does not perform MIME sniffing to determine Content-Type based on\ncontents, but does use the extension (if known); see the Go docs for\ndetails: https://pkg.go.dev/mime#TypeByExtension\n\nThe file server properly handles requests with If-Match,\nIf-Unmodified-Since, If-Modified-Since, If-None-Match, Range, and\nIf-Range headers. It includes the file's modification time in the\nLast-Modified header of the response.\n\n",
"markdownDescription":"file_server: `object` \nModule: `http.handlers.file_server` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/fileserver#FileServer) \nFileServer implements a handler that serves static files.\n\nThe path of the file to serve is constructed by joining the site root\nand the sanitized request path. Any and all files within the root and\nlinks with targets outside the site root may therefore be accessed.\nFor example, with a site root of `/www`, requests to `/foo/bar.txt`\nwill serve the file at `/www/foo/bar.txt`.\n\nThe request path is sanitized using the Go standard library's\npath.Clean() function (https://pkg.go.dev/path#Clean) before being\njoined to the root. Request paths must be valid and well-formed.\n\nFor requests that access directories instead of regular files,\nCaddy will attempt to serve an index file if present. For example,\na request to `/dir/` will attempt to serve `/dir/index.html` if\nit exists. The index file names to try are configurable. If a\nrequested directory does not have an index file, Caddy writes a\n404 response. Alternatively, file browsing can be enabled with\nthe \"browse\" parameter which shows a list of files when directories\nare requested if no index file is present.\n\nBy default, this handler will canonicalize URIs so that requests to\ndirectories end with a slash, but requests to regular files do not.\nThis is enforced with HTTP redirects automatically and can be disabled.\nCanonicalization redirects are not issued, however, if a URI rewrite\nmodified the last component of the path (the filename).\n\nThis handler sets the Etag and Last-Modified headers for static files.\nIt does not perform MIME sniffing to determine Content-Type based on\ncontents, but does use the extension (if known); see the Go docs for\ndetails: https://pkg.go.dev/mime#TypeByExtension\n\nThe file server properly handles requests with If-Match,\nIf-Unmodified-Since, If-Modified-Since, If-None-Match, Range, and\nIf-Range headers. It includes the file's modification time in the\nLast-Modified header of the response.\n \n",
"description":"browse: object\nModule: http.handlers.file_server\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/fileserver#Browse\nEnables file listings if a directory was requested and no index\nfile is present.\n\n\nBrowse configures directory browsing.\n",
"markdownDescription":"browse: `object` \nModule: `http.handlers.file_server` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/fileserver#Browse) \nEnables file listings if a directory was requested and no index\nfile is present.\n\n\nBrowse configures directory browsing. \n",
"type":"object",
"properties":{
"template_file":{
"description":"template_file: string\nModule: http.handlers.file_server\nUse this template file instead of the default browse template.\n",
"markdownDescription":"template_file: `string` \nModule: `http.handlers.file_server` \nUse this template file instead of the default browse template. \n",
"type":"string"
}
}
},
"canonical_uris":{
"description":"canonical_uris: boolean\nModule: http.handlers.file_server\nUse redirects to enforce trailing slashes for directories, or to\nremove trailing slash from URIs for files. Default is true.\n\nCanonicalization will not happen if the last element of the request's\npath (the filename) is changed in an internal rewrite, to avoid\nclobbering the explicit rewrite with implicit behavior.\n",
"markdownDescription":"canonical_uris: `boolean` \nModule: `http.handlers.file_server` \nUse redirects to enforce trailing slashes for directories, or to\nremove trailing slash from URIs for files. Default is true.\n\nCanonicalization will not happen if the last element of the request's\npath (the filename) is changed in an internal rewrite, to avoid\nclobbering the explicit rewrite with implicit behavior. \n",
"description":"file_system: any\nModule: caddy.fs\nThe file system implementation to use. By default, Caddy uses the local\ndisk file system.\n\nFile system modules used here must adhere to the following requirements:\n- Implement fs.FS interface.\n- Support seeking on opened files; i.e.returned fs.File values must\n implement the io.Seeker interface. This is required for determining\n Content-Length and satisfying Range requests.\n- fs.File values that represent directories must implement the\n fs.ReadDirFile interface so that directory listings can be procured.\n",
"markdownDescription":"file_system: `any` \nModule: `caddy.fs` \nThe file system implementation to use. By default, Caddy uses the local\ndisk file system.\n\nFile system modules used here must adhere to the following requirements:\n- Implement fs.FS interface.\n- Support seeking on opened files; i.e.returned fs.File values must\n implement the io.Seeker interface. This is required for determining\n Content-Length and satisfying Range requests.\n- fs.File values that represent directories must implement the\n fs.ReadDirFile interface so that directory listings can be procured. \n"
"description":"hide: array\nModule: http.handlers.file_server\nA list of files or folders to hide; the file server will pretend as if\nthey don't exist. Accepts globular patterns like `*.ext` or `/foo/*/bar`\nas well as placeholders. Because site roots can be dynamic, this list\nuses file system paths, not request paths. To clarify, the base of\nrelative paths is the current working directory, NOT the site root.\n\nEntries without a path separator (`/` or `\\` depending on OS) will match\nany file or directory of that name regardless of its path. To hide only a\nspecific file with a name that may not be unique, always use a path\nseparator. For example, to hide all files or folder trees named \"hidden\",\nput \"hidden\" in the list. To hide only ./hidden, put \"./hidden\" in the list.\n\nWhen possible, all paths are resolved to their absolute form before\ncomparisons are made. For maximum clarity and explictness, use complete,\nabsolute paths; or, for greater portability, use relative paths instead.\n",
"markdownDescription":"hide: `array` \nModule: `http.handlers.file_server` \nA list of files or folders to hide; the file server will pretend as if\nthey don't exist. Accepts globular patterns like `*.ext` or `/foo/*/bar`\nas well as placeholders. Because site roots can be dynamic, this list\nuses file system paths, not request paths. To clarify, the base of\nrelative paths is the current working directory, NOT the site root.\n\nEntries without a path separator (`/` or `\\` depending on OS) will match\nany file or directory of that name regardless of its path. To hide only a\nspecific file with a name that may not be unique, always use a path\nseparator. For example, to hide all files or folder trees named \"hidden\",\nput \"hidden\" in the list. To hide only ./hidden, put \"./hidden\" in the list.\n\nWhen possible, all paths are resolved to their absolute form before\ncomparisons are made. For maximum clarity and explictness, use complete,\nabsolute paths; or, for greater portability, use relative paths instead. \n",
"type":"array",
"items":{
"description":"A list of files or folders to hide; the file server will pretend as if\nthey don't exist. Accepts globular patterns like `*.ext` or `/foo/*/bar`\nas well as placeholders. Because site roots can be dynamic, this list\nuses file system paths, not request paths. To clarify, the base of\nrelative paths is the current working directory, NOT the site root.\n\nEntries without a path separator (`/` or `\\` depending on OS) will match\nany file or directory of that name regardless of its path. To hide only a\nspecific file with a name that may not be unique, always use a path\nseparator. For example, to hide all files or folder trees named \"hidden\",\nput \"hidden\" in the list. To hide only ./hidden, put \"./hidden\" in the list.\n\nWhen possible, all paths are resolved to their absolute form before\ncomparisons are made. For maximum clarity and explictness, use complete,\nabsolute paths; or, for greater portability, use relative paths instead.\n",
"markdownDescription":"A list of files or folders to hide; the file server will pretend as if\nthey don't exist. Accepts globular patterns like `*.ext` or `/foo/*/bar`\nas well as placeholders. Because site roots can be dynamic, this list\nuses file system paths, not request paths. To clarify, the base of\nrelative paths is the current working directory, NOT the site root.\n\nEntries without a path separator (`/` or `\\` depending on OS) will match\nany file or directory of that name regardless of its path. To hide only a\nspecific file with a name that may not be unique, always use a path\nseparator. For example, to hide all files or folder trees named \"hidden\",\nput \"hidden\" in the list. To hide only ./hidden, put \"./hidden\" in the list.\n\nWhen possible, all paths are resolved to their absolute form before\ncomparisons are made. For maximum clarity and explictness, use complete,\nabsolute paths; or, for greater portability, use relative paths instead. \n",
"description":"index_names: array\nModule: http.handlers.file_server\nThe names of files to try as index files if a folder is requested.\nDefault: index.html, index.txt.\n",
"markdownDescription":"index_names: `array` \nModule: `http.handlers.file_server` \nThe names of files to try as index files if a folder is requested.\nDefault: index.html, index.txt. \n",
"description":"pass_thru: boolean\nModule: http.handlers.file_server\nIf pass-thru mode is enabled and a requested file is not found,\nit will invoke the next handler in the chain instead of returning\na 404 error. By default, this is false (disabled).\n",
"markdownDescription":"pass_thru: `boolean` \nModule: `http.handlers.file_server` \nIf pass-thru mode is enabled and a requested file is not found,\nit will invoke the next handler in the chain instead of returning\na 404 error. By default, this is false (disabled). \n",
"type":"boolean"
},
"precompressed":{
"description":"precompressed: object\nModule: http.precompressed\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nSelection of encoders to use to check for precompressed files.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"precompressed: `object` \nModule: `http.precompressed` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nSelection of encoders to use to check for precompressed files.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"object",
"properties":{
"br":{
"$ref":"#/definitions/http.precompressed.br"
},
"gzip":{
"$ref":"#/definitions/http.precompressed.gzip"
},
"zstd":{
"$ref":"#/definitions/http.precompressed.zstd"
}
}
},
"precompressed_order":{
"description":"precompressed_order: array\nModule: http.handlers.file_server\nIf the client has no strong preference (q-factor), choose these encodings in order.\nIf no order specified here, the first encoding from the Accept-Encoding header\nthat both client and server support is used\n",
"markdownDescription":"precompressed_order: `array` \nModule: `http.handlers.file_server` \nIf the client has no strong preference (q-factor), choose these encodings in order.\nIf no order specified here, the first encoding from the Accept-Encoding header\nthat both client and server support is used \n",
"type":"array",
"items":{
"description":"If the client has no strong preference (q-factor), choose these encodings in order.\nIf no order specified here, the first encoding from the Accept-Encoding header\nthat both client and server support is used\n",
"markdownDescription":"If the client has no strong preference (q-factor), choose these encodings in order.\nIf no order specified here, the first encoding from the Accept-Encoding header\nthat both client and server support is used \n",
"description":"root: string\nModule: http.handlers.file_server\nThe path to the root of the site. Default is `{http.vars.root}` if set,\nor current working directory otherwise. This should be a trusted value.\n\nNote that a site root is not a sandbox. Although the file server does\nsanitize the request URI to prevent directory traversal, files (including\nlinks) within the site root may be directly accessed based on the request\npath. Files and folders within the root should be secure and trustworthy.\n",
"markdownDescription":"root: `string` \nModule: `http.handlers.file_server` \nThe path to the root of the site. Default is `{http.vars.root}` if set,\nor current working directory otherwise. This should be a trusted value.\n\nNote that a site root is not a sandbox. Although the file server does\nsanitize the request URI to prevent directory traversal, files (including\nlinks) within the site root may be directly accessed based on the request\npath. Files and folders within the root should be secure and trustworthy. \n",
"description":"status_code: string\nModule: http.handlers.file_server\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString\nOverride the status code written when successfully serving a file.\nParticularly useful when explicitly serving a file as display for\nan error, like a 404 page. A placeholder may be used. By default,\nthe status code will typically be 200, or 206 for partial content.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned.\n",
"markdownDescription":"status_code: `string` \nModule: `http.handlers.file_server` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString) \nOverride the status code written when successfully serving a file.\nParticularly useful when explicitly serving a file as display for\nan error, like a 404 page. A placeholder may be used. By default,\nthe status code will typically be 200, or 206 for partial content.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned. \n",
"type":"string"
}
}
},
"http.handlers.headers":{
"description":"headers: object\nModule: http.handlers.headers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Handler\nHandler is a middleware which modifies request and response headers.\n\nChanges to headers are applied immediately, except for the response\nheaders when Deferred is true or when Required is set. In those cases,\nthe changes are applied when the headers are written to the response.\nNote that deferred changes do not take effect if an error occurs later\nin the middleware chain.\n\nProperties in this module accept placeholders.\n\nResponse header operations can be conditioned upon response status code\nand/or other header values.\n\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.headers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Handler) \nHandler is a middleware which modifies request and response headers.\n\nChanges to headers are applied immediately, except for the response\nheaders when Deferred is true or when Required is set. In those cases,\nthe changes are applied when the headers are written to the response.\nNote that deferred changes do not take effect if an error occurs later\nin the middleware chain.\n\nProperties in this module accept placeholders.\n\nResponse header operations can be conditioned upon response status code\nand/or other header values.\n \n",
"type":"object",
"properties":{
"request":{
"description":"request: object\nModule: http.handlers.headers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#HeaderOps\nHeaderOps defines manipulations for HTTP headers.\n\n",
"description":"delete: array\nModule: http.handlers.headers\nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"delete: `array` \nModule: `http.handlers.headers` \nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"replace: object\nModule: http.handlers.headers\nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields.\n",
"markdownDescription":"replace: `object` \nModule: `http.handlers.headers` \nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields. \n",
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"object",
"properties":{
"replace":{
"description":"replace: string\nModule: http.handlers.headers\nThe string with which to replace matches.\n",
"markdownDescription":"replace: `string` \nModule: `http.handlers.headers` \nThe string with which to replace matches. \n",
"type":"string"
},
"search":{
"description":"search: string\nModule: http.handlers.headers\nThe substring to search for.\n",
"markdownDescription":"search: `string` \nModule: `http.handlers.headers` \nThe substring to search for. \n",
"type":"string"
},
"search_regexp":{
"description":"search_regexp: string\nModule: http.handlers.headers\nThe regular expression to search with.\n",
"description":"add: object\nModule: http.handlers.headers\nAdds HTTP headers; does not replace any existing header fields.\n",
"markdownDescription":"add: `object` \nModule: `http.handlers.headers` \nAdds HTTP headers; does not replace any existing header fields. \n",
"type":"object",
"additionalProperties":{
"description":"Adds HTTP headers; does not replace any existing header fields.\n",
"markdownDescription":"Adds HTTP headers; does not replace any existing header fields. \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"deferred":{
"description":"deferred: boolean\nModule: http.handlers.headers\nIf true, header operations will be deferred until\nthey are written out. Superceded if Require is set.\nUsually you will need to set this to true if any\nfields are being deleted.\n",
"markdownDescription":"deferred: `boolean` \nModule: `http.handlers.headers` \nIf true, header operations will be deferred until\nthey are written out. Superceded if Require is set.\nUsually you will need to set this to true if any\nfields are being deleted. \n",
"description":"delete: array\nModule: http.handlers.headers\nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"delete: `array` \nModule: `http.handlers.headers` \nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"replace: object\nModule: http.handlers.headers\nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields.\n",
"markdownDescription":"replace: `object` \nModule: `http.handlers.headers` \nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields. \n",
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"object",
"properties":{
"replace":{
"description":"replace: string\nModule: http.handlers.headers\nThe string with which to replace matches.\n",
"markdownDescription":"replace: `string` \nModule: `http.handlers.headers` \nThe string with which to replace matches. \n",
"type":"string"
},
"search":{
"description":"search: string\nModule: http.handlers.headers\nThe substring to search for.\n",
"markdownDescription":"search: `string` \nModule: `http.handlers.headers` \nThe substring to search for. \n",
"type":"string"
},
"search_regexp":{
"description":"search_regexp: string\nModule: http.handlers.headers\nThe regular expression to search with.\n",
"description":"require: object\nModule: http.handlers.headers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher\nIf set, header operations will be deferred until\nthey are written out and only performed if the\nresponse matches these criteria.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria.\n",
"markdownDescription":"require: `object` \nModule: `http.handlers.headers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher) \nIf set, header operations will be deferred until\nthey are written out and only performed if the\nresponse matches these criteria.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria. \n",
"type":"object",
"properties":{
"headers":{
"description":"headers: object\nModule: http.handlers.headers\nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.headers` \nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"object",
"additionalProperties":{
"description":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"status_code":{
"description":"status_code: array\nModule: http.handlers.headers\nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"status_code: `array` \nModule: `http.handlers.headers` \nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"type":"array",
"items":{
"description":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"description":"map: object\nModule: http.handlers.map\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/map#Handler\nHandler implements a middleware that maps inputs to outputs. Specifically, it\ncompares a source value against the map inputs, and for one that matches, it\napplies the output values to each destination. Destinations become placeholder\nnames.\n\nMapped placeholders are not evaluated until they are used, so even for very\nlarge mappings, this handler is quite efficient.\n\n",
"markdownDescription":"map: `object` \nModule: `http.handlers.map` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/map#Handler) \nHandler implements a middleware that maps inputs to outputs. Specifically, it\ncompares a source value against the map inputs, and for one that matches, it\napplies the output values to each destination. Destinations become placeholder\nnames.\n\nMapped placeholders are not evaluated until they are used, so even for very\nlarge mappings, this handler is quite efficient.\n \n",
"type":"object",
"properties":{
"defaults":{
"description":"defaults: array\nModule: http.handlers.map\nIf no mappings match or if the mapped output is null/nil, the associated\ndefault output will be applied (optional).\n",
"markdownDescription":"defaults: `array` \nModule: `http.handlers.map` \nIf no mappings match or if the mapped output is null/nil, the associated\ndefault output will be applied (optional). \n",
"type":"array",
"items":{
"description":"If no mappings match or if the mapped output is null/nil, the associated\ndefault output will be applied (optional).\n",
"markdownDescription":"If no mappings match or if the mapped output is null/nil, the associated\ndefault output will be applied (optional). \n",
"type":"string"
}
},
"destinations":{
"description":"destinations: array\nModule: http.handlers.map\nDestinations are the names of placeholders in which to store the outputs.\n",
"markdownDescription":"destinations: `array` \nModule: `http.handlers.map` \nDestinations are the names of placeholders in which to store the outputs. \n",
"type":"array",
"items":{
"description":"Destinations are the names of placeholders in which to store the outputs.\n",
"markdownDescription":"Destinations are the names of placeholders in which to store the outputs. \n",
"type":"string"
}
},
"mappings":{
"description":"mappings: array\nModule: http.handlers.map\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/map#Mapping\nMappings from source values (inputs) to destination values (outputs).\nThe first matching, non-nil mapping will be applied.\n\n\nMapping describes a mapping from input to outputs.\n",
"markdownDescription":"mappings: `array` \nModule: `http.handlers.map` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/map#Mapping) \nMappings from source values (inputs) to destination values (outputs).\nThe first matching, non-nil mapping will be applied.\n\n\nMapping describes a mapping from input to outputs. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/map#Mapping\nMappings from source values (inputs) to destination values (outputs).\nThe first matching, non-nil mapping will be applied.\n\n\nMapping describes a mapping from input to outputs.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/map#Mapping) \nMappings from source values (inputs) to destination values (outputs).\nThe first matching, non-nil mapping will be applied.\n\n\nMapping describes a mapping from input to outputs. \n",
"type":"object",
"properties":{
"input":{
"description":"input: string\nModule: http.handlers.map\nThe input value to match. Must be distinct from other mappings.\nMutually exclusive to input_regexp.\n",
"markdownDescription":"input: `string` \nModule: `http.handlers.map` \nThe input value to match. Must be distinct from other mappings.\nMutually exclusive to input_regexp. \n",
"type":"string"
},
"input_regexp":{
"description":"input_regexp: string\nModule: http.handlers.map\nThe input regular expression to match. Mutually exclusive to input.\n",
"markdownDescription":"input_regexp: `string` \nModule: `http.handlers.map` \nThe input regular expression to match. Mutually exclusive to input. \n",
"type":"string"
},
"outputs":{
"description":"outputs: array\nModule: http.handlers.map\nUpon a match with the input, each output is positionally correlated\nwith each destination of the parent handler. An output that is null\n(nil) will be treated as if it was not mapped at all.\n",
"markdownDescription":"outputs: `array` \nModule: `http.handlers.map` \nUpon a match with the input, each output is positionally correlated\nwith each destination of the parent handler. An output that is null\n(nil) will be treated as if it was not mapped at all. \n",
"type":"array",
"items":{
"type":[
"string",
"null"
],
"description":"Upon a match with the input, each output is positionally correlated\nwith each destination of the parent handler. An output that is null\n(nil) will be treated as if it was not mapped at all.\n",
"markdownDescription":"Upon a match with the input, each output is positionally correlated\nwith each destination of the parent handler. An output that is null\n(nil) will be treated as if it was not mapped at all. \n"
}
}
}
}
},
"source":{
"description":"source: string\nModule: http.handlers.map\nSource is the placeholder from which to get the input value.\n",
"markdownDescription":"source: `string` \nModule: `http.handlers.map` \nSource is the placeholder from which to get the input value. \n",
"type":"string"
}
}
},
"http.handlers.metrics":{
"description":"metrics: object\nModule: http.handlers.metrics\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/metrics#Metrics\nMetrics is a module that serves a /metrics endpoint so that any gathered\nmetrics can be exposed for scraping. This module is configurable by end-users\nunlike AdminMetrics.\n\n",
"markdownDescription":"metrics: `object` \nModule: `http.handlers.metrics` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/metrics#Metrics) \nMetrics is a module that serves a /metrics endpoint so that any gathered\nmetrics can be exposed for scraping. This module is configurable by end-users\nunlike AdminMetrics.\n \n",
"type":"object",
"properties":{
"disable_openmetrics":{
"description":"disable_openmetrics: boolean\nModule: http.handlers.metrics\nDisable OpenMetrics negotiation, enabled by default. May be necessary if\nthe produced metrics cannot be parsed by the service scraping metrics.\n",
"markdownDescription":"disable_openmetrics: `boolean` \nModule: `http.handlers.metrics` \nDisable OpenMetrics negotiation, enabled by default. May be necessary if\nthe produced metrics cannot be parsed by the service scraping metrics. \n",
"description":"push: object\nModule: http.handlers.push\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#Handler\nHandler is a middleware for HTTP/2 server push. Note that\nHTTP/2 server push has been deprecated by some clients and\nits use is discouraged unless you can accurately predict\nwhich resources actually need to be pushed to the client;\nit can be difficult to know what the client already has\ncached. Pushing unnecessary resources results in worse\nperformance. Consider using HTTP 103 Early Hints instead.\n\nThis handler supports pushing from Link headers; in other\nwords, if the eventual response has Link headers, this\nhandler will push the resources indicated by those headers,\neven without specifying any resources in its config.\n\n",
"markdownDescription":"push: `object` \nModule: `http.handlers.push` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#Handler) \nHandler is a middleware for HTTP/2 server push. Note that\nHTTP/2 server push has been deprecated by some clients and\nits use is discouraged unless you can accurately predict\nwhich resources actually need to be pushed to the client;\nit can be difficult to know what the client already has\ncached. Pushing unnecessary resources results in worse\nperformance. Consider using HTTP 103 Early Hints instead.\n\nThis handler supports pushing from Link headers; in other\nwords, if the eventual response has Link headers, this\nhandler will push the resources indicated by those headers,\neven without specifying any resources in its config.\n \n",
"description":"headers: object\nModule: http.handlers.push\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#HeaderConfig\nHeaders to modify for the push requests.\n\n\nHeaderConfig configures headers for synthetic push requests.\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.push` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#HeaderConfig) \nHeaders to modify for the push requests.\n\n\nHeaderConfig configures headers for synthetic push requests. \n",
"description":"delete: array\nModule: http.handlers.push\nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"delete: `array` \nModule: `http.handlers.push` \nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"replace: object\nModule: http.handlers.push\nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields.\n",
"markdownDescription":"replace: `object` \nModule: `http.handlers.push` \nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields. \n",
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"object",
"properties":{
"replace":{
"description":"replace: string\nModule: http.handlers.push\nThe string with which to replace matches.\n",
"markdownDescription":"replace: `string` \nModule: `http.handlers.push` \nThe string with which to replace matches. \n",
"type":"string"
},
"search":{
"description":"search: string\nModule: http.handlers.push\nThe substring to search for.\n",
"markdownDescription":"search: `string` \nModule: `http.handlers.push` \nThe substring to search for. \n",
"type":"string"
},
"search_regexp":{
"description":"search_regexp: string\nModule: http.handlers.push\nThe regular expression to search with.\n",
"description":"resources: array\nModule: http.handlers.push\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#Resource\nThe resources to push.\n\n\nResource represents a request for a resource to push.\n",
"markdownDescription":"resources: `array` \nModule: `http.handlers.push` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#Resource) \nThe resources to push.\n\n\nResource represents a request for a resource to push. \n",
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#Resource\nThe resources to push.\n\n\nResource represents a request for a resource to push.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/push#Resource) \nThe resources to push.\n\n\nResource represents a request for a resource to push. \n",
"description":"method: string\nModule: http.handlers.push\nMethod is the request method, which must be GET or HEAD.\nDefault is GET.\n",
"markdownDescription":"method: `string` \nModule: `http.handlers.push` \nMethod is the request method, which must be GET or HEAD.\nDefault is GET. \n",
"type":"string"
},
"target":{
"description":"target: string\nModule: http.handlers.push\nTarget is the path to the resource being pushed.\n",
"markdownDescription":"target: `string` \nModule: `http.handlers.push` \nTarget is the path to the resource being pushed. \n",
"description":"rate_limit: object\nModule: http.handlers.rate_limit\nhttps://pkg.go.dev/github.com/RussellLuo/caddy-ext/ratelimit#RateLimit\nRateLimit implements a handler for rate-limiting.\n\nIf a client exceeds the rate limit, an HTTP error with status `\u003creject_status\u003e` will\nbe returned. This error can be handled using the conventional error handlers.\nSee [handle_errors](https://caddyserver.com/docs/caddyfile/directives/handle_errors)\nfor how to set up error handlers.\n\n",
"markdownDescription":"rate_limit: `object` \nModule: `http.handlers.rate_limit` \n[godoc](https://pkg.go.dev/github.com/RussellLuo/caddy-ext/ratelimit#RateLimit) \nRateLimit implements a handler for rate-limiting.\n\nIf a client exceeds the rate limit, an HTTP error with status `\u003creject_status\u003e` will\nbe returned. This error can be handled using the conventional error handlers.\nSee [handle_errors](https://caddyserver.com/docs/caddyfile/directives/handle_errors)\nfor how to set up error handlers.\n \n",
"description":"request_body: object\nModule: http.handlers.request_body\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/requestbody#RequestBody\nRequestBody is a middleware for manipulating the request body.\n\n",
"markdownDescription":"request_body: `object` \nModule: `http.handlers.request_body` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/requestbody#RequestBody) \nRequestBody is a middleware for manipulating the request body.\n \n",
"type":"object",
"properties":{
"max_size":{
"description":"max_size: number\nModule: http.handlers.request_body\nThe maximum number of bytes to allow reading from the body by a later handler.\nIf more bytes are read, an error with HTTP status 413 is returned.\n",
"markdownDescription":"max_size: `number` \nModule: `http.handlers.request_body` \nThe maximum number of bytes to allow reading from the body by a later handler.\nIf more bytes are read, an error with HTTP status 413 is returned. \n",
"type":"number"
}
}
},
"http.handlers.reverse_proxy":{
"description":"reverse_proxy: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#Handler\nHandler implements a highly configurable and production-ready reverse proxy.\n\nUpon proxying, this module sets the following placeholders (which can be used\nboth within and after this handler; for example, in response headers):\n\nPlaceholder | Description\n------------|-------------\n`{http.reverse_proxy.upstream.address}` | The full address to the upstream as given in the config\n`{http.reverse_proxy.upstream.hostport}` | The host:port of the upstream\n`{http.reverse_proxy.upstream.host}` | The host of the upstream\n`{http.reverse_proxy.upstream.port}` | The port of the upstream\n`{http.reverse_proxy.upstream.requests}` | The approximate current number of requests to the upstream\n`{http.reverse_proxy.upstream.max_requests}` | The maximum approximate number of requests allowed to the upstream\n`{http.reverse_proxy.upstream.fails}` | The number of recent failed requests to the upstream\n`{http.reverse_proxy.upstream.latency}` | How long it took the proxy upstream to write the response header.\n`{http.reverse_proxy.upstream.latency_ms}` | Same as 'latency', but in milliseconds.\n`{http.reverse_proxy.upstream.duration}` | Time spent proxying to the upstream, including writing response body to client.\n`{http.reverse_proxy.upstream.duration_ms}` | Same as 'upstream.duration', but in milliseconds.\n`{http.reverse_proxy.duration}` | Total time spent proxying, including selecting an upstream, retries, and writing response.\n`{http.reverse_proxy.duration_ms}` | Same as 'duration', but in milliseconds.\n\n",
"markdownDescription":"reverse_proxy: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#Handler) \nHandler implements a highly configurable and production-ready reverse proxy.\n\nUpon proxying, this module sets the following placeholders (which can be used\nboth within and after this handler; for example, in response headers):\n\nPlaceholder | Description\n------------|-------------\n`{http.reverse_proxy.upstream.address}` | The full address to the upstream as given in the config\n`{http.reverse_proxy.upstream.hostport}` | The host:port of the upstream\n`{http.reverse_proxy.upstream.host}` | The host of the upstream\n`{http.reverse_proxy.upstream.port}` | The port of the upstream\n`{http.reverse_proxy.upstream.requests}` | The approximate current number of requests to the upstream\n`{http.reverse_proxy.upstream.max_requests}` | The maximum approximate number of requests allowed to the upstream\n`{http.reverse_proxy.upstream.fails}` | The number of recent failed requests to the upstream\n`{http.reverse_proxy.upstream.latency}` | How long it took the proxy upstream to write the response header.\n`{http.reverse_proxy.upstream.latency_ms}` | Same as 'latency', but in milliseconds.\n`{http.reverse_proxy.upstream.duration}` | Time spent proxying to the upstream, including writing response body to client.\n`{http.reverse_proxy.upstream.duration_ms}` | Same as 'upstream.duration', but in milliseconds.\n`{http.reverse_proxy.duration}` | Total time spent proxying, including selecting an upstream, retries, and writing response.\n`{http.reverse_proxy.duration_ms}` | Same as 'duration', but in milliseconds.\n \n",
"type":"object",
"properties":{
"buffer_requests":{
"description":"buffer_requests: boolean\nModule: http.handlers.reverse_proxy\nIf true, the entire request body will be read and buffered\nin memory before being proxied to the backend. This should\nbe avoided if at all possible for performance reasons, but\ncould be useful if the backend is intolerant of read latency.\n",
"markdownDescription":"buffer_requests: `boolean` \nModule: `http.handlers.reverse_proxy` \nIf true, the entire request body will be read and buffered\nin memory before being proxied to the backend. This should\nbe avoided if at all possible for performance reasons, but\ncould be useful if the backend is intolerant of read latency. \n",
"type":"boolean"
},
"buffer_responses":{
"description":"buffer_responses: boolean\nModule: http.handlers.reverse_proxy\nIf true, the entire response body will be read and buffered\nin memory before being proxied to the client. This should\nbe avoided if at all possible for performance reasons, but\ncould be useful if the backend has tighter memory constraints.\n",
"markdownDescription":"buffer_responses: `boolean` \nModule: `http.handlers.reverse_proxy` \nIf true, the entire response body will be read and buffered\nin memory before being proxied to the client. This should\nbe avoided if at all possible for performance reasons, but\ncould be useful if the backend has tighter memory constraints. \n",
"type":"boolean"
},
"circuit_breaker":{
"description":"circuit_breaker: any\nModule: http.reverse_proxy.circuit_breakers\nA circuit breaker may be used to relieve pressure on a backend\nthat is beginning to exhibit symptoms of stress or latency.\nBy default, there is no circuit breaker.\n",
"markdownDescription":"circuit_breaker: `any` \nModule: `http.reverse_proxy.circuit_breakers` \nA circuit breaker may be used to relieve pressure on a backend\nthat is beginning to exhibit symptoms of stress or latency.\nBy default, there is no circuit breaker. \n"
},
"dynamic_upstreams":{
"description":"dynamic_upstreams: object\nModule: http.reverse_proxy.upstreams\nA module for retrieving the list of upstreams dynamically. Dynamic\nupstreams are retrieved at every iteration of the proxy loop for\neach request (i.e. before every proxy attempt within every request).\nActive health checks do not work on dynamic upstreams, and passive\nhealth checks are only effective on dynamic upstreams if the proxy\nserver is busy enough that concurrent requests to the same backends\nare continuous. Instead of health checks for dynamic upstreams, it\nis recommended that the dynamic upstream module only return available\nbackends in the first place.\n",
"markdownDescription":"dynamic_upstreams: `object` \nModule: `http.reverse_proxy.upstreams` \nA module for retrieving the list of upstreams dynamically. Dynamic\nupstreams are retrieved at every iteration of the proxy loop for\neach request (i.e. before every proxy attempt within every request).\nActive health checks do not work on dynamic upstreams, and passive\nhealth checks are only effective on dynamic upstreams if the proxy\nserver is busy enough that concurrent requests to the same backends\nare continuous. Instead of health checks for dynamic upstreams, it\nis recommended that the dynamic upstream module only return available\nbackends in the first place. \n",
"description":"flush_interval: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nAdjusts how often to flush the response buffer. By default,\nno periodic flushing is done. A negative value disables\nresponse buffering, and flushes immediately after each\nwrite to the client. This option is ignored when the upstream's\nresponse is recognized as a streaming response, or if its\ncontent length is -1; for such responses, writes are flushed\nto the client immediately.\n\nNormally, a request will be canceled if the client disconnects\nbefore the response is received from the backend. If explicitly\nset to -1, client disconnection will be ignored and the request\nwill be completed to help facilitate low-latency streaming.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"flush_interval: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nAdjusts how often to flush the response buffer. By default,\nno periodic flushing is done. A negative value disables\nresponse buffering, and flushes immediately after each\nwrite to the client. This option is ignored when the upstream's\nresponse is recognized as a streaming response, or if its\ncontent length is -1; for such responses, writes are flushed\nto the client immediately.\n\nNormally, a request will be canceled if the client disconnects\nbefore the response is received from the backend. If explicitly\nset to -1, client disconnection will be ignored and the request\nwill be completed to help facilitate low-latency streaming.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"handle_response: array\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseHandler\nList of handlers and their associated matchers to evaluate\nafter successful roundtrips. The first handler that matches\nthe response from a backend will be invoked. The response\nbody from the backend will not be written to the client;\nit is up to the handler to finish handling the response.\nIf passive health checks are enabled, any errors from the\nhandler chain will not affect the health status of the\nbackend.\n\nThree new placeholders are available in this handler chain:\n- `{http.reverse_proxy.status_code}` The status code from the response\n- `{http.reverse_proxy.status_text}` The status text from the response\n- `{http.reverse_proxy.header.*}` The headers from the response\n\n\nResponseHandler pairs a response matcher with custom handling\nlogic. Either the status code can be changed to something else\nwhile using the original response body, or, if a status code\nis not set, it can execute a custom route list; this is useful\nfor executing handler routes based on the properties of an HTTP\nresponse that has not been written out to the client yet.\n\nTo use this type, provision it at module load time, then when\nready to use, match the response against its matcher; if it\nmatches (or doesn't have a matcher), change the status code on\nthe response if configured; otherwise invoke the routes by\ncalling `rh.Routes.Compile(next).ServeHTTP(rw, req)` (or similar).\n",
"markdownDescription":"handle_response: `array` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseHandler) \nList of handlers and their associated matchers to evaluate\nafter successful roundtrips. The first handler that matches\nthe response from a backend will be invoked. The response\nbody from the backend will not be written to the client;\nit is up to the handler to finish handling the response.\nIf passive health checks are enabled, any errors from the\nhandler chain will not affect the health status of the\nbackend.\n\nThree new placeholders are available in this handler chain:\n- `{http.reverse_proxy.status_code}` The status code from the response\n- `{http.reverse_proxy.status_text}` The status text from the response\n- `{http.reverse_proxy.header.*}` The headers from the response\n\n\nResponseHandler pairs a response matcher with custom handling\nlogic. Either the status code can be changed to something else\nwhile using the original response body, or, if a status code\nis not set, it can execute a custom route list; this is useful\nfor executing handler routes based on the properties of an HTTP\nresponse that has not been written out to the client yet.\n\nTo use this type, provision it at module load time, then when\nready to use, match the response against its matcher; if it\nmatches (or doesn't have a matcher), change the status code on\nthe response if configured; otherwise invoke the routes by\ncalling `rh.Routes.Compile(next).ServeHTTP(rw, req)` (or similar). \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseHandler\nList of handlers and their associated matchers to evaluate\nafter successful roundtrips. The first handler that matches\nthe response from a backend will be invoked. The response\nbody from the backend will not be written to the client;\nit is up to the handler to finish handling the response.\nIf passive health checks are enabled, any errors from the\nhandler chain will not affect the health status of the\nbackend.\n\nThree new placeholders are available in this handler chain:\n- `{http.reverse_proxy.status_code}` The status code from the response\n- `{http.reverse_proxy.status_text}` The status text from the response\n- `{http.reverse_proxy.header.*}` The headers from the response\n\n\nResponseHandler pairs a response matcher with custom handling\nlogic. Either the status code can be changed to something else\nwhile using the original response body, or, if a status code\nis not set, it can execute a custom route list; this is useful\nfor executing handler routes based on the properties of an HTTP\nresponse that has not been written out to the client yet.\n\nTo use this type, provision it at module load time, then when\nready to use, match the response against its matcher; if it\nmatches (or doesn't have a matcher), change the status code on\nthe response if configured; otherwise invoke the routes by\ncalling `rh.Routes.Compile(next).ServeHTTP(rw, req)` (or similar).\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseHandler) \nList of handlers and their associated matchers to evaluate\nafter successful roundtrips. The first handler that matches\nthe response from a backend will be invoked. The response\nbody from the backend will not be written to the client;\nit is up to the handler to finish handling the response.\nIf passive health checks are enabled, any errors from the\nhandler chain will not affect the health status of the\nbackend.\n\nThree new placeholders are available in this handler chain:\n- `{http.reverse_proxy.status_code}` The status code from the response\n- `{http.reverse_proxy.status_text}` The status text from the response\n- `{http.reverse_proxy.header.*}` The headers from the response\n\n\nResponseHandler pairs a response matcher with custom handling\nlogic. Either the status code can be changed to something else\nwhile using the original response body, or, if a status code\nis not set, it can execute a custom route list; this is useful\nfor executing handler routes based on the properties of an HTTP\nresponse that has not been written out to the client yet.\n\nTo use this type, provision it at module load time, then when\nready to use, match the response against its matcher; if it\nmatches (or doesn't have a matcher), change the status code on\nthe response if configured; otherwise invoke the routes by\ncalling `rh.Routes.Compile(next).ServeHTTP(rw, req)` (or similar). \n",
"type":"object",
"properties":{
"match":{
"description":"match: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher\nThe response matcher for this handler. If empty/nil,\nit always matches.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria.\n",
"markdownDescription":"match: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher) \nThe response matcher for this handler. If empty/nil,\nit always matches.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria. \n",
"type":"object",
"properties":{
"headers":{
"description":"headers: object\nModule: http.handlers.reverse_proxy\nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.reverse_proxy` \nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"object",
"additionalProperties":{
"description":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"status_code":{
"description":"status_code: array\nModule: http.handlers.reverse_proxy\nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"status_code: `array` \nModule: `http.handlers.reverse_proxy` \nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"type":"array",
"items":{
"description":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"type":"number"
}
}
}
},
"routes":{
"description":"routes: array\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe list of HTTP routes to execute if no status code is\nspecified. If evaluated, the original response body\nwill not be written.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"routes: `array` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe list of HTTP routes to execute if no status code is\nspecified. If evaluated, the original response body\nwill not be written.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe list of HTTP routes to execute if no status code is\nspecified. If evaluated, the original response body\nwill not be written.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe list of HTTP routes to execute if no status code is\nspecified. If evaluated, the original response body\nwill not be written.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"object",
"properties":{
"group":{
"description":"group: string\nModule: http.handlers.reverse_proxy\nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed.\n",
"markdownDescription":"group: `string` \nModule: `http.handlers.reverse_proxy` \nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed. \n",
"type":"string"
},
"handle":{
"description":"handle: array\nModule: http.handlers\nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"handle: `array` \nModule: `http.handlers` \nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"type":"array",
"items":{
"description":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"description":"match: array\nModule: http.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `array` \nModule: `http.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"terminal: boolean\nModule: http.handlers.reverse_proxy\nIf true, no more routes will be executed after this one.\n",
"markdownDescription":"terminal: `boolean` \nModule: `http.handlers.reverse_proxy` \nIf true, no more routes will be executed after this one. \n",
"type":"boolean"
}
}
}
},
"status_code":{
"description":"status_code: string\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString\nTo write the original response body but with a different\nstatus code, set this field to the desired status code.\nIf set, this takes priority over routes.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned.\n",
"markdownDescription":"status_code: `string` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString) \nTo write the original response body but with a different\nstatus code, set this field to the desired status code.\nIf set, this takes priority over routes.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned. \n",
"type":"string"
}
}
}
},
"headers":{
"description":"headers: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Handler\nHeaders manipulates headers between Caddy and the backend.\nBy default, all headers are passed-thru without changes,\nwith the exceptions of special hop-by-hop headers.\n\nX-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host\nare also set implicitly.\n\n\nHandler is a middleware which modifies request and response headers.\n\nChanges to headers are applied immediately, except for the response\nheaders when Deferred is true or when Required is set. In those cases,\nthe changes are applied when the headers are written to the response.\nNote that deferred changes do not take effect if an error occurs later\nin the middleware chain.\n\nProperties in this module accept placeholders.\n\nResponse header operations can be conditioned upon response status code\nand/or other header values.\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Handler) \nHeaders manipulates headers between Caddy and the backend.\nBy default, all headers are passed-thru without changes,\nwith the exceptions of special hop-by-hop headers.\n\nX-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host\nare also set implicitly.\n\n\nHandler is a middleware which modifies request and response headers.\n\nChanges to headers are applied immediately, except for the response\nheaders when Deferred is true or when Required is set. In those cases,\nthe changes are applied when the headers are written to the response.\nNote that deferred changes do not take effect if an error occurs later\nin the middleware chain.\n\nProperties in this module accept placeholders.\n\nResponse header operations can be conditioned upon response status code\nand/or other header values. \n",
"type":"object",
"properties":{
"request":{
"description":"request: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#HeaderOps\nHeaderOps defines manipulations for HTTP headers.\n\n",
"description":"delete: array\nModule: http.handlers.reverse_proxy\nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"delete: `array` \nModule: `http.handlers.reverse_proxy` \nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"replace: object\nModule: http.handlers.reverse_proxy\nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields.\n",
"markdownDescription":"replace: `object` \nModule: `http.handlers.reverse_proxy` \nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields. \n",
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"object",
"properties":{
"replace":{
"description":"replace: string\nModule: http.handlers.reverse_proxy\nThe string with which to replace matches.\n",
"markdownDescription":"replace: `string` \nModule: `http.handlers.reverse_proxy` \nThe string with which to replace matches. \n",
"type":"string"
},
"search":{
"description":"search: string\nModule: http.handlers.reverse_proxy\nThe substring to search for.\n",
"markdownDescription":"search: `string` \nModule: `http.handlers.reverse_proxy` \nThe substring to search for. \n",
"type":"string"
},
"search_regexp":{
"description":"search_regexp: string\nModule: http.handlers.reverse_proxy\nThe regular expression to search with.\n",
"description":"add: object\nModule: http.handlers.reverse_proxy\nAdds HTTP headers; does not replace any existing header fields.\n",
"markdownDescription":"add: `object` \nModule: `http.handlers.reverse_proxy` \nAdds HTTP headers; does not replace any existing header fields. \n",
"type":"object",
"additionalProperties":{
"description":"Adds HTTP headers; does not replace any existing header fields.\n",
"markdownDescription":"Adds HTTP headers; does not replace any existing header fields. \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"deferred":{
"description":"deferred: boolean\nModule: http.handlers.reverse_proxy\nIf true, header operations will be deferred until\nthey are written out. Superceded if Require is set.\nUsually you will need to set this to true if any\nfields are being deleted.\n",
"markdownDescription":"deferred: `boolean` \nModule: `http.handlers.reverse_proxy` \nIf true, header operations will be deferred until\nthey are written out. Superceded if Require is set.\nUsually you will need to set this to true if any\nfields are being deleted. \n",
"description":"delete: array\nModule: http.handlers.reverse_proxy\nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"delete: `array` \nModule: `http.handlers.reverse_proxy` \nNames of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring.\n",
"markdownDescription":"Names of HTTP header fields to delete. Basic wildcards are supported:\n\n- Start with `*` for all field names with the given suffix;\n- End with `*` for all field names with the given prefix;\n- Start and end with `*` for all field names containing a substring. \n",
"description":"replace: object\nModule: http.handlers.reverse_proxy\nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields.\n",
"markdownDescription":"replace: `object` \nModule: `http.handlers.reverse_proxy` \nPerforms in-situ substring replacements of HTTP headers.\nKeys are the field names on which to perform the associated replacements.\nIf the field name is `*`, the replacements are performed on all header fields. \n",
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement\nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/headers#Replacement) \nReplacement describes a string replacement,\neither a simple and fast substring search\nor a slower but more powerful regex search.\n \n",
"type":"object",
"properties":{
"replace":{
"description":"replace: string\nModule: http.handlers.reverse_proxy\nThe string with which to replace matches.\n",
"markdownDescription":"replace: `string` \nModule: `http.handlers.reverse_proxy` \nThe string with which to replace matches. \n",
"type":"string"
},
"search":{
"description":"search: string\nModule: http.handlers.reverse_proxy\nThe substring to search for.\n",
"markdownDescription":"search: `string` \nModule: `http.handlers.reverse_proxy` \nThe substring to search for. \n",
"type":"string"
},
"search_regexp":{
"description":"search_regexp: string\nModule: http.handlers.reverse_proxy\nThe regular expression to search with.\n",
"description":"require: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher\nIf set, header operations will be deferred until\nthey are written out and only performed if the\nresponse matches these criteria.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria.\n",
"markdownDescription":"require: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#ResponseMatcher) \nIf set, header operations will be deferred until\nthey are written out and only performed if the\nresponse matches these criteria.\n\n\nResponseMatcher is a type which can determine if an\nHTTP response matches some criteria. \n",
"type":"object",
"properties":{
"headers":{
"description":"headers: object\nModule: http.handlers.reverse_proxy\nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.reverse_proxy` \nIf set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"object",
"additionalProperties":{
"description":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/).\n",
"markdownDescription":"If set, each header specified must be one of the\nspecified values, with the same logic used by the\n[request header matcher](/docs/json/apps/http/servers/routes/match/header/). \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"status_code":{
"description":"status_code: array\nModule: http.handlers.reverse_proxy\nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"status_code: `array` \nModule: `http.handlers.reverse_proxy` \nIf set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"type":"array",
"items":{
"description":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes).\n",
"markdownDescription":"If set, one of these status codes would be required.\nA one-digit status can be used to represent all codes\nin that class (e.g. 3 for all 3xx codes). \n",
"description":"health_checks: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#HealthChecks\nHealth checks update the status of backends, whether they are\nup or down. Down backends will not be proxied to.\n\n\nHealthChecks configures active and passive health checks.\n",
"markdownDescription":"health_checks: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#HealthChecks) \nHealth checks update the status of backends, whether they are\nup or down. Down backends will not be proxied to.\n\n\nHealthChecks configures active and passive health checks. \n",
"type":"object",
"properties":{
"active":{
"description":"active: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#ActiveHealthChecks\nActive health checks run in the background on a timer. To\nminimally enable active health checks, set either path or\nport (or both). Note that active health check status\n(healthy/unhealthy) is stored per-proxy-handler, not\nglobally; this allows different handlers to use different\ncriteria to decide what defines a healthy backend.\n\nActive health checks do not run for dynamic upstreams.\n\n\nActiveHealthChecks holds configuration related to active\nhealth checks (that is, health checks which occur in a\nbackground goroutine independently).\n",
"markdownDescription":"active: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#ActiveHealthChecks) \nActive health checks run in the background on a timer. To\nminimally enable active health checks, set either path or\nport (or both). Note that active health check status\n(healthy/unhealthy) is stored per-proxy-handler, not\nglobally; this allows different handlers to use different\ncriteria to decide what defines a healthy backend.\n\nActive health checks do not run for dynamic upstreams.\n\n\nActiveHealthChecks holds configuration related to active\nhealth checks (that is, health checks which occur in a\nbackground goroutine independently). \n",
"type":"object",
"properties":{
"expect_body":{
"description":"expect_body: string\nModule: http.handlers.reverse_proxy\nA regular expression against which to match the response\nbody of a healthy backend.\n",
"markdownDescription":"expect_body: `string` \nModule: `http.handlers.reverse_proxy` \nA regular expression against which to match the response\nbody of a healthy backend. \n",
"type":"string"
},
"expect_status":{
"description":"expect_status: number\nModule: http.handlers.reverse_proxy\nThe HTTP status code to expect from a healthy backend.\n",
"markdownDescription":"expect_status: `number` \nModule: `http.handlers.reverse_proxy` \nThe HTTP status code to expect from a healthy backend. \n",
"type":"number"
},
"headers":{
"description":"headers: object\nModule: http.handlers.reverse_proxy\nHTTP headers to set on health check requests.\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.reverse_proxy` \nHTTP headers to set on health check requests. \n",
"type":"object",
"additionalProperties":{
"description":"HTTP headers to set on health check requests.\n",
"markdownDescription":"HTTP headers to set on health check requests. \n",
"type":"array",
"items":{
"type":"string"
}
}
},
"interval":{
"description":"interval: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow frequently to perform active health checks (default 30s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"interval: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow frequently to perform active health checks (default 30s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"max_size":{
"description":"max_size: number\nModule: http.handlers.reverse_proxy\nThe maximum response body to download from the backend\nduring a health check.\n",
"markdownDescription":"max_size: `number` \nModule: `http.handlers.reverse_proxy` \nThe maximum response body to download from the backend\nduring a health check. \n",
"type":"number"
},
"path":{
"description":"path: string\nModule: http.handlers.reverse_proxy\nDEPRECATED: Use 'uri' instead. This field will be removed. TODO: remove this field\n",
"markdownDescription":"path: `string` \nModule: `http.handlers.reverse_proxy` \nDEPRECATED: Use 'uri' instead. This field will be removed. TODO: remove this field \n",
"type":"string"
},
"port":{
"description":"port: number\nModule: http.handlers.reverse_proxy\nThe port to use (if different from the upstream's dial\naddress) for health checks.\n",
"markdownDescription":"port: `number` \nModule: `http.handlers.reverse_proxy` \nThe port to use (if different from the upstream's dial\naddress) for health checks. \n",
"type":"number"
},
"timeout":{
"description":"timeout: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait for a response from a backend before\nconsidering it unhealthy (default 5s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"timeout: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait for a response from a backend before\nconsidering it unhealthy (default 5s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"uri":{
"description":"uri: string\nModule: http.handlers.reverse_proxy\nThe URI (path and query) to use for health checks\n",
"markdownDescription":"uri: `string` \nModule: `http.handlers.reverse_proxy` \nThe URI (path and query) to use for health checks \n",
"type":"string"
}
}
},
"passive":{
"description":"passive: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#PassiveHealthChecks\nPassive health checks monitor proxied requests for errors or timeouts.\nTo minimally enable passive health checks, specify at least an empty\nconfig object. Passive health check state is shared (stored globally),\nso a failure from one handler will be counted by all handlers; but\nthe tolerances or standards for what defines healthy/unhealthy backends\nis configured per-proxy-handler.\n\nPassive health checks technically do operate on dynamic upstreams,\nbut are only effective for very busy proxies where the list of\nupstreams is mostly stable. This is because the shared/global\nstate of upstreams is cleaned up when the upstreams are no longer\nused. Since dynamic upstreams are allocated dynamically at each\nrequest (specifically, each iteration of the proxy loop per request),\nthey are also cleaned up after every request. Thus, if there is a\nmoment when no requests are actively referring to a particular\nupstream host, the passive health check state will be reset because\nit will be garbage-collected. It is usually better for the dynamic\nupstream module to only return healthy, available backends instead.\n\n\nPassiveHealthChecks holds configuration related to passive\nhealth checks (that is, health checks which occur during\nthe normal flow of request proxying).\n",
"markdownDescription":"passive: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#PassiveHealthChecks) \nPassive health checks monitor proxied requests for errors or timeouts.\nTo minimally enable passive health checks, specify at least an empty\nconfig object. Passive health check state is shared (stored globally),\nso a failure from one handler will be counted by all handlers; but\nthe tolerances or standards for what defines healthy/unhealthy backends\nis configured per-proxy-handler.\n\nPassive health checks technically do operate on dynamic upstreams,\nbut are only effective for very busy proxies where the list of\nupstreams is mostly stable. This is because the shared/global\nstate of upstreams is cleaned up when the upstreams are no longer\nused. Since dynamic upstreams are allocated dynamically at each\nrequest (specifically, each iteration of the proxy loop per request),\nthey are also cleaned up after every request. Thus, if there is a\nmoment when no requests are actively referring to a particular\nupstream host, the passive health check state will be reset because\nit will be garbage-collected. It is usually better for the dynamic\nupstream module to only return healthy, available backends instead.\n\n\nPassiveHealthChecks holds configuration related to passive\nhealth checks (that is, health checks which occur during\nthe normal flow of request proxying). \n",
"type":"object",
"properties":{
"fail_duration":{
"description":"fail_duration: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to remember a failed request to a backend. A duration \u003e 0\nenables passive health checking. Default is 0.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"fail_duration: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to remember a failed request to a backend. A duration \u003e 0\nenables passive health checking. Default is 0.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"max_fails":{
"description":"max_fails: number\nModule: http.handlers.reverse_proxy\nThe number of failed requests within the FailDuration window to\nconsider a backend as \"down\". Must be \u003e= 1; default is 1. Requires\nthat FailDuration be \u003e 0.\n",
"markdownDescription":"max_fails: `number` \nModule: `http.handlers.reverse_proxy` \nThe number of failed requests within the FailDuration window to\nconsider a backend as \"down\". Must be \u003e= 1; default is 1. Requires\nthat FailDuration be \u003e 0. \n",
"type":"number"
},
"unhealthy_latency":{
"description":"unhealthy_latency: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nCount the request as failed if the response takes at least this\nlong to receive.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"unhealthy_latency: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nCount the request as failed if the response takes at least this\nlong to receive.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"unhealthy_request_count":{
"description":"unhealthy_request_count: number\nModule: http.handlers.reverse_proxy\nLimits the number of simultaneous requests to a backend by\nmarking the backend as \"down\" if it has this many concurrent\nrequests or more.\n",
"markdownDescription":"unhealthy_request_count: `number` \nModule: `http.handlers.reverse_proxy` \nLimits the number of simultaneous requests to a backend by\nmarking the backend as \"down\" if it has this many concurrent\nrequests or more. \n",
"type":"number"
},
"unhealthy_status":{
"description":"unhealthy_status: array\nModule: http.handlers.reverse_proxy\nCount the request as failed if the response comes back with\none of these status codes.\n",
"markdownDescription":"unhealthy_status: `array` \nModule: `http.handlers.reverse_proxy` \nCount the request as failed if the response comes back with\none of these status codes. \n",
"type":"array",
"items":{
"description":"Count the request as failed if the response comes back with\none of these status codes.\n",
"markdownDescription":"Count the request as failed if the response comes back with\none of these status codes. \n",
"type":"number"
}
}
}
}
}
},
"load_balancing":{
"description":"load_balancing: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#LoadBalancing\nLoad balancing distributes load/requests between backends.\n\n\nLoadBalancing has parameters related to load balancing.\n",
"markdownDescription":"load_balancing: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#LoadBalancing) \nLoad balancing distributes load/requests between backends.\n\n\nLoadBalancing has parameters related to load balancing. \n",
"description":"retries: number\nModule: http.handlers.reverse_proxy\nHow many times to retry selecting available backends for each\nrequest if the next available host is down. If try_duration is\nalso configured, then retries may stop early if the duration\nis reached. By default, retries are disabled (zero).\n",
"markdownDescription":"retries: `number` \nModule: `http.handlers.reverse_proxy` \nHow many times to retry selecting available backends for each\nrequest if the next available host is down. If try_duration is\nalso configured, then retries may stop early if the duration\nis reached. By default, retries are disabled (zero). \n",
"description":"retry_match: array\nModule: http.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nA list of matcher sets that restricts with which requests retries are\nallowed. A request must match any of the given matcher sets in order\nto be retried if the connection to the upstream succeeded but the\nsubsequent round-trip failed. If the connection to the upstream failed,\na retry is always allowed. If unspecified, only GET requests will be\nallowed to be retried. Note that a retry is done with the next available\nhost according to the load balancing policy.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"retry_match: `array` \nModule: `http.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nA list of matcher sets that restricts with which requests retries are\nallowed. A request must match any of the given matcher sets in order\nto be retried if the connection to the upstream succeeded but the\nsubsequent round-trip failed. If the connection to the upstream failed,\na retry is always allowed. If unspecified, only GET requests will be\nallowed to be retried. Note that a retry is done with the next available\nhost according to the load balancing policy.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nA list of matcher sets that restricts with which requests retries are\nallowed. A request must match any of the given matcher sets in order\nto be retried if the connection to the upstream succeeded but the\nsubsequent round-trip failed. If the connection to the upstream failed,\na retry is always allowed. If unspecified, only GET requests will be\nallowed to be retried. Note that a retry is done with the next available\nhost according to the load balancing policy.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nA list of matcher sets that restricts with which requests retries are\nallowed. A request must match any of the given matcher sets in order\nto be retried if the connection to the upstream succeeded but the\nsubsequent round-trip failed. If the connection to the upstream failed,\na retry is always allowed. If unspecified, only GET requests will be\nallowed to be retried. Note that a retry is done with the next available\nhost according to the load balancing policy.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"selection_policy: object\nModule: http.reverse_proxy.selection_policies\nA selection policy is how to choose an available backend.\nThe default policy is random selection.\n",
"markdownDescription":"selection_policy: `object` \nModule: `http.reverse_proxy.selection_policies` \nA selection policy is how to choose an available backend.\nThe default policy is random selection. \n",
"description":"try_duration: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to try selecting available backends for each request\nif the next available host is down. Clients will wait for up\nto this long while the load balancer tries to find an available\nupstream host. If retries is also configured, tries may stop\nearly if the maximum retries is reached. By default, retries\nare disabled (zero duration).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"try_duration: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to try selecting available backends for each request\nif the next available host is down. Clients will wait for up\nto this long while the load balancer tries to find an available\nupstream host. If retries is also configured, tries may stop\nearly if the maximum retries is reached. By default, retries\nare disabled (zero duration).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"try_interval: number\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait between selecting the next host from the pool.\nDefault is 250ms if try_duration is enabled, otherwise zero. Only\nrelevant when a request to an upstream host fails. Be aware that\nsetting this to 0 with a non-zero try_duration can cause the CPU\nto spin if all backends are down and latency is very low.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"try_interval: `number` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait between selecting the next host from the pool.\nDefault is 250ms if try_duration is enabled, otherwise zero. Only\nrelevant when a request to an upstream host fails. Be aware that\nsetting this to 0 with a non-zero try_duration can cause the CPU\nto spin if all backends are down and latency is very low.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"max_buffer_size: number\nModule: http.handlers.reverse_proxy\nIf body buffering is enabled, the maximum size of the buffers\nused for the requests and responses (in bytes).\n",
"markdownDescription":"max_buffer_size: `number` \nModule: `http.handlers.reverse_proxy` \nIf body buffering is enabled, the maximum size of the buffers\nused for the requests and responses (in bytes). \n",
"description":"rewrite: object\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#Rewrite\nIf configured, rewrites the copy of the upstream request.\nAllows changing the request method and URI (path and query).\nSince the rewrite is applied to the copy, it does not persist\npast the reverse proxy handler.\nIf the method is changed to `GET` or `HEAD`, the request body\nwill not be copied to the backend. This allows a later request\nhandler -- either in a `handle_response` route, or after -- to\nread the body.\nBy default, no rewrite is performed, and the method and URI\nfrom the incoming request is used as-is for proxying.\n\n\nRewrite is a middleware which can rewrite/mutate HTTP requests.\n\nThe Method and URI properties are \"setters\" (the request URI\nwill be overwritten with the given values). Other properties are\n\"modifiers\" (they modify existing values in a differentiable\nway). It is atypical to combine the use of setters and\nmodifiers in a single rewrite.\n\nTo ensure consistent behavior, prefix and suffix stripping is\nperformed in the URL-decoded (unescaped, normalized) space by\ndefault except for the specific bytes where an escape sequence\nis used in the prefix or suffix pattern.\n\nFor all modifiers, paths are cleaned before being modified so that\nmultiple, consecutive slashes are collapsed into a single slash,\nand dot elements are resolved and removed. In the special case\nof a prefix, suffix, or substring containing \"//\" (repeated slashes),\nslashes will not be merged while cleaning the path so that\nthe rewrite can be interpreted literally.\n",
"markdownDescription":"rewrite: `object` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#Rewrite) \nIf configured, rewrites the copy of the upstream request.\nAllows changing the request method and URI (path and query).\nSince the rewrite is applied to the copy, it does not persist\npast the reverse proxy handler.\nIf the method is changed to `GET` or `HEAD`, the request body\nwill not be copied to the backend. This allows a later request\nhandler -- either in a `handle_response` route, or after -- to\nread the body.\nBy default, no rewrite is performed, and the method and URI\nfrom the incoming request is used as-is for proxying.\n\n\nRewrite is a middleware which can rewrite/mutate HTTP requests.\n\nThe Method and URI properties are \"setters\" (the request URI\nwill be overwritten with the given values). Other properties are\n\"modifiers\" (they modify existing values in a differentiable\nway). It is atypical to combine the use of setters and\nmodifiers in a single rewrite.\n\nTo ensure consistent behavior, prefix and suffix stripping is\nperformed in the URL-decoded (unescaped, normalized) space by\ndefault except for the specific bytes where an escape sequence\nis used in the prefix or suffix pattern.\n\nFor all modifiers, paths are cleaned before being modified so that\nmultiple, consecutive slashes are collapsed into a single slash,\nand dot elements are resolved and removed. In the special case\nof a prefix, suffix, or substring containing \"//\" (repeated slashes),\nslashes will not be merged while cleaning the path so that\nthe rewrite can be interpreted literally. \n",
"description":"method: string\nModule: http.handlers.reverse_proxy\nChanges the request's HTTP verb.\n",
"markdownDescription":"method: `string` \nModule: `http.handlers.reverse_proxy` \nChanges the request's HTTP verb. \n",
"type":"string"
},
"path_regexp":{
"description":"path_regexp: array\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer\nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression.\n",
"markdownDescription":"path_regexp: `array` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer) \nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer\nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer) \nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression. \n",
"type":"object",
"properties":{
"find":{
"description":"find: string\nModule: http.handlers.reverse_proxy\nThe regular expression to find.\n",
"markdownDescription":"find: `string` \nModule: `http.handlers.reverse_proxy` \nThe regular expression to find. \n",
"description":"strip_path_prefix: string\nModule: http.handlers.reverse_proxy\nStrips the given prefix from the beginning of the URI path.\nThe prefix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match.\n",
"markdownDescription":"strip_path_prefix: `string` \nModule: `http.handlers.reverse_proxy` \nStrips the given prefix from the beginning of the URI path.\nThe prefix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match. \n",
"description":"strip_path_suffix: string\nModule: http.handlers.reverse_proxy\nStrips the given suffix from the end of the URI path.\nThe suffix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match.\n",
"markdownDescription":"strip_path_suffix: `string` \nModule: `http.handlers.reverse_proxy` \nStrips the given suffix from the end of the URI path.\nThe suffix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match. \n",
"description":"uri: string\nModule: http.handlers.reverse_proxy\nChanges the request's URI, which consists of path and query string.\nOnly components of the URI that are specified will be changed.\nFor example, a value of \"/foo.html\" or \"foo.html\" will only change\nthe path and will preserve any existing query string. Similarly, a\nvalue of \"?a=b\" will only change the query string and will not affect\nthe path. Both can also be changed: \"/foo?a=b\" - this sets both the\npath and query string at the same time.\n\nYou can also use placeholders. For example, to preserve the existing\nquery string, you might use: \"?{http.request.uri.query}\u0026a=b\". Any\nkey-value pairs you add to the query string will not overwrite\nexisting values (individual pairs are append-only).\n\nTo clear the query string, explicitly set an empty one: \"?\"\n",
"markdownDescription":"uri: `string` \nModule: `http.handlers.reverse_proxy` \nChanges the request's URI, which consists of path and query string.\nOnly components of the URI that are specified will be changed.\nFor example, a value of \"/foo.html\" or \"foo.html\" will only change\nthe path and will preserve any existing query string. Similarly, a\nvalue of \"?a=b\" will only change the query string and will not affect\nthe path. Both can also be changed: \"/foo?a=b\" - this sets both the\npath and query string at the same time.\n\nYou can also use placeholders. For example, to preserve the existing\nquery string, you might use: \"?{http.request.uri.query}\u0026a=b\". Any\nkey-value pairs you add to the query string will not overwrite\nexisting values (individual pairs are append-only).\n\nTo clear the query string, explicitly set an empty one: \"?\" \n",
"type":"string"
},
"uri_substring":{
"description":"uri_substring: array\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer\nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement.\n",
"markdownDescription":"uri_substring: `array` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer) \nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer\nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer) \nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement. \n",
"type":"object",
"properties":{
"find":{
"description":"find: string\nModule: http.handlers.reverse_proxy\nA substring to find. Supports placeholders.\n",
"description":"limit: number\nModule: http.handlers.reverse_proxy\nMaximum number of replacements per string.\nSet to \u003c= 0 for no limit (default).\n",
"markdownDescription":"limit: `number` \nModule: `http.handlers.reverse_proxy` \nMaximum number of replacements per string.\nSet to \u003c= 0 for no limit (default). \n",
"type":"number"
},
"replace":{
"description":"replace: string\nModule: http.handlers.reverse_proxy\nThe substring to replace with. Supports placeholders.\n",
"description":"transport: object\nModule: http.reverse_proxy.transport\nConfigures the method of transport for the proxy. A transport\nis what performs the actual \"round trip\" to the backend.\nThe default transport is plaintext HTTP.\n",
"markdownDescription":"transport: `object` \nModule: `http.reverse_proxy.transport` \nConfigures the method of transport for the proxy. A transport\nis what performs the actual \"round trip\" to the backend.\nThe default transport is plaintext HTTP. \n",
"description":"key to identify transport module.\nprotocol: string\nModule: http.reverse_proxy.transport",
"markdownDescription":"key to identify `transport` module. \nprotocol: `string` \nModule: `http.reverse_proxy.transport`",
"type":"string",
"enum":[
"fastcgi",
"http"
]
}
}
}
]
},
"trusted_proxies":{
"description":"trusted_proxies: array\nModule: http.handlers.reverse_proxy\nA list of IP ranges (supports CIDR notation) from which\nX-Forwarded-* header values should be trusted. By default,\nno proxies are trusted, so existing values will be ignored\nwhen setting these headers. If the proxy is trusted, then\nexisting values will be used when constructing the final\nheader values.\n",
"markdownDescription":"trusted_proxies: `array` \nModule: `http.handlers.reverse_proxy` \nA list of IP ranges (supports CIDR notation) from which\nX-Forwarded-* header values should be trusted. By default,\nno proxies are trusted, so existing values will be ignored\nwhen setting these headers. If the proxy is trusted, then\nexisting values will be used when constructing the final\nheader values. \n",
"type":"array",
"items":{
"description":"A list of IP ranges (supports CIDR notation) from which\nX-Forwarded-* header values should be trusted. By default,\nno proxies are trusted, so existing values will be ignored\nwhen setting these headers. If the proxy is trusted, then\nexisting values will be used when constructing the final\nheader values.\n",
"markdownDescription":"A list of IP ranges (supports CIDR notation) from which\nX-Forwarded-* header values should be trusted. By default,\nno proxies are trusted, so existing values will be ignored\nwhen setting these headers. If the proxy is trusted, then\nexisting values will be used when constructing the final\nheader values. \n",
"type":"string"
}
},
"upstreams":{
"description":"upstreams: array\nModule: http.handlers.reverse_proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#Upstream\nUpstreams is the static list of backends to proxy to.\n\n\nUpstream bridges this proxy's configuration to the\nstate of the backend host it is correlated with.\nUpstream values must not be copied.\n",
"markdownDescription":"upstreams: `array` \nModule: `http.handlers.reverse_proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#Upstream) \nUpstreams is the static list of backends to proxy to.\n\n\nUpstream bridges this proxy's configuration to the\nstate of the backend host it is correlated with.\nUpstream values must not be copied. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#Upstream\nUpstreams is the static list of backends to proxy to.\n\n\nUpstream bridges this proxy's configuration to the\nstate of the backend host it is correlated with.\nUpstream values must not be copied.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#Upstream) \nUpstreams is the static list of backends to proxy to.\n\n\nUpstream bridges this proxy's configuration to the\nstate of the backend host it is correlated with.\nUpstream values must not be copied. \n",
"type":"object",
"properties":{
"dial":{
"description":"dial: string\nModule: http.handlers.reverse_proxy\nThe [network address](/docs/conventions#network-addresses)\nto dial to connect to the upstream. Must represent precisely\none socket (i.e. no port ranges). A valid network address\neither has a host and port or is a unix socket address.\n\nPlaceholders may be used to make the upstream dynamic, but be\naware of the health check implications of this: a single\nupstream that represents numerous (perhaps arbitrary) backends\ncan be considered down if one or enough of the arbitrary\nbackends is down. Also be aware of open proxy vulnerabilities.\n",
"markdownDescription":"dial: `string` \nModule: `http.handlers.reverse_proxy` \nThe [network address](/docs/conventions#network-addresses)\nto dial to connect to the upstream. Must represent precisely\none socket (i.e. no port ranges). A valid network address\neither has a host and port or is a unix socket address.\n\nPlaceholders may be used to make the upstream dynamic, but be\naware of the health check implications of this: a single\nupstream that represents numerous (perhaps arbitrary) backends\ncan be considered down if one or enough of the arbitrary\nbackends is down. Also be aware of open proxy vulnerabilities. \n",
"type":"string"
},
"lookup_srv":{
"description":"lookup_srv: string\nModule: http.handlers.reverse_proxy\nDEPRECATED: Use the SRVUpstreams module instead\n(http.reverse_proxy.upstreams.srv). This field will be\nremoved in a future version of Caddy. TODO: Remove this field.\n\nIf DNS SRV records are used for service discovery with this\nupstream, specify the DNS name for which to look up SRV\nrecords here, instead of specifying a dial address.\n",
"markdownDescription":"lookup_srv: `string` \nModule: `http.handlers.reverse_proxy` \nDEPRECATED: Use the SRVUpstreams module instead\n(http.reverse_proxy.upstreams.srv). This field will be\nremoved in a future version of Caddy. TODO: Remove this field.\n\nIf DNS SRV records are used for service discovery with this\nupstream, specify the DNS name for which to look up SRV\nrecords here, instead of specifying a dial address. \n",
"type":"string"
},
"max_requests":{
"description":"max_requests: number\nModule: http.handlers.reverse_proxy\nThe maximum number of simultaneous requests to allow to\nthis upstream. If set, overrides the global passive health\ncheck UnhealthyRequestCount value.\n",
"markdownDescription":"max_requests: `number` \nModule: `http.handlers.reverse_proxy` \nThe maximum number of simultaneous requests to allow to\nthis upstream. If set, overrides the global passive health\ncheck UnhealthyRequestCount value. \n",
"description":"rewrite: object\nModule: http.handlers.rewrite\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#Rewrite\nRewrite is a middleware which can rewrite/mutate HTTP requests.\n\nThe Method and URI properties are \"setters\" (the request URI\nwill be overwritten with the given values). Other properties are\n\"modifiers\" (they modify existing values in a differentiable\nway). It is atypical to combine the use of setters and\nmodifiers in a single rewrite.\n\nTo ensure consistent behavior, prefix and suffix stripping is\nperformed in the URL-decoded (unescaped, normalized) space by\ndefault except for the specific bytes where an escape sequence\nis used in the prefix or suffix pattern.\n\nFor all modifiers, paths are cleaned before being modified so that\nmultiple, consecutive slashes are collapsed into a single slash,\nand dot elements are resolved and removed. In the special case\nof a prefix, suffix, or substring containing \"//\" (repeated slashes),\nslashes will not be merged while cleaning the path so that\nthe rewrite can be interpreted literally.\n\n",
"markdownDescription":"rewrite: `object` \nModule: `http.handlers.rewrite` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#Rewrite) \nRewrite is a middleware which can rewrite/mutate HTTP requests.\n\nThe Method and URI properties are \"setters\" (the request URI\nwill be overwritten with the given values). Other properties are\n\"modifiers\" (they modify existing values in a differentiable\nway). It is atypical to combine the use of setters and\nmodifiers in a single rewrite.\n\nTo ensure consistent behavior, prefix and suffix stripping is\nperformed in the URL-decoded (unescaped, normalized) space by\ndefault except for the specific bytes where an escape sequence\nis used in the prefix or suffix pattern.\n\nFor all modifiers, paths are cleaned before being modified so that\nmultiple, consecutive slashes are collapsed into a single slash,\nand dot elements are resolved and removed. In the special case\nof a prefix, suffix, or substring containing \"//\" (repeated slashes),\nslashes will not be merged while cleaning the path so that\nthe rewrite can be interpreted literally.\n \n",
"description":"method: string\nModule: http.handlers.rewrite\nChanges the request's HTTP verb.\n",
"markdownDescription":"method: `string` \nModule: `http.handlers.rewrite` \nChanges the request's HTTP verb. \n",
"type":"string"
},
"path_regexp":{
"description":"path_regexp: array\nModule: http.handlers.rewrite\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer\nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression.\n",
"markdownDescription":"path_regexp: `array` \nModule: `http.handlers.rewrite` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer) \nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer\nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#regexReplacer) \nPerforms regular expression replacements on the URI path.\n\n\nregexReplacer describes a replacement using a regular expression. \n",
"type":"object",
"properties":{
"find":{
"description":"find: string\nModule: http.handlers.rewrite\nThe regular expression to find.\n",
"markdownDescription":"find: `string` \nModule: `http.handlers.rewrite` \nThe regular expression to find. \n",
"description":"strip_path_prefix: string\nModule: http.handlers.rewrite\nStrips the given prefix from the beginning of the URI path.\nThe prefix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match.\n",
"markdownDescription":"strip_path_prefix: `string` \nModule: `http.handlers.rewrite` \nStrips the given prefix from the beginning of the URI path.\nThe prefix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match. \n",
"description":"strip_path_suffix: string\nModule: http.handlers.rewrite\nStrips the given suffix from the end of the URI path.\nThe suffix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match.\n",
"markdownDescription":"strip_path_suffix: `string` \nModule: `http.handlers.rewrite` \nStrips the given suffix from the end of the URI path.\nThe suffix should be written in normalized (unescaped) form,\nbut if an escaping (`%xx`) is used, the path will be required\nto have that same escape at that position in order to match. \n",
"description":"uri: string\nModule: http.handlers.rewrite\nChanges the request's URI, which consists of path and query string.\nOnly components of the URI that are specified will be changed.\nFor example, a value of \"/foo.html\" or \"foo.html\" will only change\nthe path and will preserve any existing query string. Similarly, a\nvalue of \"?a=b\" will only change the query string and will not affect\nthe path. Both can also be changed: \"/foo?a=b\" - this sets both the\npath and query string at the same time.\n\nYou can also use placeholders. For example, to preserve the existing\nquery string, you might use: \"?{http.request.uri.query}\u0026a=b\". Any\nkey-value pairs you add to the query string will not overwrite\nexisting values (individual pairs are append-only).\n\nTo clear the query string, explicitly set an empty one: \"?\"\n",
"markdownDescription":"uri: `string` \nModule: `http.handlers.rewrite` \nChanges the request's URI, which consists of path and query string.\nOnly components of the URI that are specified will be changed.\nFor example, a value of \"/foo.html\" or \"foo.html\" will only change\nthe path and will preserve any existing query string. Similarly, a\nvalue of \"?a=b\" will only change the query string and will not affect\nthe path. Both can also be changed: \"/foo?a=b\" - this sets both the\npath and query string at the same time.\n\nYou can also use placeholders. For example, to preserve the existing\nquery string, you might use: \"?{http.request.uri.query}\u0026a=b\". Any\nkey-value pairs you add to the query string will not overwrite\nexisting values (individual pairs are append-only).\n\nTo clear the query string, explicitly set an empty one: \"?\" \n",
"type":"string"
},
"uri_substring":{
"description":"uri_substring: array\nModule: http.handlers.rewrite\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer\nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement.\n",
"markdownDescription":"uri_substring: `array` \nModule: `http.handlers.rewrite` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer) \nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer\nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/rewrite#substrReplacer) \nPerforms substring replacements on the URI.\n\n\nsubstrReplacer describes either a simple and fast substring replacement. \n",
"type":"object",
"properties":{
"find":{
"description":"find: string\nModule: http.handlers.rewrite\nA substring to find. Supports placeholders.\n",
"description":"limit: number\nModule: http.handlers.rewrite\nMaximum number of replacements per string.\nSet to \u003c= 0 for no limit (default).\n",
"markdownDescription":"limit: `number` \nModule: `http.handlers.rewrite` \nMaximum number of replacements per string.\nSet to \u003c= 0 for no limit (default). \n",
"type":"number"
},
"replace":{
"description":"replace: string\nModule: http.handlers.rewrite\nThe substring to replace with. Supports placeholders.\n",
"description":"static_response: object\nModule: http.handlers.static_response\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#StaticResponse\nStaticResponse implements a simple responder for static responses.\n\n",
"markdownDescription":"static_response: `object` \nModule: `http.handlers.static_response` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#StaticResponse) \nStaticResponse implements a simple responder for static responses.\n \n",
"type":"object",
"properties":{
"abort":{
"description":"abort: boolean\nModule: http.handlers.static_response\nImmediately and forcefully closes the connection without\nwriting a response. Interrupts any other HTTP streams on\nthe same connection.\n",
"markdownDescription":"abort: `boolean` \nModule: `http.handlers.static_response` \nImmediately and forcefully closes the connection without\nwriting a response. Interrupts any other HTTP streams on\nthe same connection. \n",
"description":"body: string\nModule: http.handlers.static_response\nThe response body. If non-empty, the Content-Type header may\nbe added automatically if it is not explicitly configured nor\nalready set on the response; the default value is\n\"text/plain; charset=utf-8\" unless the body is a valid JSON object\nor array, in which case the value will be \"application/json\".\nOther than those common special cases the Content-Type header\nshould be set explicitly if it is desired because MIME sniffing\nis disabled for safety.\n",
"markdownDescription":"body: `string` \nModule: `http.handlers.static_response` \nThe response body. If non-empty, the Content-Type header may\nbe added automatically if it is not explicitly configured nor\nalready set on the response; the default value is\n\"text/plain; charset=utf-8\" unless the body is a valid JSON object\nor array, in which case the value will be \"application/json\".\nOther than those common special cases the Content-Type header\nshould be set explicitly if it is desired because MIME sniffing\nis disabled for safety. \n",
"description":"close: boolean\nModule: http.handlers.static_response\nIf true, the server will close the client's connection\nafter writing the response.\n",
"markdownDescription":"close: `boolean` \nModule: `http.handlers.static_response` \nIf true, the server will close the client's connection\nafter writing the response. \n",
"description":"headers: object\nModule: http.handlers.static_response\nHeader fields to set on the response; overwrites any existing\nheader fields of the same names after normalization.\n",
"markdownDescription":"headers: `object` \nModule: `http.handlers.static_response` \nHeader fields to set on the response; overwrites any existing\nheader fields of the same names after normalization. \n",
"description":"status_code: string\nModule: http.handlers.static_response\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString\nThe HTTP status code to respond with. Can be an integer or,\nif needing to use a placeholder, a string.\n\nIf the status code is 103 (Early Hints), the response headers\nwill be written to the client immediately, the body will be\nignored, and the next handler will be invoked. This behavior\nis EXPERIMENTAL while RFC 8297 is a draft, and may be changed\nor removed.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned.\n",
"markdownDescription":"status_code: `string` \nModule: `http.handlers.static_response` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#WeakString) \nThe HTTP status code to respond with. Can be an integer or,\nif needing to use a placeholder, a string.\n\nIf the status code is 103 (Early Hints), the response headers\nwill be written to the client immediately, the body will be\nignored, and the next handler will be invoked. This behavior\nis EXPERIMENTAL while RFC 8297 is a draft, and may be changed\nor removed.\n\n\nWeakString is a type that unmarshals any JSON value\nas a string literal, with the following exceptions:\n\n1. actual string values are decoded as strings; and\n2. null is decoded as empty string;\n\nand provides methods for getting the value as various\nprimitive types. However, using this type removes any\ntype safety as far as deserializing JSON is concerned. \n",
"description":"subroute: object\nModule: http.handlers.subroute\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Subroute\nSubroute implements a handler that compiles and executes routes.\nThis is useful for a batch of routes that all inherit the same\nmatchers, or for multiple routes that should be treated as a\nsingle route.\n\nYou can also use subroutes to handle errors from its handlers.\nFirst the primary routes will be executed, and if they return an\nerror, the errors routes will be executed; in that case, an error\nis only returned to the entry point at the server if there is an\nadditional error returned from the errors routes.\n\n",
"markdownDescription":"subroute: `object` \nModule: `http.handlers.subroute` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Subroute) \nSubroute implements a handler that compiles and executes routes.\nThis is useful for a batch of routes that all inherit the same\nmatchers, or for multiple routes that should be treated as a\nsingle route.\n\nYou can also use subroutes to handle errors from its handlers.\nFirst the primary routes will be executed, and if they return an\nerror, the errors routes will be executed; in that case, an error\nis only returned to the entry point at the server if there is an\nadditional error returned from the errors routes.\n \n",
"type":"object",
"properties":{
"errors":{
"description":"errors: object\nModule: http.handlers.subroute\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#HTTPErrorConfig\nIf the primary routes return an error, error handling\ncan be promoted to this configuration instead.\n\n\nHTTPErrorConfig determines how to handle errors\nfrom the HTTP handlers.\n",
"markdownDescription":"errors: `object` \nModule: `http.handlers.subroute` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#HTTPErrorConfig) \nIf the primary routes return an error, error handling\ncan be promoted to this configuration instead.\n\n\nHTTPErrorConfig determines how to handle errors\nfrom the HTTP handlers. \n",
"type":"object",
"properties":{
"routes":{
"description":"routes: array\nModule: http.handlers.subroute\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"routes: `array` \nModule: `http.handlers.subroute` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe routes to evaluate after the primary handler\nchain returns an error. In an error route, extra\nplaceholders are available:\n\nPlaceholder | Description\n------------|---------------\n`{http.error.status_code}` | The recommended HTTP status code\n`{http.error.status_text}` | The status text associated with the recommended status code\n`{http.error.message}` | The error message\n`{http.error.trace}` | The origin of the error\n`{http.error.id}` | An identifier for this occurrence of the error\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"object",
"properties":{
"group":{
"description":"group: string\nModule: http.handlers.subroute\nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed.\n",
"markdownDescription":"group: `string` \nModule: `http.handlers.subroute` \nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed. \n",
"type":"string"
},
"handle":{
"description":"handle: array\nModule: http.handlers\nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"handle: `array` \nModule: `http.handlers` \nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"type":"array",
"items":{
"description":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"description":"match: array\nModule: http.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `array` \nModule: `http.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"terminal: boolean\nModule: http.handlers.subroute\nIf true, no more routes will be executed after this one.\n",
"markdownDescription":"terminal: `boolean` \nModule: `http.handlers.subroute` \nIf true, no more routes will be executed after this one. \n",
"type":"boolean"
}
}
}
}
}
},
"routes":{
"description":"routes: array\nModule: http.handlers.subroute\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe primary list of routes to compile and execute.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"routes: `array` \nModule: `http.handlers.subroute` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe primary list of routes to compile and execute.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route\nThe primary list of routes to compile and execute.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#Route) \nThe primary list of routes to compile and execute.\n\n\nRoute consists of a set of rules for matching HTTP requests,\na list of handlers to execute, and optional flow control\nparameters which customize the handling of HTTP requests\nin a highly flexible and performant manner. \n",
"type":"object",
"properties":{
"group":{
"description":"group: string\nModule: http.handlers.subroute\nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed.\n",
"markdownDescription":"group: `string` \nModule: `http.handlers.subroute` \nGroup is an optional name for a group to which this\nroute belongs. Grouping a route makes it mutually\nexclusive with others in its group; if a route belongs\nto a group, only the first matching route in that group\nwill be executed. \n",
"type":"string"
},
"handle":{
"description":"handle: array\nModule: http.handlers\nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"handle: `array` \nModule: `http.handlers` \nThe list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"type":"array",
"items":{
"description":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes.\n",
"markdownDescription":"The list of handlers for this route. Upon matching a request, they are chained\ntogether in a middleware fashion: requests flow from the first handler to the last\n(top of the list to the bottom), with the possibility that any handler could stop\nthe chain and/or return an error. Responses flow back through the chain (bottom of\nthe list to the top) as they are written out to the client.\n\nNot all handlers call the next handler in the chain. For example, the reverse_proxy\nhandler always sends a request upstream or returns an error. Thus, configuring\nhandlers after reverse_proxy in the same route is illogical, since they would never\nbe executed. You will want to put handlers which originate the response at the very\nend of your route(s). The documentation for a module should state whether it invokes\nthe next handler, but sometimes it is common sense.\n\nSome handlers manipulate the response. Remember that requests flow down the list, and\nresponses flow up the list.\n\nFor example, if you wanted to use both `templates` and `encode` handlers, you would\nneed to put `templates` after `encode` in your route, because responses flow up.\nThus, `templates` will be able to parse and execute the plain-text response as a\ntemplate, and then return it up to the `encode` handler which will then compress it\ninto a binary format.\n\nIf `templates` came before `encode`, then `encode` would write a compressed,\nbinary-encoded response to `templates` which would not be able to parse the response\nproperly.\n\nThe correct order, then, is this:\n\n [\n {\"handler\": \"encode\"},\n {\"handler\": \"templates\"},\n {\"handler\": \"file_server\"}\n ]\n\nThe request flows ⬇️ DOWN (`encode` -\u003e `templates` -\u003e `file_server`).\n\n1. First, `encode` will choose how to `encode` the response and wrap the response.\n2. Then, `templates` will wrap the response with a buffer.\n3. Finally, `file_server` will originate the content from a file.\n\nThe response flows ⬆️ UP (`file_server` -\u003e `templates` -\u003e `encode`):\n\n1. First, `file_server` will write the file to the response.\n2. That write will be buffered and then executed by `templates`.\n3. Lastly, the write from `templates` will flow into `encode` which will compress the stream.\n\nIf you think of routes in this way, it will be easy and even fun to solve the puzzle of writing correct routes. \n",
"description":"match: array\nModule: http.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `array` \nModule: `http.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nThe matcher sets which will be used to qualify this\nroute for a request (essentially the \"if\" statement\nof this route). Each matcher set is OR'ed, but matchers\nwithin a set are AND'ed together.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"delimiters: array\nModule: http.handlers.templates\nThe template action delimiters. If set, must be precisely two elements:\nthe opening and closing delimiters. Default: `[\"{{\", \"}}\"]`\n",
"markdownDescription":"delimiters: `array` \nModule: `http.handlers.templates` \nThe template action delimiters. If set, must be precisely two elements:\nthe opening and closing delimiters. Default: `[\"{{\", \"}}\"]` \n",
"type":"array",
"items":{
"description":"The template action delimiters. If set, must be precisely two elements:\nthe opening and closing delimiters. Default: `[\"{{\", \"}}\"]`\n",
"markdownDescription":"The template action delimiters. If set, must be precisely two elements:\nthe opening and closing delimiters. Default: `[\"{{\", \"}}\"]` \n",
"type":"string"
}
},
"file_root":{
"description":"file_root: string\nModule: http.handlers.templates\nThe root path from which to load files. Required if template functions\naccessing the file system are used (such as include). Default is\n`{http.vars.root}` if set, or current working directory otherwise.\n",
"markdownDescription":"file_root: `string` \nModule: `http.handlers.templates` \nThe root path from which to load files. Required if template functions\naccessing the file system are used (such as include). Default is\n`{http.vars.root}` if set, or current working directory otherwise. \n",
"type":"string"
},
"mime_types":{
"description":"mime_types: array\nModule: http.handlers.templates\nThe MIME types for which to render templates. It is important to use\nthis if the route matchers do not exclude images or other binary files.\nDefault is text/plain, text/markdown, and text/html.\n",
"markdownDescription":"mime_types: `array` \nModule: `http.handlers.templates` \nThe MIME types for which to render templates. It is important to use\nthis if the route matchers do not exclude images or other binary files.\nDefault is text/plain, text/markdown, and text/html. \n",
"type":"array",
"items":{
"description":"The MIME types for which to render templates. It is important to use\nthis if the route matchers do not exclude images or other binary files.\nDefault is text/plain, text/markdown, and text/html.\n",
"markdownDescription":"The MIME types for which to render templates. It is important to use\nthis if the route matchers do not exclude images or other binary files.\nDefault is text/plain, text/markdown, and text/html. \n",
"type":"string"
}
}
}
},
"http.handlers.tracing":{
"description":"tracing: object\nModule: http.handlers.tracing\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/tracing#Tracing\nTracing implements an HTTP handler that adds support for distributed tracing,\nusing OpenTelemetry. This module is responsible for the injection and\npropagation of the trace context. Configure this module via environment\nvariables (see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md).\nSome values can be overwritten in the configuration file.\n\n",
"markdownDescription":"tracing: `object` \nModule: `http.handlers.tracing` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/tracing#Tracing) \nTracing implements an HTTP handler that adds support for distributed tracing,\nusing OpenTelemetry. This module is responsible for the injection and\npropagation of the trace context. Configure this module via environment\nvariables (see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md).\nSome values can be overwritten in the configuration file.\n \n",
"type":"object",
"properties":{
"span":{
"description":"span: string\nModule: http.handlers.tracing\nSpanName is a span name. It should follow the naming guidelines here:\nhttps://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span\n",
"markdownDescription":"span: `string` \nModule: `http.handlers.tracing` \nSpanName is a span name. It should follow the naming guidelines here:\nhttps://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span \n",
"type":"string"
}
}
},
"http.handlers.vars":{
"description":"vars: object\nModule: http.handlers.vars\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#VarsMiddleware\nVarsMiddleware is an HTTP middleware which sets variables to\nhave values that can be used in the HTTP request handler\nchain. The primary way to access variables is with placeholders,\nwhich have the form: `{http.vars.variable_name}`, or with\nthe `vars` and `vars_regexp` request matchers.\n\nThe key is the variable name, and the value is the value of the\nvariable. Both the name and value may use or contain placeholders.\n\n",
"markdownDescription":"vars: `object` \nModule: `http.handlers.vars` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#VarsMiddleware) \nVarsMiddleware is an HTTP middleware which sets variables to\nhave values that can be used in the HTTP request handler\nchain. The primary way to access variables is with placeholders,\nwhich have the form: `{http.vars.variable_name}`, or with\nthe `vars` and `vars_regexp` request matchers.\n\nThe key is the variable name, and the value is the value of the\nvariable. Both the name and value may use or contain placeholders.\n \n",
"type":"object",
"additionalProperties":{}
},
"http.matchers.expression":{
"description":"expression: string\nModule: http.matchers.expression\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchExpression\nMatchExpression matches requests by evaluating a\n[CEL](https://github.com/google/cel-spec) expression.\nThis enables complex logic to be expressed using a comfortable,\nfamiliar syntax. Please refer to\n[the standard definitions of CEL functions and operators](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).\n\nThis matcher's JSON interface is actually a string, not a struct.\nThe generated docs are not correct because this type has custom\nmarshaling logic.\n\nCOMPATIBILITY NOTE: This module is still experimental and is not\nsubject to Caddy's compatibility guarantee.\n\n",
"markdownDescription":"expression: `string` \nModule: `http.matchers.expression` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchExpression) \nMatchExpression matches requests by evaluating a\n[CEL](https://github.com/google/cel-spec) expression.\nThis enables complex logic to be expressed using a comfortable,\nfamiliar syntax. Please refer to\n[the standard definitions of CEL functions and operators](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).\n\nThis matcher's JSON interface is actually a string, not a struct.\nThe generated docs are not correct because this type has custom\nmarshaling logic.\n\nCOMPATIBILITY NOTE: This module is still experimental and is not\nsubject to Caddy's compatibility guarantee.\n \n",
"description":"file: object\nModule: http.matchers.file\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/fileserver#MatchFile\nMatchFile is an HTTP request matcher that can match\nrequests based upon file existence.\n\nUpon matching, three new placeholders will be made\navailable:\n\n- `{http.matchers.file.relative}` The root-relative\npath of the file. This is often useful when rewriting\nrequests.\n- `{http.matchers.file.absolute}` The absolute path\nof the matched file.\n- `{http.matchers.file.type}` Set to \"directory\" if\nthe matched file is a directory, \"file\" otherwise.\n- `{http.matchers.file.remainder}` Set to the remainder\nof the path if the path was split by `split_path`.\n\nEven though file matching may depend on the OS path\nseparator, the placeholder values always use /.\n\n",
"markdownDescription":"file: `object` \nModule: `http.matchers.file` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/fileserver#MatchFile) \nMatchFile is an HTTP request matcher that can match\nrequests based upon file existence.\n\nUpon matching, three new placeholders will be made\navailable:\n\n- `{http.matchers.file.relative}` The root-relative\npath of the file. This is often useful when rewriting\nrequests.\n- `{http.matchers.file.absolute}` The absolute path\nof the matched file.\n- `{http.matchers.file.type}` Set to \"directory\" if\nthe matched file is a directory, \"file\" otherwise.\n- `{http.matchers.file.remainder}` Set to the remainder\nof the path if the path was split by `split_path`.\n\nEven though file matching may depend on the OS path\nseparator, the placeholder values always use /.\n \n",
"description":"file_system: any\nModule: caddy.fs\nThe file system implementation to use. By default, the\nlocal disk file system will be used.\n",
"markdownDescription":"file_system: `any` \nModule: `caddy.fs` \nThe file system implementation to use. By default, the\nlocal disk file system will be used. \n"
"description":"root: string\nModule: http.matchers.file\nThe root directory, used for creating absolute\nfile paths, and required when working with\nrelative paths; if not specified, `{http.vars.root}`\nwill be used, if set; otherwise, the current\ndirectory is assumed. Accepts placeholders.\n",
"markdownDescription":"root: `string` \nModule: `http.matchers.file` \nThe root directory, used for creating absolute\nfile paths, and required when working with\nrelative paths; if not specified, `{http.vars.root}`\nwill be used, if set; otherwise, the current\ndirectory is assumed. Accepts placeholders. \n",
"type":"string"
},
"split_path":{
"description":"split_path: array\nModule: http.matchers.file\nA list of delimiters to use to split the path in two\nwhen trying files. If empty, no splitting will\noccur, and the path will be tried as-is. For each\nsplit value, the left-hand side of the split,\nincluding the split value, will be the path tried.\nFor example, the path `/remote.php/dav/` using the\nsplit value `.php` would try the file `/remote.php`.\nEach delimiter must appear at the end of a URI path\ncomponent in order to be used as a split delimiter.\n",
"markdownDescription":"split_path: `array` \nModule: `http.matchers.file` \nA list of delimiters to use to split the path in two\nwhen trying files. If empty, no splitting will\noccur, and the path will be tried as-is. For each\nsplit value, the left-hand side of the split,\nincluding the split value, will be the path tried.\nFor example, the path `/remote.php/dav/` using the\nsplit value `.php` would try the file `/remote.php`.\nEach delimiter must appear at the end of a URI path\ncomponent in order to be used as a split delimiter. \n",
"type":"array",
"items":{
"description":"A list of delimiters to use to split the path in two\nwhen trying files. If empty, no splitting will\noccur, and the path will be tried as-is. For each\nsplit value, the left-hand side of the split,\nincluding the split value, will be the path tried.\nFor example, the path `/remote.php/dav/` using the\nsplit value `.php` would try the file `/remote.php`.\nEach delimiter must appear at the end of a URI path\ncomponent in order to be used as a split delimiter.\n",
"markdownDescription":"A list of delimiters to use to split the path in two\nwhen trying files. If empty, no splitting will\noccur, and the path will be tried as-is. For each\nsplit value, the left-hand side of the split,\nincluding the split value, will be the path tried.\nFor example, the path `/remote.php/dav/` using the\nsplit value `.php` would try the file `/remote.php`.\nEach delimiter must appear at the end of a URI path\ncomponent in order to be used as a split delimiter. \n",
"type":"string"
}
},
"try_files":{
"description":"try_files: array\nModule: http.matchers.file\nThe list of files to try. Each path here is\nconsidered related to Root. If nil, the request\nURL's path will be assumed. Files and\ndirectories are treated distinctly, so to match\na directory, the filepath MUST end in a forward\nslash `/`. To match a regular file, there must\nbe no trailing slash. Accepts placeholders. If\nthe policy is \"first_exist\", then an error may\nbe triggered as a fallback by configuring \"=\"\nfollowed by a status code number,\nfor example \"=404\".\n",
"markdownDescription":"try_files: `array` \nModule: `http.matchers.file` \nThe list of files to try. Each path here is\nconsidered related to Root. If nil, the request\nURL's path will be assumed. Files and\ndirectories are treated distinctly, so to match\na directory, the filepath MUST end in a forward\nslash `/`. To match a regular file, there must\nbe no trailing slash. Accepts placeholders. If\nthe policy is \"first_exist\", then an error may\nbe triggered as a fallback by configuring \"=\"\nfollowed by a status code number,\nfor example \"=404\". \n",
"type":"array",
"items":{
"description":"The list of files to try. Each path here is\nconsidered related to Root. If nil, the request\nURL's path will be assumed. Files and\ndirectories are treated distinctly, so to match\na directory, the filepath MUST end in a forward\nslash `/`. To match a regular file, there must\nbe no trailing slash. Accepts placeholders. If\nthe policy is \"first_exist\", then an error may\nbe triggered as a fallback by configuring \"=\"\nfollowed by a status code number,\nfor example \"=404\".\n",
"markdownDescription":"The list of files to try. Each path here is\nconsidered related to Root. If nil, the request\nURL's path will be assumed. Files and\ndirectories are treated distinctly, so to match\na directory, the filepath MUST end in a forward\nslash `/`. To match a regular file, there must\nbe no trailing slash. Accepts placeholders. If\nthe policy is \"first_exist\", then an error may\nbe triggered as a fallback by configuring \"=\"\nfollowed by a status code number,\nfor example \"=404\". \n",
"type":"string"
}
},
"try_policy":{
"description":"try_policy: string\nModule: http.matchers.file\nHow to choose a file in TryFiles. Can be:\n\n- first_exist\n- smallest_size\n- largest_size\n- most_recently_modified\n\nDefault is first_exist.\n",
"markdownDescription":"try_policy: `string` \nModule: `http.matchers.file` \nHow to choose a file in TryFiles. Can be:\n\n- first_exist\n- smallest_size\n- largest_size\n- most_recently_modified\n\nDefault is first_exist. \n",
"type":"string"
}
}
},
"http.matchers.header":{
"description":"header: object\nModule: http.matchers.header\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchHeader\nMatchHeader matches requests by header fields. The key is the field\nname and the array is the list of field values. It performs fast,\nexact string comparisons of the field values. Fast prefix, suffix,\nand substring matches can also be done by suffixing, prefixing, or\nsurrounding the value with the wildcard `*` character, respectively.\nIf a list is null, the header must not exist. If the list is empty,\nthe field must simply exist, regardless of its value.\n\n",
"markdownDescription":"header: `object` \nModule: `http.matchers.header` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchHeader) \nMatchHeader matches requests by header fields. The key is the field\nname and the array is the list of field values. It performs fast,\nexact string comparisons of the field values. Fast prefix, suffix,\nand substring matches can also be done by suffixing, prefixing, or\nsurrounding the value with the wildcard `*` character, respectively.\nIf a list is null, the header must not exist. If the list is empty,\nthe field must simply exist, regardless of its value.\n \n",
"type":"object",
"additionalProperties":{
"type":"array",
"items":{
"type":"string"
}
}
},
"http.matchers.header_regexp":{
"description":"header_regexp: object\nModule: http.matchers.header_regexp\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp\nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n\n",
"markdownDescription":"header_regexp: `object` \nModule: `http.matchers.header_regexp` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp) \nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n \n",
"type":"object",
"additionalProperties":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp\nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp) \nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n \n",
"properties":{
"name":{
"description":"name: string\nModule: http.matchers.header_regexp\nA unique name for this regular expression. Optional,\nbut useful to prevent overwriting captures from other\nregexp matchers.\n",
"markdownDescription":"name: `string` \nModule: `http.matchers.header_regexp` \nA unique name for this regular expression. Optional,\nbut useful to prevent overwriting captures from other\nregexp matchers. \n",
"type":"string"
},
"pattern":{
"description":"pattern: string\nModule: http.matchers.header_regexp\nThe regular expression to evaluate, in RE2 syntax,\nwhich is the same general syntax used by Go, Perl,\nand Python. For details, see\n[Go's regexp package](https://golang.org/pkg/regexp/).\nCaptures are accessible via placeholders. Unnamed\ncapture groups are exposed as their numeric, 1-based\nindex, while named capture groups are available by\nthe capture group name.\n",
"markdownDescription":"pattern: `string` \nModule: `http.matchers.header_regexp` \nThe regular expression to evaluate, in RE2 syntax,\nwhich is the same general syntax used by Go, Perl,\nand Python. For details, see\n[Go's regexp package](https://golang.org/pkg/regexp/).\nCaptures are accessible via placeholders. Unnamed\ncapture groups are exposed as their numeric, 1-based\nindex, while named capture groups are available by\nthe capture group name. \n",
"type":"string"
}
}
}
},
"http.matchers.host":{
"description":"host: array\nModule: http.matchers.host\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchHost\nMatchHost matches requests by the Host value (case-insensitive).\n\nWhen used in a top-level HTTP route,\n[qualifying domain names](/docs/automatic-https#hostname-requirements)\nmay trigger [automatic HTTPS](/docs/automatic-https), which automatically\nprovisions and renews certificates for you. Before doing this, you\nshould ensure that DNS records for these domains are properly configured,\nespecially A/AAAA pointed at your server.\n\nAutomatic HTTPS can be\n[customized or disabled](/docs/modules/http#servers/automatic_https).\n\nWildcards (`*`) may be used to represent exactly one label of the\nhostname, in accordance with RFC 1034 (because host matchers are also\nused for automatic HTTPS which influences TLS certificates). Thus,\na host of `*` matches hosts like `localhost` or `internal` but not\n`example.com`. To catch all hosts, omit the host matcher entirely.\n\nThe wildcard can be useful for matching all subdomains, for example:\n`*.example.com` matches `foo.example.com` but not `foo.bar.example.com`.\n\nDuplicate entries will return an error.\n\n",
"markdownDescription":"host: `array` \nModule: `http.matchers.host` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchHost) \nMatchHost matches requests by the Host value (case-insensitive).\n\nWhen used in a top-level HTTP route,\n[qualifying domain names](/docs/automatic-https#hostname-requirements)\nmay trigger [automatic HTTPS](/docs/automatic-https), which automatically\nprovisions and renews certificates for you. Before doing this, you\nshould ensure that DNS records for these domains are properly configured,\nespecially A/AAAA pointed at your server.\n\nAutomatic HTTPS can be\n[customized or disabled](/docs/modules/http#servers/automatic_https).\n\nWildcards (`*`) may be used to represent exactly one label of the\nhostname, in accordance with RFC 1034 (because host matchers are also\nused for automatic HTTPS which influences TLS certificates). Thus,\na host of `*` matches hosts like `localhost` or `internal` but not\n`example.com`. To catch all hosts, omit the host matcher entirely.\n\nThe wildcard can be useful for matching all subdomains, for example:\n`*.example.com` matches `foo.example.com` but not `foo.bar.example.com`.\n\nDuplicate entries will return an error.\n \n",
"type":"array",
"items":{
"type":"string"
}
},
"http.matchers.method":{
"description":"method: array\nModule: http.matchers.method\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchMethod\nMatchMethod matches requests by the method.\n\n",
"markdownDescription":"method: `array` \nModule: `http.matchers.method` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchMethod) \nMatchMethod matches requests by the method.\n \n",
"type":"array",
"items":{
"type":"string"
}
},
"http.matchers.not":{
"description":"not: array\nModule: http.matchers.not\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchNot\nMatchNot matches requests by negating the results of its matcher\nsets. A single \"not\" matcher takes one or more matcher sets. Each\nmatcher set is OR'ed; in other words, if any matcher set returns\ntrue, the final result of the \"not\" matcher is false. Individual\nmatchers within a set work the same (i.e. different matchers in\nthe same set are AND'ed).\n\nNOTE: The generated docs which describe the structure of this\nmodule are wrong because of how this type unmarshals JSON in a\ncustom way. The correct structure is:\n\n```json\n[\n\t{},\n\t{}\n]\n```\n\nwhere each of the array elements is a matcher set, i.e. an\nobject keyed by matcher name.\n\n",
"markdownDescription":"not: `array` \nModule: `http.matchers.not` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchNot) \nMatchNot matches requests by negating the results of its matcher\nsets. A single \"not\" matcher takes one or more matcher sets. Each\nmatcher set is OR'ed; in other words, if any matcher set returns\ntrue, the final result of the \"not\" matcher is false. Individual\nmatchers within a set work the same (i.e. different matchers in\nthe same set are AND'ed).\n\nNOTE: The generated docs which describe the structure of this\nmodule are wrong because of how this type unmarshals JSON in a\ncustom way. The correct structure is:\n\n```json\n[\n\t{},\n\t{}\n]\n```\n\nwhere each of the array elements is a matcher set, i.e. an\nobject keyed by matcher name.\n \n",
"description":"path: array\nModule: http.matchers.path\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchPath\nMatchPath case-insensitively matches requests by the URI's path. Path\nmatching is exact, not prefix-based, giving you more control and clarity\nover matching. Wildcards (`*`) may be used:\n\n- At the end only, for a prefix match (`/prefix/*`)\n- At the beginning only, for a suffix match (`*.suffix`)\n- On both sides only, for a substring match (`*/contains/*`)\n- In the middle, for a globular match (`/accounts/*/info`)\n\nSlashes are significant; i.e. `/foo*` matches `/foo`, `/foo/`, `/foo/bar`,\nand `/foobar`; but `/foo/*` does not match `/foo` or `/foobar`. Valid\npaths start with a slash `/`.\n\nBecause there are, in general, multiple possible escaped forms of any\npath, path matchers operate in unescaped space; that is, path matchers\nshould be written in their unescaped form to prevent ambiguities and\npossible security issues, as all request paths will be normalized to\ntheir unescaped forms before matcher evaluation.\n\nHowever, escape sequences in a match pattern are supported; they are\ncompared with the request's raw/escaped path for those bytes only.\nIn other words, a matcher of `/foo%2Fbar` will match a request path\nof precisely `/foo%2Fbar`, but not `/foo/bar`. It follows that matching\nthe literal percent sign (%) in normalized space can be done using the\nescaped form, `%25`.\n\nEven though wildcards (`*`) operate in the normalized space, the special\nescaped wildcard (`%*`), which is not a valid escape sequence, may be\nused in place of a span that should NOT be decoded; that is, `/bands/%*`\nwill match `/bands/AC%2fDC` whereas `/bands/*` will not.\n\nEven though path matching is done in normalized space, the special\nwildcard `%*` may be used in place of a span that should NOT be decoded;\nthat is, `/bands/%*/` will match `/bands/AC%2fDC/` whereas `/bands/*/`\nwill not.\n\nThis matcher is fast, so it does not support regular expressions or\ncapture groups. For slower but more powerful matching, use the\npath_regexp matcher. (Note that due to the special treatment of\nescape sequences in matcher patterns, they may perform slightly slower\nin high-traffic environments.)\n\n",
"markdownDescription":"path: `array` \nModule: `http.matchers.path` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchPath) \nMatchPath case-insensitively matches requests by the URI's path. Path\nmatching is exact, not prefix-based, giving you more control and clarity\nover matching. Wildcards (`*`) may be used:\n\n- At the end only, for a prefix match (`/prefix/*`)\n- At the beginning only, for a suffix match (`*.suffix`)\n- On both sides only, for a substring match (`*/contains/*`)\n- In the middle, for a globular match (`/accounts/*/info`)\n\nSlashes are significant; i.e. `/foo*` matches `/foo`, `/foo/`, `/foo/bar`,\nand `/foobar`; but `/foo/*` does not match `/foo` or `/foobar`. Valid\npaths start with a slash `/`.\n\nBecause there are, in general, multiple possible escaped forms of any\npath, path matchers operate in unescaped space; that is, path matchers\nshould be written in their unescaped form to prevent ambiguities and\npossible security issues, as all request paths will be normalized to\ntheir unescaped forms before matcher evaluation.\n\nHowever, escape sequences in a match pattern are supported; they are\ncompared with the request's raw/escaped path for those bytes only.\nIn other words, a matcher of `/foo%2Fbar` will match a request path\nof precisely `/foo%2Fbar`, but not `/foo/bar`. It follows that matching\nthe literal percent sign (%) in normalized space can be done using the\nescaped form, `%25`.\n\nEven though wildcards (`*`) operate in the normalized space, the special\nescaped wildcard (`%*`), which is not a valid escape sequence, may be\nused in place of a span that should NOT be decoded; that is, `/bands/%*`\nwill match `/bands/AC%2fDC` whereas `/bands/*` will not.\n\nEven though path matching is done in normalized space, the special\nwildcard `%*` may be used in place of a span that should NOT be decoded;\nthat is, `/bands/%*/` will match `/bands/AC%2fDC/` whereas `/bands/*/`\nwill not.\n\nThis matcher is fast, so it does not support regular expressions or\ncapture groups. For slower but more powerful matching, use the\npath_regexp matcher. (Note that due to the special treatment of\nescape sequences in matcher patterns, they may perform slightly slower\nin high-traffic environments.)\n \n",
"description":"path_regexp: object\nModule: http.matchers.path_regexp\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchPathRE\nMatchPathRE matches requests by a regular expression on the URI's path.\nPath matching is performed in the unescaped (decoded) form of the path.\n\nUpon a match, it adds placeholders to the request: `{http.regexp.name.capture_group}`\nwhere `name` is the regular expression's name, and `capture_group` is either\nthe named or positional capture group from the expression itself. If no name\nis given, then the placeholder omits the name: `{http.regexp.capture_group}`\n(potentially leading to collisions).\n\n",
"markdownDescription":"path_regexp: `object` \nModule: `http.matchers.path_regexp` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchPathRE) \nMatchPathRE matches requests by a regular expression on the URI's path.\nPath matching is performed in the unescaped (decoded) form of the path.\n\nUpon a match, it adds placeholders to the request: `{http.regexp.name.capture_group}`\nwhere `name` is the regular expression's name, and `capture_group` is either\nthe named or positional capture group from the expression itself. If no name\nis given, then the placeholder omits the name: `{http.regexp.capture_group}`\n(potentially leading to collisions).\n \n",
"description":"name: string\nModule: http.matchers.path_regexp\nA unique name for this regular expression. Optional,\nbut useful to prevent overwriting captures from other\nregexp matchers.\n",
"markdownDescription":"name: `string` \nModule: `http.matchers.path_regexp` \nA unique name for this regular expression. Optional,\nbut useful to prevent overwriting captures from other\nregexp matchers. \n",
"type":"string"
},
"pattern":{
"description":"pattern: string\nModule: http.matchers.path_regexp\nThe regular expression to evaluate, in RE2 syntax,\nwhich is the same general syntax used by Go, Perl,\nand Python. For details, see\n[Go's regexp package](https://golang.org/pkg/regexp/).\nCaptures are accessible via placeholders. Unnamed\ncapture groups are exposed as their numeric, 1-based\nindex, while named capture groups are available by\nthe capture group name.\n",
"markdownDescription":"pattern: `string` \nModule: `http.matchers.path_regexp` \nThe regular expression to evaluate, in RE2 syntax,\nwhich is the same general syntax used by Go, Perl,\nand Python. For details, see\n[Go's regexp package](https://golang.org/pkg/regexp/).\nCaptures are accessible via placeholders. Unnamed\ncapture groups are exposed as their numeric, 1-based\nindex, while named capture groups are available by\nthe capture group name. \n",
"type":"string"
}
}
},
"http.matchers.protocol":{
"description":"protocol: string\nModule: http.matchers.protocol\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchProtocol\nMatchProtocol matches requests by protocol. Recognized values are\n\"http\", \"https\", and \"grpc\".\n\n",
"markdownDescription":"protocol: `string` \nModule: `http.matchers.protocol` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchProtocol) \nMatchProtocol matches requests by protocol. Recognized values are\n\"http\", \"https\", and \"grpc\".\n \n",
"description":"query: object\nModule: http.matchers.query\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchQuery\nMatchQuery matches requests by the URI's query string. It takes a JSON object\nkeyed by the query keys, with an array of string values to match for that key.\nQuery key matches are exact, but wildcards may be used for value matches. Both\nkeys and values may be placeholders.\nAn example of the structure to match `?key=value\u0026topic=api\u0026query=something` is:\n\n```json\n{\n\t\"key\": [\"value\"],\n\t\"topic\": [\"api\"],\n\t\"query\": [\"*\"]\n}\n```\n\nInvalid query strings, including those with bad escapings or illegal characters\nlike semicolons, will fail to parse and thus fail to match.\n\n",
"markdownDescription":"query: `object` \nModule: `http.matchers.query` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchQuery) \nMatchQuery matches requests by the URI's query string. It takes a JSON object\nkeyed by the query keys, with an array of string values to match for that key.\nQuery key matches are exact, but wildcards may be used for value matches. Both\nkeys and values may be placeholders.\nAn example of the structure to match `?key=value\u0026topic=api\u0026query=something` is:\n\n```json\n{\n\t\"key\": [\"value\"],\n\t\"topic\": [\"api\"],\n\t\"query\": [\"*\"]\n}\n```\n\nInvalid query strings, including those with bad escapings or illegal characters\nlike semicolons, will fail to parse and thus fail to match.\n \n",
"description":"remote_ip: object\nModule: http.matchers.remote_ip\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRemoteIP\nMatchRemoteIP matches requests by client IP (or CIDR range).\n\n",
"markdownDescription":"remote_ip: `object` \nModule: `http.matchers.remote_ip` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRemoteIP) \nMatchRemoteIP matches requests by client IP (or CIDR range).\n \n",
"type":"object",
"properties":{
"forwarded":{
"description":"forwarded: boolean\nModule: http.matchers.remote_ip\nIf true, prefer the first IP in the request's X-Forwarded-For\nheader, if present, rather than the immediate peer's IP, as\nthe reference IP against which to match. Note that it is easy\nto spoof request headers. Default: false\n",
"markdownDescription":"forwarded: `boolean` \nModule: `http.matchers.remote_ip` \nIf true, prefer the first IP in the request's X-Forwarded-For\nheader, if present, rather than the immediate peer's IP, as\nthe reference IP against which to match. Note that it is easy\nto spoof request headers. Default: false \n",
"type":"boolean"
},
"ranges":{
"description":"ranges: array\nModule: http.matchers.remote_ip\nThe IPs or CIDR ranges to match.\n",
"markdownDescription":"ranges: `array` \nModule: `http.matchers.remote_ip` \nThe IPs or CIDR ranges to match. \n",
"type":"array",
"items":{
"description":"The IPs or CIDR ranges to match.\n",
"markdownDescription":"The IPs or CIDR ranges to match. \n",
"description":"vars: object\nModule: http.matchers.vars\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#VarsMatcher\nVarsMatcher is an HTTP request matcher which can match\nrequests based on variables in the context or placeholder\nvalues. The key is the placeholder or name of the variable,\nand the values are possible values the variable can be in\norder to match (logical OR'ed).\n\nIf the key is surrounded by `{ }` it is assumed to be a\nplaceholder. Otherwise, it will be considered a variable\nname.\n\nPlaceholders in the keys are not expanded, but\nplaceholders in the values are.\n\n",
"markdownDescription":"vars: `object` \nModule: `http.matchers.vars` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#VarsMatcher) \nVarsMatcher is an HTTP request matcher which can match\nrequests based on variables in the context or placeholder\nvalues. The key is the placeholder or name of the variable,\nand the values are possible values the variable can be in\norder to match (logical OR'ed).\n\nIf the key is surrounded by `{ }` it is assumed to be a\nplaceholder. Otherwise, it will be considered a variable\nname.\n\nPlaceholders in the keys are not expanded, but\nplaceholders in the values are.\n \n",
"description":"vars_regexp: object\nModule: http.matchers.vars_regexp\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp\nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n\n",
"markdownDescription":"vars_regexp: `object` \nModule: `http.matchers.vars_regexp` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp) \nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n \n",
"type":"object",
"additionalProperties":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp\nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp#MatchRegexp) \nMatchRegexp is an embedable type for matching\nusing regular expressions. It adds placeholders\nto the request's replacer.\n \n",
"properties":{
"name":{
"description":"name: string\nModule: http.matchers.vars_regexp\nA unique name for this regular expression. Optional,\nbut useful to prevent overwriting captures from other\nregexp matchers.\n",
"markdownDescription":"name: `string` \nModule: `http.matchers.vars_regexp` \nA unique name for this regular expression. Optional,\nbut useful to prevent overwriting captures from other\nregexp matchers. \n",
"type":"string"
},
"pattern":{
"description":"pattern: string\nModule: http.matchers.vars_regexp\nThe regular expression to evaluate, in RE2 syntax,\nwhich is the same general syntax used by Go, Perl,\nand Python. For details, see\n[Go's regexp package](https://golang.org/pkg/regexp/).\nCaptures are accessible via placeholders. Unnamed\ncapture groups are exposed as their numeric, 1-based\nindex, while named capture groups are available by\nthe capture group name.\n",
"markdownDescription":"pattern: `string` \nModule: `http.matchers.vars_regexp` \nThe regular expression to evaluate, in RE2 syntax,\nwhich is the same general syntax used by Go, Perl,\nand Python. For details, see\n[Go's regexp package](https://golang.org/pkg/regexp/).\nCaptures are accessible via placeholders. Unnamed\ncapture groups are exposed as their numeric, 1-based\nindex, while named capture groups are available by\nthe capture group name. \n",
"description":"layer4: object\nModule: layer4\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/layer4#App\nApp is a Caddy app that operates closest to layer 4 of the OSI model.\n\n",
"markdownDescription":"layer4: `object` \nModule: `layer4` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/layer4#App) \nApp is a Caddy app that operates closest to layer 4 of the OSI model.\n \n",
"type":"object",
"properties":{
"servers":{
"description":"servers: object\nModule: layer4\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/layer4#Server\nServer represents a Caddy layer4 server.\n\n",
"description":"routes: array\nModule: layer4\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/layer4#Route\nRoute represents a collection of handlers that are gated\nby matching and other kinds of logic.\n\n",
"markdownDescription":"routes: `array` \nModule: `layer4` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/layer4#Route) \nRoute represents a collection of handlers that are gated\nby matching and other kinds of logic.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/mholt/caddy-l4/layer4#Route\nRoute represents a collection of handlers that are gated\nby matching and other kinds of logic.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/layer4#Route) \nRoute represents a collection of handlers that are gated\nby matching and other kinds of logic.\n \n",
"description":"match: array\nModule: layer4.matchers\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n\n",
"markdownDescription":"match: `array` \nModule: `layer4.matchers` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n \n",
"description":"echo: object\nModule: layer4.handlers.echo\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4echo#Handler\nHandler is a simple handler that writes what it reads.\n\n",
"markdownDescription":"echo: `object` \nModule: `layer4.handlers.echo` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4echo#Handler) \nHandler is a simple handler that writes what it reads.\n \n",
"type":"object"
},
"layer4.handlers.proxy":{
"description":"proxy: object\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#Handler\nHandler is a handler that can proxy connections.\n\n",
"markdownDescription":"proxy: `object` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#Handler) \nHandler is a handler that can proxy connections.\n \n",
"type":"object",
"properties":{
"health_checks":{
"description":"health_checks: object\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#HealthChecks\nHealth checks update the status of backends, whether they are\nup or down. Down backends will not be proxied to.\n\n\nHealthChecks configures active and passive health checks.\n",
"markdownDescription":"health_checks: `object` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#HealthChecks) \nHealth checks update the status of backends, whether they are\nup or down. Down backends will not be proxied to.\n\n\nHealthChecks configures active and passive health checks. \n",
"type":"object",
"properties":{
"active":{
"description":"active: object\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#ActiveHealthChecks\nActive health checks run in the background on a timer. To\nminimally enable active health checks, set either path or\nport (or both).\n\n\nActiveHealthChecks holds configuration related to active health\nchecks (that is, health checks which occur independently in a\nbackground goroutine).\n",
"markdownDescription":"active: `object` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#ActiveHealthChecks) \nActive health checks run in the background on a timer. To\nminimally enable active health checks, set either path or\nport (or both).\n\n\nActiveHealthChecks holds configuration related to active health\nchecks (that is, health checks which occur independently in a\nbackground goroutine). \n",
"type":"object",
"properties":{
"interval":{
"description":"interval: number\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow frequently to perform active health checks (default 30s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"interval: `number` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow frequently to perform active health checks (default 30s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"port":{
"description":"port: number\nModule: layer4.handlers.proxy\nThe port to use (if different from the upstream's dial\naddress) for health checks.\n",
"markdownDescription":"port: `number` \nModule: `layer4.handlers.proxy` \nThe port to use (if different from the upstream's dial\naddress) for health checks. \n",
"type":"number"
},
"timeout":{
"description":"timeout: number\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait for a connection to be established with\npeer before considering it unhealthy (default 5s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"timeout: `number` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait for a connection to be established with\npeer before considering it unhealthy (default 5s).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
},
"passive":{
"description":"passive: object\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#PassiveHealthChecks\nPassive health checks monitor proxied connections for errors or timeouts.\nTo minimally enable passive health checks, specify at least an empty\nconfig object.\n\n\nPassiveHealthChecks holds configuration related to passive\nhealth checks (that is, health checks which occur during\nthe normal flow of connection proxying).\n",
"markdownDescription":"passive: `object` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#PassiveHealthChecks) \nPassive health checks monitor proxied connections for errors or timeouts.\nTo minimally enable passive health checks, specify at least an empty\nconfig object.\n\n\nPassiveHealthChecks holds configuration related to passive\nhealth checks (that is, health checks which occur during\nthe normal flow of connection proxying). \n",
"type":"object",
"properties":{
"fail_duration":{
"description":"fail_duration: number\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to remember a failed connection to a backend. A\nduration \u003e 0 enables passive health checking. Default 0.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"fail_duration: `number` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to remember a failed connection to a backend. A\nduration \u003e 0 enables passive health checking. Default 0.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"max_fails":{
"description":"max_fails: number\nModule: layer4.handlers.proxy\nThe number of failed connections within the FailDuration window to\nconsider a backend as \"down\". Must be \u003e= 1; default is 1. Requires\nthat FailDuration be \u003e 0.\n",
"markdownDescription":"max_fails: `number` \nModule: `layer4.handlers.proxy` \nThe number of failed connections within the FailDuration window to\nconsider a backend as \"down\". Must be \u003e= 1; default is 1. Requires\nthat FailDuration be \u003e 0. \n",
"type":"number"
},
"unhealthy_connnection_count":{
"description":"unhealthy_connnection_count: number\nModule: layer4.handlers.proxy\nLimits the number of simultaneous connections to a backend by\nmarking the backend as \"down\" if it has this many or more\nconcurrent connections.\n",
"markdownDescription":"unhealthy_connnection_count: `number` \nModule: `layer4.handlers.proxy` \nLimits the number of simultaneous connections to a backend by\nmarking the backend as \"down\" if it has this many or more\nconcurrent connections. \n",
"type":"number"
}
}
}
}
},
"load_balancing":{
"description":"load_balancing: object\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#LoadBalancing\nLoad balancing distributes load/connections between backends.\n\n\nLoadBalancing has parameters related to load balancing.\n",
"markdownDescription":"load_balancing: `object` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#LoadBalancing) \nLoad balancing distributes load/connections between backends.\n\n\nLoadBalancing has parameters related to load balancing. \n",
"type":"object",
"properties":{
"selection":{
"description":"selection: object\nModule: layer4.proxy.selection_policies\nA selection policy is how to choose an available backend.\nThe default policy is random selection.\n",
"markdownDescription":"selection: `object` \nModule: `layer4.proxy.selection_policies` \nA selection policy is how to choose an available backend.\nThe default policy is random selection. \n",
"description":"try_duration: number\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to try selecting available backends for each connection\nif the next available host is down. By default, this retry is\ndisabled. Clients will wait for up to this long while the load\nbalancer tries to find an available upstream host.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"try_duration: `number` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to try selecting available backends for each connection\nif the next available host is down. By default, this retry is\ndisabled. Clients will wait for up to this long while the load\nbalancer tries to find an available upstream host.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"try_interval":{
"description":"try_interval: number\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait between selecting the next host from the pool. Default\nis 250ms. Only relevant when a connection to an upstream host fails. Be\naware that setting this to 0 with a non-zero try_duration can cause the\nCPU to spin if all backends are down and latency is very low.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"try_interval: `number` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait between selecting the next host from the pool. Default\nis 250ms. Only relevant when a connection to an upstream host fails. Be\naware that setting this to 0 with a non-zero try_duration can cause the\nCPU to spin if all backends are down and latency is very low.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
},
"proxy_protocol":{
"description":"proxy_protocol: string\nModule: layer4.handlers.proxy\nSpecifies the version of the Proxy Protocol header to add, either \"v1\" or \"v2\".\nRef: https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt\n",
"markdownDescription":"proxy_protocol: `string` \nModule: `layer4.handlers.proxy` \nSpecifies the version of the Proxy Protocol header to add, either \"v1\" or \"v2\".\nRef: https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt \n",
"type":"string"
},
"upstreams":{
"description":"upstreams: array\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#Upstream\nUpstreams is the list of backends to proxy to.\n\n\nUpstream represents a proxy upstream.\n",
"markdownDescription":"upstreams: `array` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#Upstream) \nUpstreams is the list of backends to proxy to.\n\n\nUpstream represents a proxy upstream. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#Upstream\nUpstreams is the list of backends to proxy to.\n\n\nUpstream represents a proxy upstream.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxy#Upstream) \nUpstreams is the list of backends to proxy to.\n\n\nUpstream represents a proxy upstream. \n",
"type":"object",
"properties":{
"dial":{
"description":"dial: array\nModule: layer4.handlers.proxy\nThe network addresses to dial. Supports placeholders, but not port\nranges currently (each address must be exactly 1 socket).\n",
"markdownDescription":"dial: `array` \nModule: `layer4.handlers.proxy` \nThe network addresses to dial. Supports placeholders, but not port\nranges currently (each address must be exactly 1 socket). \n",
"type":"array",
"items":{
"description":"The network addresses to dial. Supports placeholders, but not port\nranges currently (each address must be exactly 1 socket).\n",
"markdownDescription":"The network addresses to dial. Supports placeholders, but not port\nranges currently (each address must be exactly 1 socket). \n",
"type":"string"
}
},
"max_connections":{
"description":"max_connections: number\nModule: layer4.handlers.proxy\nHow many connections this upstream is allowed to\nhave before being marked as unhealthy (if \u003e 0).\n",
"markdownDescription":"max_connections: `number` \nModule: `layer4.handlers.proxy` \nHow many connections this upstream is allowed to\nhave before being marked as unhealthy (if \u003e 0). \n",
"type":"number"
},
"tls":{
"description":"tls: object\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#TLSConfig\nSet this field to enable TLS to the upstream.\n\n\nTLSConfig holds configuration related to the TLS configuration for the\ntransport/client.\n",
"markdownDescription":"tls: `object` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy#TLSConfig) \nSet this field to enable TLS to the upstream.\n\n\nTLSConfig holds configuration related to the TLS configuration for the\ntransport/client. \n",
"type":"object",
"properties":{
"client_certificate_automate":{
"description":"client_certificate_automate: string\nModule: layer4.handlers.proxy\nIf specified, Caddy will use and automate a client certificate\nwith this subject name.\n",
"markdownDescription":"client_certificate_automate: `string` \nModule: `layer4.handlers.proxy` \nIf specified, Caddy will use and automate a client certificate\nwith this subject name. \n",
"type":"string"
},
"client_certificate_file":{
"description":"client_certificate_file: string\nModule: layer4.handlers.proxy\nPEM-encoded client certificate filename to present to servers.\n",
"markdownDescription":"client_certificate_file: `string` \nModule: `layer4.handlers.proxy` \nPEM-encoded client certificate filename to present to servers. \n",
"type":"string"
},
"client_certificate_key_file":{
"description":"client_certificate_key_file: string\nModule: layer4.handlers.proxy\nPEM-encoded key to use with the client certificate.\n",
"markdownDescription":"client_certificate_key_file: `string` \nModule: `layer4.handlers.proxy` \nPEM-encoded key to use with the client certificate. \n",
"description":"except_ports: array\nModule: layer4.handlers.proxy\nSkip TLS ports specifies a list of upstream ports on which TLS should not be\nattempted even if it is configured. Handy when using dynamic upstreams that\nreturn HTTP and HTTPS endpoints too.\nWhen specified, TLS will automatically be configured on the transport.\nThe value can be a list of any valid tcp port numbers, default empty.\n",
"markdownDescription":"except_ports: `array` \nModule: `layer4.handlers.proxy` \nSkip TLS ports specifies a list of upstream ports on which TLS should not be\nattempted even if it is configured. Handy when using dynamic upstreams that\nreturn HTTP and HTTPS endpoints too.\nWhen specified, TLS will automatically be configured on the transport.\nThe value can be a list of any valid tcp port numbers, default empty. \n",
"description":"Skip TLS ports specifies a list of upstream ports on which TLS should not be\nattempted even if it is configured. Handy when using dynamic upstreams that\nreturn HTTP and HTTPS endpoints too.\nWhen specified, TLS will automatically be configured on the transport.\nThe value can be a list of any valid tcp port numbers, default empty.\n",
"markdownDescription":"Skip TLS ports specifies a list of upstream ports on which TLS should not be\nattempted even if it is configured. Handy when using dynamic upstreams that\nreturn HTTP and HTTPS endpoints too.\nWhen specified, TLS will automatically be configured on the transport.\nThe value can be a list of any valid tcp port numbers, default empty. \n",
"description":"handshake_timeout: number\nModule: layer4.handlers.proxy\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nThe duration to allow a TLS handshake to a server. Default: No timeout.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"handshake_timeout: `number` \nModule: `layer4.handlers.proxy` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nThe duration to allow a TLS handshake to a server. Default: No timeout.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"insecure_skip_verify":{
"description":"insecure_skip_verify: boolean\nModule: layer4.handlers.proxy\nIf true, TLS verification of server certificates will be disabled.\nThis is insecure and may be removed in the future. Do not use this\noption except in testing or local development environments.\n",
"markdownDescription":"insecure_skip_verify: `boolean` \nModule: `layer4.handlers.proxy` \nIf true, TLS verification of server certificates will be disabled.\nThis is insecure and may be removed in the future. Do not use this\noption except in testing or local development environments. \n",
"description":"renegotiation: string\nModule: layer4.handlers.proxy\nTLS renegotiation level. TLS renegotiation is the act of performing\nsubsequent handshakes on a connection after the first.\nThe level can be:\n - \"never\": (the default) disables renegotiation.\n - \"once\": allows a remote server to request renegotiation once per connection.\n - \"freely\": allows a remote server to repeatedly request renegotiation.\n",
"markdownDescription":"renegotiation: `string` \nModule: `layer4.handlers.proxy` \nTLS renegotiation level. TLS renegotiation is the act of performing\nsubsequent handshakes on a connection after the first.\nThe level can be:\n - \"never\": (the default) disables renegotiation.\n - \"once\": allows a remote server to request renegotiation once per connection.\n - \"freely\": allows a remote server to repeatedly request renegotiation. \n",
"description":"root_ca_pem_files: array\nModule: layer4.handlers.proxy\nList of PEM-encoded CA certificate files to add to the same trust\nstore as RootCAPool (or root_ca_pool in the JSON).\n",
"markdownDescription":"root_ca_pem_files: `array` \nModule: `layer4.handlers.proxy` \nList of PEM-encoded CA certificate files to add to the same trust\nstore as RootCAPool (or root_ca_pool in the JSON). \n",
"type":"array",
"items":{
"description":"List of PEM-encoded CA certificate files to add to the same trust\nstore as RootCAPool (or root_ca_pool in the JSON).\n",
"markdownDescription":"List of PEM-encoded CA certificate files to add to the same trust\nstore as RootCAPool (or root_ca_pool in the JSON). \n",
"type":"string"
}
},
"root_ca_pool":{
"description":"root_ca_pool: array\nModule: layer4.handlers.proxy\nOptional list of base64-encoded DER-encoded CA certificates to trust.\n",
"markdownDescription":"root_ca_pool: `array` \nModule: `layer4.handlers.proxy` \nOptional list of base64-encoded DER-encoded CA certificates to trust. \n",
"type":"array",
"items":{
"description":"Optional list of base64-encoded DER-encoded CA certificates to trust.\n",
"markdownDescription":"Optional list of base64-encoded DER-encoded CA certificates to trust. \n",
"description":"server_name: string\nModule: layer4.handlers.proxy\nThe server name used when verifying the certificate received in the TLS\nhandshake. By default, this will use the upstream address' host part.\nYou only need to override this if your upstream address does not match the\ncertificate the upstream is likely to use. For example if the upstream\naddress is an IP address, then you would need to configure this to the\nhostname being served by the upstream server. Currently, this does not\nsupport placeholders because the TLS config is not provisioned on each\nconnection, so a static value must be used.\n",
"markdownDescription":"server_name: `string` \nModule: `layer4.handlers.proxy` \nThe server name used when verifying the certificate received in the TLS\nhandshake. By default, this will use the upstream address' host part.\nYou only need to override this if your upstream address does not match the\ncertificate the upstream is likely to use. For example if the upstream\naddress is an IP address, then you would need to configure this to the\nhostname being served by the upstream server. Currently, this does not\nsupport placeholders because the TLS config is not provisioned on each\nconnection, so a static value must be used. \n",
"description":"proxy_protocol: object\nModule: layer4.handlers.proxy_protocol\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxyprotocol#Handler\nHandler is a connection handler that accepts the PROXY protocol.\n\n",
"markdownDescription":"proxy_protocol: `object` \nModule: `layer4.handlers.proxy_protocol` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4proxyprotocol#Handler) \nHandler is a connection handler that accepts the PROXY protocol.\n \n",
"type":"object",
"properties":{
"allow":{
"description":"allow: array\nModule: layer4.handlers.proxy_protocol\nAn optional list of CIDR ranges to allow/require PROXY headers from.\n",
"markdownDescription":"allow: `array` \nModule: `layer4.handlers.proxy_protocol` \nAn optional list of CIDR ranges to allow/require PROXY headers from. \n",
"type":"array",
"items":{
"description":"An optional list of CIDR ranges to allow/require PROXY headers from.\n",
"markdownDescription":"An optional list of CIDR ranges to allow/require PROXY headers from. \n",
"type":"string"
}
},
"timeout":{
"description":"timeout: number\nModule: layer4.handlers.proxy_protocol\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait for the PROXY protocol header to be received.\nDefaults to zero, which means timeout is disabled.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"timeout: `number` \nModule: `layer4.handlers.proxy_protocol` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait for the PROXY protocol header to be received.\nDefaults to zero, which means timeout is disabled.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"tee: object\nModule: layer4.handlers.tee\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4tee#Handler\nHandler is a layer4 handler that replicates a connection so\nthat a branch of handlers can concurrently handle it. Reads\nhappen in lock-step with all concurrent branches so as to\navoid buffering: if one of the branches (including the main\nhandler chain) stops reading from the connection, it will\nblock all branches.\n\n",
"markdownDescription":"tee: `object` \nModule: `layer4.handlers.tee` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4tee#Handler) \nHandler is a layer4 handler that replicates a connection so\nthat a branch of handlers can concurrently handle it. Reads\nhappen in lock-step with all concurrent branches so as to\navoid buffering: if one of the branches (including the main\nhandler chain) stops reading from the connection, it will\nblock all branches.\n \n",
"type":"object",
"properties":{
"branch":{
"description":"branch: array\nModule: layer4.handlers\nHandlers is the list of handlers that constitute this\nconcurrent branch. Any handlers that do connection\nmatching (which involves recording and rewinding the\nstream) are unsafe to tee, so do all connection\nmatching before teeing.\n",
"markdownDescription":"branch: `array` \nModule: `layer4.handlers` \nHandlers is the list of handlers that constitute this\nconcurrent branch. Any handlers that do connection\nmatching (which involves recording and rewinding the\nstream) are unsafe to tee, so do all connection\nmatching before teeing. \n",
"type":"array",
"items":{
"description":"Handlers is the list of handlers that constitute this\nconcurrent branch. Any handlers that do connection\nmatching (which involves recording and rewinding the\nstream) are unsafe to tee, so do all connection\nmatching before teeing.\n",
"markdownDescription":"Handlers is the list of handlers that constitute this\nconcurrent branch. Any handlers that do connection\nmatching (which involves recording and rewinding the\nstream) are unsafe to tee, so do all connection\nmatching before teeing. \n",
"description":"latency: number\nModule: layer4.handlers.throttle\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nDelay before initial read on each connection.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"latency: `number` \nModule: `layer4.handlers.throttle` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nDelay before initial read on each connection.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"read_burst_size":{
"description":"read_burst_size: number\nModule: layer4.handlers.throttle\nThe maximum number of bytes to read at once (rate permitting) per connection.\nIf a rate is specified, burst must be greater than zero; default is same as\nthe rate (truncated to integer).\n",
"markdownDescription":"read_burst_size: `number` \nModule: `layer4.handlers.throttle` \nThe maximum number of bytes to read at once (rate permitting) per connection.\nIf a rate is specified, burst must be greater than zero; default is same as\nthe rate (truncated to integer). \n",
"type":"number"
},
"read_bytes_per_second":{
"description":"read_bytes_per_second: object\nModule: layer4.handlers.throttle\nThe number of bytes to read per second, per connection.\n",
"markdownDescription":"read_bytes_per_second: `object` \nModule: `layer4.handlers.throttle` \nThe number of bytes to read per second, per connection. \n",
"type":"object"
},
"total_read_burst_size":{
"description":"total_read_burst_size: number\nModule: layer4.handlers.throttle\nThe maximum number of bytes to read at once (rate permitting) across all\nconnections (\"per handler\"). If a rate is specified, burst must be greater\nthan zero; default is same as the rate (truncated to integer).\n",
"markdownDescription":"total_read_burst_size: `number` \nModule: `layer4.handlers.throttle` \nThe maximum number of bytes to read at once (rate permitting) across all\nconnections (\"per handler\"). If a rate is specified, burst must be greater\nthan zero; default is same as the rate (truncated to integer). \n",
"type":"number"
},
"total_read_bytes_per_second":{
"description":"total_read_bytes_per_second: object\nModule: layer4.handlers.throttle\nThe number of bytes to read per second, across all connections (\"per handler\").\n",
"markdownDescription":"total_read_bytes_per_second: `object` \nModule: `layer4.handlers.throttle` \nThe number of bytes to read per second, across all connections (\"per handler\"). \n",
"type":"object"
}
}
},
"layer4.handlers.tls":{
"description":"tls: object\nModule: layer4.handlers.tls\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4tls#Handler\nHandler is a connection handler that terminates TLS.\n\n",
"markdownDescription":"tls: `object` \nModule: `layer4.handlers.tls` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4tls#Handler) \nHandler is a connection handler that terminates TLS.\n \n",
"type":"object",
"properties":{
"connection_policies":{
"description":"connection_policies: array\nModule: layer4.handlers.tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy\nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used.\n\n",
"markdownDescription":"connection_policies: `array` \nModule: `layer4.handlers.tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy) \nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy\nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ConnectionPolicy) \nConnectionPolicy specifies the logic for handling a TLS handshake.\nAn empty policy is valid; safe and sensible defaults will be used.\n \n",
"type":"object",
"properties":{
"alpn":{
"description":"alpn: array\nModule: layer4.handlers.tls\nProtocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake.\n",
"markdownDescription":"alpn: `array` \nModule: `layer4.handlers.tls` \nProtocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake. \n",
"type":"array",
"items":{
"description":"Protocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake.\n",
"markdownDescription":"Protocols to use for Application-Layer Protocol\nNegotiation (ALPN) during the handshake. \n",
"type":"string"
}
},
"certificate_selection":{
"description":"certificate_selection: object\nModule: layer4.handlers.tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CustomCertSelectionPolicy\nHow to choose a certificate if more than one matched\nthe given ServerName (SNI) value.\n\n\nCustomCertSelectionPolicy represents a policy for selecting the certificate\nused to complete a handshake when there may be multiple options. All fields\nspecified must match the candidate certificate for it to be chosen.\nThis was needed to solve https://github.com/caddyserver/caddy/issues/2588.\n",
"markdownDescription":"certificate_selection: `object` \nModule: `layer4.handlers.tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CustomCertSelectionPolicy) \nHow to choose a certificate if more than one matched\nthe given ServerName (SNI) value.\n\n\nCustomCertSelectionPolicy represents a policy for selecting the certificate\nused to complete a handshake when there may be multiple options. All fields\nspecified must match the candidate certificate for it to be chosen.\nThis was needed to solve https://github.com/caddyserver/caddy/issues/2588. \n",
"type":"object",
"properties":{
"all_tags":{
"description":"all_tags: array\nModule: layer4.handlers.tls\nThe certificate must have all of the tags in the list.\n",
"markdownDescription":"all_tags: `array` \nModule: `layer4.handlers.tls` \nThe certificate must have all of the tags in the list. \n",
"type":"array",
"items":{
"description":"The certificate must have all of the tags in the list.\n",
"markdownDescription":"The certificate must have all of the tags in the list. \n",
"type":"string"
}
},
"any_tag":{
"description":"any_tag: array\nModule: layer4.handlers.tls\nThe certificate must have at least one of the tags in the list.\n",
"markdownDescription":"any_tag: `array` \nModule: `layer4.handlers.tls` \nThe certificate must have at least one of the tags in the list. \n",
"type":"array",
"items":{
"description":"The certificate must have at least one of the tags in the list.\n",
"markdownDescription":"The certificate must have at least one of the tags in the list. \n",
"type":"string"
}
},
"public_key_algorithm":{
"description":"public_key_algorithm: number\nModule: layer4.handlers.tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#PublicKeyAlgorithm\nThe certificate must use this public key algorithm.\n\n\nPublicKeyAlgorithm is a JSON-unmarshalable wrapper type.\n",
"markdownDescription":"public_key_algorithm: `number` \nModule: `layer4.handlers.tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#PublicKeyAlgorithm) \nThe certificate must use this public key algorithm.\n\n\nPublicKeyAlgorithm is a JSON-unmarshalable wrapper type. \n",
"type":"number"
},
"serial_number":{
"description":"serial_number: array\nModule: layer4.handlers.tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt\nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string.\n",
"markdownDescription":"serial_number: `array` \nModule: `layer4.handlers.tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt) \nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt\nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#bigInt) \nThe certificate must have one of these serial numbers.\n\n\nbigInt is a big.Int type that interops with JSON encodings as a string. \n",
"type":"object"
}
},
"subject_organization":{
"description":"subject_organization: array\nModule: layer4.handlers.tls\nThe certificate must have one of these organization names.\n",
"markdownDescription":"subject_organization: `array` \nModule: `layer4.handlers.tls` \nThe certificate must have one of these organization names. \n",
"type":"array",
"items":{
"description":"The certificate must have one of these organization names.\n",
"markdownDescription":"The certificate must have one of these organization names. \n",
"type":"string"
}
}
}
},
"cipher_suites":{
"description":"cipher_suites: array\nModule: layer4.handlers.tls\nThe list of cipher suites to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"cipher_suites: `array` \nModule: `layer4.handlers.tls` \nThe list of cipher suites to support. Caddy's\ndefaults are modern and secure. \n",
"type":"array",
"items":{
"description":"The list of cipher suites to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"The list of cipher suites to support. Caddy's\ndefaults are modern and secure. \n",
"description":"mode: string\nModule: layer4.handlers.tls\nThe mode for authenticating the client. Allowed values are:\n\nMode | Description\n-----|---------------\n`request` | Ask clients for a certificate, but allow even if there isn't one; do not verify it\n`require` | Require clients to present a certificate, but do not verify it\n`verify_if_given` | Ask clients for a certificate; allow even if there isn't one, but verify it if there is\n`require_and_verify` | Require clients to present a valid certificate that is verified\n\nThe default mode is `require_and_verify` if any\nTrustedCACerts or TrustedCACertPEMFiles or TrustedLeafCerts\nare provided; otherwise, the default mode is `require`.\n",
"markdownDescription":"mode: `string` \nModule: `layer4.handlers.tls` \nThe mode for authenticating the client. Allowed values are:\n\nMode | Description\n-----|---------------\n`request` | Ask clients for a certificate, but allow even if there isn't one; do not verify it\n`require` | Require clients to present a certificate, but do not verify it\n`verify_if_given` | Ask clients for a certificate; allow even if there isn't one, but verify it if there is\n`require_and_verify` | Require clients to present a valid certificate that is verified\n\nThe default mode is `require_and_verify` if any\nTrustedCACerts or TrustedCACertPEMFiles or TrustedLeafCerts\nare provided; otherwise, the default mode is `require`. \n",
"type":"string"
},
"trusted_ca_certs":{
"description":"trusted_ca_certs: array\nModule: layer4.handlers.tls\nA list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected.\n",
"markdownDescription":"trusted_ca_certs: `array` \nModule: `layer4.handlers.tls` \nA list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected. \n",
"type":"array",
"items":{
"description":"A list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected.\n",
"markdownDescription":"A list of base64 DER-encoded CA certificates\nagainst which to validate client certificates.\nClient certs which are not signed by any of\nthese CAs will be rejected. \n",
"type":"string"
}
},
"trusted_ca_certs_pem_files":{
"description":"trusted_ca_certs_pem_files: array\nModule: layer4.handlers.tls\nTrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected.\n",
"markdownDescription":"trusted_ca_certs_pem_files: `array` \nModule: `layer4.handlers.tls` \nTrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected. \n",
"type":"array",
"items":{
"description":"TrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected.\n",
"markdownDescription":"TrustedCACertPEMFiles is a list of PEM file names\nfrom which to load certificates of trusted CAs.\nClient certificates which are not signed by any of\nthese CA certificates will be rejected. \n",
"description":"trusted_leaf_certs: array\nModule: layer4.handlers.tls\nDEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected.\n",
"markdownDescription":"trusted_leaf_certs: `array` \nModule: `layer4.handlers.tls` \nDEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected. \n",
"description":"DEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected.\n",
"markdownDescription":"DEPRECATED: This field is deprecated and will be removed in\na future version. Please use the `validators` field instead\nwith the tls.client_auth.leaf module instead.\n\nA list of base64 DER-encoded client leaf certs\nto accept. If this list is not empty, client certs\nwhich are not in this list will be rejected. \n",
"description":"verifiers: array\nModule: tls.client_auth\nClient certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked.\n",
"markdownDescription":"verifiers: `array` \nModule: `tls.client_auth` \nClient certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked. \n",
"description":"Client certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked.\n",
"markdownDescription":"Client certificate verification modules. These can perform\ncustom client authentication checks, such as ensuring the\ncertificate is not revoked. \n",
"description":"key to identify verifiers module.\nverifier: string\nModule: tls.client_auth",
"markdownDescription":"key to identify `verifiers` module. \nverifier: `string` \nModule: `tls.client_auth`",
"type":"string",
"enum":[
"leaf"
]
}
}
}
]
}
}
}
},
"curves":{
"description":"curves: array\nModule: layer4.handlers.tls\nThe list of elliptic curves to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"curves: `array` \nModule: `layer4.handlers.tls` \nThe list of elliptic curves to support. Caddy's\ndefaults are modern and secure. \n",
"type":"array",
"items":{
"description":"The list of elliptic curves to support. Caddy's\ndefaults are modern and secure.\n",
"markdownDescription":"The list of elliptic curves to support. Caddy's\ndefaults are modern and secure. \n",
"type":"string"
}
},
"default_sni":{
"description":"default_sni: string\nModule: layer4.handlers.tls\nDefaultSNI becomes the ServerName in a ClientHello if there\nis no policy configured for the empty SNI value.\n",
"markdownDescription":"default_sni: `string` \nModule: `layer4.handlers.tls` \nDefaultSNI becomes the ServerName in a ClientHello if there\nis no policy configured for the empty SNI value. \n",
"description":"insecure_secrets_log: string\nModule: layer4.handlers.tls\nAlso known as \"SSLKEYLOGFILE\", TLS secrets will be written to\nthis file in NSS key log format which can then be parsed by\nWireshark and other tools. This is INSECURE as it allows other\nprograms or tools to decrypt TLS connections. However, this\ncapability can be useful for debugging and troubleshooting.\n**ENABLING THIS LOG COMPROMISES SECURITY!**\n\nThis feature is EXPERIMENTAL and subject to change or removal.\n",
"markdownDescription":"insecure_secrets_log: `string` \nModule: `layer4.handlers.tls` \nAlso known as \"SSLKEYLOGFILE\", TLS secrets will be written to\nthis file in NSS key log format which can then be parsed by\nWireshark and other tools. This is INSECURE as it allows other\nprograms or tools to decrypt TLS connections. However, this\ncapability can be useful for debugging and troubleshooting.\n**ENABLING THIS LOG COMPROMISES SECURITY!**\n\nThis feature is EXPERIMENTAL and subject to change or removal. \n",
"description":"match: object\nModule: tls.handshake_match\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nHow to match this policy with a TLS ClientHello. If\nthis policy is the first to match, it will be used.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"match: `object` \nModule: `tls.handshake_match` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nHow to match this policy with a TLS ClientHello. If\nthis policy is the first to match, it will be used.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"protocol_max: string\nModule: layer4.handlers.tls\nMaximum TLS protocol version to allow. Default: `tls1.3`\n",
"markdownDescription":"protocol_max: `string` \nModule: `layer4.handlers.tls` \nMaximum TLS protocol version to allow. Default: `tls1.3` \n",
"type":"string"
},
"protocol_min":{
"description":"protocol_min: string\nModule: layer4.handlers.tls\nMinimum TLS protocol version to allow. Default: `tls1.2`\n",
"markdownDescription":"protocol_min: `string` \nModule: `layer4.handlers.tls` \nMinimum TLS protocol version to allow. Default: `tls1.2` \n",
"type":"string"
}
}
}
}
}
},
"layer4.matchers.http":{
"description":"http: any\nModule: layer4.matchers.http\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4http#MatchHTTP\nMatchHTTP is able to match HTTP connections. The auto-generated\ndocumentation for this type is wrong; instead of an object, it\nis an array of matcher set objects.\n\n",
"markdownDescription":"http: `any` \nModule: `layer4.matchers.http` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4http#MatchHTTP) \nMatchHTTP is able to match HTTP connections. The auto-generated\ndocumentation for this type is wrong; instead of an object, it\nis an array of matcher set objects.\n \n"
},
"layer4.matchers.ip":{
"description":"ip: object\nModule: layer4.matchers.ip\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/layer4#MatchIP\nMatchIP matches requests by remote IP (or CIDR range).\n\n",
"markdownDescription":"ip: `object` \nModule: `layer4.matchers.ip` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/layer4#MatchIP) \nMatchIP matches requests by remote IP (or CIDR range).\n \n",
"description":"ssh: object\nModule: layer4.matchers.ssh\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4ssh#MatchSSH\nMatchSSH is able to match SSH connections.\n\n",
"markdownDescription":"ssh: `object` \nModule: `layer4.matchers.ssh` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4ssh#MatchSSH) \nMatchSSH is able to match SSH connections.\n \n",
"type":"object"
},
"layer4.matchers.tls":{
"description":"tls: any\nModule: layer4.matchers.tls\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4tls#MatchTLS\nMatchTLS is able to match TLS connections. Its structure\nis different from the auto-generated documentation. This\nvalue should be a map of matcher names to their values.\n\n",
"markdownDescription":"tls: `any` \nModule: `layer4.matchers.tls` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4tls#MatchTLS) \nMatchTLS is able to match TLS connections. Its structure\nis different from the auto-generated documentation. This\nvalue should be a map of matcher names to their values.\n \n"
},
"layer4.matchers.xmpp":{
"description":"xmpp: object\nModule: layer4.matchers.xmpp\nhttps://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4xmpp#MatchXMPP\nMatchXMPP is able to match XMPP connections.\n\n",
"markdownDescription":"xmpp: `object` \nModule: `layer4.matchers.xmpp` \n[godoc](https://pkg.go.dev/github.com/mholt/caddy-l4/modules/l4xmpp#MatchXMPP) \nMatchXMPP is able to match XMPP connections.\n \n",
"description":"pki: object\nModule: pki\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#PKI\nPKI provides Public Key Infrastructure facilities for Caddy.\n\nThis app can define certificate authorities (CAs) which are capable\nof signing certificates. Other modules can be configured to use\nthe CAs defined by this app for issuing certificates or getting\nkey information needed for establishing trust.\n\n",
"markdownDescription":"pki: `object` \nModule: `pki` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#PKI) \nPKI provides Public Key Infrastructure facilities for Caddy.\n\nThis app can define certificate authorities (CAs) which are capable\nof signing certificates. Other modules can be configured to use\nthe CAs defined by this app for issuing certificates or getting\nkey information needed for establishing trust.\n \n",
"type":"object",
"properties":{
"certificate_authorities":{
"description":"certificate_authorities: object\nModule: pki\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#CA\nThe certificate authorities to manage. Each CA is keyed by an\nID that is used to uniquely identify it from other CAs.\nAt runtime, the GetCA() method should be used instead to ensure\nthe default CA is provisioned if it hadn't already been.\nThe default CA ID is \"local\".\n\n\nCA describes a certificate authority, which consists of\nroot/signing certificates and various settings pertaining\nto the issuance of certificates and trusting them.\n",
"markdownDescription":"certificate_authorities: `object` \nModule: `pki` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#CA) \nThe certificate authorities to manage. Each CA is keyed by an\nID that is used to uniquely identify it from other CAs.\nAt runtime, the GetCA() method should be used instead to ensure\nthe default CA is provisioned if it hadn't already been.\nThe default CA ID is \"local\".\n\n\nCA describes a certificate authority, which consists of\nroot/signing certificates and various settings pertaining\nto the issuance of certificates and trusting them. \n",
"type":"object",
"additionalProperties":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#CA\nThe certificate authorities to manage. Each CA is keyed by an\nID that is used to uniquely identify it from other CAs.\nAt runtime, the GetCA() method should be used instead to ensure\nthe default CA is provisioned if it hadn't already been.\nThe default CA ID is \"local\".\n\n\nCA describes a certificate authority, which consists of\nroot/signing certificates and various settings pertaining\nto the issuance of certificates and trusting them.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#CA) \nThe certificate authorities to manage. Each CA is keyed by an\nID that is used to uniquely identify it from other CAs.\nAt runtime, the GetCA() method should be used instead to ensure\nthe default CA is provisioned if it hadn't already been.\nThe default CA ID is \"local\".\n\n\nCA describes a certificate authority, which consists of\nroot/signing certificates and various settings pertaining\nto the issuance of certificates and trusting them. \n",
"properties":{
"install_trust":{
"description":"install_trust: boolean\nModule: pki\nWhether Caddy will attempt to install the CA's root\ninto the system trust store, as well as into Java\nand Mozilla Firefox trust stores. Default: true.\n",
"markdownDescription":"install_trust: `boolean` \nModule: `pki` \nWhether Caddy will attempt to install the CA's root\ninto the system trust store, as well as into Java\nand Mozilla Firefox trust stores. Default: true. \n",
"type":"boolean"
},
"intermediate":{
"description":"intermediate: object\nModule: pki\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#KeyPair\nThe intermediate (signing) certificate; if null, one will be generated.\n\n\nKeyPair represents a public-private key pair, where the\npublic key is also called a certificate.\n",
"markdownDescription":"intermediate: `object` \nModule: `pki` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#KeyPair) \nThe intermediate (signing) certificate; if null, one will be generated.\n\n\nKeyPair represents a public-private key pair, where the\npublic key is also called a certificate. \n",
"description":"certificate: string\nModule: pki\nThe certificate. By default, this should be the path to\na PEM file unless format is something else.\n",
"markdownDescription":"certificate: `string` \nModule: `pki` \nThe certificate. By default, this should be the path to\na PEM file unless format is something else. \n",
"type":"string"
},
"format":{
"description":"format: string\nModule: pki\nThe format in which the certificate and private\nkey are provided. Default: pem_file\n",
"markdownDescription":"format: `string` \nModule: `pki` \nThe format in which the certificate and private\nkey are provided. Default: pem_file \n",
"type":"string"
},
"private_key":{
"description":"private_key: string\nModule: pki\nThe private key. By default, this should be the path to\na PEM file unless format is something else.\n",
"markdownDescription":"private_key: `string` \nModule: `pki` \nThe private key. By default, this should be the path to\na PEM file unless format is something else. \n",
"type":"string"
}
}
},
"intermediate_common_name":{
"description":"intermediate_common_name: string\nModule: pki\nThe name to put in the CommonName field of the\nintermediate certificates.\n",
"markdownDescription":"intermediate_common_name: `string` \nModule: `pki` \nThe name to put in the CommonName field of the\nintermediate certificates. \n",
"type":"string"
},
"name":{
"description":"name: string\nModule: pki\nThe user-facing name of the certificate authority.\n",
"markdownDescription":"name: `string` \nModule: `pki` \nThe user-facing name of the certificate authority. \n",
"type":"string"
},
"root":{
"description":"root: object\nModule: pki\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#KeyPair\nThe root certificate to use; if null, one will be generated.\n\n\nKeyPair represents a public-private key pair, where the\npublic key is also called a certificate.\n",
"markdownDescription":"root: `object` \nModule: `pki` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddypki#KeyPair) \nThe root certificate to use; if null, one will be generated.\n\n\nKeyPair represents a public-private key pair, where the\npublic key is also called a certificate. \n",
"type":"object",
"properties":{
"certificate":{
"description":"certificate: string\nModule: pki\nThe certificate. By default, this should be the path to\na PEM file unless format is something else.\n",
"markdownDescription":"certificate: `string` \nModule: `pki` \nThe certificate. By default, this should be the path to\na PEM file unless format is something else. \n",
"type":"string"
},
"format":{
"description":"format: string\nModule: pki\nThe format in which the certificate and private\nkey are provided. Default: pem_file\n",
"markdownDescription":"format: `string` \nModule: `pki` \nThe format in which the certificate and private\nkey are provided. Default: pem_file \n",
"type":"string"
},
"private_key":{
"description":"private_key: string\nModule: pki\nThe private key. By default, this should be the path to\na PEM file unless format is something else.\n",
"markdownDescription":"private_key: `string` \nModule: `pki` \nThe private key. By default, this should be the path to\na PEM file unless format is something else. \n",
"type":"string"
}
}
},
"root_common_name":{
"description":"root_common_name: string\nModule: pki\nThe name to put in the CommonName field of the\nroot certificate.\n",
"markdownDescription":"root_common_name: `string` \nModule: `pki` \nThe name to put in the CommonName field of the\nroot certificate. \n",
"type":"string"
},
"storage":{
"description":"storage: object\nModule: caddy.storage\nOptionally configure a separate storage module associated with this\nissuer, instead of using Caddy's global/default-configured storage.\nThis can be useful if you want to keep your signing keys in a\nseparate location from your leaf certificates.\n",
"markdownDescription":"storage: `object` \nModule: `caddy.storage` \nOptionally configure a separate storage module associated with this\nissuer, instead of using Caddy's global/default-configured storage.\nThis can be useful if you want to keep your signing keys in a\nseparate location from your leaf certificates. \n",
"type":"object",
"required":[
"module"
],
"allOf":[
{
"if":{
"properties":{
"module":{
"const":"consul"
}
}
},
"then":{
"$ref":"#/definitions/caddy.storage.consul"
}
},
{
"if":{
"properties":{
"module":{
"const":"file_system"
}
}
},
"then":{
"$ref":"#/definitions/caddy.storage.file_system"
}
},
{
"properties":{
"module":{
"description":"key to identify storage module.\nmodule: string\nModule: caddy.storage",
"markdownDescription":"key to identify `storage` module. \nmodule: `string` \nModule: `caddy.storage`",
"description":"config: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch#Config\nConfig is a configuration of Server.\n\n",
"markdownDescription":"config: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch#Config) \nConfig is a configuration of Server.\n \n",
"description":"access_list_configs: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration\nAccessListConfigs hold the configurations for the ACL of the token validator.\n\n\nRuleConfiguration consists of a list of conditions and and actions\n",
"markdownDescription":"access_list_configs: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration) \nAccessListConfigs hold the configurations for the ACL of the token validator.\n\n\nRuleConfiguration consists of a list of conditions and and actions \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration\nAccessListConfigs hold the configurations for the ACL of the token validator.\n\n\nRuleConfiguration consists of a list of conditions and and actions\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration) \nAccessListConfigs hold the configurations for the ACL of the token validator.\n\n\nRuleConfiguration consists of a list of conditions and and actions \n",
"description":"api: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn#APIConfig\nAPI holds the configuration for API endpoints.\n\n\nAPIConfig holds the configuration for API endpoints.\n",
"markdownDescription":"api: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn#APIConfig) \nAPI holds the configuration for API endpoints.\n\n\nAPIConfig holds the configuration for API endpoints. \n",
"description":"cookie_config: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/cookie#Config\nCookieConfig holds the configuration for the cookies issues by Authenticator.\n\n\nConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n",
"markdownDescription":"cookie_config: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/cookie#Config) \nCookieConfig holds the configuration for the cookies issues by Authenticator.\n\n\nConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator. \n",
"type":"object",
"properties":{
"domains":{
"description":"domains: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/cookie#DomainConfig\nDomainConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n\n",
"markdownDescription":"domains: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/cookie#DomainConfig) \nDomainConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n \n",
"type":"object",
"additionalProperties":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/cookie#DomainConfig\nDomainConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/cookie#DomainConfig) \nDomainConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n \n",
"description":"crypto_key_configs: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig\nCryptoKeyConfigs hold the configurations for the keys used to issue and validate user tokens.\n\n\nCryptoKeyConfig is common token-related configuration settings.\n",
"markdownDescription":"crypto_key_configs: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig) \nCryptoKeyConfigs hold the configurations for the keys used to issue and validate user tokens.\n\n\nCryptoKeyConfig is common token-related configuration settings. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig\nCryptoKeyConfigs hold the configurations for the keys used to issue and validate user tokens.\n\n\nCryptoKeyConfig is common token-related configuration settings.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig) \nCryptoKeyConfigs hold the configurations for the keys used to issue and validate user tokens.\n\n\nCryptoKeyConfig is common token-related configuration settings. \n",
"type":"object",
"properties":{
"algorithm":{
"description":"algorithm: string\nModule: security\nAlgorithm is either hmac, rsa, or ecdsa.\n",
"markdownDescription":"algorithm: `string` \nModule: `security` \nAlgorithm is either hmac, rsa, or ecdsa. \n",
"type":"string"
},
"dir_path":{
"description":"dir_path: string\nModule: security\nDirPath is the path to a directory containing crypto keys.\n",
"markdownDescription":"dir_path: `string` \nModule: `security` \nDirPath is the path to a directory containing crypto keys. \n",
"type":"string"
},
"env_var_name":{
"description":"env_var_name: string\nModule: security\nEnvVarName is the name of environment variables holding either the value of\na key or the path a directory or file containing a key.\n",
"markdownDescription":"env_var_name: `string` \nModule: `security` \nEnvVarName is the name of environment variables holding either the value of\na key or the path a directory or file containing a key. \n",
"type":"string"
},
"env_var_type":{
"description":"env_var_type: string\nModule: security\nEnvVarType indicates how to interpret the value found in the EnvVarName. If\nit is blank, then the assumption is the environment variable value\ncontains either public or private key.\n",
"markdownDescription":"env_var_type: `string` \nModule: `security` \nEnvVarType indicates how to interpret the value found in the EnvVarName. If\nit is blank, then the assumption is the environment variable value\ncontains either public or private key. \n",
"type":"string"
},
"env_var_value":{
"description":"env_var_value: string\nModule: security\nEnvVarValue is the value associated with the environment variable set by EnvVarName.\n",
"markdownDescription":"env_var_value: `string` \nModule: `security` \nEnvVarValue is the value associated with the environment variable set by EnvVarName. \n",
"type":"string"
},
"file_path":{
"description":"file_path: string\nModule: security\nFilePath is the path of a file containing either private or public key.\n",
"markdownDescription":"file_path: `string` \nModule: `security` \nFilePath is the path of a file containing either private or public key. \n",
"type":"string"
},
"id":{
"description":"id: string\nModule: security\nID is the key ID, aka kid.\n",
"markdownDescription":"id: `string` \nModule: `security` \nID is the key ID, aka kid. \n",
"type":"string"
},
"seq":{
"description":"seq: number\nModule: security\nSeq is the order in which a key would be processed.\n",
"markdownDescription":"seq: `number` \nModule: `security` \nSeq is the order in which a key would be processed. \n",
"type":"number"
},
"source":{
"description":"source: string\nModule: security\nSource is either config or env.\n",
"markdownDescription":"source: `string` \nModule: `security` \nSource is either config or env. \n",
"type":"string"
},
"token_eval_expr":{
"description":"token_eval_expr: array\nModule: security\nEvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification.\n",
"markdownDescription":"token_eval_expr: `array` \nModule: `security` \nEvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification. \n",
"type":"array",
"items":{
"description":"EvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification.\n",
"markdownDescription":"EvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification. \n",
"type":"string"
}
},
"token_lifetime":{
"description":"token_lifetime: number\nModule: security\nTokenLifetime is the expected token grant lifetime in seconds.\n",
"markdownDescription":"token_lifetime: `number` \nModule: `security` \nTokenLifetime is the expected token grant lifetime in seconds. \n",
"type":"number"
},
"token_name":{
"description":"token_name: string\nModule: security\nTokenName is the token name associated with the key.\n",
"markdownDescription":"token_name: `string` \nModule: `security` \nTokenName is the token name associated with the key. \n",
"type":"string"
},
"token_secret":{
"description":"token_secret: string\nModule: security\nSecret is the shared key used with HMAC algorithm.\n",
"markdownDescription":"token_secret: `string` \nModule: `security` \nSecret is the shared key used with HMAC algorithm. \n",
"type":"string"
},
"token_sign_method":{
"description":"token_sign_method: string\nModule: security\nPreferredSignMethod is the preferred method to sign tokens, e.g.\nall HMAC keys could use HS256, HS384, and HS512 methods. By default,\nthe preferred method is HS512. However, one may prefer using HS256.\n",
"markdownDescription":"token_sign_method: `string` \nModule: `security` \nPreferredSignMethod is the preferred method to sign tokens, e.g.\nall HMAC keys could use HS256, HS384, and HS512 methods. By default,\nthe preferred method is HS512. However, one may prefer using HS256. \n",
"type":"string"
},
"usage":{
"description":"usage: string\nModule: security\nUsage is the intended key usage. The values are: sign, verify, both,\nor auto.\n",
"markdownDescription":"usage: `string` \nModule: `security` \nUsage is the intended key usage. The values are: sign, verify, both,\nor auto. \n",
"type":"string"
}
}
}
},
"crypto_key_store_config":{
"description":"crypto_key_store_config: object\nModule: security\nCryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime.\n",
"markdownDescription":"crypto_key_store_config: `object` \nModule: `security` \nCryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime. \n",
"type":"object",
"additionalProperties":{
"description":"CryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime.\n",
"markdownDescription":"CryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime. \n"
}
},
"identity_providers":{
"description":"identity_providers: array\nModule: security\nThe names of identity providers.\n",
"markdownDescription":"identity_providers: `array` \nModule: `security` \nThe names of identity providers. \n",
"type":"array",
"items":{
"description":"The names of identity providers.\n",
"markdownDescription":"The names of identity providers. \n",
"type":"string"
}
},
"identity_stores":{
"description":"identity_stores: array\nModule: security\nThe names of identity stores.\n",
"markdownDescription":"identity_stores: `array` \nModule: `security` \nThe names of identity stores. \n",
"type":"array",
"items":{
"description":"The names of identity stores.\n",
"markdownDescription":"The names of identity stores. \n",
"description":"token_grantor_options: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/options#TokenGrantorOptions\nTokenGrantorOptions holds the configuration for the tokens issues by Authenticator.\n\n\nTokenGrantorOptions provides options for TokenGrantor.\n",
"markdownDescription":"token_grantor_options: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/options#TokenGrantorOptions) \nTokenGrantorOptions holds the configuration for the tokens issues by Authenticator.\n\n\nTokenGrantorOptions provides options for TokenGrantor. \n",
"description":"token_validator_options: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/options#TokenValidatorOptions\nTokenValidatorOptions holds the configuration for the token validator.\n\n\nTokenValidatorOptions provides options for TokenValidator.\n",
"markdownDescription":"token_validator_options: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/options#TokenValidatorOptions) \nTokenValidatorOptions holds the configuration for the token validator.\n\n\nTokenValidatorOptions provides options for TokenValidator. \n",
"description":"ui: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#Parameters\nUI holds the configuration for the user interface.\n\n\nParameters represent a common set of configuration settings\nfor HTML UI.\n",
"markdownDescription":"ui: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#Parameters) \nUI holds the configuration for the user interface.\n\n\nParameters represent a common set of configuration settings\nfor HTML UI. \n",
"description":"private_links: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#Link\nLink represents a single HTML link.\n\n",
"markdownDescription":"private_links: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#Link) \nLink represents a single HTML link.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#Link\nLink represents a single HTML link.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#Link) \nLink represents a single HTML link.\n \n",
"description":"realms: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#UserRealm\nUserRealm represents a single authentication realm/domain.\n\n",
"markdownDescription":"realms: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#UserRealm) \nUserRealm represents a single authentication realm/domain.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#UserRealm\nUserRealm represents a single authentication realm/domain.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/ui#UserRealm) \nUserRealm represents a single authentication realm/domain.\n \n",
"description":"user_transformer_configs: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/transformer#Config\nUserTransformerConfig holds the configuration for the user transformer.\n\n\nConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n",
"markdownDescription":"user_transformer_configs: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/transformer#Config) \nUserTransformerConfig holds the configuration for the user transformer.\n\n\nConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/transformer#Config\nUserTransformerConfig holds the configuration for the user transformer.\n\n\nConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authn/transformer#Config) \nUserTransformerConfig holds the configuration for the user transformer.\n\n\nConfig represents a common set of configuration settings\napplicable to the cookies issued by authn.Authenticator. \n",
"description":"authorization_policies: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz#PolicyConfig\nPolicyConfig is Gatekeeper configuration.\n\n",
"markdownDescription":"authorization_policies: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz#PolicyConfig) \nPolicyConfig is Gatekeeper configuration.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz#PolicyConfig\nPolicyConfig is Gatekeeper configuration.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz#PolicyConfig) \nPolicyConfig is Gatekeeper configuration.\n \n",
"type":"object",
"properties":{
"access_list_rules":{
"description":"access_list_rules: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration\nRuleConfiguration consists of a list of conditions and and actions\n\n",
"markdownDescription":"access_list_rules: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration) \nRuleConfiguration consists of a list of conditions and and actions\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration\nRuleConfiguration consists of a list of conditions and and actions\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/acl#RuleConfiguration) \nRuleConfiguration consists of a list of conditions and and actions\n \n",
"description":"auth_proxy_config: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authproxy#Config\nConfig is a config for an identity provider.\n\n",
"markdownDescription":"auth_proxy_config: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authproxy#Config) \nConfig is a config for an identity provider.\n \n",
"type":"object",
"properties":{
"api_key_auth":{
"description":"api_key_auth: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authproxy#APIKeyAuthConfig\nAPIKeyAuthConfig is a config for API key-based authentication.\n\n",
"markdownDescription":"api_key_auth: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authproxy#APIKeyAuthConfig) \nAPIKeyAuthConfig is a config for API key-based authentication.\n \n",
"description":"basic_auth: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authproxy#BasicAuthConfig\nBasicAuthConfig is a config for basic authentication.\n\n",
"markdownDescription":"basic_auth: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authproxy#BasicAuthConfig) \nBasicAuthConfig is a config for basic authentication.\n \n",
"description":"bypass_configs: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/bypass#Config\nThe list of URI prefixes which bypass authorization.\n\n\nConfig contains the entry for the authorization bypass.\n",
"markdownDescription":"bypass_configs: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/bypass#Config) \nThe list of URI prefixes which bypass authorization.\n\n\nConfig contains the entry for the authorization bypass. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/bypass#Config\nThe list of URI prefixes which bypass authorization.\n\n\nConfig contains the entry for the authorization bypass.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/bypass#Config) \nThe list of URI prefixes which bypass authorization.\n\n\nConfig contains the entry for the authorization bypass. \n",
"description":"crypto_key_configs: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig\nCryptoKeyConfig is common token-related configuration settings.\n\n",
"markdownDescription":"crypto_key_configs: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig) \nCryptoKeyConfig is common token-related configuration settings.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig\nCryptoKeyConfig is common token-related configuration settings.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/kms#CryptoKeyConfig) \nCryptoKeyConfig is common token-related configuration settings.\n \n",
"type":"object",
"properties":{
"algorithm":{
"description":"algorithm: string\nModule: security\nAlgorithm is either hmac, rsa, or ecdsa.\n",
"markdownDescription":"algorithm: `string` \nModule: `security` \nAlgorithm is either hmac, rsa, or ecdsa. \n",
"type":"string"
},
"dir_path":{
"description":"dir_path: string\nModule: security\nDirPath is the path to a directory containing crypto keys.\n",
"markdownDescription":"dir_path: `string` \nModule: `security` \nDirPath is the path to a directory containing crypto keys. \n",
"type":"string"
},
"env_var_name":{
"description":"env_var_name: string\nModule: security\nEnvVarName is the name of environment variables holding either the value of\na key or the path a directory or file containing a key.\n",
"markdownDescription":"env_var_name: `string` \nModule: `security` \nEnvVarName is the name of environment variables holding either the value of\na key or the path a directory or file containing a key. \n",
"type":"string"
},
"env_var_type":{
"description":"env_var_type: string\nModule: security\nEnvVarType indicates how to interpret the value found in the EnvVarName. If\nit is blank, then the assumption is the environment variable value\ncontains either public or private key.\n",
"markdownDescription":"env_var_type: `string` \nModule: `security` \nEnvVarType indicates how to interpret the value found in the EnvVarName. If\nit is blank, then the assumption is the environment variable value\ncontains either public or private key. \n",
"type":"string"
},
"env_var_value":{
"description":"env_var_value: string\nModule: security\nEnvVarValue is the value associated with the environment variable set by EnvVarName.\n",
"markdownDescription":"env_var_value: `string` \nModule: `security` \nEnvVarValue is the value associated with the environment variable set by EnvVarName. \n",
"type":"string"
},
"file_path":{
"description":"file_path: string\nModule: security\nFilePath is the path of a file containing either private or public key.\n",
"markdownDescription":"file_path: `string` \nModule: `security` \nFilePath is the path of a file containing either private or public key. \n",
"type":"string"
},
"id":{
"description":"id: string\nModule: security\nID is the key ID, aka kid.\n",
"markdownDescription":"id: `string` \nModule: `security` \nID is the key ID, aka kid. \n",
"type":"string"
},
"seq":{
"description":"seq: number\nModule: security\nSeq is the order in which a key would be processed.\n",
"markdownDescription":"seq: `number` \nModule: `security` \nSeq is the order in which a key would be processed. \n",
"type":"number"
},
"source":{
"description":"source: string\nModule: security\nSource is either config or env.\n",
"markdownDescription":"source: `string` \nModule: `security` \nSource is either config or env. \n",
"type":"string"
},
"token_eval_expr":{
"description":"token_eval_expr: array\nModule: security\nEvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification.\n",
"markdownDescription":"token_eval_expr: `array` \nModule: `security` \nEvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification. \n",
"type":"array",
"items":{
"description":"EvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification.\n",
"markdownDescription":"EvalExpr is a list of expressions evaluated whether a specific key\nshould be used for signing and verification. \n",
"type":"string"
}
},
"token_lifetime":{
"description":"token_lifetime: number\nModule: security\nTokenLifetime is the expected token grant lifetime in seconds.\n",
"markdownDescription":"token_lifetime: `number` \nModule: `security` \nTokenLifetime is the expected token grant lifetime in seconds. \n",
"type":"number"
},
"token_name":{
"description":"token_name: string\nModule: security\nTokenName is the token name associated with the key.\n",
"markdownDescription":"token_name: `string` \nModule: `security` \nTokenName is the token name associated with the key. \n",
"type":"string"
},
"token_secret":{
"description":"token_secret: string\nModule: security\nSecret is the shared key used with HMAC algorithm.\n",
"markdownDescription":"token_secret: `string` \nModule: `security` \nSecret is the shared key used with HMAC algorithm. \n",
"type":"string"
},
"token_sign_method":{
"description":"token_sign_method: string\nModule: security\nPreferredSignMethod is the preferred method to sign tokens, e.g.\nall HMAC keys could use HS256, HS384, and HS512 methods. By default,\nthe preferred method is HS512. However, one may prefer using HS256.\n",
"markdownDescription":"token_sign_method: `string` \nModule: `security` \nPreferredSignMethod is the preferred method to sign tokens, e.g.\nall HMAC keys could use HS256, HS384, and HS512 methods. By default,\nthe preferred method is HS512. However, one may prefer using HS256. \n",
"type":"string"
},
"usage":{
"description":"usage: string\nModule: security\nUsage is the intended key usage. The values are: sign, verify, both,\nor auto.\n",
"markdownDescription":"usage: `string` \nModule: `security` \nUsage is the intended key usage. The values are: sign, verify, both,\nor auto. \n",
"type":"string"
}
}
}
},
"crypto_key_store_config":{
"description":"crypto_key_store_config: object\nModule: security\nCryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime.\n",
"markdownDescription":"crypto_key_store_config: `object` \nModule: `security` \nCryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime. \n",
"type":"object",
"additionalProperties":{
"description":"CryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime.\n",
"markdownDescription":"CryptoKeyStoreConfig hold the default configuration for the keys, e.g. token name and lifetime. \n"
"description":"header_injection_configs: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/injector#Config\nThe list of mappings between header names and field names.\n\n\nConfig contains the entry for the HTTP header injection.\n",
"markdownDescription":"header_injection_configs: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/injector#Config) \nThe list of mappings between header names and field names.\n\n\nConfig contains the entry for the HTTP header injection. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/injector#Config\nThe list of mappings between header names and field names.\n\n\nConfig contains the entry for the HTTP header injection.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/authz/injector#Config) \nThe list of mappings between header names and field names.\n\n\nConfig contains the entry for the HTTP header injection. \n",
"description":"pass_claims_with_headers: boolean\nModule: security\nPass claims from JWT token via HTTP X- headers.\n",
"markdownDescription":"pass_claims_with_headers: `boolean` \nModule: `security` \nPass claims from JWT token via HTTP X- headers. \n",
"type":"boolean"
},
"redirect_with_javascript":{
"description":"redirect_with_javascript: boolean\nModule: security\nEnable the redirect with Javascript, as opposed to HTTP redirect.\n",
"markdownDescription":"redirect_with_javascript: `boolean` \nModule: `security` \nEnable the redirect with Javascript, as opposed to HTTP redirect. \n",
"description":"validate_method_path: boolean\nModule: security\nValidate HTTP method and path.\n",
"markdownDescription":"validate_method_path: `boolean` \nModule: `security` \nValidate HTTP method and path. \n",
"type":"boolean"
},
"validate_source_address":{
"description":"validate_source_address: boolean\nModule: security\nValidate source address matches between HTTP request and JWT token.\n",
"markdownDescription":"validate_source_address: `boolean` \nModule: `security` \nValidate source address matches between HTTP request and JWT token. \n",
"type":"boolean"
}
}
}
},
"credentials":{
"description":"credentials: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/credentials#Config\nConfig represents a collection of various credentials.\n\n",
"markdownDescription":"credentials: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/credentials#Config) \nConfig represents a collection of various credentials.\n \n",
"type":"object",
"properties":{
"generic":{
"description":"generic: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/credentials#Generic\nGeneric represents username and password credentials, with optional\ndomain name field.\n\n",
"markdownDescription":"generic: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/credentials#Generic) \nGeneric represents username and password credentials, with optional\ndomain name field.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/credentials#Generic\nGeneric represents username and password credentials, with optional\ndomain name field.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/credentials#Generic) \nGeneric represents username and password credentials, with optional\ndomain name field.\n \n",
"description":"identity_stores: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/ids#IdentityStoreConfig\nIdentityStoreConfig represents an identity store configuration.\n\n",
"markdownDescription":"identity_stores: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/ids#IdentityStoreConfig) \nIdentityStoreConfig represents an identity store configuration.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/ids#IdentityStoreConfig\nIdentityStoreConfig represents an identity store configuration.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/ids#IdentityStoreConfig) \nIdentityStoreConfig represents an identity store configuration.\n \n",
"description":"messaging: object\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/messaging#Config\nConfig represents a collection of various messaging providers.\n\n",
"markdownDescription":"messaging: `object` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/messaging#Config) \nConfig represents a collection of various messaging providers.\n \n",
"description":"file_providers: array\nModule: security\nhttps://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/messaging#FileProvider\nFileProvider represents file messaging provider which writes messages\nto a local file system,\n\n",
"markdownDescription":"file_providers: `array` \nModule: `security` \n[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/messaging#FileProvider) \nFileProvider represents file messaging provider which writes messages\nto a local file system,\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/messaging#FileProvider\nFileProvider represents file messaging provider which writes messages\nto a local file system,\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/greenpau/go-authcrunch/pkg/messaging#FileProvider) \nFileProvider represents file messaging provider which writes messages\nto a local file system,\n \n",
"description":"tls: object\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#TLS\nTLS provides TLS facilities including certificate\nloading and management, client auth, and more.\n\n",
"markdownDescription":"tls: `object` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#TLS) \nTLS provides TLS facilities including certificate\nloading and management, client auth, and more.\n \n",
"type":"object",
"properties":{
"automation":{
"description":"automation: object\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomationConfig\nConfigures certificate automation.\n\n\nAutomationConfig governs the automated management of TLS certificates.\n",
"markdownDescription":"automation: `object` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomationConfig) \nConfigures certificate automation.\n\n\nAutomationConfig governs the automated management of TLS certificates. \n",
"type":"object",
"properties":{
"ocsp_interval":{
"description":"ocsp_interval: number\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nCaddy staples OCSP (and caches the response) for all\nqualifying certificates by default. This setting\nchanges how often it scans responses for freshness,\nand updates them if they are getting stale. Default: 1h\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"ocsp_interval: `number` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nCaddy staples OCSP (and caches the response) for all\nqualifying certificates by default. This setting\nchanges how often it scans responses for freshness,\nand updates them if they are getting stale. Default: 1h\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"on_demand":{
"description":"on_demand: object\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#OnDemandConfig\nOn-Demand TLS defers certificate operations to the\nmoment they are needed, e.g. during a TLS handshake.\nUseful when you don't know all the hostnames at\nconfig-time, or when you are not in control of the\ndomain names you are managing certificates for.\nIn 2015, Caddy became the first web server to\nimplement this experimental technology.\n\nNote that this field does not enable on-demand TLS;\nit only configures it for when it is used. To enable\nit, create an automation policy with `on_demand`.\n\n\nOnDemandConfig configures on-demand TLS, for obtaining\nneeded certificates at handshake-time. Because this\nfeature can easily be abused, you should use this to\nestablish rate limits and/or an internal endpoint that\nCaddy can \"ask\" if it should be allowed to manage\ncertificates for a given hostname.\n",
"markdownDescription":"on_demand: `object` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#OnDemandConfig) \nOn-Demand TLS defers certificate operations to the\nmoment they are needed, e.g. during a TLS handshake.\nUseful when you don't know all the hostnames at\nconfig-time, or when you are not in control of the\ndomain names you are managing certificates for.\nIn 2015, Caddy became the first web server to\nimplement this experimental technology.\n\nNote that this field does not enable on-demand TLS;\nit only configures it for when it is used. To enable\nit, create an automation policy with `on_demand`.\n\n\nOnDemandConfig configures on-demand TLS, for obtaining\nneeded certificates at handshake-time. Because this\nfeature can easily be abused, you should use this to\nestablish rate limits and/or an internal endpoint that\nCaddy can \"ask\" if it should be allowed to manage\ncertificates for a given hostname. \n",
"type":"object",
"properties":{
"ask":{
"description":"ask: string\nModule: tls\nIf Caddy needs to obtain or renew a certificate\nduring a TLS handshake, it will perform a quick\nHTTP request to this URL to check if it should be\nallowed to try to get a certificate for the name\nin the \"domain\" query string parameter, like so:\n`?domain=example.com`. The endpoint must return a\n200 OK status if a certificate is allowed;\nanything else will cause it to be denied.\nRedirects are not followed.\n",
"markdownDescription":"ask: `string` \nModule: `tls` \nIf Caddy needs to obtain or renew a certificate\nduring a TLS handshake, it will perform a quick\nHTTP request to this URL to check if it should be\nallowed to try to get a certificate for the name\nin the \"domain\" query string parameter, like so:\n`?domain=example.com`. The endpoint must return a\n200 OK status if a certificate is allowed;\nanything else will cause it to be denied.\nRedirects are not followed. \n",
"type":"string"
},
"rate_limit":{
"description":"rate_limit: object\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#RateLimit\nAn optional rate limit to throttle the\nissuance of certificates from handshakes.\n\n\nRateLimit specifies an interval with optional burst size.\n",
"markdownDescription":"rate_limit: `object` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#RateLimit) \nAn optional rate limit to throttle the\nissuance of certificates from handshakes.\n\n\nRateLimit specifies an interval with optional burst size. \n",
"type":"object",
"properties":{
"burst":{
"description":"burst: number\nModule: tls\nHow many times during an interval a certificate can be obtained.\n",
"markdownDescription":"burst: `number` \nModule: `tls` \nHow many times during an interval a certificate can be obtained. \n",
"type":"number"
},
"interval":{
"description":"interval: number\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nA duration value. A certificate may be obtained 'burst'\ntimes during this interval.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"interval: `number` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nA duration value. A certificate may be obtained 'burst'\ntimes during this interval.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
}
}
},
"policies":{
"description":"policies: array\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomationPolicy\nThe list of automation policies. The first policy matching\na certificate or subject name will be applied.\n\n\nAutomationPolicy designates the policy for automating the\nmanagement (obtaining, renewal, and revocation) of managed\nTLS certificates.\n\nAn AutomationPolicy value is not valid until it has been\nprovisioned; use the `AddAutomationPolicy()` method on the\nTLS app to properly provision a new policy.\n",
"markdownDescription":"policies: `array` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomationPolicy) \nThe list of automation policies. The first policy matching\na certificate or subject name will be applied.\n\n\nAutomationPolicy designates the policy for automating the\nmanagement (obtaining, renewal, and revocation) of managed\nTLS certificates.\n\nAn AutomationPolicy value is not valid until it has been\nprovisioned; use the `AddAutomationPolicy()` method on the\nTLS app to properly provision a new policy. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomationPolicy\nThe list of automation policies. The first policy matching\na certificate or subject name will be applied.\n\n\nAutomationPolicy designates the policy for automating the\nmanagement (obtaining, renewal, and revocation) of managed\nTLS certificates.\n\nAn AutomationPolicy value is not valid until it has been\nprovisioned; use the `AddAutomationPolicy()` method on the\nTLS app to properly provision a new policy.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomationPolicy) \nThe list of automation policies. The first policy matching\na certificate or subject name will be applied.\n\n\nAutomationPolicy designates the policy for automating the\nmanagement (obtaining, renewal, and revocation) of managed\nTLS certificates.\n\nAn AutomationPolicy value is not valid until it has been\nprovisioned; use the `AddAutomationPolicy()` method on the\nTLS app to properly provision a new policy. \n",
"type":"object",
"properties":{
"disable_ocsp_stapling":{
"description":"disable_ocsp_stapling: boolean\nModule: tls\nDisables OCSP stapling. Disabling OCSP stapling puts clients at\ngreater risk, reduces their privacy, and usually lowers client\nperformance. It is NOT recommended to disable this unless you\nare able to justify the costs.\nEXPERIMENTAL. Subject to change.\n",
"markdownDescription":"disable_ocsp_stapling: `boolean` \nModule: `tls` \nDisables OCSP stapling. Disabling OCSP stapling puts clients at\ngreater risk, reduces their privacy, and usually lowers client\nperformance. It is NOT recommended to disable this unless you\nare able to justify the costs.\nEXPERIMENTAL. Subject to change. \n",
"type":"boolean"
},
"get_certificate":{
"description":"get_certificate: array\nModule: tls.get_certificate\nModules that can get a custom certificate to use for any\ngiven TLS handshake at handshake-time. Custom certificates\ncan be useful if another entity is managing certificates\nand Caddy need only get it and serve it.\n\nTODO: This is an EXPERIMENTAL feature. It is subject to change or removal.\n",
"markdownDescription":"get_certificate: `array` \nModule: `tls.get_certificate` \nModules that can get a custom certificate to use for any\ngiven TLS handshake at handshake-time. Custom certificates\ncan be useful if another entity is managing certificates\nand Caddy need only get it and serve it.\n\nTODO: This is an EXPERIMENTAL feature. It is subject to change or removal. \n",
"type":"array",
"items":{
"description":"Modules that can get a custom certificate to use for any\ngiven TLS handshake at handshake-time. Custom certificates\ncan be useful if another entity is managing certificates\nand Caddy need only get it and serve it.\n\nTODO: This is an EXPERIMENTAL feature. It is subject to change or removal.\n",
"markdownDescription":"Modules that can get a custom certificate to use for any\ngiven TLS handshake at handshake-time. Custom certificates\ncan be useful if another entity is managing certificates\nand Caddy need only get it and serve it.\n\nTODO: This is an EXPERIMENTAL feature. It is subject to change or removal. \n",
"description":"key to identify get_certificate module.\nvia: string\nModule: tls.get_certificate",
"markdownDescription":"key to identify `get_certificate` module. \nvia: `string` \nModule: `tls.get_certificate`",
"type":"string",
"enum":[
"http",
"tailscale"
]
}
}
}
]
}
},
"issuers":{
"description":"issuers: array\nModule: tls.issuance\nThe modules that may issue certificates. Default: internal if all\nsubjects do not qualify for public certificates; othewise acme and\nzerossl.\n",
"markdownDescription":"issuers: `array` \nModule: `tls.issuance` \nThe modules that may issue certificates. Default: internal if all\nsubjects do not qualify for public certificates; othewise acme and\nzerossl. \n",
"type":"array",
"items":{
"description":"The modules that may issue certificates. Default: internal if all\nsubjects do not qualify for public certificates; othewise acme and\nzerossl.\n",
"markdownDescription":"The modules that may issue certificates. Default: internal if all\nsubjects do not qualify for public certificates; othewise acme and\nzerossl. \n",
"description":"key_type: string\nModule: tls\nThe type of key to generate for certificates.\nSupported values: `ed25519`, `p256`, `p384`, `rsa2048`, `rsa4096`.\n",
"markdownDescription":"key_type: `string` \nModule: `tls` \nThe type of key to generate for certificates.\nSupported values: `ed25519`, `p256`, `p384`, `rsa2048`, `rsa4096`. \n",
"type":"string"
},
"must_staple":{
"description":"must_staple: boolean\nModule: tls\nIf true, certificates will be requested with MustStaple. Not all\nCAs support this, and there are potentially serious consequences\nof enabling this feature without proper threat modeling.\n",
"markdownDescription":"must_staple: `boolean` \nModule: `tls` \nIf true, certificates will be requested with MustStaple. Not all\nCAs support this, and there are potentially serious consequences\nof enabling this feature without proper threat modeling. \n",
"type":"boolean"
},
"ocsp_overrides":{
"description":"ocsp_overrides: object\nModule: tls\nOverrides the URLs of OCSP responders embedded in certificates.\nEach key is a OCSP server URL to override, and its value is the\nreplacement. An empty value will disable querying of that server.\nEXPERIMENTAL. Subject to change.\n",
"markdownDescription":"ocsp_overrides: `object` \nModule: `tls` \nOverrides the URLs of OCSP responders embedded in certificates.\nEach key is a OCSP server URL to override, and its value is the\nreplacement. An empty value will disable querying of that server.\nEXPERIMENTAL. Subject to change. \n",
"type":"object",
"additionalProperties":{
"description":"Overrides the URLs of OCSP responders embedded in certificates.\nEach key is a OCSP server URL to override, and its value is the\nreplacement. An empty value will disable querying of that server.\nEXPERIMENTAL. Subject to change.\n",
"markdownDescription":"Overrides the URLs of OCSP responders embedded in certificates.\nEach key is a OCSP server URL to override, and its value is the\nreplacement. An empty value will disable querying of that server.\nEXPERIMENTAL. Subject to change. \n"
}
},
"on_demand":{
"description":"on_demand: boolean\nModule: tls\nIf true, certificates will be managed \"on demand\"; that is, during\nTLS handshakes or when needed, as opposed to at startup or config\nload. This enables On-Demand TLS for this policy.\n",
"markdownDescription":"on_demand: `boolean` \nModule: `tls` \nIf true, certificates will be managed \"on demand\"; that is, during\nTLS handshakes or when needed, as opposed to at startup or config\nload. This enables On-Demand TLS for this policy. \n",
"type":"boolean"
},
"renewal_window_ratio":{
"description":"renewal_window_ratio: object\nModule: tls\nHow long before a certificate's expiration to try renewing it,\nas a function of its total lifetime. As a general and conservative\nrule, it is a good idea to renew a certificate when it has about\n1/3 of its total lifetime remaining. This utilizes the majority\nof the certificate's lifetime while still saving time to\ntroubleshoot problems. However, for extremely short-lived certs,\nyou may wish to increase the ratio to ~1/2.\n",
"markdownDescription":"renewal_window_ratio: `object` \nModule: `tls` \nHow long before a certificate's expiration to try renewing it,\nas a function of its total lifetime. As a general and conservative\nrule, it is a good idea to renew a certificate when it has about\n1/3 of its total lifetime remaining. This utilizes the majority\nof the certificate's lifetime while still saving time to\ntroubleshoot problems. However, for extremely short-lived certs,\nyou may wish to increase the ratio to ~1/2. \n",
"type":"object"
},
"storage":{
"description":"storage: object\nModule: caddy.storage\nOptionally configure a separate storage module associated with this\nmanager, instead of using Caddy's global/default-configured storage.\n",
"markdownDescription":"storage: `object` \nModule: `caddy.storage` \nOptionally configure a separate storage module associated with this\nmanager, instead of using Caddy's global/default-configured storage. \n",
"description":"subjects: array\nModule: tls\nWhich subjects (hostnames or IP addresses) this policy applies to.\n",
"markdownDescription":"subjects: `array` \nModule: `tls` \nWhich subjects (hostnames or IP addresses) this policy applies to. \n",
"type":"array",
"items":{
"description":"Which subjects (hostnames or IP addresses) this policy applies to.\n",
"markdownDescription":"Which subjects (hostnames or IP addresses) this policy applies to. \n",
"type":"string"
}
}
}
}
},
"renew_interval":{
"description":"renew_interval: number\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nEvery so often, Caddy will scan all loaded, managed\ncertificates for expiration. This setting changes how\nfrequently the scan for expiring certificates is\nperformed. Default: 10m\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"renew_interval: `number` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nEvery so often, Caddy will scan all loaded, managed\ncertificates for expiration. This setting changes how\nfrequently the scan for expiring certificates is\nperformed. Default: 10m\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"storage_clean_interval":{
"description":"storage_clean_interval: number\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow often to scan storage units for old or expired\nassets and remove them. These scans exert lots of\nreads (and list operations) on the storage module, so\nchoose a longer interval for large deployments.\nDefault: 24h\n\nStorage will always be cleaned when the process first\nstarts. Then, a new cleaning will be started this\nduration after the previous cleaning started if the\nprevious cleaning finished in less than half the time\nof this interval (otherwise next start will be skipped).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"storage_clean_interval: `number` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow often to scan storage units for old or expired\nassets and remove them. These scans exert lots of\nreads (and list operations) on the storage module, so\nchoose a longer interval for large deployments.\nDefault: 24h\n\nStorage will always be cleaned when the process first\nstarts. Then, a new cleaning will be started this\nduration after the previous cleaning started if the\nprevious cleaning finished in less than half the time\nof this interval (otherwise next start will be skipped).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
},
"cache":{
"description":"cache: object\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertCacheOptions\nConfigures the in-memory certificate cache.\n\n\nCertCacheOptions configures the certificate cache.\n",
"markdownDescription":"cache: `object` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertCacheOptions) \nConfigures the in-memory certificate cache.\n\n\nCertCacheOptions configures the certificate cache. \n",
"type":"object",
"properties":{
"capacity":{
"description":"capacity: number\nModule: tls\nMaximum number of certificates to allow in the\ncache. If reached, certificates will be randomly\nevicted to make room for new ones. Default: 10,000\n",
"markdownDescription":"capacity: `number` \nModule: `tls` \nMaximum number of certificates to allow in the\ncache. If reached, certificates will be randomly\nevicted to make room for new ones. Default: 10,000 \n",
"type":"number"
}
}
},
"certificates":{
"description":"certificates: object\nModule: tls.certificates\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nCaches certificates in memory for quick use during\nTLS handshakes. Each key is the name of a certificate\nloader module. All loaded certificates get pooled\ninto the same cache and may be used to complete TLS\nhandshakes for the relevant server names (SNI).\nCertificates loaded manually (anything other than\n\"automate\") are not automatically managed and will\nhave to be refreshed manually before they expire.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"certificates: `object` \nModule: `tls.certificates` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nCaches certificates in memory for quick use during\nTLS handshakes. Each key is the name of a certificate\nloader module. All loaded certificates get pooled\ninto the same cache and may be used to complete TLS\nhandshakes for the relevant server names (SNI).\nCertificates loaded manually (anything other than\n\"automate\") are not automatically managed and will\nhave to be refreshed manually before they expire.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"disable_ocsp_stapling: boolean\nModule: tls\nDisables OCSP stapling for manually-managed certificates only.\nTo configure OCSP stapling for automated certificates, use an\nautomation policy instead.\n\nDisabling OCSP stapling puts clients at greater risk, reduces their\nprivacy, and usually lowers client performance. It is NOT recommended\nto disable this unless you are able to justify the costs.\nEXPERIMENTAL. Subject to change.\n",
"markdownDescription":"disable_ocsp_stapling: `boolean` \nModule: `tls` \nDisables OCSP stapling for manually-managed certificates only.\nTo configure OCSP stapling for automated certificates, use an\nautomation policy instead.\n\nDisabling OCSP stapling puts clients at greater risk, reduces their\nprivacy, and usually lowers client performance. It is NOT recommended\nto disable this unless you are able to justify the costs.\nEXPERIMENTAL. Subject to change. \n",
"description":"key_source: object\nModule: tls.stek\nKeySource is the method by which Caddy produces or obtains\nTLS session ticket keys (STEKs). By default, Caddy generates\nthem internally using a secure pseudorandom source.\n",
"markdownDescription":"key_source: `object` \nModule: `tls.stek` \nKeySource is the method by which Caddy produces or obtains\nTLS session ticket keys (STEKs). By default, Caddy generates\nthem internally using a secure pseudorandom source. \n",
"type":"object",
"required":[
"provider"
],
"allOf":[
{
"if":{
"properties":{
"provider":{
"const":"distributed"
}
}
},
"then":{
"$ref":"#/definitions/tls.stek.distributed"
}
},
{
"if":{
"properties":{
"provider":{
"const":"standard"
}
}
},
"then":{
"$ref":"#/definitions/tls.stek.standard"
}
},
{
"properties":{
"provider":{
"description":"key to identify key_source module.\nprovider: string\nModule: tls.stek",
"markdownDescription":"key to identify `key_source` module. \nprovider: `string` \nModule: `tls.stek`",
"type":"string",
"enum":[
"distributed",
"standard"
]
}
}
}
]
},
"max_keys":{
"description":"max_keys: number\nModule: tls\nThe maximum number of keys to keep in rotation. Default: 4.\n",
"markdownDescription":"max_keys: `number` \nModule: `tls` \nThe maximum number of keys to keep in rotation. Default: 4. \n",
"type":"number"
},
"rotation_interval":{
"description":"rotation_interval: number\nModule: tls\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow often Caddy rotates STEKs. Default: 12h.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"rotation_interval: `number` \nModule: `tls` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow often Caddy rotates STEKs. Default: 12h.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
}
}
},
"tls.certificates.automate":{
"description":"automate: array\nModule: tls.certificates.automate\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomateLoader\nAutomateLoader will automatically manage certificates for the names in the\nlist, including obtaining and renewing certificates. Automated certificates\nare managed according to their matching automation policy, configured\nelsewhere in this app.\n\nTechnically, this is a no-op certificate loader module that is treated as\na special case: it uses this app's automation features to load certificates\nfor the list of hostnames, rather than loading certificates manually.\n\n",
"markdownDescription":"automate: `array` \nModule: `tls.certificates.automate` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#AutomateLoader) \nAutomateLoader will automatically manage certificates for the names in the\nlist, including obtaining and renewing certificates. Automated certificates\nare managed according to their matching automation policy, configured\nelsewhere in this app.\n\nTechnically, this is a no-op certificate loader module that is treated as\na special case: it uses this app's automation features to load certificates\nfor the list of hostnames, rather than loading certificates manually.\n \n",
"type":"array",
"items":{
"type":"string"
}
},
"tls.certificates.load_files":{
"description":"load_files: array\nModule: tls.certificates.load_files\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair\nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk.\n\n",
"markdownDescription":"load_files: `array` \nModule: `tls.certificates.load_files` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair) \nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk.\n \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair\nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk.\n\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair) \nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk.\n \n",
"type":"object",
"properties":{
"certificate":{
"description":"certificate: string\nModule: tls.certificates.load_files\nPath to the certificate (public key) file.\n",
"markdownDescription":"certificate: `string` \nModule: `tls.certificates.load_files` \nPath to the certificate (public key) file. \n",
"type":"string"
},
"format":{
"description":"format: string\nModule: tls.certificates.load_files\nThe format of the cert and key. Can be \"pem\". Default: \"pem\"\n",
"markdownDescription":"format: `string` \nModule: `tls.certificates.load_files` \nThe format of the cert and key. Can be \"pem\". Default: \"pem\" \n",
"type":"string"
},
"key":{
"description":"key: string\nModule: tls.certificates.load_files\nPath to the private key file.\n",
"markdownDescription":"key: `string` \nModule: `tls.certificates.load_files` \nPath to the private key file. \n",
"type":"string"
},
"tags":{
"description":"tags: array\nModule: tls.certificates.load_files\nArbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates.\n",
"markdownDescription":"tags: `array` \nModule: `tls.certificates.load_files` \nArbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates. \n",
"type":"array",
"items":{
"description":"Arbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates.\n",
"markdownDescription":"Arbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates. \n",
"type":"string"
}
}
}
}
},
"tls.certificates.load_folders":{
"description":"load_folders: array\nModule: tls.certificates.load_folders\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#FolderLoader\nFolderLoader loads certificates and their associated keys from disk\nby recursively walking the specified directories, looking for PEM\nfiles which contain both a certificate and a key.\n\n",
"markdownDescription":"load_folders: `array` \nModule: `tls.certificates.load_folders` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#FolderLoader) \nFolderLoader loads certificates and their associated keys from disk\nby recursively walking the specified directories, looking for PEM\nfiles which contain both a certificate and a key.\n \n",
"type":"array",
"items":{
"type":"string"
}
},
"tls.certificates.load_pem":{
"description":"load_pem: array\nModule: tls.certificates.load_pem\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyPEMPair\nCertKeyPEMPair pairs certificate and key PEM blocks.\n\n",
"description":"tags: array\nModule: tls.certificates.load_pem\nArbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates.\n",
"markdownDescription":"tags: `array` \nModule: `tls.certificates.load_pem` \nArbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates. \n",
"type":"array",
"items":{
"description":"Arbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates.\n",
"markdownDescription":"Arbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates. \n",
"type":"string"
}
}
}
}
},
"tls.certificates.load_storage":{
"description":"load_storage: object\nModule: tls.certificates.load_storage\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#StorageLoader\nStorageLoader loads certificates and their associated keys\nfrom the globally configured storage module.\n\n",
"markdownDescription":"load_storage: `object` \nModule: `tls.certificates.load_storage` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#StorageLoader) \nStorageLoader loads certificates and their associated keys\nfrom the globally configured storage module.\n \n",
"type":"object",
"properties":{
"pairs":{
"description":"pairs: array\nModule: tls.certificates.load_storage\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair\nA list of pairs of certificate and key file names along with their\nencoding format so that they can be loaded from storage.\n\n\nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk.\n",
"markdownDescription":"pairs: `array` \nModule: `tls.certificates.load_storage` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair) \nA list of pairs of certificate and key file names along with their\nencoding format so that they can be loaded from storage.\n\n\nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair\nA list of pairs of certificate and key file names along with their\nencoding format so that they can be loaded from storage.\n\n\nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#CertKeyFilePair) \nA list of pairs of certificate and key file names along with their\nencoding format so that they can be loaded from storage.\n\n\nCertKeyFilePair pairs certificate and key file names along with their\nencoding format so that they can be loaded from disk. \n",
"type":"object",
"properties":{
"certificate":{
"description":"certificate: string\nModule: tls.certificates.load_storage\nPath to the certificate (public key) file.\n",
"markdownDescription":"certificate: `string` \nModule: `tls.certificates.load_storage` \nPath to the certificate (public key) file. \n",
"type":"string"
},
"format":{
"description":"format: string\nModule: tls.certificates.load_storage\nThe format of the cert and key. Can be \"pem\". Default: \"pem\"\n",
"markdownDescription":"format: `string` \nModule: `tls.certificates.load_storage` \nThe format of the cert and key. Can be \"pem\". Default: \"pem\" \n",
"type":"string"
},
"key":{
"description":"key: string\nModule: tls.certificates.load_storage\nPath to the private key file.\n",
"markdownDescription":"key: `string` \nModule: `tls.certificates.load_storage` \nPath to the private key file. \n",
"type":"string"
},
"tags":{
"description":"tags: array\nModule: tls.certificates.load_storage\nArbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates.\n",
"markdownDescription":"tags: `array` \nModule: `tls.certificates.load_storage` \nArbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates. \n",
"type":"array",
"items":{
"description":"Arbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates.\n",
"markdownDescription":"Arbitrary values to associate with this certificate.\nCan be useful when you want to select a particular\ncertificate when there may be multiple valid candidates. \n",
"description":"http: object\nModule: tls.get_certificate.http\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#HTTPCertGetter\nHTTPCertGetter can get a certificate via HTTP(S) request.\n\n",
"markdownDescription":"http: `object` \nModule: `tls.get_certificate.http` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#HTTPCertGetter) \nHTTPCertGetter can get a certificate via HTTP(S) request.\n \n",
"type":"object",
"properties":{
"url":{
"description":"url: string\nModule: tls.get_certificate.http\nThe URL from which to download the certificate. Required.\n\nThe URL will be augmented with query string parameters taken\nfrom the TLS handshake:\n\n- server_name: The SNI value\n- signature_schemes: Comma-separated list of hex IDs of signatures\n- cipher_suites: Comma-separated list of hex IDs of cipher suites\n\nTo be valid, the response must be HTTP 200 with a PEM body\nconsisting of blocks for the certificate chain and the private\nkey.\n",
"markdownDescription":"url: `string` \nModule: `tls.get_certificate.http` \nThe URL from which to download the certificate. Required.\n\nThe URL will be augmented with query string parameters taken\nfrom the TLS handshake:\n\n- server_name: The SNI value\n- signature_schemes: Comma-separated list of hex IDs of signatures\n- cipher_suites: Comma-separated list of hex IDs of cipher suites\n\nTo be valid, the response must be HTTP 200 with a PEM body\nconsisting of blocks for the certificate chain and the private\nkey. \n",
"type":"string"
}
}
},
"tls.get_certificate.tailscale":{
"description":"tailscale: object\nModule: tls.get_certificate.tailscale\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#Tailscale\nTailscale is a module that can get certificates from the local Tailscale process.\n\n",
"markdownDescription":"tailscale: `object` \nModule: `tls.get_certificate.tailscale` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#Tailscale) \nTailscale is a module that can get certificates from the local Tailscale process.\n \n",
"type":"object",
"properties":{
"optional":{
"description":"optional: boolean\nModule: tls.get_certificate.tailscale\nIf true, this module will operate in \"best-effort\" mode and\nignore \"soft\" errors; i.e. try Tailscale, and if it doesn't connect\nor return a certificate, oh well. Failure to connect to Tailscale\nresults in a no-op instead of an error. Intended for the use case\nwhere this module is added implicitly for convenience, even if\nTailscale isn't necessarily running.\n",
"markdownDescription":"optional: `boolean` \nModule: `tls.get_certificate.tailscale` \nIf true, this module will operate in \"best-effort\" mode and\nignore \"soft\" errors; i.e. try Tailscale, and if it doesn't connect\nor return a certificate, oh well. Failure to connect to Tailscale\nresults in a no-op instead of an error. Intended for the use case\nwhere this module is added implicitly for convenience, even if\nTailscale isn't necessarily running. \n",
"description":"remote_ip: object\nModule: tls.handshake_match.remote_ip\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#MatchRemoteIP\nMatchRemoteIP matches based on the remote IP of the\nconnection. Specific IPs or CIDR ranges can be specified.\n\nNote that IPs can sometimes be spoofed, so do not rely\non this as a replacement for actual authentication.\n\n",
"markdownDescription":"remote_ip: `object` \nModule: `tls.handshake_match.remote_ip` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#MatchRemoteIP) \nMatchRemoteIP matches based on the remote IP of the\nconnection. Specific IPs or CIDR ranges can be specified.\n\nNote that IPs can sometimes be spoofed, so do not rely\non this as a replacement for actual authentication.\n \n",
"type":"object",
"properties":{
"not_ranges":{
"description":"not_ranges: array\nModule: tls.handshake_match.remote_ip\nThe IPs or CIDR ranges to *NOT* match.\n",
"markdownDescription":"not_ranges: `array` \nModule: `tls.handshake_match.remote_ip` \nThe IPs or CIDR ranges to *NOT* match. \n",
"type":"array",
"items":{
"description":"The IPs or CIDR ranges to *NOT* match.\n",
"markdownDescription":"The IPs or CIDR ranges to *NOT* match. \n",
"type":"string"
}
},
"ranges":{
"description":"ranges: array\nModule: tls.handshake_match.remote_ip\nThe IPs or CIDR ranges to match.\n",
"markdownDescription":"ranges: `array` \nModule: `tls.handshake_match.remote_ip` \nThe IPs or CIDR ranges to match. \n",
"type":"array",
"items":{
"description":"The IPs or CIDR ranges to match.\n",
"markdownDescription":"The IPs or CIDR ranges to match. \n",
"type":"string"
}
}
}
},
"tls.handshake_match.sni":{
"description":"sni: array\nModule: tls.handshake_match.sni\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#MatchServerName\nMatchServerName matches based on SNI. Names in\nthis list may use left-most-label wildcards,\nsimilar to wildcard certificates.\n\n",
"markdownDescription":"sni: `array` \nModule: `tls.handshake_match.sni` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#MatchServerName) \nMatchServerName matches based on SNI. Names in\nthis list may use left-most-label wildcards,\nsimilar to wildcard certificates.\n \n",
"type":"array",
"items":{
"type":"string"
}
},
"tls.issuance.acme":{
"description":"acme: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ACMEIssuer\nACMEIssuer manages certificates using the ACME protocol (RFC 8555).\n\n",
"markdownDescription":"acme: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ACMEIssuer) \nACMEIssuer manages certificates using the ACME protocol (RFC 8555).\n \n",
"type":"object",
"properties":{
"account_key":{
"description":"account_key: string\nModule: tls.issuance.acme\nIf you have an existing account with the ACME server, put\nthe private key here in PEM format. The ACME client will\nlook up your account information with this key first before\ntrying to create a new one. You can use placeholders here,\nfor example if you have it in an environment variable.\n",
"markdownDescription":"account_key: `string` \nModule: `tls.issuance.acme` \nIf you have an existing account with the ACME server, put\nthe private key here in PEM format. The ACME client will\nlook up your account information with this key first before\ntrying to create a new one. You can use placeholders here,\nfor example if you have it in an environment variable. \n",
"type":"string"
},
"acme_timeout":{
"description":"acme_timeout: number\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nTime to wait before timing out an ACME operation.\nDefault: 0 (no timeout)\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"acme_timeout: `number` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nTime to wait before timing out an ACME operation.\nDefault: 0 (no timeout)\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"ca":{
"description":"ca: string\nModule: tls.issuance.acme\nThe URL to the CA's ACME directory endpoint. Default:\nhttps://acme-v02.api.letsencrypt.org/directory\n",
"markdownDescription":"ca: `string` \nModule: `tls.issuance.acme` \nThe URL to the CA's ACME directory endpoint. Default:\nhttps://acme-v02.api.letsencrypt.org/directory \n",
"type":"string"
},
"challenges":{
"description":"challenges: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChallengesConfig\nConfigures the various ACME challenge types.\n\n\nChallengesConfig configures the ACME challenges.\n",
"markdownDescription":"challenges: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChallengesConfig) \nConfigures the various ACME challenge types.\n\n\nChallengesConfig configures the ACME challenges. \n",
"type":"object",
"properties":{
"bind_host":{
"description":"bind_host: string\nModule: tls.issuance.acme\nOptionally customize the host to which a listener\nis bound if required for solving a challenge.\n",
"markdownDescription":"bind_host: `string` \nModule: `tls.issuance.acme` \nOptionally customize the host to which a listener\nis bound if required for solving a challenge. \n",
"type":"string"
},
"dns":{
"description":"dns: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#DNSChallengeConfig\nConfigures the ACME DNS challenge. Because this\nchallenge typically requires credentials for\ninterfacing with a DNS provider, this challenge is\nnot enabled by default. This is the only challenge\ntype which does not require a direct connection\nto Caddy from an external server.\n\nNOTE: DNS providers are currently being upgraded,\nand this API is subject to change, but should be\nstabilized soon.\n\n\nDNSChallengeConfig configures the ACME DNS challenge.\n\nNOTE: This API is still experimental and is subject to change.\n",
"markdownDescription":"dns: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#DNSChallengeConfig) \nConfigures the ACME DNS challenge. Because this\nchallenge typically requires credentials for\ninterfacing with a DNS provider, this challenge is\nnot enabled by default. This is the only challenge\ntype which does not require a direct connection\nto Caddy from an external server.\n\nNOTE: DNS providers are currently being upgraded,\nand this API is subject to change, but should be\nstabilized soon.\n\n\nDNSChallengeConfig configures the ACME DNS challenge.\n\nNOTE: This API is still experimental and is subject to change. \n",
"type":"object",
"properties":{
"override_domain":{
"description":"override_domain: string\nModule: tls.issuance.acme\nOverride the domain to use for the DNS challenge. This\nis to delegate the challenge to a different domain,\ne.g. one that updates faster or one with a provider API.\n",
"markdownDescription":"override_domain: `string` \nModule: `tls.issuance.acme` \nOverride the domain to use for the DNS challenge. This\nis to delegate the challenge to a different domain,\ne.g. one that updates faster or one with a provider API. \n",
"type":"string"
},
"propagation_delay":{
"description":"propagation_delay: number\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait before starting propagation checks.\nDefault: 0 (no wait).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"propagation_delay: `number` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait before starting propagation checks.\nDefault: 0 (no wait).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"propagation_timeout":{
"description":"propagation_timeout: number\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nMaximum time to wait for temporary DNS record to appear.\nSet to -1 to disable propagation checks.\nDefault: 2 minutes.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"propagation_timeout: `number` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nMaximum time to wait for temporary DNS record to appear.\nSet to -1 to disable propagation checks.\nDefault: 2 minutes.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"provider":{
"description":"provider: any\nModule: dns.providers\nThe DNS provider module to use which will manage\nthe DNS records relevant to the ACME challenge.\n",
"markdownDescription":"provider: `any` \nModule: `dns.providers` \nThe DNS provider module to use which will manage\nthe DNS records relevant to the ACME challenge. \n"
},
"resolvers":{
"description":"resolvers: array\nModule: tls.issuance.acme\nCustom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS.\n",
"markdownDescription":"resolvers: `array` \nModule: `tls.issuance.acme` \nCustom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS. \n",
"type":"array",
"items":{
"description":"Custom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS.\n",
"markdownDescription":"Custom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS. \n",
"type":"string"
}
},
"ttl":{
"description":"ttl: number\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nThe TTL of the TXT record used for the DNS challenge.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"ttl: `number` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nThe TTL of the TXT record used for the DNS challenge.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
},
"http":{
"description":"http: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#HTTPChallengeConfig\nHTTP configures the ACME HTTP challenge. This\nchallenge is enabled and used automatically\nand by default.\n\n\nHTTPChallengeConfig configures the ACME HTTP challenge.\n",
"markdownDescription":"http: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#HTTPChallengeConfig) \nHTTP configures the ACME HTTP challenge. This\nchallenge is enabled and used automatically\nand by default.\n\n\nHTTPChallengeConfig configures the ACME HTTP challenge. \n",
"type":"object",
"properties":{
"alternate_port":{
"description":"alternate_port: number\nModule: tls.issuance.acme\nAn alternate port on which to service this\nchallenge. Note that the HTTP challenge port is\nhard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard HTTP challenge port to this one.\n",
"markdownDescription":"alternate_port: `number` \nModule: `tls.issuance.acme` \nAn alternate port on which to service this\nchallenge. Note that the HTTP challenge port is\nhard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard HTTP challenge port to this one. \n",
"type":"number"
},
"disabled":{
"description":"disabled: boolean\nModule: tls.issuance.acme\nIf true, the HTTP challenge will be disabled.\n",
"markdownDescription":"disabled: `boolean` \nModule: `tls.issuance.acme` \nIf true, the HTTP challenge will be disabled. \n",
"type":"boolean"
}
}
},
"tls-alpn":{
"description":"tls-alpn: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#TLSALPNChallengeConfig\nTLSALPN configures the ACME TLS-ALPN challenge.\nThis challenge is enabled and used automatically\nand by default.\n\n\nTLSALPNChallengeConfig configures the ACME TLS-ALPN challenge.\n",
"markdownDescription":"tls-alpn: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#TLSALPNChallengeConfig) \nTLSALPN configures the ACME TLS-ALPN challenge.\nThis challenge is enabled and used automatically\nand by default.\n\n\nTLSALPNChallengeConfig configures the ACME TLS-ALPN challenge. \n",
"type":"object",
"properties":{
"alternate_port":{
"description":"alternate_port: number\nModule: tls.issuance.acme\nAn alternate port on which to service this\nchallenge. Note that the TLS-ALPN challenge port\nis hard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard TLS-ALPN challenge port to this one.\n",
"markdownDescription":"alternate_port: `number` \nModule: `tls.issuance.acme` \nAn alternate port on which to service this\nchallenge. Note that the TLS-ALPN challenge port\nis hard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard TLS-ALPN challenge port to this one. \n",
"type":"number"
},
"disabled":{
"description":"disabled: boolean\nModule: tls.issuance.acme\nIf true, the TLS-ALPN challenge will be disabled.\n",
"markdownDescription":"disabled: `boolean` \nModule: `tls.issuance.acme` \nIf true, the TLS-ALPN challenge will be disabled. \n",
"type":"boolean"
}
}
}
}
},
"email":{
"description":"email: string\nModule: tls.issuance.acme\nYour email address, so the CA can contact you if necessary.\nNot required, but strongly recommended to provide one so\nyou can be reached if there is a problem. Your email is\nnot sent to any Caddy mothership or used for any purpose\nother than ACME transactions.\n",
"markdownDescription":"email: `string` \nModule: `tls.issuance.acme` \nYour email address, so the CA can contact you if necessary.\nNot required, but strongly recommended to provide one so\nyou can be reached if there is a problem. Your email is\nnot sent to any Caddy mothership or used for any purpose\nother than ACME transactions. \n",
"type":"string"
},
"external_account":{
"description":"external_account: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/mholt/acmez/acme#EAB\nIf using an ACME CA that requires an external account\nbinding, specify the CA-provided credentials here.\n\n\nEAB (External Account Binding) contains information\nnecessary to bind or map an ACME account to some\nother account known by the CA.\n\nExternal account bindings are \"used to associate an\nACME account with an existing account in a non-ACME\nsystem, such as a CA customer database.\"\n\n\"To enable ACME account binding, the CA operating the\nACME server needs to provide the ACME client with a\nMAC key and a key identifier, using some mechanism\noutside of ACME.\" §7.3.4\n",
"markdownDescription":"external_account: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/mholt/acmez/acme#EAB) \nIf using an ACME CA that requires an external account\nbinding, specify the CA-provided credentials here.\n\n\nEAB (External Account Binding) contains information\nnecessary to bind or map an ACME account to some\nother account known by the CA.\n\nExternal account bindings are \"used to associate an\nACME account with an existing account in a non-ACME\nsystem, such as a CA customer database.\"\n\n\"To enable ACME account binding, the CA operating the\nACME server needs to provide the ACME client with a\nMAC key and a key identifier, using some mechanism\noutside of ACME.\" §7.3.4 \n",
"type":"object",
"properties":{
"key_id":{
"description":"key_id: string\nModule: tls.issuance.acme\n\"The key identifier MUST be an ASCII string.\" §7.3.4\n",
"markdownDescription":"key_id: `string` \nModule: `tls.issuance.acme` \n\"The key identifier MUST be an ASCII string.\" §7.3.4 \n",
"type":"string"
},
"mac_key":{
"description":"mac_key: string\nModule: tls.issuance.acme\n\"The MAC key SHOULD be provided in base64url-encoded\nform, to maximize compatibility between non-ACME\nprovisioning systems and ACME clients.\" §7.3.4\n",
"markdownDescription":"mac_key: `string` \nModule: `tls.issuance.acme` \n\"The MAC key SHOULD be provided in base64url-encoded\nform, to maximize compatibility between non-ACME\nprovisioning systems and ACME clients.\" §7.3.4 \n",
"type":"string"
}
}
},
"preferred_chains":{
"description":"preferred_chains: object\nModule: tls.issuance.acme\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChainPreference\nPreferences for selecting alternate certificate chains, if offered\nby the CA. By default, the first offered chain will be selected.\nIf configured, the chains may be sorted and the first matching chain\nwill be selected.\n\n\nChainPreference describes the client's preferred certificate chain,\nuseful if the CA offers alternate chains. The first matching chain\nwill be selected.\n",
"markdownDescription":"preferred_chains: `object` \nModule: `tls.issuance.acme` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChainPreference) \nPreferences for selecting alternate certificate chains, if offered\nby the CA. By default, the first offered chain will be selected.\nIf configured, the chains may be sorted and the first matching chain\nwill be selected.\n\n\nChainPreference describes the client's preferred certificate chain,\nuseful if the CA offers alternate chains. The first matching chain\nwill be selected. \n",
"type":"object",
"properties":{
"any_common_name":{
"description":"any_common_name: array\nModule: tls.issuance.acme\nSelect first chain that has any issuer with one\nof these common names.\n",
"markdownDescription":"any_common_name: `array` \nModule: `tls.issuance.acme` \nSelect first chain that has any issuer with one\nof these common names. \n",
"type":"array",
"items":{
"description":"Select first chain that has any issuer with one\nof these common names.\n",
"markdownDescription":"Select first chain that has any issuer with one\nof these common names. \n",
"type":"string"
}
},
"root_common_name":{
"description":"root_common_name: array\nModule: tls.issuance.acme\nSelect first chain having a root with one of\nthese common names.\n",
"markdownDescription":"root_common_name: `array` \nModule: `tls.issuance.acme` \nSelect first chain having a root with one of\nthese common names. \n",
"type":"array",
"items":{
"description":"Select first chain having a root with one of\nthese common names.\n",
"markdownDescription":"Select first chain having a root with one of\nthese common names. \n",
"type":"string"
}
},
"smallest":{
"description":"smallest: boolean\nModule: tls.issuance.acme\nPrefer chains with the fewest number of bytes.\n",
"markdownDescription":"smallest: `boolean` \nModule: `tls.issuance.acme` \nPrefer chains with the fewest number of bytes. \n",
"type":"boolean"
}
}
},
"test_ca":{
"description":"test_ca: string\nModule: tls.issuance.acme\nThe URL to the test CA's ACME directory endpoint.\nThis endpoint is only used during retries if there\nis a failure using the primary CA. Default:\nhttps://acme-staging-v02.api.letsencrypt.org/directory\n",
"markdownDescription":"test_ca: `string` \nModule: `tls.issuance.acme` \nThe URL to the test CA's ACME directory endpoint.\nThis endpoint is only used during retries if there\nis a failure using the primary CA. Default:\nhttps://acme-staging-v02.api.letsencrypt.org/directory \n",
"type":"string"
},
"trusted_roots_pem_files":{
"description":"trusted_roots_pem_files: array\nModule: tls.issuance.acme\nAn array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes.\n",
"markdownDescription":"trusted_roots_pem_files: `array` \nModule: `tls.issuance.acme` \nAn array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes. \n",
"type":"array",
"items":{
"description":"An array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes.\n",
"markdownDescription":"An array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes. \n",
"type":"string"
}
}
}
},
"tls.issuance.internal":{
"description":"internal: object\nModule: tls.issuance.internal\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#InternalIssuer\nInternalIssuer is a certificate issuer that generates\ncertificates internally using a locally-configured\nCA which can be customized using the `pki` app.\n\n",
"markdownDescription":"internal: `object` \nModule: `tls.issuance.internal` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#InternalIssuer) \nInternalIssuer is a certificate issuer that generates\ncertificates internally using a locally-configured\nCA which can be customized using the `pki` app.\n \n",
"type":"object",
"properties":{
"ca":{
"description":"ca: string\nModule: tls.issuance.internal\nThe ID of the CA to use for signing. The default\nCA ID is \"local\". The CA can be configured with the\n`pki` app.\n",
"markdownDescription":"ca: `string` \nModule: `tls.issuance.internal` \nThe ID of the CA to use for signing. The default\nCA ID is \"local\". The CA can be configured with the\n`pki` app. \n",
"type":"string"
},
"lifetime":{
"description":"lifetime: number\nModule: tls.issuance.internal\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nThe validity period of certificates.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"lifetime: `number` \nModule: `tls.issuance.internal` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nThe validity period of certificates.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"sign_with_root":{
"description":"sign_with_root: boolean\nModule: tls.issuance.internal\nIf true, the root will be the issuer instead of\nthe intermediate. This is NOT recommended and should\nonly be used when devices/clients do not properly\nvalidate certificate chains.\n",
"markdownDescription":"sign_with_root: `boolean` \nModule: `tls.issuance.internal` \nIf true, the root will be the issuer instead of\nthe intermediate. This is NOT recommended and should\nonly be used when devices/clients do not properly\nvalidate certificate chains. \n",
"description":"zerossl: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ZeroSSLIssuer\nZeroSSLIssuer makes an ACME issuer for getting certificates\nfrom ZeroSSL by automatically generating EAB credentials.\nPlease be sure to set a valid email address in your config\nso you can access/manage your domains in your ZeroSSL account.\n\nThis issuer is only needed for automatic generation of EAB\ncredentials. If manually configuring/reusing EAB credentials,\nthe standard ACMEIssuer may be used if desired.\n\n",
"markdownDescription":"zerossl: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ZeroSSLIssuer) \nZeroSSLIssuer makes an ACME issuer for getting certificates\nfrom ZeroSSL by automatically generating EAB credentials.\nPlease be sure to set a valid email address in your config\nso you can access/manage your domains in your ZeroSSL account.\n\nThis issuer is only needed for automatic generation of EAB\ncredentials. If manually configuring/reusing EAB credentials,\nthe standard ACMEIssuer may be used if desired.\n \n",
"description":"account_key: string\nModule: tls.issuance.zerossl\nIf you have an existing account with the ACME server, put\nthe private key here in PEM format. The ACME client will\nlook up your account information with this key first before\ntrying to create a new one. You can use placeholders here,\nfor example if you have it in an environment variable.\n",
"markdownDescription":"account_key: `string` \nModule: `tls.issuance.zerossl` \nIf you have an existing account with the ACME server, put\nthe private key here in PEM format. The ACME client will\nlook up your account information with this key first before\ntrying to create a new one. You can use placeholders here,\nfor example if you have it in an environment variable. \n",
"type":"string"
},
"acme_timeout":{
"description":"acme_timeout: number\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nTime to wait before timing out an ACME operation.\nDefault: 0 (no timeout)\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"acme_timeout: `number` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nTime to wait before timing out an ACME operation.\nDefault: 0 (no timeout)\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"description":"api_key: string\nModule: tls.issuance.zerossl\nThe API key (or \"access key\") for using the ZeroSSL API.\nThis is optional, but can be used if you have an API key\nalready and don't want to supply your email address.\n",
"markdownDescription":"api_key: `string` \nModule: `tls.issuance.zerossl` \nThe API key (or \"access key\") for using the ZeroSSL API.\nThis is optional, but can be used if you have an API key\nalready and don't want to supply your email address. \n",
"description":"ca: string\nModule: tls.issuance.zerossl\nThe URL to the CA's ACME directory endpoint. Default:\nhttps://acme-v02.api.letsencrypt.org/directory\n",
"markdownDescription":"ca: `string` \nModule: `tls.issuance.zerossl` \nThe URL to the CA's ACME directory endpoint. Default:\nhttps://acme-v02.api.letsencrypt.org/directory \n",
"type":"string"
},
"challenges":{
"description":"challenges: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChallengesConfig\nConfigures the various ACME challenge types.\n\n\nChallengesConfig configures the ACME challenges.\n",
"markdownDescription":"challenges: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChallengesConfig) \nConfigures the various ACME challenge types.\n\n\nChallengesConfig configures the ACME challenges. \n",
"type":"object",
"properties":{
"bind_host":{
"description":"bind_host: string\nModule: tls.issuance.zerossl\nOptionally customize the host to which a listener\nis bound if required for solving a challenge.\n",
"markdownDescription":"bind_host: `string` \nModule: `tls.issuance.zerossl` \nOptionally customize the host to which a listener\nis bound if required for solving a challenge. \n",
"type":"string"
},
"dns":{
"description":"dns: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#DNSChallengeConfig\nConfigures the ACME DNS challenge. Because this\nchallenge typically requires credentials for\ninterfacing with a DNS provider, this challenge is\nnot enabled by default. This is the only challenge\ntype which does not require a direct connection\nto Caddy from an external server.\n\nNOTE: DNS providers are currently being upgraded,\nand this API is subject to change, but should be\nstabilized soon.\n\n\nDNSChallengeConfig configures the ACME DNS challenge.\n\nNOTE: This API is still experimental and is subject to change.\n",
"markdownDescription":"dns: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#DNSChallengeConfig) \nConfigures the ACME DNS challenge. Because this\nchallenge typically requires credentials for\ninterfacing with a DNS provider, this challenge is\nnot enabled by default. This is the only challenge\ntype which does not require a direct connection\nto Caddy from an external server.\n\nNOTE: DNS providers are currently being upgraded,\nand this API is subject to change, but should be\nstabilized soon.\n\n\nDNSChallengeConfig configures the ACME DNS challenge.\n\nNOTE: This API is still experimental and is subject to change. \n",
"type":"object",
"properties":{
"override_domain":{
"description":"override_domain: string\nModule: tls.issuance.zerossl\nOverride the domain to use for the DNS challenge. This\nis to delegate the challenge to a different domain,\ne.g. one that updates faster or one with a provider API.\n",
"markdownDescription":"override_domain: `string` \nModule: `tls.issuance.zerossl` \nOverride the domain to use for the DNS challenge. This\nis to delegate the challenge to a different domain,\ne.g. one that updates faster or one with a provider API. \n",
"type":"string"
},
"propagation_delay":{
"description":"propagation_delay: number\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nHow long to wait before starting propagation checks.\nDefault: 0 (no wait).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"propagation_delay: `number` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nHow long to wait before starting propagation checks.\nDefault: 0 (no wait).\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"propagation_timeout":{
"description":"propagation_timeout: number\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nMaximum time to wait for temporary DNS record to appear.\nSet to -1 to disable propagation checks.\nDefault: 2 minutes.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"propagation_timeout: `number` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nMaximum time to wait for temporary DNS record to appear.\nSet to -1 to disable propagation checks.\nDefault: 2 minutes.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
},
"provider":{
"description":"provider: any\nModule: dns.providers\nThe DNS provider module to use which will manage\nthe DNS records relevant to the ACME challenge.\n",
"markdownDescription":"provider: `any` \nModule: `dns.providers` \nThe DNS provider module to use which will manage\nthe DNS records relevant to the ACME challenge. \n"
},
"resolvers":{
"description":"resolvers: array\nModule: tls.issuance.zerossl\nCustom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS.\n",
"markdownDescription":"resolvers: `array` \nModule: `tls.issuance.zerossl` \nCustom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS. \n",
"type":"array",
"items":{
"description":"Custom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS.\n",
"markdownDescription":"Custom DNS resolvers to prefer over system/built-in defaults.\nOften necessary to configure when using split-horizon DNS. \n",
"type":"string"
}
},
"ttl":{
"description":"ttl: number\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration\nThe TTL of the TXT record used for the DNS challenge.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`.\n",
"markdownDescription":"ttl: `number` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Duration) \nThe TTL of the TXT record used for the DNS challenge.\n\n\nDuration can be an integer or a string. An integer is\ninterpreted as nanoseconds. If a string, it is a Go\ntime.Duration value such as `300ms`, `1.5h`, or `2h45m`;\nvalid units are `ns`, `us`/`µs`, `ms`, `s`, `m`, `h`, and `d`. \n",
"type":"number"
}
}
},
"http":{
"description":"http: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#HTTPChallengeConfig\nHTTP configures the ACME HTTP challenge. This\nchallenge is enabled and used automatically\nand by default.\n\n\nHTTPChallengeConfig configures the ACME HTTP challenge.\n",
"markdownDescription":"http: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#HTTPChallengeConfig) \nHTTP configures the ACME HTTP challenge. This\nchallenge is enabled and used automatically\nand by default.\n\n\nHTTPChallengeConfig configures the ACME HTTP challenge. \n",
"type":"object",
"properties":{
"alternate_port":{
"description":"alternate_port: number\nModule: tls.issuance.zerossl\nAn alternate port on which to service this\nchallenge. Note that the HTTP challenge port is\nhard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard HTTP challenge port to this one.\n",
"markdownDescription":"alternate_port: `number` \nModule: `tls.issuance.zerossl` \nAn alternate port on which to service this\nchallenge. Note that the HTTP challenge port is\nhard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard HTTP challenge port to this one. \n",
"type":"number"
},
"disabled":{
"description":"disabled: boolean\nModule: tls.issuance.zerossl\nIf true, the HTTP challenge will be disabled.\n",
"markdownDescription":"disabled: `boolean` \nModule: `tls.issuance.zerossl` \nIf true, the HTTP challenge will be disabled. \n",
"type":"boolean"
}
}
},
"tls-alpn":{
"description":"tls-alpn: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#TLSALPNChallengeConfig\nTLSALPN configures the ACME TLS-ALPN challenge.\nThis challenge is enabled and used automatically\nand by default.\n\n\nTLSALPNChallengeConfig configures the ACME TLS-ALPN challenge.\n",
"markdownDescription":"tls-alpn: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#TLSALPNChallengeConfig) \nTLSALPN configures the ACME TLS-ALPN challenge.\nThis challenge is enabled and used automatically\nand by default.\n\n\nTLSALPNChallengeConfig configures the ACME TLS-ALPN challenge. \n",
"type":"object",
"properties":{
"alternate_port":{
"description":"alternate_port: number\nModule: tls.issuance.zerossl\nAn alternate port on which to service this\nchallenge. Note that the TLS-ALPN challenge port\nis hard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard TLS-ALPN challenge port to this one.\n",
"markdownDescription":"alternate_port: `number` \nModule: `tls.issuance.zerossl` \nAn alternate port on which to service this\nchallenge. Note that the TLS-ALPN challenge port\nis hard-coded into the spec and cannot be changed,\nso you would have to forward packets from the\nstandard TLS-ALPN challenge port to this one. \n",
"type":"number"
},
"disabled":{
"description":"disabled: boolean\nModule: tls.issuance.zerossl\nIf true, the TLS-ALPN challenge will be disabled.\n",
"markdownDescription":"disabled: `boolean` \nModule: `tls.issuance.zerossl` \nIf true, the TLS-ALPN challenge will be disabled. \n",
"type":"boolean"
}
}
}
}
},
"email":{
"description":"email: string\nModule: tls.issuance.zerossl\nYour email address, so the CA can contact you if necessary.\nNot required, but strongly recommended to provide one so\nyou can be reached if there is a problem. Your email is\nnot sent to any Caddy mothership or used for any purpose\nother than ACME transactions.\n",
"markdownDescription":"email: `string` \nModule: `tls.issuance.zerossl` \nYour email address, so the CA can contact you if necessary.\nNot required, but strongly recommended to provide one so\nyou can be reached if there is a problem. Your email is\nnot sent to any Caddy mothership or used for any purpose\nother than ACME transactions. \n",
"type":"string"
},
"external_account":{
"description":"external_account: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/mholt/acmez/acme#EAB\nIf using an ACME CA that requires an external account\nbinding, specify the CA-provided credentials here.\n\n\nEAB (External Account Binding) contains information\nnecessary to bind or map an ACME account to some\nother account known by the CA.\n\nExternal account bindings are \"used to associate an\nACME account with an existing account in a non-ACME\nsystem, such as a CA customer database.\"\n\n\"To enable ACME account binding, the CA operating the\nACME server needs to provide the ACME client with a\nMAC key and a key identifier, using some mechanism\noutside of ACME.\" §7.3.4\n",
"markdownDescription":"external_account: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/mholt/acmez/acme#EAB) \nIf using an ACME CA that requires an external account\nbinding, specify the CA-provided credentials here.\n\n\nEAB (External Account Binding) contains information\nnecessary to bind or map an ACME account to some\nother account known by the CA.\n\nExternal account bindings are \"used to associate an\nACME account with an existing account in a non-ACME\nsystem, such as a CA customer database.\"\n\n\"To enable ACME account binding, the CA operating the\nACME server needs to provide the ACME client with a\nMAC key and a key identifier, using some mechanism\noutside of ACME.\" §7.3.4 \n",
"type":"object",
"properties":{
"key_id":{
"description":"key_id: string\nModule: tls.issuance.zerossl\n\"The key identifier MUST be an ASCII string.\" §7.3.4\n",
"markdownDescription":"key_id: `string` \nModule: `tls.issuance.zerossl` \n\"The key identifier MUST be an ASCII string.\" §7.3.4 \n",
"type":"string"
},
"mac_key":{
"description":"mac_key: string\nModule: tls.issuance.zerossl\n\"The MAC key SHOULD be provided in base64url-encoded\nform, to maximize compatibility between non-ACME\nprovisioning systems and ACME clients.\" §7.3.4\n",
"markdownDescription":"mac_key: `string` \nModule: `tls.issuance.zerossl` \n\"The MAC key SHOULD be provided in base64url-encoded\nform, to maximize compatibility between non-ACME\nprovisioning systems and ACME clients.\" §7.3.4 \n",
"type":"string"
}
}
},
"preferred_chains":{
"description":"preferred_chains: object\nModule: tls.issuance.zerossl\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChainPreference\nPreferences for selecting alternate certificate chains, if offered\nby the CA. By default, the first offered chain will be selected.\nIf configured, the chains may be sorted and the first matching chain\nwill be selected.\n\n\nChainPreference describes the client's preferred certificate chain,\nuseful if the CA offers alternate chains. The first matching chain\nwill be selected.\n",
"markdownDescription":"preferred_chains: `object` \nModule: `tls.issuance.zerossl` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls#ChainPreference) \nPreferences for selecting alternate certificate chains, if offered\nby the CA. By default, the first offered chain will be selected.\nIf configured, the chains may be sorted and the first matching chain\nwill be selected.\n\n\nChainPreference describes the client's preferred certificate chain,\nuseful if the CA offers alternate chains. The first matching chain\nwill be selected. \n",
"type":"object",
"properties":{
"any_common_name":{
"description":"any_common_name: array\nModule: tls.issuance.zerossl\nSelect first chain that has any issuer with one\nof these common names.\n",
"markdownDescription":"any_common_name: `array` \nModule: `tls.issuance.zerossl` \nSelect first chain that has any issuer with one\nof these common names. \n",
"type":"array",
"items":{
"description":"Select first chain that has any issuer with one\nof these common names.\n",
"markdownDescription":"Select first chain that has any issuer with one\nof these common names. \n",
"type":"string"
}
},
"root_common_name":{
"description":"root_common_name: array\nModule: tls.issuance.zerossl\nSelect first chain having a root with one of\nthese common names.\n",
"markdownDescription":"root_common_name: `array` \nModule: `tls.issuance.zerossl` \nSelect first chain having a root with one of\nthese common names. \n",
"type":"array",
"items":{
"description":"Select first chain having a root with one of\nthese common names.\n",
"markdownDescription":"Select first chain having a root with one of\nthese common names. \n",
"type":"string"
}
},
"smallest":{
"description":"smallest: boolean\nModule: tls.issuance.zerossl\nPrefer chains with the fewest number of bytes.\n",
"markdownDescription":"smallest: `boolean` \nModule: `tls.issuance.zerossl` \nPrefer chains with the fewest number of bytes. \n",
"type":"boolean"
}
}
},
"test_ca":{
"description":"test_ca: string\nModule: tls.issuance.zerossl\nThe URL to the test CA's ACME directory endpoint.\nThis endpoint is only used during retries if there\nis a failure using the primary CA. Default:\nhttps://acme-staging-v02.api.letsencrypt.org/directory\n",
"markdownDescription":"test_ca: `string` \nModule: `tls.issuance.zerossl` \nThe URL to the test CA's ACME directory endpoint.\nThis endpoint is only used during retries if there\nis a failure using the primary CA. Default:\nhttps://acme-staging-v02.api.letsencrypt.org/directory \n",
"type":"string"
},
"trusted_roots_pem_files":{
"description":"trusted_roots_pem_files: array\nModule: tls.issuance.zerossl\nAn array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes.\n",
"markdownDescription":"trusted_roots_pem_files: `array` \nModule: `tls.issuance.zerossl` \nAn array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes. \n",
"type":"array",
"items":{
"description":"An array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes.\n",
"markdownDescription":"An array of files of CA certificates to accept when connecting to the\nACME CA. Generally, you should only use this if the ACME CA endpoint\nis internal or for development/testing purposes. \n",
"type":"string"
}
}
}
},
"tls.stek.distributed":{
"description":"distributed: object\nModule: tls.stek.distributed\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls/distributedstek#Provider\nProvider implements a distributed STEK provider. This\nmodule will obtain STEKs from a storage module instead\nof generating STEKs internally. This allows STEKs to be\ncoordinated, improving TLS session resumption in a cluster.\n\n",
"markdownDescription":"distributed: `object` \nModule: `tls.stek.distributed` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls/distributedstek#Provider) \nProvider implements a distributed STEK provider. This\nmodule will obtain STEKs from a storage module instead\nof generating STEKs internally. This allows STEKs to be\ncoordinated, improving TLS session resumption in a cluster.\n \n",
"type":"object",
"properties":{
"storage":{
"description":"storage: object\nModule: caddy.storage\nThe storage module wherein to store and obtain session\nticket keys. If unset, Caddy's default/global-configured\nstorage module will be used.\n",
"markdownDescription":"storage: `object` \nModule: `caddy.storage` \nThe storage module wherein to store and obtain session\nticket keys. If unset, Caddy's default/global-configured\nstorage module will be used. \n",
"type":"object",
"required":[
"module"
],
"allOf":[
{
"if":{
"properties":{
"module":{
"const":"consul"
}
}
},
"then":{
"$ref":"#/definitions/caddy.storage.consul"
}
},
{
"if":{
"properties":{
"module":{
"const":"file_system"
}
}
},
"then":{
"$ref":"#/definitions/caddy.storage.file_system"
}
},
{
"properties":{
"module":{
"description":"key to identify storage module.\nmodule: string\nModule: caddy.storage",
"markdownDescription":"key to identify `storage` module. \nmodule: `string` \nModule: `caddy.storage`",
"description":"admin: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminConfig\nAdminConfig configures Caddy's API endpoint, which is used\nto manage Caddy while it is running.\n\n",
"markdownDescription":"admin: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminConfig) \nAdminConfig configures Caddy's API endpoint, which is used\nto manage Caddy while it is running.\n \n",
"type":"object",
"properties":{
"config":{
"description":"config: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ConfigSettings\nOptions pertaining to configuration management.\n\n\nConfigSettings configures the management of configuration.\n",
"markdownDescription":"config: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ConfigSettings) \nOptions pertaining to configuration management.\n\n\nConfigSettings configures the management of configuration. \n",
"type":"object",
"properties":{
"load":{
"description":"load: object\nModule: caddy.config_loaders\nLoads a configuration to use. This is helpful if your configs are\nmanaged elsewhere, and you want Caddy to pull its config dynamically\nwhen it starts. The pulled config completely replaces the current\none, just like any other config load. It is an error if a pulled\nconfig is configured to pull another config.\n\nEXPERIMENTAL: Subject to change.\n",
"markdownDescription":"load: `object` \nModule: `caddy.config_loaders` \nLoads a configuration to use. This is helpful if your configs are\nmanaged elsewhere, and you want Caddy to pull its config dynamically\nwhen it starts. The pulled config completely replaces the current\none, just like any other config load. It is an error if a pulled\nconfig is configured to pull another config.\n\nEXPERIMENTAL: Subject to change. \n",
"type":"object",
"required":[
"module"
],
"allOf":[
{
"if":{
"properties":{
"module":{
"const":"http"
}
}
},
"then":{
"$ref":"#/definitions/caddy.config_loaders.http"
}
},
{
"properties":{
"module":{
"description":"key to identify load module.\nmodule: string\nModule: caddy.config_loaders",
"markdownDescription":"key to identify `load` module. \nmodule: `string` \nModule: `caddy.config_loaders`",
"type":"string",
"enum":[
"http"
]
}
}
}
]
},
"load_delay":{
"description":"load_delay: number",
"markdownDescription":"load_delay: `number`",
"type":"number"
},
"persist":{
"description":"persist: boolean\nWhether to keep a copy of the active config on disk. Default is true.\nNote that \"pulled\" dynamic configs (using the neighboring \"load\" module)\nare not persisted; only configs that are pushed to Caddy get persisted.\n",
"markdownDescription":"persist: `boolean` \nWhether to keep a copy of the active config on disk. Default is true.\nNote that \"pulled\" dynamic configs (using the neighboring \"load\" module)\nare not persisted; only configs that are pushed to Caddy get persisted. \n",
"type":"boolean"
}
}
},
"disabled":{
"description":"disabled: boolean\nIf true, the admin endpoint will be completely disabled.\nNote that this makes any runtime changes to the config\nimpossible, since the interface to do so is through the\nadmin endpoint.\n",
"markdownDescription":"disabled: `boolean` \nIf true, the admin endpoint will be completely disabled.\nNote that this makes any runtime changes to the config\nimpossible, since the interface to do so is through the\nadmin endpoint. \n",
"type":"boolean"
},
"enforce_origin":{
"description":"enforce_origin: boolean\nIf true, CORS headers will be emitted, and requests to the\nAPI will be rejected if their `Host` and `Origin` headers\ndo not match the expected value(s). Use `origins` to\ncustomize which origins/hosts are allowed. If `origins` is\nnot set, the listen address is the only value allowed by\ndefault. Enforced only on local (plaintext) endpoint.\n",
"markdownDescription":"enforce_origin: `boolean` \nIf true, CORS headers will be emitted, and requests to the\nAPI will be rejected if their `Host` and `Origin` headers\ndo not match the expected value(s). Use `origins` to\ncustomize which origins/hosts are allowed. If `origins` is\nnot set, the listen address is the only value allowed by\ndefault. Enforced only on local (plaintext) endpoint. \n",
"type":"boolean"
},
"identity":{
"description":"identity: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#IdentityConfig\nOptions that establish this server's identity. Identity refers to\ncredentials which can be used to uniquely identify and authenticate\nthis server instance. This is required if remote administration is\nenabled (but does not require remote administration to be enabled).\nDefault: no identity management.\n\n\nIdentityConfig configures management of this server's identity. An identity\nconsists of credentials that uniquely verify this instance; for example,\nTLS certificates (public + private key pairs).\n",
"markdownDescription":"identity: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#IdentityConfig) \nOptions that establish this server's identity. Identity refers to\ncredentials which can be used to uniquely identify and authenticate\nthis server instance. This is required if remote administration is\nenabled (but does not require remote administration to be enabled).\nDefault: no identity management.\n\n\nIdentityConfig configures management of this server's identity. An identity\nconsists of credentials that uniquely verify this instance; for example,\nTLS certificates (public + private key pairs). \n",
"type":"object",
"properties":{
"identifiers":{
"description":"identifiers: array\nList of names or IP addresses which refer to this server.\nCertificates will be obtained for these identifiers so\nsecure TLS connections can be made using them.\n",
"markdownDescription":"identifiers: `array` \nList of names or IP addresses which refer to this server.\nCertificates will be obtained for these identifiers so\nsecure TLS connections can be made using them. \n",
"type":"array",
"items":{
"description":"List of names or IP addresses which refer to this server.\nCertificates will be obtained for these identifiers so\nsecure TLS connections can be made using them.\n",
"markdownDescription":"List of names or IP addresses which refer to this server.\nCertificates will be obtained for these identifiers so\nsecure TLS connections can be made using them. \n",
"type":"string"
}
},
"issuers":{
"description":"issuers: array\nModule: tls.issuance\nIssuers that can provide this admin endpoint its identity\ncertificate(s). Default: ACME issuers configured for\nZeroSSL and Let's Encrypt. Be sure to change this if you\nrequire credentials for private identifiers.\n",
"markdownDescription":"issuers: `array` \nModule: `tls.issuance` \nIssuers that can provide this admin endpoint its identity\ncertificate(s). Default: ACME issuers configured for\nZeroSSL and Let's Encrypt. Be sure to change this if you\nrequire credentials for private identifiers. \n",
"type":"array",
"items":{
"description":"Issuers that can provide this admin endpoint its identity\ncertificate(s). Default: ACME issuers configured for\nZeroSSL and Let's Encrypt. Be sure to change this if you\nrequire credentials for private identifiers.\n",
"markdownDescription":"Issuers that can provide this admin endpoint its identity\ncertificate(s). Default: ACME issuers configured for\nZeroSSL and Let's Encrypt. Be sure to change this if you\nrequire credentials for private identifiers. \n",
"required":[
"module"
],
"allOf":[
{
"if":{
"properties":{
"module":{
"const":"acme"
}
}
},
"then":{
"$ref":"#/definitions/tls.issuance.acme"
}
},
{
"if":{
"properties":{
"module":{
"const":"internal"
}
}
},
"then":{
"$ref":"#/definitions/tls.issuance.internal"
}
},
{
"if":{
"properties":{
"module":{
"const":"zerossl"
}
}
},
"then":{
"$ref":"#/definitions/tls.issuance.zerossl"
}
},
{
"properties":{
"module":{
"description":"key to identify issuers module.\nmodule: string\nModule: tls.issuance",
"markdownDescription":"key to identify `issuers` module. \nmodule: `string` \nModule: `tls.issuance`",
"type":"string",
"enum":[
"acme",
"internal",
"zerossl"
]
}
}
}
]
}
}
}
},
"listen":{
"description":"listen: string\nThe address to which the admin endpoint's listener should\nbind itself. Can be any single network address that can be\nparsed by Caddy. Default: localhost:2019\n",
"markdownDescription":"listen: `string` \nThe address to which the admin endpoint's listener should\nbind itself. Can be any single network address that can be\nparsed by Caddy. Default: localhost:2019 \n",
"type":"string"
},
"origins":{
"description":"origins: array\nThe list of allowed origins/hosts for API requests. Only needed\nif accessing the admin endpoint from a host different from the\nsocket's network interface or if `enforce_origin` is true. If not\nset, the listener address will be the default value. If set but\nempty, no origins will be allowed. Enforced only on local\n(plaintext) endpoint.\n",
"markdownDescription":"origins: `array` \nThe list of allowed origins/hosts for API requests. Only needed\nif accessing the admin endpoint from a host different from the\nsocket's network interface or if `enforce_origin` is true. If not\nset, the listener address will be the default value. If set but\nempty, no origins will be allowed. Enforced only on local\n(plaintext) endpoint. \n",
"type":"array",
"items":{
"description":"The list of allowed origins/hosts for API requests. Only needed\nif accessing the admin endpoint from a host different from the\nsocket's network interface or if `enforce_origin` is true. If not\nset, the listener address will be the default value. If set but\nempty, no origins will be allowed. Enforced only on local\n(plaintext) endpoint.\n",
"markdownDescription":"The list of allowed origins/hosts for API requests. Only needed\nif accessing the admin endpoint from a host different from the\nsocket's network interface or if `enforce_origin` is true. If not\nset, the listener address will be the default value. If set but\nempty, no origins will be allowed. Enforced only on local\n(plaintext) endpoint. \n",
"type":"string"
}
},
"remote":{
"description":"remote: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#RemoteAdmin\nOptions pertaining to remote administration. By default, remote\nadministration is disabled. If enabled, identity management must\nalso be configured, as that is how the endpoint is secured.\nSee the neighboring \"identity\" object.\n\nEXPERIMENTAL: This feature is subject to change.\n\n\nRemoteAdmin enables and configures remote administration. If enabled,\na secure listener enforcing mutual TLS authentication will be started\non a different port from the standard plaintext admin server.\n\nThis endpoint is secured using identity management, which must be\nconfigured separately (because identity management does not depend\non remote administration). See the admin/identity config struct.\n\nEXPERIMENTAL: Subject to change.\n",
"markdownDescription":"remote: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#RemoteAdmin) \nOptions pertaining to remote administration. By default, remote\nadministration is disabled. If enabled, identity management must\nalso be configured, as that is how the endpoint is secured.\nSee the neighboring \"identity\" object.\n\nEXPERIMENTAL: This feature is subject to change.\n\n\nRemoteAdmin enables and configures remote administration. If enabled,\na secure listener enforcing mutual TLS authentication will be started\non a different port from the standard plaintext admin server.\n\nThis endpoint is secured using identity management, which must be\nconfigured separately (because identity management does not depend\non remote administration). See the admin/identity config struct.\n\nEXPERIMENTAL: Subject to change. \n",
"type":"object",
"properties":{
"access_control":{
"description":"access_control: array\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminAccess\nList of access controls for this secure admin endpoint.\nThis configures TLS mutual authentication (i.e. authorized\nclient certificates), but also application-layer permissions\nlike which paths and methods each identity is authorized for.\n\n\nAdminAccess specifies what permissions an identity or group\nof identities are granted.\n",
"markdownDescription":"access_control: `array` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminAccess) \nList of access controls for this secure admin endpoint.\nThis configures TLS mutual authentication (i.e. authorized\nclient certificates), but also application-layer permissions\nlike which paths and methods each identity is authorized for.\n\n\nAdminAccess specifies what permissions an identity or group\nof identities are granted. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminAccess\nList of access controls for this secure admin endpoint.\nThis configures TLS mutual authentication (i.e. authorized\nclient certificates), but also application-layer permissions\nlike which paths and methods each identity is authorized for.\n\n\nAdminAccess specifies what permissions an identity or group\nof identities are granted.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminAccess) \nList of access controls for this secure admin endpoint.\nThis configures TLS mutual authentication (i.e. authorized\nclient certificates), but also application-layer permissions\nlike which paths and methods each identity is authorized for.\n\n\nAdminAccess specifies what permissions an identity or group\nof identities are granted. \n",
"type":"object",
"properties":{
"permissions":{
"description":"permissions: array\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminPermissions\nLimits what the associated identities are allowed to do.\nIf unspecified, all permissions are granted.\n\n\nAdminPermissions specifies what kinds of requests are allowed\nto be made to the admin endpoint.\n",
"markdownDescription":"permissions: `array` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminPermissions) \nLimits what the associated identities are allowed to do.\nIf unspecified, all permissions are granted.\n\n\nAdminPermissions specifies what kinds of requests are allowed\nto be made to the admin endpoint. \n",
"type":"array",
"items":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminPermissions\nLimits what the associated identities are allowed to do.\nIf unspecified, all permissions are granted.\n\n\nAdminPermissions specifies what kinds of requests are allowed\nto be made to the admin endpoint.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#AdminPermissions) \nLimits what the associated identities are allowed to do.\nIf unspecified, all permissions are granted.\n\n\nAdminPermissions specifies what kinds of requests are allowed\nto be made to the admin endpoint. \n",
"type":"object",
"properties":{
"methods":{
"description":"methods: array\nThe HTTP methods allowed for the given paths.\n",
"markdownDescription":"methods: `array` \nThe HTTP methods allowed for the given paths. \n",
"type":"array",
"items":{
"description":"The HTTP methods allowed for the given paths.\n",
"markdownDescription":"The HTTP methods allowed for the given paths. \n",
"type":"string"
}
},
"paths":{
"description":"paths: array\nThe API paths allowed. Paths are simple prefix matches.\nAny subpath of the specified paths will be allowed.\n",
"markdownDescription":"paths: `array` \nThe API paths allowed. Paths are simple prefix matches.\nAny subpath of the specified paths will be allowed. \n",
"type":"array",
"items":{
"description":"The API paths allowed. Paths are simple prefix matches.\nAny subpath of the specified paths will be allowed.\n",
"markdownDescription":"The API paths allowed. Paths are simple prefix matches.\nAny subpath of the specified paths will be allowed. \n",
"type":"string"
}
}
}
}
},
"public_keys":{
"description":"public_keys: array\nBase64-encoded DER certificates containing public keys to accept.\n(The contents of PEM certificate blocks are base64-encoded DER.)\nAny of these public keys can appear in any part of a verified chain.\n",
"markdownDescription":"public_keys: `array` \nBase64-encoded DER certificates containing public keys to accept.\n(The contents of PEM certificate blocks are base64-encoded DER.)\nAny of these public keys can appear in any part of a verified chain. \n",
"type":"array",
"items":{
"description":"Base64-encoded DER certificates containing public keys to accept.\n(The contents of PEM certificate blocks are base64-encoded DER.)\nAny of these public keys can appear in any part of a verified chain.\n",
"markdownDescription":"Base64-encoded DER certificates containing public keys to accept.\n(The contents of PEM certificate blocks are base64-encoded DER.)\nAny of these public keys can appear in any part of a verified chain. \n",
"type":"string"
}
}
}
}
},
"listen":{
"description":"listen: string\nThe address on which to start the secure listener.\nDefault: :2021\n",
"markdownDescription":"listen: `string` \nThe address on which to start the secure listener.\nDefault: :2021 \n",
"type":"string"
}
}
}
}
},
"apps":{
"description":"apps: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap\nAppsRaw are the apps that Caddy will load and run. The\napp module name is the key, and the app's config is the\nassociated value.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage.\n",
"markdownDescription":"apps: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#ModuleMap) \nAppsRaw are the apps that Caddy will load and run. The\napp module name is the key, and the app's config is the\nassociated value.\n\n\nModuleMap is a map that can contain multiple modules,\nwhere the map key is the module's name. (The namespace\nis usually read from an associated field's struct tag.)\nBecause the module's name is given as the key in a\nmodule map, the name does not have to be given in the\njson.RawMessage. \n",
"description":"logging: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#Logging\nLogging facilitates logging within Caddy. The default log is\ncalled \"default\" and you can customize it. You can also define\nadditional logs.\n\nBy default, all logs at INFO level and higher are written to\nstandard error (\"stderr\" writer) in a human-readable format\n(\"console\" encoder if stdout is an interactive terminal, \"json\"\nencoder otherwise).\n\nAll defined logs accept all log entries by default, but you\ncan filter by level and module/logger names. A logger's name\nis the same as the module's name, but a module may append to\nlogger names for more specificity. For example, you can\nfilter logs emitted only by HTTP handlers using the name\n\"http.handlers\", because all HTTP handler module names have\nthat prefix.\n\nCaddy logs (except the sink) are zero-allocation, so they are\nvery high-performing in terms of memory and CPU time. Enabling\nsampling can further increase throughput on extremely high-load\nservers.\n\n",
"markdownDescription":"logging: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#Logging) \nLogging facilitates logging within Caddy. The default log is\ncalled \"default\" and you can customize it. You can also define\nadditional logs.\n\nBy default, all logs at INFO level and higher are written to\nstandard error (\"stderr\" writer) in a human-readable format\n(\"console\" encoder if stdout is an interactive terminal, \"json\"\nencoder otherwise).\n\nAll defined logs accept all log entries by default, but you\ncan filter by level and module/logger names. A logger's name\nis the same as the module's name, but a module may append to\nlogger names for more specificity. For example, you can\nfilter logs emitted only by HTTP handlers using the name\n\"http.handlers\", because all HTTP handler module names have\nthat prefix.\n\nCaddy logs (except the sink) are zero-allocation, so they are\nvery high-performing in terms of memory and CPU time. Enabling\nsampling can further increase throughput on extremely high-load\nservers.\n \n",
"type":"object",
"properties":{
"logs":{
"description":"logs: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#CustomLog\nLogs are your logs, keyed by an arbitrary name of your\nchoosing. The default log can be customized by defining\na log called \"default\". You can further define other logs\nand filter what kinds of entries they accept.\n\n\nCustomLog represents a custom logger configuration.\n\nBy default, a log will emit all log entries. Some entries\nwill be skipped if sampling is enabled. Further, the Include\nand Exclude parameters define which loggers (by name) are\nallowed or rejected from emitting in this log. If both Include\nand Exclude are populated, their values must be mutually\nexclusive, and longer namespaces have priority. If neither\nare populated, all logs are emitted.\n",
"markdownDescription":"logs: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#CustomLog) \nLogs are your logs, keyed by an arbitrary name of your\nchoosing. The default log can be customized by defining\na log called \"default\". You can further define other logs\nand filter what kinds of entries they accept.\n\n\nCustomLog represents a custom logger configuration.\n\nBy default, a log will emit all log entries. Some entries\nwill be skipped if sampling is enabled. Further, the Include\nand Exclude parameters define which loggers (by name) are\nallowed or rejected from emitting in this log. If both Include\nand Exclude are populated, their values must be mutually\nexclusive, and longer namespaces have priority. If neither\nare populated, all logs are emitted. \n",
"type":"object",
"additionalProperties":{
"description":"https://pkg.go.dev/github.com/caddyserver/caddy/v2#CustomLog\nLogs are your logs, keyed by an arbitrary name of your\nchoosing. The default log can be customized by defining\na log called \"default\". You can further define other logs\nand filter what kinds of entries they accept.\n\n\nCustomLog represents a custom logger configuration.\n\nBy default, a log will emit all log entries. Some entries\nwill be skipped if sampling is enabled. Further, the Include\nand Exclude parameters define which loggers (by name) are\nallowed or rejected from emitting in this log. If both Include\nand Exclude are populated, their values must be mutually\nexclusive, and longer namespaces have priority. If neither\nare populated, all logs are emitted.\n",
"markdownDescription":"[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#CustomLog) \nLogs are your logs, keyed by an arbitrary name of your\nchoosing. The default log can be customized by defining\na log called \"default\". You can further define other logs\nand filter what kinds of entries they accept.\n\n\nCustomLog represents a custom logger configuration.\n\nBy default, a log will emit all log entries. Some entries\nwill be skipped if sampling is enabled. Further, the Include\nand Exclude parameters define which loggers (by name) are\nallowed or rejected from emitting in this log. If both Include\nand Exclude are populated, their values must be mutually\nexclusive, and longer namespaces have priority. If neither\nare populated, all logs are emitted. \n",
"properties":{
"encoder":{
"description":"encoder: object\nModule: caddy.logging.encoders\nThe encoder is how the log entries are formatted or encoded.\n",
"markdownDescription":"encoder: `object` \nModule: `caddy.logging.encoders` \nThe encoder is how the log entries are formatted or encoded. \n",
"description":"key to identify encoder module.\nformat: string\nModule: caddy.logging.encoders",
"markdownDescription":"key to identify `encoder` module. \nformat: `string` \nModule: `caddy.logging.encoders`",
"type":"string",
"enum":[
"console",
"filter",
"json"
]
}
}
}
]
},
"exclude":{
"description":"exclude: array\nExclude defines the names of loggers that should be\nskipped by this log. For example, to exclude only\nHTTP access logs, you would exclude \"http.log.access\".\n",
"markdownDescription":"exclude: `array` \nExclude defines the names of loggers that should be\nskipped by this log. For example, to exclude only\nHTTP access logs, you would exclude \"http.log.access\". \n",
"type":"array",
"items":{
"description":"Exclude defines the names of loggers that should be\nskipped by this log. For example, to exclude only\nHTTP access logs, you would exclude \"http.log.access\".\n",
"markdownDescription":"Exclude defines the names of loggers that should be\nskipped by this log. For example, to exclude only\nHTTP access logs, you would exclude \"http.log.access\". \n",
"type":"string"
}
},
"include":{
"description":"include: array\nInclude defines the names of loggers to emit in this\nlog. For example, to include only logs emitted by the\nadmin API, you would include \"admin.api\".\n",
"markdownDescription":"include: `array` \nInclude defines the names of loggers to emit in this\nlog. For example, to include only logs emitted by the\nadmin API, you would include \"admin.api\". \n",
"type":"array",
"items":{
"description":"Include defines the names of loggers to emit in this\nlog. For example, to include only logs emitted by the\nadmin API, you would include \"admin.api\".\n",
"markdownDescription":"Include defines the names of loggers to emit in this\nlog. For example, to include only logs emitted by the\nadmin API, you would include \"admin.api\". \n",
"type":"string"
}
},
"level":{
"description":"level: string\nLevel is the minimum level to emit, and is inclusive.\nPossible levels: DEBUG, INFO, WARN, ERROR, PANIC, and FATAL\n",
"markdownDescription":"level: `string` \nLevel is the minimum level to emit, and is inclusive.\nPossible levels: DEBUG, INFO, WARN, ERROR, PANIC, and FATAL \n",
"type":"string"
},
"sampling":{
"description":"sampling: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#LogSampling\nSampling configures log entry sampling. If enabled,\nonly some log entries will be emitted. This is useful\nfor improving performance on extremely high-pressure\nservers.\n\n\nLogSampling configures log entry sampling.\n",
"markdownDescription":"sampling: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#LogSampling) \nSampling configures log entry sampling. If enabled,\nonly some log entries will be emitted. This is useful\nfor improving performance on extremely high-pressure\nservers.\n\n\nLogSampling configures log entry sampling. \n",
"type":"object",
"properties":{
"first":{
"description":"first: number\nLog this many entries within a given level and\nmessage for each interval.\n",
"markdownDescription":"first: `number` \nLog this many entries within a given level and\nmessage for each interval. \n",
"type":"number"
},
"interval":{
"description":"interval: number\nhttps://pkg.go.dev/time#Duration\nThe window over which to conduct sampling.\n\n\nA Duration represents the elapsed time between two instants\nas an int64 nanosecond count. The representation limits the\nlargest representable duration to approximately 290 years.\n",
"markdownDescription":"interval: `number` \n[godoc](https://pkg.go.dev/time#Duration) \nThe window over which to conduct sampling.\n\n\nA Duration represents the elapsed time between two instants\nas an int64 nanosecond count. The representation limits the\nlargest representable duration to approximately 290 years. \n",
"type":"number"
},
"thereafter":{
"description":"thereafter: number\nIf more entries with the same level and message\nare seen during the same interval, keep one in\nthis many entries until the end of the interval.\n",
"markdownDescription":"thereafter: `number` \nIf more entries with the same level and message\nare seen during the same interval, keep one in\nthis many entries until the end of the interval. \n",
"type":"number"
}
}
},
"writer":{
"description":"writer: object\nModule: caddy.logging.writers\nThe writer defines where log entries are emitted.\n",
"markdownDescription":"writer: `object` \nModule: `caddy.logging.writers` \nThe writer defines where log entries are emitted. \n",
"description":"key to identify writer module.\noutput: string\nModule: caddy.logging.writers",
"markdownDescription":"key to identify `writer` module. \noutput: `string` \nModule: `caddy.logging.writers`",
"type":"string",
"enum":[
"discard",
"file",
"net",
"stderr",
"stdout"
]
}
}
}
]
}
}
}
},
"sink":{
"description":"sink: object\nhttps://pkg.go.dev/github.com/caddyserver/caddy/v2#StandardLibLog\nSink is the destination for all unstructured logs emitted\nfrom Go's standard library logger. These logs are common\nin dependencies that are not designed specifically for use\nin Caddy. Because it is global and unstructured, the sink\nlacks most advanced features and customizations.\n\n\nStandardLibLog configures the default Go standard library\nglobal logger in the log package. This is necessary because\nmodule dependencies which are not built specifically for\nCaddy will use the standard logger. This is also known as\nthe \"sink\" logger.\n",
"markdownDescription":"sink: `object` \n[godoc](https://pkg.go.dev/github.com/caddyserver/caddy/v2#StandardLibLog) \nSink is the destination for all unstructured logs emitted\nfrom Go's standard library logger. These logs are common\nin dependencies that are not designed specifically for use\nin Caddy. Because it is global and unstructured, the sink\nlacks most advanced features and customizations.\n\n\nStandardLibLog configures the default Go standard library\nglobal logger in the log package. This is necessary because\nmodule dependencies which are not built specifically for\nCaddy will use the standard logger. This is also known as\nthe \"sink\" logger. \n",
"type":"object",
"properties":{
"writer":{
"description":"writer: object\nModule: caddy.logging.writers\nThe module that writes out log entries for the sink.\n",
"markdownDescription":"writer: `object` \nModule: `caddy.logging.writers` \nThe module that writes out log entries for the sink. \n",
"description":"storage: object\nModule: caddy.storage\nStorageRaw is a storage module that defines how/where Caddy\nstores assets (such as TLS certificates). The default storage\nmodule is `caddy.storage.file_system` (the local file system),\nand the default path\n[depends on the OS and environment](/docs/conventions#data-directory).\n",
"markdownDescription":"storage: `object` \nModule: `caddy.storage` \nStorageRaw is a storage module that defines how/where Caddy\nstores assets (such as TLS certificates). The default storage\nmodule is `caddy.storage.file_system` (the local file system),\nand the default path\n[depends on the OS and environment](/docs/conventions#data-directory). \n",
"type":"object",
"required":[
"module"
],
"allOf":[
{
"if":{
"properties":{
"module":{
"const":"consul"
}
}
},
"then":{
"$ref":"#/definitions/caddy.storage.consul"
}
},
{
"if":{
"properties":{
"module":{
"const":"file_system"
}
}
},
"then":{
"$ref":"#/definitions/caddy.storage.file_system"
}
},
{
"properties":{
"module":{
"description":"key to identify storage module.\nmodule: string\nModule: caddy.storage",
"markdownDescription":"key to identify `storage` module. \nmodule: `string` \nModule: `caddy.storage`",
