Command Line Interface
This page describes Casket's command line interface. For a quick reference and to see default values, run Casket with
-h, for example:
Remember that Casket runs fine without any options. These flags simply give you more control over the process if needed.
Indicates that you have read and agree to the Let's Encrypt Subscriber Agreement. If this flag is not specified, it is possible that Casket will prompt you to agree to terms during runtime. Thus, this flag is recommended in automated environments.
Base URL to the certificate authority's ACME server directory. Used for creating TLS certificates.
Change the ACME CA HTTP timeout. Not usually necessary unless your network experiences significant latency contacting the ACME CA server. In those cases, raising this value can help. Accepts a duration value; default is
The Casketfile to use to configure Casket. Must be a valid path to the file, either relative or absolute. Can be a glob string as well, to load all matching files as if they were imported into a single configuration.
CPU cap. Can be a percentage (e.g. "75%") or a number indicating how many cores to use (e.g. 3).
Specifies a default ServerName (SNI) value to use during a TLS handshake if the ClientHello has an empty one. Setting this flag essentially chooses a "default" certificate to respond with if a client does not support SNI. This setting does not apply when the client provides a ServerName value.
Disables the ACME HTTP challenge used for obtaining certificates.
Disables the ACME TLS-ALPN challenge used for obtaining certificates.
Comma-separated list of specific telemetry metrics to disable. Note that only top-level metrics can be specified (i.e. "cpu", but not "cpu.aes_ni").
Print the environment and exit.
The file from which to load the environment.
Email address to use for TLS certificate generation if not specified for a site in the Casketfile. It is not required, but is strongly recommended so you can recover your account if you lose your private key. If an email is not available, Casket may prompt you for an email address during runtime. This option is recommended in automated environments if not specified in the Casketfile.
Duration of the graceful shutdown period. If you reload extremely frequently (multiple times per second), make this duration short. Syntax is same as Go's time.ParseDuration function (5s, 1m30s, etc).
-help or -h
Show basic flag help. Casket will terminate after showing help; it will not serve sites.
The default hostname or IP address to listen on. Sites defined in the Casketfile without a hostname will assume this one. This is usually used with
-port to quickly get simple sites up and running without a Casketfile.
The port to use for HTTP (default 80). Changing this can have unintended consequences, be careful. The ACME HTTP challenge requires port 80 externally. Using this flag implies you are forwarding port 80 internally.
The port to use for HTTPS (default 443). Changing this can have unintended consequences, be careful. The ACME TLS-ALPN challenge requires port 443 externally. Using this flag implies you are forwarding port 443 internally.
HTTP/2 support. Disable it for the whole process by setting to false. To disable for specific sites, use the tls directive's "alpn" setting.
Enable the process log. The value must be either the path to a log file, stdout, or stderr. Casket will create the log file if it does not already exist. This file will be used to log information and errors that occur during runtime. The log file is rotated when it gets large, so it is safe to use for long-running processes.
The number of megabytes at which the process log file should be rolled/rotated. Default is 100. Set to 0 to disable automatic process log rotation.
If true, rotated process log files will be gzipped. Default is true.
The pidfile to write. Used with automated environments. Casket will write a file containing the current process ID.
Lists the plugins registered with Casket. Casket will terminate after printing; it will not serve sites.
The default port to listen on. This is usually used with
-host to quickly get simple sites up and running without a Casketfile.
Enables experimental QUIC support. See the QUIC wiki page for more details how to experiment with QUIC.
Quiet mode. If quiet, Casket will not print informational initialization output, only the addresses being served.
Hostname for which to revoke the SSL certificate. Casket will stop after revocation is complete; it will not serve sites if this option is used. The certificate must be under Casket's management.
Revocation is meant for compromised private keys only. Do not revoke a certificate to renew it.
Path to the default site root from which to serve files.
Change the server type. Default is http. If your Casketfile is for another server type, use this option to tell it which server type to use.
Parse the Casketfile and exit. If syntactically valid, a message will be printed to stdout and the process log (if any) and will exit with status 0. If not, an error will be returned with a non-zero exit status.
Print the version. It also prints build information if not from a tagged release. Casket will terminate after printing; it does not serve sites if this option is used.
On POSIX-compliant systems, Casket can be controlled with signals. Here we list them roughly in order from the most forceful action to most graceful.
Forcefully exits the process immediately. This signal cannot be caught, so Casket won't know what hit it. Any pidfile created with the
-pidfile flag and other runtime assets will NOT be cleaned up by Casket.
Forcefully exits the process without executing shutdown hooks.
Forcefully exits the process after executing shutdown hooks. This is the only "signal" that works on Windows (Ctrl+C). A second SIGINT forces immediate termination, even if shutdown hooks are still running.
Gracefully stops the server after executing shutdown hooks.
Reloads the configuration file, then gracefully restarts the server. If there is an error with the new configuration, the error is logged and the configuration rolls back with zero downtime.
Gracefully restarts the process with an updated binary. Useful when upgrading the Casket binary. Replace the binary with a new version and send this signal. Configuration will be transferred to the new process. If an error occurs, the error will be logged and the configuration rolls back with zero downtime.
Casket also accepts non-flag arguments, which are understood to be shorthand Casketfile text. This is useful for quick, temporary server instances.
Each unflagged argument is a line in a Casketfile that serves the default host and port. Remember to enclose the line in quotes if it contains spaces or other special characters.
For example, a server that lets you browse files on the default host and port:
To serve markdown files on-the-fly, instantly, on a custom port:
casket -port 8080 markdown
All of the above, but with an access log:
casket -port 8080 browse markdown "log access.log"
This shorthand feature is intended for quick, simple configurations only.
Pipe a Casketfile
Advanced users may wish to pipe the contents of a Casketfile into Casket from programmed environments. If you pipe in the Casketfile, you must use the
-conf flag with a value of
stdin - for example:
echo "localhost:1234" | casket -conf stdin
Piping the Casketfile is convenient when starting Casket using a dynamically-generated Casketfile from a parent process you have control over.
If you pipe in a Casketfile, it will be impossible to read from stdin later in the program because the parent process must send EOF to close the pipe so Casket can unblock and start serving. This will cause problems, for instance, if Casket has to prompt you for an email address or agreement to terms. So when piping input, use flags to avoid the need for stdin later (e.g. the -email flag).
Casket recognizes certain environment variables.
The home folder. Casket will create a .casket folder here if using managed TLS (automatic HTTPS), and possibly persist other state here in the future or if configured to do so.
If set, Casket will use this folder to store assets instead of the default $HOME/.casket. When running multiple Casket instances serving unrelated sites (e.g. as part of a hosting service shared among many users), it is strongly recommended for each Casket instance to have its own CASKETPATH so that instances aren't stepping on each other and sharing state.
true, Casket will treat request paths in a case-sensitive manner when accessing assets on the file system or matching requests for middleware handlers. The default is 0 (false; meaning case-INsensitive paths).
A custom file path to the file where the instance UUID is stored. This should be set if you have multiple Casket instances configured to share the same CASKETPATH (e.g. in a cluster), so that each instance will act individually. (They can still share the CASKETPATH and gain the benefits of sharing certificate resources, etc.)
The name of the clustering plugin to use. Cluster plugins allow Casket to operate in clusters or behind load balancers with any storage backend implemented by the plugin. The default is "file" which uses the local file system, meaning that if the CASKETPATH is a shared folder, any instances in the cluster sharing that folder can coordinate the management of certificates, etc. See the docs for your clustering plugin to know how to configure it; and see a list of CertMagic storage implementations.
- 0 - normal or expected exit
- 1 - error before server finished starting
- 2 - double SIGINT (force quit)
- 3 - error stopping with SIGTERM
- 4 - shutdown callback(s) returned error(s)
A good rule of thumb is to NOT automatically restart Casket if it exits with status of 1.