This section assumes that checkcert is installed via pypi, and the ``certcheck`` entry-point in the path (which ``pip install checkcert`` should do automatically). If running from source, the full path to python and the checkcert.py script itself would need to be specified.
The green text is showing that the certificate is valid. If the certificate had expired, the text would be displayed in Red. The ``--valid`` option may be specified to display a text represention of the cert validity in addtion to just coloring the output to show validity. When run with ``--valid``, the output will look like:
..figure:: images/valid.png
:alt:output with valid option
Display cert validity in output text
..note:: Output color is generated via Click's styling which should be aware of how the text is being handled and appropriately strip out the color sequences if output is being piped to another command, for example. The plain text output may be enforced with the ``--no-color`` option
Querying multiple domains
-------------------------
Multiple domains can be checked from a single command. Simply separate them on the command line with a space. So to check `www.example.com` and `www.example.org`, this can be run as:
``checkcert www.example.com www.example.org``
Which will generate:
..figure:: images/multi.png
:alt:multi-domain output
Mutliple domains specified
Specify alternate ports
-----------------------
By default, the standard port `443` will be used. If a service is running on an alternate port, simply append `:portnum` to the domain. So if example.com was listening on 444 instead of 443, anywhere the domain is specified, the format ``example.com:444`` may be used instead.
Domains from a file
-------------------
While specifying a few domains on the commanline is fine, if there are many domains to check, an input file may be specified instead. Each domain should be on its own line. Alternate ports may be specified in this file too. For example, if a file named `domains.txt` is created with the following content:
..code-block:: text
www.example.com
example.org
example.com:444
Then checkcert may be run as follows:
``checkcert --filename domains.txt``
Each line in the file will be parsed and checked the same as if it were run on the command line.
SubjectAlternateName handling
-----------------------------
checkcert has a `--san` option that will optionally show the subjectAlternateNames for a domain. This will output the same as previous iterations, but will add a list of SANs associated with the certificate retrieved.
..figure:: images/san.png
:alt:subjectalternatename example
output with the SAN line
Just the SANs
^^^^^^^^^^^^^
It may be useful to output just the SANs for a given domain. This may be done by specifying the ``--san-only`` option. By default this will output all of SANs, separated by a space.
Running ``checkcert --san-only www.example.com`` will yield::
If an alternate separator is desired, add the ``--sep <separator>`` option, so for comma separated, run ``checkcert --san-only --sep , www.example.com`` which will yield::
If it is desired to output that list to another command as commandline options (for example when migrating from a managed PKI front-end to using ACME/certbot). Certbot wants the domains specified as -d. checkcert may run as: ``checkcert --san-only --sep " -d "- www.example.com`` which will return::
..note:: the documentation for certbot specifies multiple domains should be specified each with their own '-d' option. certbot in particular seems to work with a comma-separated list too, even though the docs don't specify that it works that way.
Notice that the " -d " is used as a **separator** and therefore the first entry does not have a -d before it. To make -d show up before every entry (as would be required in this case) The ``--pre`` option must be added to "prefix" the entry with the separator; thus, running ``checkcert --san-only --sep " -d " --pre www.example.com`` will yield::
..note:: Since this is utilizing separator in a slightly different way, the space before the option must be specified, otherwise everything would run together. checkcert is aware of this and will strip off the space at the beginning if ``--pre`` is used.
This output could be directly included into certbot as ``certbot $(checkcert --san-only --sep " -d " --pre www.example.com")``
..note:: Certbot was the specific reason this was added. As such, it will prepend the name queried to the list. The domain itself is not always included in the SAN list, checkcert will verify if the domain is in the list and will always prefix it if not. If example.com was not in the list of SANS, but ``checkcert --san --pre --sep " -d " example.com`` was used, '-d example.com' will be the first entry even if it was not part of the SANs.
