Use the Docker CLI to pull this image
By default Vaultbot will only renew certificates that are due for renewal within a specified period. Therefore Vaultbot is ideal for running at a fixed interval (e.g. crontab). This tool is also inspired by the well-known certbot for letsencrypt.
Requesting and renewing a certificate is straightforward. See the following self-explanatory example:
./vaultbot --vault_addr=http://localhost:1234 --vault_token=myroot --pki_mount=pki --pki_role_name=example-dot-com --pki_common_name=mydomain.com --pki_ttl=24h --pki_renew_time=4h --pki_alt_names=otherdomain.com,testing.com --pki_ip_sans=127.0.0.1
You can also see further usage information by running
In addition to the Docker Image, there are automated builds for all major platforms. You can find all releases in the tags section. Simply click on downloads and select "artifacts" to get the desired version. Alternatively feel free to build the latest release from master yourself.
You can configure Vaultbot by specifying command line options or the corresponding environment variables.
Usage: vaultbot [OPTIONS] Application Options: -v, --verbose Show verbose debug information Vault Options: --vault_addr= The address of the Vault server expressed as a URL and port (default: http://127.0.0.1:8200) [$VAULT_ADDR] --vault_cacert= Path to a PEM-encoded CA cert file to use to verify the Vault server SSL certificate. [$VAULT_CACERT] --vault_capath= Path to a directory of PEM-encoded CA cert files to verify the Vault server SSL certificate. If VAULT_CACERT is specified, its value will take precedence. [$VAULT_CAPATH] --vault_client_cert= Path to a PEM-encoded client certificate for TLS authentication to the Vault server. [$VAULT_CLIENT_CERT] --vault_client_key= Path to an unencrypted PEM-encoded private key matching the client certificate. [$VAULT_CLIENT_KEY] --vault_client_timeout= Timeout variable for the vault client. [$VAULT_CLIENT_TIMEOUT] --vault_skip_verify If set, do not verify Vault's presented certificate before communicating with it. Setting this variable is not recommended except during testing. [$VAULT_SKIP_VERIFY] --vault_tls_server_name= If set, use the given name as the SNI host when connecting via TLS. [$VAULT_TLS_SERVER_NAME] --vault_max_retries= The maximum number of retries when a 5xx error code is encountered. [$VAULT_MAX_RETRIES] --vault_token= The Vault authentication token. [$VAULT_TOKEN] --vault_renew_token If set, vaultbot tries to automatically renew the current token [$RENEW_TOKEN] PKI Options: --pki_mount= Specifies the PKI backend mount path (default: pki) [$PKI_MOUNT] --pki_role_name= Specifies the name of the role to create the certificate against [$PKI_ROLE_NAME] --pki_common_name= Specifies the requested CN for the certificate [$PKI_ROLE_NAME] --pki_alt_names= Specifies requested Subject Alternative Names, in a comma-delimited list [$PKI_ALT_NAMES] --pki_ip_sans= Specifies requested IP Subject Alternative Names, in a comma-delimited list [$PKI_IP_SANS] --pki_ttl= Specifies requested Time To Live [$PKI_TTL] --pki_exclude_cn_from_sans If set, the given common_name will not be included in DNS or Email Subject Alternate Names (as appropriate) [$EXCLUDE_CN_FROM_SANS] --pki_renew_percent= Percentage of requested certificate TTL, which triggers a renewal when passed (>0.00, <1.00) (default: 0.75) [$PKI_RENEW_TIME] --pki_renew_time= Time in hours before certificate expiry, which triggers a renewal (e.g. 12h, 1m). Takes precedence over renew_time when set. [$PKI_RENEW_TIME] --pki_force_renew If set, the certificate will be renewed without checking the expiry [$PKI_FORCE_RENEW] --pki_cert_path= Path to the requested / to be updated certificate (default: cert.pem) [$PKI_CERT_PATH] --pki_cachain_path= Path to the CA Chain of the requested / to be updated certificate (default: chain.pem) [$PKI_CACHAIN_PATH] --pki_privkey_path= Path to the private key of the requested / to be updated certificate (default: key.pem) [$PKI_PRIVKEY_PATH] -y, --auto_confirm If set, user prompts will be auto confirmed with yes [$AUTO_CONFIRM] Help Options: -h, --help Show this help message
When Vaultbot is run and
pki_cert_path points to an existing certificate, the certificate is only renewed and overwritten when specific criteria are met.
You can either specify
pki_renew_percent (e.g. 0.75), to renew the certificate after 75% of its lifespan has been reached. Otherwise you can specify
pki_renew_time to set a fixed amount of time before the expiry-date, which will trigger a renewal when passed.
If you want to renew the certificate on every run, you can specify the
By default Vaultbot performs a small set of sanity checks before overwriting an existing certificate at the
If the newly requested certificate data (common name, dns alternative names, ip SANS) differs from the data specified in the existing certificate at the location, the user will be asked for confirmation.
If you want to skip these checks in automated environments, you can specify the
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
See also the list of contributors who participated in this project.