Help

Generating an SSH keypair

Uploading a public key

You can upload a new public key to your account from the home page.

Iconography

Most objects that are known by SSH Key Authority are represented by icons:

Servers

Physical or virtual servers.

Server accounts

Accounts on servers (eg. root@myserver is a server account).

Users

Users of SSH Key Authority.

Groups

Collections of users or server accounts.

Begin by browsing the server list. Click on the server that you need access to.

You should see a "request access" form, in which you will need to enter the name of the account on the server that you are requesting access for. For example, if you need access to the root account, then that is what you should enter in this field.

Once you have successfully requested access, the designated server administators will be sent a mail informing them of your request and you will need to wait for one of them to grant your access.

You will need to have a public key uploaded for your access to work. See the getting started guide.

Contact to have your server(s) added to SSH Key Authority.

SSH connection failed

SSH key authority was unable to establish an SSH connection to your server. This could indicate that the server is offline or otherwise unreachable, or that the SSH server is not running.

SSH host key verification failed

SSH key authority was able to open an SSH connection to your server, but the host key no longer matches the one that is on record for your server. If this is expected (eg. your server has been migrated to a new host), you can reset the host key on the "Settings" page of your server. Press the "Clear" button for the host key fingerprint and then "Save changes".

SSH host key collision

Your server has the same SSH host key as another server. This should be corrected by regenerating the SSH host keys on one or both of the affected servers.

SSH authentication failed

Although SSH key authority was able to connect to your server via SSH, it failed to log in. See the guides for setting up full account syncing or legacy root account syncing.

SFTP subsystem failed

SSH key authority currently relies on SFTP in order to determine if an account's key file needs updating or not. We are hoping to remove this dependency at some point, but for now your server needs to support SFTP (which openssh does by default) for key synchronization to work.

x account(s) failed to sync

Failed to clean up x file(s)

SSH key authority could not write to at least one of the files in /var/local/keys-sync (or /root/.ssh/authorized_keys2 for legacy sync). This is typically caused by one of 3 possibilities:

• Issues with file ownership - this directory and all files in it must be owned by the keys-sync user
• Read-only filesystem
• Disk full

Multiple hosts with same IP address

At least one other host managed by SSH Key Authority resolves to the same IP address as your server. SSH Key Authority will refuse to sync to either server until this is resolved.

= 3) { ?>

Hostnames file missing

The /var/local/keys-sync/.hostnames file does not exist on the server. SSH Key Authority uses the contents of this file to verify that it is allowed to sync to your server.

Hostname check failed

The server name was not found in /var/local/keys-sync/.hostnames when SSH Key Authority tried to sync to your server.

Key directory does not exist

Your server has not been set up for full account syncing. The root account is being synced, but other accounts are not.

Using legacy sync method

Your server has been set up for full account syncing (stage 1), but the authentication on your server has not been switched over to keys control (stage 2). Legacy syncing is still being used, so only the root account sync is taking effect.

Stage 1

If SSH Key Authority is reporting "Key directory does not exist" for your server, then Stage 1 is required.

1. Create keys-sync account: adduser --system --disabled-password --home /var/local/keys-sync --shell /bin/sh keys-sync
2. Change the permissions of /var/local/keys-sync to 711: chmod 0711 /var/local/keys-sync
3. Create /var/local/keys-sync/keys-sync file (owned by keys-sync, permissions 0644) with the following SSH key in it:

   get('keys-sync-pubkey'))?>

= 3) { ?>
4. Create /var/local/keys-sync/.hostnames text file (owned by keys-sync, permissions 0644) with the server's hostname in it

Verify Stage 1 success

Once Stage 1 has been deployed to your server, trigger a resync from SSH Key Authority. The server should no longer have the "Key directory does not exist" warning after syncing (the "Using legacy sync method" warning is expected at this point instead). You can check the contents of the /var/local/keys-sync directory to make sure that the access looks right.

Stage 2

1. Reconfigure SSH (/etc/ssh/sshd_config) to use:
   • "AuthorizedKeysFile /var/local/keys-sync/%u"
   • "StrictModes no"
2. Restart SSH server

This stage stops any .ssh/authorized_keys* files from having any effect and transfers login authentication authority over to the /var/local/keys-sync directory.

After triggering a resync from SSH Key Authority, your server should be listed as "Synced successfully".

While this sync method is simpler to set up, we recommend setting up full account syncing where possible.

Add the following to the /root/.ssh/authorized_keys file (create it if it does not exist):

get('keys-sync-pubkey'))?>

The /root and /root/.ssh directories must be accessible only by root.

For access to accounts by employees:

1. Go to your server's page (ie. /servers/<hostname>).
2. If the account is not listed yet, add it with the "Create account" form.
3. Click "Manage account" for the relevant account.
4. In the "Add user to account" form, enter the user's intranet account name and submit.

For server-to-server access, assuming that both of the servers involved are managed by SSH Key Authority:

Example: foo@source.example.com needs SSH access to bar@destination.example.com

1. Go to the admin page for source.example.com (ie. /servers/source.example.com).
2. Add the "foo" account to keys ("Manage this account with SSH Key Authority") if it is not already listed.
3. Go to the manage account page for "foo".
4. On the Public keys tab, add the SSH public key for the foo@source.example.com account.
5. Go to the admin page for destination.example.com (ie. /servers/destination.example.com).
6. Add the "bar" account to keys ("Manage this account with SSH Key Authority") if it is not already listed.
7. Go to the manage account page for "bar".
8. On the Access tab, add server-to-server access for foo@source.example.com.

In the above example if source.example.com is not yet known by SSH Key Authority, please contact to add it to the system.