Troubleshooting SSL
===================

Implementing security best practices can often create complex and unique
problems. This document aims to guide you through resolving common SSL
connection issues.

Before using the NETLAB+ API
----------------------------

We recommend fully setting up and debugging the NETLAB+ webserver. This topic,
as well as how to enable the API, are available in your NETLAB+ documentation.

How the NETLAB+ API uses SSL
----------------------------

NETLAB+ serves its API on port 9000. This API is wrapped inside SSL and secured
using the same certificate as the web server. The netlab-sdk and Python will
usually use the host system's openssl and installed certificate authorities.

The certificate hostname is (by default) validated against the "host" value
in the netlab-sdk configuration. You can change this behavior by setting the
"server_hostname" or setting "ssl" to "noverify". See :py:mod:`netlab.config`
for more details.

Advanced Debugging
------------------

Sometimes a deep investigation is needed. We recommend using `netlab debug` to
inspect every part of the SSL connection. Note that the debug command will use
the openssl command if it is installed. **We recommend installing openssl.**

You can run `netlab debug --help` for an explanation of all the options. The
`--output-file` option will let you log all the debug output to a file. If you
are having trouble getting this file off a jumpbox system,
the `--wormhole` option may be useful.