Procedural Manual: Troubleshooting SSH Connection Issues on Ubuntu

This guide provides steps to troubleshoot and resolve SSH connection issues when you have the public key for your devices, but cannot SSH into them. It assumes you are encountering the error "Could not open a connection to your authentication agent" and cannot connect even after resolving that issue.

Step 1: Check if SSH Agent is Running

1. Verify if SSH agent is running:

   echo $SSH_AGENT_PID
   • If this command outputs a number (Process ID), your agent is running.
   • If no output is shown, proceed to Step 2 to start the SSH agent.

Step 2: Start SSH Agent (If Not Running)

1. Manually start the SSH agent:

   eval "$(ssh-agent -s)"
   • This command will start the SSH agent and output the process ID (PID) for confirmation.

Step 3: Add Your SSH Key to the Agent

1. Add your private key to the SSH agent:

   ssh-add ~/.ssh/id_rsa
   • Replace id_rsa with the correct private key file if you're using a different name.
   • Expected Output: "Identity added" should appear if the key was successfully added.

Step 4: Verify the SSH Key is Loaded

1. List the keys added to the SSH agent:

   ssh-add -l
   • Expected Output: Your key fingerprint should be listed.
   • If no key is listed, repeat Step 3.

Step 5: Check SSH Key Permissions

1. Ensure the private key file has the correct permissions:

   chmod 600 ~/.ssh/id_rsa
   • This sets the correct permissions for your private key.

2. Ensure the .ssh directory has the right permissions:

   chmod 700 ~/.ssh

Step 6: Check if the Public Key is on the Server

1. Verify that your public key is in the authorized_keys file on the server:

   • If you can access the server by other means, check the contents of ~/.ssh/authorized_keys on the remote server.

2. Add your public key to the server’s authorized_keys file if missing:

   cat ~/.ssh/id_rsa.pub | ssh username@hostname 'cat >> ~/.ssh/authorized_keys'

Step 7: Test SSH Connection with Verbose Output

1. Attempt to SSH into the server with verbose logging to see details:

   ssh -v username@hostname
   • This provides detailed debug output, showing each step of the SSH process.
   • Review the output for any specific errors or issues (e.g., permission denied, missing public key, etc.).

Step 8: Force the SSH Command to Use the Correct Key

1. Explicitly specify the private key in the SSH command:

   ssh -i ~/.ssh/id_rsa username@hostname

Step 9: Additional Troubleshooting (If Still Failing)

1. Check for SSH Configuration Conflicts:

   • Open the ~/.ssh/config file (create it if it doesn’t exist) and add an entry for your host:

     Host hostname
         User username
         IdentityFile ~/.ssh/id_rsa
   • Replace hostname and username with your actual values.
   • Save the file and try connecting again.

2. Key Format Issues:

   • If you are using an ed25519 key, ensure the server supports it. If not, generate a new RSA key pair:

     ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa
   • Add the new public key to the server's authorized_keys file.

Conclusion

After following these steps, you should be able to resolve the issue with SSH access. If the problem persists, review the verbose output from Step 7 for more clues, and ensure that your public key is correctly installed on the remote server.