🛠️Troubleshooting

The following is the troubleshooting guide for installing, deploying, and using OpenPubkey SSH.

Use this index to navigate:

> My SSH command isn't working

If you find that new SSH commands are failing, it's likely that you need to re-authenticate.

Run zli login --opk to log in again.

On EC2 instances running one of AWS’s Ubuntu images, you may need to perform one additional server configuration step.

As mentioned in Installation & Deployment, OPK SSH requires your remote host to have no existing AuthorizedKeysCommands.

In the case of EC2 instances running an AWS Ubuntu image, the problem lies in the EC2 Instance Connect package, which forces sshd to run an AuthorizedKeysCommand that is not visible from /etc/ssh/sshd_config.

If you’re unable to connect using OPK SSH, you can verify that your instance uses EC2 Instance Connect by monitoring your server’s logs when you try to SSH. On Ubuntu these can be found here:

tail -f /var/log/auth.log

On Amazon Linux, they can be found here:

tail -f /var/log/secure

You may see that it is (unsuccessfully) trying to authenticate with a command that looks something like: AuthorizedKeysCommand /usr/share/ec2-instance-connect/eic_run_authorized_keys ubuntu ....

To resolve this, you will need to uninstall EC2 Instance Connect.

On Amazon Linux, this looks like:

sudo yum remove ec2-instance-connect

On Ubuntu, this looks like:

sudo apt-get remove ec2-instance-connect

CAUTION: Before taking the action to uninstall EC2 Instance Connect, you must ensure that you are not utilizing it for an additional purpose.

Include Statements On Your Server's sshd_config

OPK SSH automatically comments out occurrences of AuthorizedKeysCommand when you configure a server. If your sshd_config file contains an Include statement, you may need to check the files it references for any additional AuthorizedKeysCommand s.

> How do I know if my SSH command is using OPK SSH?

To test your OPK SSH configuration, follow How To Test OPK SSH Is Configured Correctly.

> How do I remove my traditional SSH keys now that OPK SSH is configured?

See Remove Your SSH Keys for guidance.

> Where do I find my logs?

OPK SSH logs can be found at var/log/openpubkey.log.

> My connection failed with "Connection fails: sshd logs fatal: percent_expand: string too long."

This happens when your server is running a version of OpenSSH prior to v. 8.1. Older versions of OpenSSH impose a limit on public key sizes, and the key you generate when you log in can be too large. Unfortunately the only fix is to use a newer version of SSH on your server.

> I can't authenticate. I received this error: "Too many authentication failures for user {X}."

This happens when your SSH client tries too many keys and fails before reaching the right key. Because our SSH solution relies on using default keys, this can happen. Read here for more information.

To fix this issue, please specify the OPK key in your SSH command:

$ ssh -i <path to OPK key> -o IdentitiesOnly=yes <user>@<target>

You can also configure your SSH config to use a specific key instead of trying multiple:

Host <target>
  User <user>
  HostName <host ip address>
  Port 22
  IdentityFile <path to opk key>

Product feedback? Send us a note at [email protected].

PreviousAccessing Your Remote Host

Last updated