Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,13 @@ Now, run it::
If you would like to run ``crash`` from any directory, and without the leading
``./``, the file has to be in a directory that is on your `PATH`_.

Troubleshooting
===============

The documentation section about `troubleshooting connection errors`_ provides
support and guidelines how to debug and resolve problems when connecting to
`CrateDB`_ or `CrateDB Cloud`_.

Contributing
============

Expand All @@ -104,3 +111,4 @@ Looking for more help? Check out our `support channels`_.
.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
.. _pip: https://pypi.python.org/pypi/pip
.. _support channels: https://cratedb.com/support/
.. _troubleshooting connection errors: https://cratedb.com/docs/crate/crash/en/latest/troubleshooting.html
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ The CrateDB Shell (aka *Crash*) is an interactive `command-line interface`_
getting-started
run
commands
troubleshooting
appendices/index

.. _command-line interface: https://en.wikipedia.org/wiki/Command-line_interface
Expand Down
59 changes: 59 additions & 0 deletions docs/troubleshooting.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
===============
Troubleshooting
===============

This sections enumerates potential connection problems with ``crash``,
and how to investigate and resolve them.


Debugging connection errors
===========================

If you are connecting to `CrateDB`_, for example like this::

crash --hosts 'http://localhost:4200' -U 'admin' -W

... and ``crash`` responds with a connection error message like this::

CONNECT ERROR

you may want to add the ``--verbose`` command line option, in order to find out
about the reason why the connection fails. It could be a DNS / name resolution
error, or it could be a problem related to SSL termination.

Other than ``--verbose``, you can also use the shorthand version ``-v``::

crash --hosts 'http://localhost:4200' -U 'admin' -W -v



SSL connection errors
=====================

`A recent problem`_ outlined SSL connectivity problems when connecting to
`CrateDB Cloud`_::

crash --hosts 'https://MY-CLUSTER-NAME.eks1.eu-west-1.aws.cratedb.net:4200' -U 'admin' -W -v

The verbose output using ``crash -v`` signaled a certificate verification error
like that::

Server not available, exception: HTTPSConnectionPool(host='MY-CLUSTER-NAME.eks1.eu-west-1.aws.cratedb.net', port=4200):
Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(1, '
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)')))

If you are on macOS, the Python Installer offers an easy option to install the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is also available after installation in /Applications/Python 3.11/Install Certificates.command

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I will add this guidance to the documentation text.

required SSL root certificates. Because ``crash`` uses Python, this is the
right choice to resolve the problem durably.

.. figure:: https://github.com/crate/crash/assets/453543/c4e49d7e-86d8-40f6-b0d8-f64889f9d972
Comment on lines +30 to +49
Copy link
Member Author

@amotl amotl Jan 31, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it possible this can also happen on Windows? Are we running some sort of integration tests against CrateDB Cloud? It might sound like overkill, but it may also be absolutely reasonable.

For this patch about the documentation, maybe someone wants to provide a corresponding screenshot if it is the same story there, if someone has a Windows machine at hand?

Note to self: For the integration tests, this is another use-case for quickly whipping up an automation with Racker.

Copy link
Contributor

@proddata proddata Feb 1, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we running some sort of integration tests against CrateDB Cloud?

CrateDB Cloud is using Let's Encrypt certificates. You need your Python installation to trust/have access to Let's Encrypt intermediate certificates to verify their validity. Not much one could test 🤷

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aight. Do we know about LE coverage in regular trust stores? Like, it actually should be inside Windows and macOS already, no?

Shall we look at adding certifi or truststore into the mix, to provide a better UX?
-- https://community.cratedb.com/t/issue-connecting-to-cratedb-cloud-cluster-from-local-machine/1707/14

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like it works well on Windows, at least within a Docker container. I actually don't know where the SSL root certificates are coming from in this case, so please take it with a grain of salt -- it is just "almost native".

# Acquire a Windows terminal shell, in DOS mode.
export RACKER_WDM_MACHINE=2019-box
racker --verbose run --rm -it --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019 -- cmd
rem Install Python, including registration on %PATH%.
scoop install python
C:\Users\ContainerAdministrator\scoop\apps\python\current\install-pep-514.reg
set PATH=%PATH%;C:\Users\ContainerAdministrator\scoop\apps\python\current\Scripts

rem Invoke crash connecting to CrateDB Cloud.
pip install crash
crash --hosts "https://admin:{REDACTED}@testdrive.aks1.westeurope.azure.cratedb.net:4200"

image


In order to install the SSL root certificates retroactively, you can use a
command like::

/Applications/Python 3.11/Install Certificates.command


.. _a recent problem: https://community.cratedb.com/t/issue-connecting-to-cratedb-cloud-cluster-from-local-machine/1707
.. _CrateDB: https://github.com/crate/crate
.. _CrateDB Cloud: https://console.cratedb.cloud