Client Connection Troubleshooting

2020-02-16

Before you begin

Make sure you have already completed Node Startup Troubleshooting and have 6 nodes running securely.

Problem 1: SSL required

In this scenario, you try to connect a user without providing a client certificate.

Step 1. Simulate the problem

  1. In a new terminal, as the root user, create a new user called kirk:

    $ ./cockroach user set kirk --certs-dir=certs --host=localhost:26257
    
  2. As the kirk user, try to connect to the cluster:

    $ ./cockroach sql \
    --certs-dir=certs \
    --host=localhost:26257 \
    --user=kirk \
    --execute="SHOW DATABASES;"
    

    Because kirk doesn't have a client certificate in the certs directory, the cluster asks for the user's password:

    Enter password:
    
  3. Because kirk doesn't have a password, press Enter.

    The connection attempt fails, and the following error is printed to stderr:

    Error: pq: invalid password
    Failed running "sql"
    

Step 2. Resolve the problem

To successfully connect the user, you must first either generate a client certificate or create a password for the user. It's generally best to use certificates over passwords, so do that here.

  1. Generate a client certificate for the kirk user:

    $ ./cockroach cert create-client \
    kirk \
    --certs-dir=certs \
    --ca-key=my-safe-directory/ca.key
    
  2. As the kirk user, try to connect to the cluster again:

    $ ./cockroach sql \
    --certs-dir=certs \
    --host=localhost:26257 \
    --user=kirk \
    --execute="SHOW DATABASES;"
    

    This time, the connection attempt succeeds:

      database_name
    +---------------+
    (0 rows)
    

Problem 2: Wrong host or port

In this scenario, you try to connect the kirk user again but specify a --port that is not in use by any of the existing nodes.

Step 1. Simulate the problem

Try to connect the kirk user:

$ ./cockroach sql \
--certs-dir=certs \
--host=localhost:26257 \
--user=kirk \
--port=20000 \
--execute="SHOW DATABASES;"

The connection attempt fails, and the following is printed to stderr:

Error: unable to connect or connection lost.

Please check the address and credentials such as certificates (if attempting to
communicate with a secure cluster).

dial tcp [::1]:20000: connect: connection refused
Failed running "sql"

Step 2. Resolve the problem

To successfully connect the user, try again using a correct --port:

$ ./cockroach sql \
--certs-dir=certs \
--host=localhost:26257 \
--user=kirk \
--port=26259 \
--execute="SHOW DATABASES;"

This time, the connection attempt succeeds:

  database_name
+---------------+
(0 rows)

Clean up

In the next module, you'll start a new cluster from scratch, so take a moment to clean things up.

  1. Stop all CockroachDB nodes:

    $ pkill -9 cockroach
    
  2. Remove the nodes' data directories:

    $ rm -rf node1 node2 node3 node4 node5 node6
    

What's next?

Under-Replication Troubleshooting