🛠️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 AuthorizedKeysCommand
s.
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:
On Amazon Linux, they can be found here:
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:
On Ubuntu, this looks like:
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
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?
> How do I remove my traditional SSH keys now that OPK SSH is configured?
> 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
."
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:
You can also configure your SSH config to use a specific key instead of trying multiple:
Product feedback? Send us a note at product@bastionzero.com.
Last updated