Fork me on GitHub

Restricted Session for SSH

Restricted Session for SSH

Restricted Session for SSH

Length: 05:22

With a Restricted Session, Teleport allows the administrator to specify a policy to apply to SSH sessions. This policy can restrict access to certain resources. Currently Teleport supports network restrictions with more types coming in the future.


Teleport 7.0+ with Restricted Sessions requires Linux kernel 5.8 (or above).

You can check your kernel version using the uname command. The output should look something like the following.

uname -r


Linux distributions and supported kernels

Distro nameDistro versionKernel version
Ubuntu "Groovy Gorilla"20.105.8+

Network Restrictions

Network restrictions work similar to a firewall but with several differences:

  1. Firewall rules apply to the entire machine whereas network restrictions are applied only to SSH sessions.
  2. Whereas firewall typically blocks ingress (inbound) connections, network restrictions block egress (outbound) connections.
  3. Firewall rules are typically static but Restricted Session comes with an API allowing the rules to be dynamically updated across the entire fleet.

Step 1/4. Install and configure Teleport node

Follow our installation instructions to install Teleport Auth, Proxy and Nodes.

Set up the Teleport node with this /etc/teleport.yaml. See our configuration file setup for more instructions.


Restricted Session requires Enhanced Recording to be enabled as well. This requirement will be removed in the future.

# Example config to be saved as /etc/teleport.yaml
  nodename: graviton-node
  auth_token: exampletoken
  # Replace with IP of Teleport Auth server.
  data_dir: /var/lib/teleport
  enabled: false
  enabled: false
  enabled: true
    # Must be enabled for Restricted Sessions to work.
    enabled: true
    # Optional: Controls where cgroupv2 hierarchy is mounted. Default value:
    # /cgroup2.
    cgroup_path: /cgroup2

    enabled: true

Step 2/4. Define a network restrictions policy

Create a file netpolicy.yaml:

kind: network_restrictions
version: v4
  name: network-restrictions
  # When Restricted Session is enabled, the network policy becomes
  # "deny-all". Must add back the ranges to allow
    # Allow LAN access
    - cidr:
    - cidr:
    - cidr:

    # Allow link-local
    - cidr:
    - cidr: fe80::/10

    # Allow localhost
    - cidr:
    - cidr: ::1/128

  # Override "allow" list with exceptions
    # Finance database
    - cidr:

Install the policy using tctl:

tctl create -f netpolicy.yaml

network restrictions have been updated

  • If the Restricted Session is not enabled in teleport.yaml, all network operations will be allowed.
  • When the Restricted Session is enabled but network_restrictions object has not been created via tctl or the API, the default policy stays allow-all.
  • However when the network_restrictions object is created, the default policy switches to deny-all. Be sure to add back all the necessary ranges into the allow list.

Step 3/4. Test by logging into node via Teleport

curl -v

* Trying 2607:f8b0:4005:809::200e:80...


* Immediate connect fail for 2607:f8b0:4005:809::200e: Operation not permitted

* Trying


* Immediate connect fail for Operation not permitted

* Closing connection 0

curl: (7) Couldn't connect to server

Step 4/4. Inspect logs

The audit log will contain an entry with event (there may be more entries present for the same curl command):

  "ei": 173,
  "event": "",
  "uid": "dda39eb4-13e1-45fd-a039-35b4dca1fa51",
  "code": "T4002I",
  "time": "2021-07-22T22:24:14.984Z",
  "cluster_name": "teleport-quickstart",
  "user": "demo",
  "login": "demo",
  "sid": "c8e0b0d5-3994-4221-b701-c1ae17d871f1",
  "namespace": "default",
  "server_id": "4951c001-8dad-4e21-abb6-c03f69b72d2e",
  "pid": 319267,
  "cgroup_id": 10863,
  "program": "curl",
  "src_addr": "",
  "dst_addr": "",
  "dst_port": 80,
  "version": 4,
  "operation": 0,
  "action": 1

This is the same event that is issued by Enhanced Recording. You can differentiate them by the action field. Enhanced Recording sets the action to 0 (OBSERVED) while Restricted Session sets this value to 1 (DENIED).


Restricted Session requires Enhanced Recording to be enabled as well. This requirement will be removed in the future. To quickly check the status of the audit log, you can simply tail the logs with tail -f /var/lib/teleport/log/events.log, the resulting capture from Teleport will be a JSON log for each command and network request.

Have a suggestion or can’t find something?