From 5ded580444e9258cb35a9c94192d3c1d63e7b74f Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Thu, 16 Feb 2023 11:14:07 -0500 Subject: [PATCH] cmd: Adjust documentation for commands (#5377) --- cmd/commands.go | 30 ++++++++++++++--------- modules/caddyhttp/reverseproxy/command.go | 17 +++++++++---- 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/cmd/commands.go b/cmd/commands.go index 9216b898a..9daabd144 100644 --- a/cmd/commands.go +++ b/cmd/commands.go @@ -91,14 +91,15 @@ the KEY=VALUE format will be loaded into the Caddy process. On Windows, the spawned child process will remain attached to the terminal, so closing the window will forcefully stop Caddy; to avoid forgetting this, try -using 'caddy run' instead to keep it in the foreground.`, +using 'caddy run' instead to keep it in the foreground. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("start", flag.ExitOnError) fs.String("config", "", "Configuration file") - fs.String("envfile", "", "Environment file to load") fs.String("adapter", "", "Name of config adapter to apply") - fs.String("pidfile", "", "Path of file to which to write process ID") + fs.String("envfile", "", "Environment file to load") fs.Bool("watch", false, "Reload changed config file automatically") + fs.String("pidfile", "", "Path of file to which to write process ID") return fs }(), }) @@ -138,7 +139,8 @@ save file. It is not an error if --resume is used and no autosave file exists. If --watch is specified, the config file will be loaded automatically after changes. ⚠️ This can make unintentional config changes easier; only use this -option in a local development environment.`, +option in a local development environment. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("run", flag.ExitOnError) fs.String("config", "", "Configuration file") @@ -163,7 +165,8 @@ Stops the background Caddy process as gracefully as possible. It requires that the admin API is enabled and accessible, since it will use the API's /stop endpoint. The address of this request can be customized -using the --address flag, or from the given --config, if not the default.`, +using the --address flag, or from the given --config, if not the default. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("stop", flag.ExitOnError) fs.String("address", "", "The address to use to reach the admin API endpoint, if not the default") @@ -185,7 +188,8 @@ workflows revolving around config files. Since the admin endpoint is configurable, the endpoint configuration is loaded from the --address flag if specified; otherwise it is loaded from the given -config file; otherwise the default is assumed.`, +config file; otherwise the default is assumed. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("reload", flag.ExitOnError) fs.String("config", "", "Configuration file (required)") @@ -273,7 +277,8 @@ for human readability. If --validate is used, the adapted config will be checked for validity. If the config is invalid, an error will be printed to stderr and a non- -zero exit status will be returned.`, +zero exit status will be returned. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("adapt", flag.ExitOnError) fs.String("config", "", "Configuration file to adapt (required)") @@ -295,7 +300,8 @@ This reveals any errors with the configuration through the loading and provisioning stages. If --envfile is specified, an environment file with environment variables in -the KEY=VALUE format will be loaded into the Caddy process.`, +the KEY=VALUE format will be loaded into the Caddy process. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("validate", flag.ExitOnError) fs.String("config", "", "Input configuration file") @@ -308,7 +314,7 @@ the KEY=VALUE format will be loaded into the Caddy process.`, RegisterCommand(Command{ Name: "fmt", Func: cmdFmt, - Usage: "[--overwrite] []", + Usage: "[--overwrite] [--diff] []", Short: "Formats a Caddyfile", Long: ` Formats the Caddyfile by adding proper indentation and spaces to improve @@ -324,7 +330,8 @@ is not a valid patch format. If you wish you use stdin instead of a regular file, use - as the path. When reading from stdin, the --overwrite flag has no effect: the result -is always printed to stdout.`, +is always printed to stdout. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("fmt", flag.ExitOnError) fs.Bool("overwrite", false, "Overwrite the input file with the results") @@ -339,7 +346,8 @@ is always printed to stdout.`, Short: "Upgrade Caddy (EXPERIMENTAL)", Long: ` Downloads an updated Caddy binary with the same modules/plugins at the -latest versions. EXPERIMENTAL: May be changed or removed.`, +latest versions. EXPERIMENTAL: May be changed or removed. +`, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("upgrade", flag.ExitOnError) fs.Bool("keep-backup", false, "Keep the backed up binary, instead of deleting it") diff --git a/modules/caddyhttp/reverseproxy/command.go b/modules/caddyhttp/reverseproxy/command.go index 44f4c2224..04fb9b4d9 100644 --- a/modules/caddyhttp/reverseproxy/command.go +++ b/modules/caddyhttp/reverseproxy/command.go @@ -35,7 +35,7 @@ func init() { caddycmd.RegisterCommand(caddycmd.Command{ Name: "reverse-proxy", Func: cmdReverseProxy, - Usage: "[--from ] [--to ] [--change-host-header]", + Usage: "[--from ] [--to ] [--change-host-header] [--insecure] [--internal-certs] [--disable-redirects]", Short: "A quick and production-ready reverse proxy", Long: ` A simple but production-ready reverse proxy. Useful for quick deployments, @@ -52,16 +52,23 @@ If the --from address has a host or IP, Caddy will attempt to serve the proxy over HTTPS with a certificate (unless overridden by the HTTP scheme or port). -If --change-host-header is set, the Host header on the request will be modified -from its original incoming value to the address of the upstream. (Otherwise, by -default, all incoming headers are passed through unmodified.) +If serving HTTPS: + --disable-redirects can be used to avoid binding to the HTTP port. + --internal-certs can be used to force issuance certs using the internal + CA instead of attempting to issue a public certificate. + +For proxying: + --change-host-header sets the Host header on the request to the address + of the upstream, instead of defaulting to the incoming Host header. + --insecure disables TLS verification with the upstream. WARNING: THIS + DISABLES SECURITY BY NOT VERIFYING THE UPSTREAM'S CERTIFICATE. `, Flags: func() *flag.FlagSet { fs := flag.NewFlagSet("reverse-proxy", flag.ExitOnError) fs.String("from", "localhost", "Address on which to receive traffic") fs.Var(&reverseProxyCmdTo, "to", "Upstream address(es) to which traffic should be sent") fs.Bool("change-host-header", false, "Set upstream Host header to address of upstream") - fs.Bool("insecure", false, "Disable TLS verification (WARNING: DISABLES SECURITY BY NOT VERIFYING SSL CERTIFICATES!)") + fs.Bool("insecure", false, "Disable TLS verification (WARNING: DISABLES SECURITY BY NOT VERIFYING TLS CERTIFICATES!)") fs.Bool("internal-certs", false, "Use internal CA for issuing certs") fs.Bool("debug", false, "Enable verbose debug logs") fs.Bool("disable-redirects", false, "Disable HTTP->HTTPS redirects")