self-hosted/teleport
self-hosted/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport synced 2024-10-22 18:23:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #49 from gravitational/alexander/docs

Browse source 
update the docs
This commit is contained in:
Alexander Klizhentas 2015-10-31 14:42:43 -07:00
parent 50dea951c5 7164f2dd66
commit ff45bb1529
3 changed files with 53 additions and 218 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

263
README.md
View file

@ -9,8 +9,19 @@ traditional SSH with the following capabilities:
* Includes session record/replay and keeps audit logs.
It also contains a few nice conveniences like built-in command multiplexing, web-based
administration and more. `Teleport` is a standalone executable. It has one external
dependency: [Etcd](https://coreos.com/etcd/)
administration and more. `Teleport` is a standalone executable.
Teleport uses [Etcd](https://coreos.com/etcd/) in HA mode or [Boltdb](https://github.com/boltdb/bolt) in standalone mode.
## Status
**Teleport is not ready to be used in production yet**
We are currently fixing outstanding security issues, and working on hardening.
## Design document
Take a look at [Teleport design document](https://docs.google.com/a/gravitational.io/document/d/10-DjtvKFjsiPHcMDArHtjvepdQg5iZUWSafAF03OBbE/edit?usp=sharing)
## Developer Docs
@ -20,44 +31,33 @@ Take a look at [Developer API](docs/api.md)
![Overview](docs/img/teleport.png)
A Teleport daemon needs to be running on every server in a cluster. Each instance
assumes one of these roles:
Teleport system consists of several independent parts that can be set up in various combinations:
* Auth server
* SSH server
* Proxy
**Teleport Auth**
**Auth server**
Auth server acts as Authentication and Authorization server, SSH host and user certificate authority, stores audit logs and access
records and is the only stateful component in the system.
Auth server is connected to Etcd backend or embedded bolt database and acts as:
*Note* Read more about SSH authorities in this [intro article](https://www.digitalocean.com/community/tutorials/how-to-create-an-ssh-ca-to-validate-hosts-and-clients-with-ubuntu)
*Note* Auth server does not itself provide any support for interactive sessions and remote command execution
* Teleport Auth Server acts as Authentication and Authorization server,
* SSH host and user certificate authority
* Stores audit logs and access records and is the only stateful component in the system.
**Teleport SSH**
Teleport SSH server is a simple stateless server written in Go that only supports SSH user certificates as authentication method,
generates structured events and supports interactive collaborative sessions.
Read more about SSH authorities in this [intro article](https://www.digitalocean.com/community/tutorials/how-to-create-an-ssh-ca-to-validate-hosts-and-clients-with-ubuntu)
**Teleport Proxy**
**Note:** Auth server does not itself provide any support for interactive sessions and remote command execution
**SSH server**
Teleport SSH server is a simple stateless server written in Go that only supports SSH user certificates as authentication method, generates structured events and supports interactive collaborative sessions
**Web access portal**
Web access portal is stateless too, it connects to the auth server
and provides SSH access, view of the logs and key management interfaces.
Teleport Proxy is a stateless SSH proxy that implements 2-factor web authentication and proxies traffic to the remote SSH nodes.
## Installation
Teleport is currently a private project and should be cloned from
the repository.
Teleport is open source, however it and should be cloned from the repository.
**Prerequisites**
* `go >= 1.4.2`
* `etcd >= v2.0.10`
* `etcd >= v2.0.10` (in case of HA mode)
**Clone the latest master**
@ -73,217 +73,52 @@ git clone git@github.com:gravitational/teleport.git
make install
```
This should install the binaries, check that the binaries are installed.
This should install `teleport` and `tctl` binaries, check that the binaries are installed.
```shell
ls ${GOPATH}/bin/tctl ${GOPATH}/bin/teleport
```
## Auth Server
## Quickstart: embedded mode
```shell
# create the directory where auth server will keep it's local state
mkdir -p /var/lib/teleport-auth
mkdir -p /var/lib/teleport
# make sure it is not owned by root
chown <<USER>>:<<GROUP>> /var/lib/teleport
# start teleport binary with auth role enabled
teleport -auth\
-authBackend=etcd\
-authBackendConfig='{"nodes": ["http://127.0.0.1:4001"], "key": "/teleport"}'\
-authDomain=example.com\
-authSSHAddr=tcp://0.0.0.0:32000\
-log=console\
-logSeverity=INFO\
-dataDir=/var/lib/teleport-auth\
-fqdn=auth.example.com
# start teleport in embedded mode
make run-embedded
```
**Note:** `authSSHAddr` sets up a special-purpose SSH-powered API endpoint that the auth server exposes for nodes and web portals to check access.
**Note:** `run-embedded` executes teleport with configuration file in `examples/embedded.yaml` check it out for more details
## SSH Server
### Quickstart: Web access via proxy
On the first connection attempt SSH nodes will attempt to connect to the auth server and register itself.
Get a one-time security token from the auth server for a SSH node to connect to the server:
Teleport allows to access the cluster via web portal. The web portal is guarded by 2-factor authentication. Here's how to log in:
**Step 1. Get the token**
This command will generate a one time secure token allowing server `node1.example.com` to register with the server within the next 120 seconds.
* Create a user entry for yourself:
```shell
tctl token generate -fqdn=node1.example.com
tctl user set-pass --user=<user> --pass=<pass>
```
**Step 2. Start the SSH node**
**Important:** Username and password are not enough to log in into teleport, for second factor it uses HOTP tokens.
Tool generated QR code for you too, and placed it in the current working directory. Follow next steps to set up your phone to use QR key:
Pass the token from the step 1 and pass it to the teleport SSH node on start:
* Set up Google Authenticator app on your phone (available for free for Android and iPhone)
```shell
# create a directory for the local node state
mkdir -p /var/lib/teleport-node
Check out QR.png file that was written to the local directory and scan QR code. Follow next step to login:
# start the server
TELEPORT_SSH_TOKEN=<token here> teleport -ssh\
-log=console\
-logSeverity=INFO\
-dataDir=/var/lib/teleport-node\
-fqdn=node1.example.com\
-authServer=tcp://auth.example.com:32000
-sshAddr=tcp://0.0.0.0:33000
```
* Open a browser: http://localhost:33007/web/login and enter username, password and QR code
SSH node will use the token to connect to the auth server and provision the signed SSH host certificate and private key.
The subsequent starts/restart will use the host certificates to authenticate with the Auth server.
## Web Server
Control panel node is optional, and is only needed if you want to access the cluster via web interface.
```shell
# create a directory for the local node state
mkdir -p /var/lib/teleport-cp
teleport -cp\
-cpDomain=example.com\
-log=console\
-logSeverity=INFO\
-dataDir=/var/lib/teleport-cp\
-fqdn=cp.gravitational.io\
-authServer=tcp://auth.gravitational.io:32000
```
**Note:** Unlike SSH node, CP node does not need to use any provisioning step, as it's just a web interface using SSH auth server APIs.
**Step 1. Get the token**
This command will generate a one time secure token allowing server `node1.example.com` to register with the server within the next 120 seconds.
```shell
tctl token generate -fqdn=node1.example.com
```
**Step 2. Start the SSH node**
Pass the token from the step 1 and pass it to the teleport SSH node on start:
```shell
# create a directory for the local node state
mkdir -p /var/lib/teleport-node
# start the server
TELEPORT_SSH_TOKEN=<token here> teleport -ssh\
-log=console\
-logSeverity=INFO\
-dataDir=/var/lib/teleport-node\
-fqdn=node1.example.com\
-authServer=tcp://auth.example.com:32000
-sshAddr=tcp://0.0.0.0:33000
```
SSH node will use the token to connect to the auth server and provision the signed SSH host certificate and private key.
The subsequent starts/restart will use the host certificates to authenticate with the Auth server.
### SSH access
Connecting to Teleport is like connecting to any other SSH server, except that it
does not support password and host based auth, and only works with keys signed by the authority.
**Sign the SSH key**
If you don't have they key yet:
```shell
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```
To sign the key, you can use the tctl command on the auth server:
```shell
tctl user upsert_key -user=user -keyid=user-key1 -key=user.pub
```
Teleport user CA (certificate authority) will sign the key and returned the signed certificate.
You can place it near the private and public keys in file `user-cert.pub` and use it to connect to the server.
**Add the keys to agent**
SSH agent is a little program that holds the keys in memory and authenticates on your behalf.
Check if ssh agent is running:
```shell
pidof ssh-agent
```
If the command above returns nothing, start the agent:
```shell
eval $(ssh-agent)
```
Add keys to the agent:
```shell
ssh-add /<path-to-key>/user
```
Check if the keys are loaded
```shell
ssh-add -l
2048 8f:c2:cf:85:c4:02:7a:f9:73:ae:c7:62:ae:c0:36:04 rsa w/o comment (RSA)
2048 8f:c2:cf:85:c4:02:7a:f9:73:ae:c7:62:ae:c0:36:04 rsa w/o comment (RSA-CERT)
```
Log in:
```ssh
ssh -p 33000 node1.example.com
```
#### Trusting Host CA
You may have noticed the following warning when connecting to the host:
```shell
The authenticity of host '[node1.gravitational.io]:33000 ([127.0.0.1]:33000)' can't be established.
RSA key fingerprint is 9d:ff:8b:aa:b5:af:70:33:90:a8:1c:1e:85:af:02:a6.
Are you sure you want to continue connecting (yes/no)
```
This warning means that your client have not seen this host before and is not sure if it's trusted or not.
It will be displayed each time you log in to the server that was not seen before.
This is quite annoying to deal with, and thankfully, there's a solution for it.
All host keys used by teleport are signed by the host authority. Instead of validating the keys,
you can validate the authority.
**Get the host CA certificate**
```shell
# from the auth server:
tctl hostca pubkey
```
Copy the certificate and write this line to your home folder's `.ssh/known_hosts`:
```shell
@cert-authority *.example.com <certificate-key-here>
```
This line will tell the SSH client to trust all hosts whose public keys are signed by this authority.
### Web access
Teleport allows to access the cluster via optional web portal handled by CP server.
**Create a password**
Grant user web access using auth server user api
```shell
tctl user set_pass -user=alex -pass=pwd123
```
Now users can log in using their usernames and passwords into the portal
**Note:** If you failed to log in for the first time, try to refresh the token. Teleport will try to sync up your phone and token on the next attempt.
### Quickstart: SSH access via proxy
This is still in progress, should be merged soon. Follow the progress here:
https://github.com/gravitational/teleport/compare/alex/ssh-agent

BIN
docs/img/teleport.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.4 KiB

After

Width:  |  Height:  |  Size: 15 KiB

8
examples/embedded.yaml
View file

@ -4,7 +4,7 @@ log:
data_dir: /var/lib/teleport # directory where teleport stores it's state (SSH keys and database data)
hostname: node1.gravitational.io # SSH hostname of this node
hostname: localhost # SSH hostname of this node
ssh:
# enable simple ssh endpoint
@ -14,13 +14,13 @@ reverse_tunnel:
# this node will try to connect to remote web proxy and establish reverse SSH tunnel
# so web proxy can access all the nodes in the cluster through this tunnel
enabled: true
dial_addr: tcp://node1.gravitational.io:33006
dial_addr: tcp://localhost:33006
auth:
# auth is authentication and authorization server for users and hosts
# it acts like SSH user CA authority and host CA authority
enabled: true
host_authority_domain: gravitational.io
host_authority_domain: localhost
keys_backend:
type: bolt
@ -38,4 +38,4 @@ proxy:
# proxy starts web and ssh proxy that allow inbound connections from remote nodes
enabled: true
assets_dir: assets/web # directory with javascript, html and css for web
reverse_tunnel_listen_addr: tcp://node1.gravitational.io:33006
reverse_tunnel_listen_addr: tcp://localhost:33006