{"id":13646502,"url":"https://github.com/cloudflare/certmgr","last_synced_at":"2025-04-06T08:15:16.410Z","repository":{"id":13855006,"uuid":"71087190","full_name":"cloudflare/certmgr","owner":"cloudflare","description":"Automated certificate management using a CFSSL CA.","archived":false,"fork":false,"pushed_at":"2024-09-22T16:55:09.000Z","size":34905,"stargazers_count":218,"open_issues_count":21,"forks_count":40,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-10-08T12:48:09.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-17T00:51:21.000Z","updated_at":"2024-09-10T10:55:29.000Z","dependencies_parsed_at":"2024-01-14T09:59:30.777Z","dependency_job_id":"b997a445-ac3f-44b0-bc61-b06a51e45315","html_url":"https://github.com/cloudflare/certmgr","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcertmgr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcertmgr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcertmgr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcertmgr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/certmgr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451667,"owners_count":20940944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:02:57.546Z","updated_at":"2025-04-06T08:15:16.377Z","avatar_url":"https://github.com/cloudflare.png","language":"Go","readme":"# certmgr\n\n[![Build Status](https://travis-ci.org/cloudflare/certmgr.svg?branch=master)](https://travis-ci.org/cloudflare/certmgr)\n[![godoc](https://godoc.org/github.com/cloudflare/certmgr?status.svg)](https://godoc.org/github.com/cloudflare/certmgr)\n\ncertmgr is a tool for managing certificates using CFSSL. It does the\nfollowing:\n\n* Ensures certificates are present.\n* Renews certificates before they expire.\n* Triggering a service reload or restart on certificate updates.\n\nIt operates on **certificate specs**, which are JSON files containing\nthe information needed to generate a certificate.\n\nAt regular intervals, `certmgr` will check that the parameters set in a certificate spec match the PKI material on disk. `certmgr` will take actions as needed in ensuring and regenerating PKI material as needed. If there's an error, a material refresh will happen at a later time.\n\nWhen run without any subcommands, certmgr will start monitoring\ncertificates. The configuration and specifications can be validated\nusing the `check` subcommand.\n\nIf you want to further understand the package logic, take a look at the [godocs](https://godoc.org/github.com/cloudflare/certmgr). \n\n**Note**: `certmgr` requires Go 1.11 or later due to [cfssl](https://github.com/cloudflare/cfssl) dependency. \n\n\n## Web server\n\nWhen appropriately configured, `certmgr` will start a web server that\nhas the following endpoints:\n\n* `/` just contains certmgr start time and current address.\n* `/metrics` is the Prometheus endpoint (see the Metrics section).\n\n## Metrics\n\nPrometheus is used to collect some useful `certmgr` metrics. You can find them in the [godoc](https://godoc.org/github.com/cloudflare/certmgr/metrics). \n\n## certmgr.yaml\n\nThe configuration file must be a YAML file; it is expected to be in\n`/etc/certmgr/certmgr.yaml`. The location can be changed using the\n`-f` flag.\n\nAn example `certmgr.yaml` file is:\n\n```\ndir: /etc/certmgr.d\ndefault_remote: ca.example.net:8888\nsvcmgr: systemd\nbefore: 72h\ninterval: 30m\n\nmetrics_port: 8080\nmetrics_address: localhost\n```\n\nThis contains all of the currently available parameters:\n\n* `dir`: this specifies the directory containing the certificate specs\n* `svcmgr`: this specifies the service manager to use for restarting\n  or reloading services. This can be `systemd` (using `systemctl`),\n  `sysv` (using `service`), `circus` (using `circusctl`), `openrc` (using `rc-service`),\n  `dummy` (no restart/reload behavior), or `command` (see the command svcmgr section\n  for details of how to use this).\n* `before`: optional: this is the default duration before a certificate expiry that certmgr starts attempting to\n  renew PKI.  This defaults to 72 hours.\n* `interval`: optional: this is the default for how often `certmgr` will check certificate expirations\n  and update PKI material on disk upon any changes (if necessary).  This defaults to one hour.\n* `interval_splay`: optional: this is used to vary the interval period.  A random time between 0\n  and this value is added to `interval` if specified.  This defaults to 0.\n* `initial_splay`: if specified, a random sleep period between 0 and this value is used\n  for the initial sleep after startup of a spec.  This provides a way to ensure that\n  if a fleet of certmgr are restarted at the same time, their period of wakeup is randomized\n  to avoid said fleet waking up and doing interval checks at the same time for a given spec.\n  This defaults to 0.\n* `metrics_address`: specifies the address for the Prometheus HTTP\n  endpoint.\n* `metrics_port`: specifies the port for the Prometheus HTTP endpoint.\n* `take_actions_only_if_running`: boolean, if true, only fire a spec's action if the service is actually running.\n  If this is set to false (the default for historical reasons), this can lead to certmgr starting a downed service\n  when PKI expiry occurs.\n\n\n## PKI Specs\n\nA spec is used to manage PKI material for a consuming app.  A spec does not have to request a certificate/key, and does not have to request a CA; it must request at least one of those two modes, however.\n\nSaid another way; you can use this to maintain a CA on disk.  You can use this to maintain certificate/key pair signed by the given authority; you can do both modes if you wish, but one must be specified by the spec.\n\nAn example spec that writes both a CA and certificate key pair defined in JSON:\n\n```\n{\n    \"service\": \"nginx\",\n    \"action\": \"restart\",\n    \"request\": {\n        \"CN\": \"www.example.net\",\n        \"hosts\": [\n            \"example.net\",\n            \"www.example.net\"\n        ],\n        \"key\": {\n            \"algo\": \"ecdsa\",\n            \"size\": 521\n        },\n        \"names\": [\n            {\n                \"C\": \"US\",\n                \"ST\": \"CA\",\n                \"L\": \"San Francisco\",\n                \"O\": \"Example, LLC\"\n            }\n        ]\n    },\n    \"private_key\": {\n        \"path\": \"/etc/ssl/private/www.key\",\n        \"owner\": \"www-data\",\n        \"group\": \"www-data\",\n        \"mode\": \"0600\"\n    },\n    \"certificate\": {\n        \"path\": \"/home/kyle/tmp/certmgr/certs/test1.pem\",\n        \"owner\": \"www-data\",\n        \"group\": \"www-data\"\n    },\n    \"ca\": {\n        \"path\": \"/etc/myservice/ca.pem\",\n        \"owner\": \"www-data\",\n        \"group\": \"www-data\"\n    },\n    \"authority\": {\n        \"remote\": \"ca.example.net:8888\",\n        \"auth_key\": \"012345678012345678\",\n        \"label\": \"www_ca\",\n        \"profile\": \"three-month\",\n        \"root_ca\": \"/etc/cfssl/api_server_ca.pem\"\n    }\n}\n```\n\nAnd this is an example that writes just the CA to disk:\n```\n{\n    \"service\": \"nginx\",\n    \"action\": \"restart\",\n    \"authority\": {\n        \"remote\": \"ca.example.net:8888\",\n        \"auth_key\": \"012345678012345678\",\n        \"label\": \"www_ca\",\n        \"profile\": \"three-month\",\n        \"file\": {\n            \"path\": \"/etc/myservice/ca.pem\",\n            \"owner\": \"www-data\",\n            \"group\": \"www-data\"\n        },\n        \"root_ca\": \"/etc/cfssl/api_server_ca.pem\"\n    }\n}\n```\n\nA certificate spec has the following fields:\n\n* `service`: this is optional, and names the service that the `action`\n  should be applied to.\n* `action`: this is optional, and may be one of \"restart\", \"reload\",\n  or \"nop\".\n* `svcmgr`: this is optional, and defaults to whatever the global\n  config defines.  This allows fine-grained control for specifying the\n  svcmgr per cert.  If you're using this in a raw certificate definition,\n  you likely want the 'command' svcmgr- see that section for details of\n  how to use it.\n* `request`: a CFSSL certificate request (see below).  If this is specified, a `certificate` and `private_key` field is required.\n* `private_key` and `certificate`: file specifications (see below) for\n  the private key and certificate.  Both must be specified- as must `request`- if you wish to manage a certificate/key pair.\n* `authority`: contains the CFSSL CA configuration (see below).\n* `before`: optional: this is the default duration before a certificate expiry that certmgr starts attempting to\n  renew PKI.  This defaults to the managers default, which defaults to 72 hours if unspecified.\n* `interval`: optional: this is the default for how often `certmgr` will check certificate expirations\n  and update PKI material on disk upon any changes (if necessary).  This defaults to the managers default, which\n  defaults to one hour if unspecified.\n* `interval_splay`: optional: this is used to vary the interval period.  A random time between 0\n  and this value is added to `interval` if specified.  This defaults to the managers default, which defaults to 0\n  if unspecified.\n* `initial_splay`: if specified, a random sleep period between 0 and this value is used\n  for the initial sleep after startup of a spec.  This provides a way to ensure that\n  if a fleet of certmgr are restarted at the same time, their period of wakeup is randomized\n  to avoid said fleet waking up and doing interval checks at the same time for a given spec.\n  This defaults to the managers default, which defaults to 0 if unspecified.\n* `take_actions_only_if_running`: boolean, if true, only fire a spec's action if the service is actually running.\n  If this is set to false (the default for historical reasons), this can lead to certmgr starting a downed service\n  when PKI expiry occurs.\n* `key_usages`: optional: An array of strings defining what this key should be used for. Certmgr will consider a cert invalid\n   if it does not contain these key usages. Possible values are from cfssl's [ExtKeyUsage map](https://github.com/cloudflare/cfssl/blob/1.3.3/config/config.go#L568)\n  \n\n\n**Note**: `certmgr` will throw a warning if `svcmgr` is `dummy` _AND_ `action` is \"nop\" or undefined. This is because such a setup will not properly restart or reload a service upon certificate renewal, which will likely cause your service to crash. Running `certmgr` with the `--strict` flag will not even load a certificate spec with a `dummy svcmgr` and undefined/nop `action` configuration.\n\n\nFile specifications contain the following fields:\n\n* `path`: this is required, and is the path to store the file.\n* `owner`: this is optional; if it's not provided, the current user is\n  used.\n* `group`: this is optional; if it's not provided, the primary group\n  of the current user is used.\n* `mode`: this is optional; if it's not provided, \"0644\" will be\n  used. It should be a numeric file mode.\n\nCFSSL certificate requests have the following fields:\n\n* `CN`: this contains the common name for the certificate.\n* `hosts`: this is a list of SANs and/or IP addresses for the\n  certificate.\n* `key`: this is optional; it should contain an \"algo\" of either \"rsa\"\n  or \"ecdsa\" and a \"size\" appropriate for the chosen\n  algorithm. Recommendations are \"rsa\" and 2048 or \"ecdsa\"\n  and 256. The default is \"ecdsa\" and 256.\n* `names`: contains PKIX name information, including the \"C\"\n  (country), \"ST\" (state), \"L\" (locality/city), \"O\" (organisation),\n  and \"OU\" (organisational unit) fields.\n\nThe CA specification contains the following fields:\n\n* `remote`: the CA to use. If not provided, the default remote from\n  the config file is used.\n* `auth_key`: the authentication key used to request a certificate.\n* `auth_key_file`: optional, if defined read the auth_key from this. If\n  `auth_key` and `auth_key_file` is defined, `auth_key` is used.\n* `label`: the CA to use for the certificate.\n* `profile`: the CA profile that should be used.\n* `file`: if this is included, the CA certificate will be saved here. It\n  follows the same file specification format above. Use this if you want to save your CA cert to disk.\n* `root_ca`: optionally, a path to a certificate to trust as CA for the\n  cfssl API server certificate. Usable if the \"remote\" is tls enabled\n  and configured with a self-signed certificate. By default,\n  the system root CA chain is trusted.\n\n## `command svcmgr` and how to use it\n\nIf the svcmgr is set to `command`, then `action` is interpreted as a\nshell snippet to invoke via  `bash -c`.  Bash is preferred since\nit allows parse checks to run. If Bash isn't available, parse checks\nare skipped and `sh -c` is used.  If `sh` can't be found, then this svcmgr\nis disabled. The `command svcmgr` is useful in Marathon environments.\n\nEnvironment variables are set as follows:\n\n* CERTMGR_CA_PATH: if CA was configured for the spec, this is the path\n  to the CA ondisk that was changed.\n* CERTMGR_CERT_PATH: This is the path to the cert that was written.\n* CERTMGR_KEY_PATH: This is the path to the key that was written.\n\n## Subcommands\n\nIn addition to the certificate manager, there are a few utilities\nfunctions specified:\n\n* `check`: validates the configuration file and all the certificate\n  specs available in the certificate spec directory.  Note that if you\n  wish to operate on just one spec, you can use `-d /path/to/that/spec`\n  to accomplish it.\n* `clean`: removes all of the certificates and private keys specified\n  by the certificate specs.  Note that if you wish to operate on just one spec,\n  you can use `-d /path/to/that/spec` to accomplish it.\n* `ensure`: attempts to load all certificate specs, and ensure that\n  the TLS key pairs they identify exist, are valid, and that they are\n  up-to-date.  Note that if you wish to operate on just one spec, you\n  can use `-d /path/to/that/spec` to accomplish this.\n* `genconfig`: generates a default configuration file and ensures the\n  default service directory exists.\n* `version`: prints certificate manager's version, the version of Go\n  it was built with, and shows the current configuration.\n\n## See also\n\nThe `certmgr` spec is included as `SPEC.rst`.\n\n\n## Contributing\n\nTo contribute, fork this repo and make your changes. Then, make a PR to this repo. A PR requires at least one approval from a repo admin and successful CI build.\n\n### Unit Testing\nUnit tests can be written locally. This should be straightforward in a Linux environment.\nTo run them in a non-Linux environment, have Docker up and run `make test`. This will spin up a container with your local build. From here you can `go test -v ./...` your files. This unconventional setup is because [cfssl](https://github.com/cloudflare/cfssl), the underlying logic of `certmgr`, uses [cgo](https://golang.org/cmd/cgo/). \n","funding_links":[],"categories":["Go","Infrastructure \u0026 Operations"],"sub_categories":["Certificate Management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fcertmgr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fcertmgr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fcertmgr/lists"}