teleport

package module
v0.1.0-alpha.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 19, 2016 License: Apache-2.0 Imports: 7 Imported by: 0

README

Teleport

Teleport is a SSH infrastructure for clusters of Linux servers. Teleport extends traditional SSH with the following capabilities:

  • Provides coordinated and secure access to multiple Linux clusters by multiple teams with different permissions.
  • Enforces cluster-specific security policies.
  • 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.

Teleport uses Etcd in HA mode or Boltdb in standalone mode.

Deploying

Every commit to master branch triggers Jenkins to deploy to https://teleport.gravitational.io You can also deploy via Slack by sending a /deploy message like this:

/deploy teleport staging master

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

Developer Docs

Take a look at Developer API

Overview

Overview

Teleport system consists of several independent parts that can be set up in various combinations:

Teleport Auth

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.

Note Read more about SSH authorities in this intro article Note Auth server does not itself provide any support for interactive sessions and remote command execution

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.

Teleport Proxy

Teleport Proxy is a stateless SSH proxy that implements 2-factor web authentication and proxies traffic to the remote SSH nodes.

Installation

Teleport is open source, however it and should be cloned from the repository.

Prerequisites

  • go >= 1.4.2
  • etcd >= v2.0.10 (in case of HA mode)

Clone the latest master

mkdir -p $(GOPATH)/src/github/gravitational
cd $(GOPATH)/src/github/gravitational
git clone git@github.com:gravitational/teleport.git

Compile

make install

This should install teleport and tctl binaries, check that the binaries are installed.

ls ${GOPATH}/bin/tctl ${GOPATH}/bin/teleport

Quickstart

# create the directory where auth server will keep it's local state
mkdir -p /var/lib/teleport
# make sure it is not owned by root
chown <<USER>>:<<GROUP>> /var/lib/teleport

# start teleport in embedded mode
teleport start

Note: run-embedded executes teleport with configuration file in examples/embedded.yaml check it out for more details

Web access via proxy

Teleport allows to access the cluster via web portal. The web portal is guarded by 2-factor authentication. Here's how to log in:

  • Create a user entry:
tctl users add alex root,centos

And follow instructions.

OpenSSH client -> Teleport Proxy

To use OpenSSH client with Teleport you need to run Teleport ssh agent on your local machine.

  1. Login into proxy
tsh --proxy=<addr> login

This command will retrieve and store user certificates signed by the proper certificate authority

  1. Start the agent
tsh --proxy=<addr> agent

It will output something like:

SSH_AUTH_SOCK=/tmp/316b647c-a81c-4d7c-a916-1c80f38ce0f6.socket; export SSH_AUTH_SOCK;

You can simply copy and paste this into terminal to tell your SSH client to use agent

  1. Tell OpenSSH to use proxy as a jump host using config
Host *
     ForwardAgent no

# tells open ssh to use proxy.example.com as a jumphost when logging
# to any server matching patter *.node.example.com
# beware of recurison here (when proxy name matches your pattern)
Host *.node.example.com
  ProxyCommand ssh -p 3023 %r@proxy.example.com -s proxy:%h:%p
  1. Tell OpenSSH client to trust hosts managed by teleport
tctl authorities --type=host export >> ~/.ssh/authorized_keys
  1. Then you can connect to your ssh nodes as usual:
  ssh -p 22 user@a.node.example.com
Teleport Proxy -> OpenSSH server
  1. Export user certificate authorities used by Teleport to a file
tctl authorities --type=user export > /etc/ssh/user-ca.pub
  1. Tell OpenSSH to trust exporeted authorities

In your /etc/ssh/sshd_config

# this instructs OpenSSH to trust certificates signed by teleport's user authorities
TrustedUserCAKeys /etc/ssh/user-ca.pub
Ansible

By default Ansible uses OpenSSH client. To make Ansible work with Teleport you need:

  • config your OpenSSH client
  • enable scp mode in the Ansible config file(default /etc/ansible/ansible.cfg):
scp_if_ssh = True

Documentation

Index

Constants

View Source
const (
	// BoltBackendType is a BoltDB backend
	BoltBackendType = "bolt"

	// ETCDBackendType is etcd backend
	ETCDBackendType = "etcd"

	// Component indicates a component of teleport, used for logging
	Component = "component"

	// ComponentFields stores component-specific fields
	ComponentFields = "fields"

	// ComponentReverseTunnel is reverse tunnel agent and server
	// that together establish a bi-directional SSH revers tunnel
	// to bypass firewall restrictions
	ComponentReverseTunnel = "reversetunnel"

	// ComponentNode is SSH node (SSH server serving requests)
	ComponentNode = "node"

	// ComponentProxy is SSH proxy (SSH server forwarding connections)
	ComponentProxy = "proxy"

	// ComponentTunClient is a tunnel client
	ComponentTunClient = "tunclient"

	// DefaultTimeout sets read and wrie timeouts for SSH server ops
	DefaultTimeout time.Duration = 30 * time.Second

	// DebugOutputEnvVar tells tests to use verbose debug output
	DebugOutputEnvVar = "TELEPORT_DEBUG_TESTS"
)
View Source
const ForeverTTL time.Duration = 0

ForeverTTL means that object TTL will not expire unless deleted

Variables

This section is empty.

Functions

func ConvertSystemError

func ConvertSystemError(err error) error

ConvertSystemError converts system error to appropriate teleport error if it is possible, otherwise, returns original error

func IsAccessDenied

func IsAccessDenied(e error) bool

IsAccessDenied detects if this error is of AccessDeniedError

func IsAlreadyExists

func IsAlreadyExists(e error) bool

IsAlreadyExists returns if this is error indicating that object already exists

func IsBadParameter

func IsBadParameter(e error) bool

IsBadParameter detects if this error is of BadParameter kind

func IsCompareFailed

func IsCompareFailed(e error) bool

IsCompareFailed detects if this error is of CompareFailed kind

func IsConnectionProblem

func IsConnectionProblem(e error) bool

IsConnectionProblem detects if this error is of ConnectionProblemError

func IsLimitExceeded

func IsLimitExceeded(e error) bool

IsLimitExceeded detects if this error is of LimitExceededError

func IsMissingParameter

func IsMissingParameter(e error) bool

IsMissingParameter detects if this error is of MissingParameter kind

func IsNotFound

func IsNotFound(e error) bool

IsNotFound returns whether this error indicates that the object is not found

func IsReadonly

func IsReadonly(e error) bool

IsReadonly detects if this error is of ReadonlyError

func IsSystemError

func IsSystemError(e error) bool

IsSystemError returns if this is a system error

Types

type AccessDeniedError

type AccessDeniedError struct {
	trace.Traces
	Message string `json:"message"`
}

AccessDeniedError indicates denied access

func AccessDenied

func AccessDenied(message string) *AccessDeniedError

AccessDenied returns new access denied error

func (*AccessDeniedError) Error

func (e *AccessDeniedError) Error() string

Error is debug - friendly error message

func (*AccessDeniedError) IsAccessDeniedError

func (e *AccessDeniedError) IsAccessDeniedError() bool

IsAccessDeniedError indicates that this error is of AccessDenied type

func (*AccessDeniedError) OrigError

func (e *AccessDeniedError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type AlreadyAcquiredError

type AlreadyAcquiredError struct {
	trace.Traces `json:"traces"`
	Message      string `json:"message"`
}

AlreadyAcquiredError is returned when lock has been acquired

func (*AlreadyAcquiredError) Error

func (e *AlreadyAcquiredError) Error() string

Error returns log friendly description

func (*AlreadyAcquiredError) IsAlreadyAcquiredError

func (e *AlreadyAcquiredError) IsAlreadyAcquiredError() bool

IsAlreadyAcquiredError returns true to indicate that this is AlreadyAcquiredError

func (*AlreadyAcquiredError) OrigError

func (e *AlreadyAcquiredError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type AlreadyExistsError

type AlreadyExistsError struct {
	trace.Traces `json:"traces"`
	// Message is user-friendly error message
	Message string `json:"message"`
}

AlreadyExistsError indicates that there's a duplicate object that already exists in the storage/system

func AlreadyExists

func AlreadyExists(message string) *AlreadyExistsError

AlreadyExists returns new AlreadyExists error

func (*AlreadyExistsError) Error

func (n *AlreadyExistsError) Error() string

Error returns log-friendly error description

func (AlreadyExistsError) IsAlreadyExistsError

func (AlreadyExistsError) IsAlreadyExistsError() bool

IsAlreadyExistsError indicates that this error is of AlreadyExists kind

func (*AlreadyExistsError) OrigError

func (e *AlreadyExistsError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type BadParameterError

type BadParameterError struct {
	trace.Traces
	Param string `json:"param"`
	Err   string `json:"message"`
}

BadParameterError indicates that something is wrong with passed parameter to API method

func BadParameter

func BadParameter(name, message string) *BadParameterError

BadParameter returns a new instance of BadParameterError

func (*BadParameterError) Error

func (b *BadParameterError) Error() string

Error returrns debug friendly message

func (*BadParameterError) IsBadParameterError

func (b *BadParameterError) IsBadParameterError() bool

IsBadParameterError indicates that error is of bad parameter type

func (*BadParameterError) OrigError

func (b *BadParameterError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type CompareFailedError

type CompareFailedError struct {
	trace.Traces
	// Message is user-friendly error message
	Message string `json:"message"`
}

CompareFailedError indicates that compare failed (e.g wrong password or hash)

func (*CompareFailedError) Error

func (e *CompareFailedError) Error() string

Error is debug - friendly message

func (*CompareFailedError) IsCompareFailedError

func (e *CompareFailedError) IsCompareFailedError() bool

IsCompareFailedError indicates that this is compare failed error

func (*CompareFailedError) OrigError

func (e *CompareFailedError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type ConnectionProblemError

type ConnectionProblemError struct {
	trace.Traces
	Message string `json:"message"`
	Err     error  `json:"-"`
}

ConnectionProblemError indicates any network error that has occured

func ConnectionProblem

func ConnectionProblem(message string, err error) *ConnectionProblemError

ConnectionProblem returns ConnectionProblem

func (*ConnectionProblemError) Error

func (c *ConnectionProblemError) Error() string

Error is debug - friendly error message

func (*ConnectionProblemError) IsConnectionProblemError

func (c *ConnectionProblemError) IsConnectionProblemError() bool

IsConnectionProblemError indicates that this error is of ConnectionProblem

func (*ConnectionProblemError) OrigError

func (c *ConnectionProblemError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type LimitExceededError

type LimitExceededError struct {
	trace.Traces
	Message string `json:"message"`
}

LimitExceededError indicates rate limit or connection limit problem

func LimitExceeded

func LimitExceeded(message string) *LimitExceededError

LimitExceeded returns new limit exceeded error

func (*LimitExceededError) Error

func (c *LimitExceededError) Error() string

Error is debug - friendly error message

func (*LimitExceededError) IsLimitExceededError

func (c *LimitExceededError) IsLimitExceededError() bool

IsLimitExceededError indicates that this error is of ConnectionProblem

func (*LimitExceededError) OrigError

func (c *LimitExceededError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type MissingParameterError

type MissingParameterError struct {
	trace.Traces `json:"traces"`
	// Param is the name of the missing parameter
	Param string
}

MissingParameterError indicates that one of the parameters was missing

func (*MissingParameterError) Error

func (m *MissingParameterError) Error() string

Error returns log-friendly description of the error

func (*MissingParameterError) IsMissingParameterError

func (m *MissingParameterError) IsMissingParameterError() bool

IsMissingParameterError indicates that this error is of MissingParameter type

func (*MissingParameterError) OrigError

func (e *MissingParameterError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type NotFoundError

type NotFoundError struct {
	trace.Traces `json:"traces"`
	Message      string `json:"message"`
}

NotFoundError indicates that object has not been found

func NotFound

func NotFound(message string) *NotFoundError

NotFound returns new instance of not found error

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

Error returns log friendly description of an error

func (*NotFoundError) IsNotFoundError

func (e *NotFoundError) IsNotFoundError() bool

IsNotFoundError returns true to indicate that is NotFoundError

func (*NotFoundError) OrigError

func (e *NotFoundError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type ReadonlyError

type ReadonlyError struct {
	trace.Traces
	Message string `json:"message"`
}

ReadonlyError indicates that some backend can only read, not write

func (*ReadonlyError) Error

func (e *ReadonlyError) Error() string

Error is debug - friendly error message

func (*ReadonlyError) IsReadonlyError

func (e *ReadonlyError) IsReadonlyError() bool

IsReadonlyError indicates that this error is of Readonly type

func (*ReadonlyError) OrigError

func (e *ReadonlyError) OrigError() error

OrigError returns original error (in this case this is the error itself)

type Role added in v1.0.0

type Role string

Role identifies the role of SSH server connection

const (
	// RoleAuth is for teleport auth server (authority, authentication and authorization)
	RoleAuth Role = "Auth"
	// RoleUser is a role for teleport SSH user
	RoleUser Role = "User"
	// RoleWeb is for web access users
	RoleWeb Role = "Web"
	// RoleNode is a role for SSH node in the cluster
	RoleNode Role = "Node"
	// RoleProxy is a role for SSH proxy in the cluster
	RoleProxy Role = "Proxy"
	// RoleAdmin is admin role
	RoleAdmin Role = "Admin"
	// RoleProvisionToken is a role for nodes authenticated using provisioning tokens
	RoleProvisionToken Role = "ProvisionToken"
	// RoleSignup is for first time signing up users
	RoleSignup Role = "Signup"
)

func (Role) Check added in v1.0.0

func (r Role) Check() error

Check checks if this a a valid role value, returns nil if it's ok, false otherwise

func (Role) String added in v1.0.0

func (r Role) String() string

String returns debug-friendly representation of this role

type SystemError

type SystemError struct {
	trace.Traces `json:"traces"`
	// Message is user-friendly error message
	Message string        `json:"message"`
	Code    syscall.Errno `json:"code"`
}

SystemError is the error raised by Operating system usually contains error code returned by linux API

func NewSystemError

func NewSystemError(code syscall.Errno, message string) *SystemError

NewSystemError returns a new system error

func (*SystemError) Error

func (s *SystemError) Error() string

Error returns log-friendly error description

func (SystemError) IsSystemError

func (SystemError) IsSystemError() bool

IsSystemError indicates that this error is of system error kind

func (*SystemError) OrigError

func (s *SystemError) OrigError() error

OrigError returns original error (in this case this is the error itself)

Directories

Path Synopsis
lib
backend
Package backend represents interface for accessing local or remote storage
Package backend represents interface for accessing local or remote storage
backend/boltbk
Package boltbk implements BoltDB backed backend for standalone instances and test mode, you should use Etcd in production
Package boltbk implements BoltDB backed backend for standalone instances and test mode, you should use Etcd in production
backend/etcdbk
Package etcdbk implements Etcd powered backend
Package etcdbk implements Etcd powered backend
backend/test
Package test contains a backend acceptance test suite that is backend implementation independant each backend will use the suite to test itself
Package test contains a backend acceptance test suite that is backend implementation independant each backend will use the suite to test itself
defaults
Package defaults contains default constants set in various parts of teleport codebase
Package defaults contains default constants set in various parts of teleport codebase
events
Package events contains structured events emitted by various parts of teleport, they are collected by auth server for audit purposes
Package events contains structured events emitted by various parts of teleport, they are collected by auth server for audit purposes
events/test
Package test contains a log backend acceptance test suite that is implementation independant each backend will use the suite to test itself
Package test contains a log backend acceptance test suite that is implementation independant each backend will use the suite to test itself
httplib
Package httplib implements common utility functions for writing classic HTTP handlers
Package httplib implements common utility functions for writing classic HTTP handlers
limiter
Package limiter implements connection and rate limiters for teleport
Package limiter implements connection and rate limiters for teleport
recorder
Package recorder implements session recorder - it captures all the output that can be later replayed in terminals
Package recorder implements session recorder - it captures all the output that can be later replayed in terminals
reversetunnel
Package reversetunnel sets up persistent reverse tunnel between remote site and teleport proxy, when site agents dial to teleport proxy's socket and teleport proxy can connect to any server through this tunnel.
Package reversetunnel sets up persistent reverse tunnel between remote site and teleport proxy, when site agents dial to teleport proxy's socket and teleport proxy can connect to any server through this tunnel.
service
Package service implements teleport running service, takes care of initialization, cleanup and shutdown procedures
Package service implements teleport running service, takes care of initialization, cleanup and shutdown procedures
services
Package services implements statefule services provided by teleport, like certificate authority management, user and web sessions, events and logs
Package services implements statefule services provided by teleport, like certificate authority management, user and web sessions, events and logs
session
Package session is used for bookeeping of SSH interactive sessions that happen in realtime across the teleport cluster
Package session is used for bookeeping of SSH interactive sessions that happen in realtime across the teleport cluster
srv
web
Package web implements web proxy handler that provides web interface to view and connect to teleport nodes
Package web implements web proxy handler that provides web interface to view and connect to teleport nodes
tool
tsh

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL