Getting Started¶
kssh allows you to define realms of servers where access is granted based off of membership in different teams. Imagine that you have a staging environment that everyone should be granted access to and a production environment that you want to restrict access to a smaller group of people. For this exercise we’ll also set up a third realm that grants root access to all machines.
Start by creating a new Keybase user to use for the CA chatbot:
keybase signup # Creates a new Keybase user to use for the SSH CA bot
keybase paperkey # Generate a new paper key
Note that this system will not work if you attempt to use the same user for the CA chatbot as for kssh. It is required to use distinct users.
Then create {TEAM}.ssh.staging
, {TEAM}.ssh.production
, {TEAM}.ssh.root_everywhere
as new Keybase subteams
and add the bot to those subteams. Add users to those subteams based off of the permissions you wish to grant
different users
On a secured server (note that this server only needs docker installed) that you wish to use to run the CA chatbot:
git clone git@github.com:keybase/bot-sshca.git
cd bot-sshca/docker/
cp env.list.example env.list
nano env.list # Fill in the values including the previously generated paper key
make generate # Generate a new CA key
Running make generate
will output a list of configuration steps to run on each server you wish to use with the CA chatbot.
These commands create a new user to use with kssh (the developer
user), add the CA’s public key to the server, and
configure the server to trust the public key.
Now you must define a mapping between Keybase teams and the users on the servers that members of those teams are
allowed to access. If you wish to make the user foo
on your server available to anyone in team.ssh.bar
,
create the file /etc/ssh/auth_principals/foo
with contents team.ssh.bar
.
More concretely following the current example setup:
- For each server in your staging environment:
- Create the file
/etc/ssh/auth_principals/root
with contents{TEAM}.ssh.root_everywhere
- Create the file
/etc/ssh/auth_principals/developer
with contents{TEAM}.ssh.staging
- Create the file
- For each server in your production environment:
- Create the file
/etc/ssh/auth_principals/root
with contents{TEAM}.ssh.root_everywhere
- Create the file
/etc/ssh/auth_principals/developer
with contents{TEAM}.ssh.production
- Create the file
Now on the server where you wish to run the chatbot, start the chatbot itself:
make serve # Runs inside of docker for ease of use
You can confirm that the bot is running by sending the message ping @bot_username
in any of the configured team chat
channels (if CHAT_CHANNEL
is configured, the message must be sent in that specific channel). The bot should reply with
pong @your_username
.
Now you can download the kssh binary and start SSHing! See https://github.com/keybase/bot-sshca/releases to download the most recent version of kssh for your platform.
sudo mv kssh-{platform} /usr/local/bin/kssh
sudo chmod +x /usr/local/bin/kssh
kssh developer@staging-server-ip # If in {TEAM}.ssh.staging
kssh developer@production-server-ip # If in {TEAM}.ssh.production
kssh root@server # If in {TEAM}.ssh.root_everywhere
We recommend building kssh yourself and distributing the binary among your team (perhaps in Keybase Files!).
Updating environment variables¶
If you update any environment variables, it is necessary to restart the keybaseca service. This can be done
by running make restart
. Note that it is not required to re-run make generate
.
Note that this means kssh
will not work for a brief period of time while the container restarts.