{"slug":"send-tailscale-ssh-session-recordings-to-s3","title":"Send Tailscale SSH session recordings to S3","tags":["tailscale"],"agent_summary":"Last validated: Jan 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Send Tailscale SSH session recordings to S3\r\n\r\nLast validated: Jan 9, 2026\r\n\r\nBy default, Tailscale SSH session recording will save recordings to the Docker host's filesystem. While this is a fast and straightforward way to deploy session recorders, you may want to use a more scalable and resilient storage solution like Amazon S3.\r\n\r\nTailscale SSH session recordingis currently [in beta](https://tailscale.com/docs/reference/tailscale-release-stages#beta). To try it, follow the steps below to enable it for your network using Tailscale v1.40.1 or later.\r\n\r\nTailscale SSH session recordingis available for [the Personal and Enterprise plans](https://tailscale.com/pricing).\r\n\r\nYou can configure session recorder nodes to send recordings to Amazon S3 or another S3-compatible object storage service such as MinIO, Wasabi, Google Cloud Storage, or [Cloudflare R2](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3#cloudflare-r2-compatibility).\r\n\r\nIf you deploy recorder nodes with the built-in web UI enabled, users can access recordings stored in S3 in the web UI.\r\n\r\n## [Configure S3 as storage for session recording nodes](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#configure-s3-as-storage-for-session-recording-nodes)\r\n\r\n### [Prerequisites](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#prerequisites)\r\n\r\nTo configure S3 as the backend storage for session recording, you must have access to an AWS account with permission to create:\r\n\r\n- S3 buckets\r\n- IAM policies\r\n\r\nand _either_\r\n\r\n- IAM users\r\n- IAM user access keys\r\n\r\nor\r\n\r\n- an IAM role\r\n\r\n### [Create an IAM policy and user/role](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#create-an-iam-policy-and-userrole)\r\n\r\n[Create the following IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) in your AWS account. Replace `` with the name of your S3 bucket on both lines of the `Resource` section.\r\n\r\n```json\r\n{\r\n \"Version\": \"2012-10-17\",\r\n \"Statement\": [\\\r\n {\\\r\n \"Effect\": \"Allow\",\\\r\n \"Action\": [\\\r\n \"s3:PutObject\",\\\r\n \"s3:GetBucketLocation\",\\\r\n \"s3:GetObject\",\\\r\n \"s3:ListBucket\"\\\r\n ],\\\r\n \"Resource\": [\\\r\n \"arn:aws:s3:::/*\",\\\r\n \"arn:aws:s3:::\"\\\r\n ]\\\r\n }\\\r\n ]\r\n}\r\n```\r\n\r\nIf you are running the recorder nodes without the built-in web UI, you can omit `s3:GetObject` and `s3:ListBucket` from this policy. `s3:PutObject` and `s3:GetBucketLocation` are always required.\r\n\r\nIf you plan to use IAM access keys for permission to write to the bucket, assign this policy a new IAM user, and [create an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) for this user. If you plan to use an IAM role, [create an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html) and attach the previously defined policy to the role.\r\n\r\n### [Deploy the recorder node](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#deploy-the-recorder-node)\r\n\r\nDeploying a recorder node with S3 as the storage backend is similar to the standard filesystem deployment. You'll need to add your IAM credentials or role, and the S3 bucket information.\r\n\r\n#### [Deploy with AWS access keys](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#deploy-with-aws-access-keys)\r\n\r\nFor AWS access keys, specify the AWS access key and secret key:\r\n\r\n```shell\r\ndocker run --name tsrecorder --rm -it \\\r\n -e TS_AUTHKEY=$TS_AUTHKEY \\\r\n -e AWS_ACCESS_KEY=$AWS_ACCESS_KEY \\\r\n -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \\\r\n -v $HOME/tsrecorder:/data \\\r\n tailscale/tsrecorder:stable \\\r\n /tsrecorder --dst='s3://s3.us-east-2.amazonaws.com' --statedir=/data/state \\\r\n --bucket=$S3_BUCKET_NAME --ui \\\r\n```\r\n\r\n#### [Deploy with attached IAM roles](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#deploy-with-attached-iam-roles)\r\n\r\nFor IAM roles, the credentials are retrieved from the AWS metadata service. You'll need to assign an IAM role (and if using an EC2 instance, an [IAM instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)) to the container.\r\n\r\n```shell\r\ndocker run --name tsrecorder --rm -it \\\r\n -e TS_AUTHKEY=$TS_AUTHKEY \\\r\n -v $HOME/tsrecorder:/data \\\r\n tailscale/tsrecorder:stable \\\r\n /tsrecorder --dst='s3://s3.us-east-2.amazonaws.com' --statedir=/data/state \\\r\n --bucket=$S3_BUCKET_NAME --ui \\\r\n```\r\n\r\nIf the instance you're provisioning the Docker container is using [Instance Metadata v2](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/configuring-instance-metadata-service.html), the default `PUT` response hop limit is 1 (that is, from the EC2 instance to the metadata service). For IAM instance profiles to work with Docker, you must first configure the limit to account for the extra hop through the EC2 instance, [so 2 at minimum](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/configuring-IMDS-existing-instances.html#modify-PUT-response-hop-limit).\r\n\r\nRequired flags:\r\n\r\n- `--dst` Specifies where recordings will be saved. Accepts a local file path or an S3 region URL. The value must begin with `s3://` if you intend to use S3 storage for storing the recordings. You can alternatively define the value as an environment variable, `TSRECORDER_DST`.\r\n- `--statedir` Specifies where the recorder should store its internal state. Accepts a local file path.\r\n\r\nOptional flags:\r\n\r\n- `--hostname` Specifies a hostname to use for the recorder node. Defaults to `recorder`. You can alternatively define the value as an environment variable, `TSRECORDER_HOSTNAME`.\r\n- `--access-key` The AWS access key for an IAM user that can upload recordings to an S3 bucket. Required when using S3 as a storage backend if no IAM role is passed to the instance. You can alternatively define the secret access key as an environment variable, `AWS_ACCESS_KEY_ID`.\r\n- `--secret-key` The AWS secret access key for an IAM user that can upload recordings to an S3 bucket. Required when using S3 as a storage backend if no IAM role is passed to the instance. You can alternatively define the secret access key as an environment variable, `AWS_SECRET_ACCESS_KEY`.\r\n- `--bucket` The name of the S3 bucket where the recorder should upload recordings. Required when using S3 as a storage backend. You can alternatively define the secret access key as an environment variable, `TSRECORDER_BUCKET`.\r\n- `--state` Path to Tailscale state file, used to persist recorder state across container restarts. This can be a persistent volume or a Kubernetes [`Secret`](https://kubernetes.io/docs/concepts/configuration/secret/). You can alternatively define this value as an environment variable, `TS_STATE`.\r\n - To use a `Secret`, specify `kube:`. If set to use a `Secret` for state storage, the recorder must have permissions to read, update, and patch the `Secret`. If the `Secret` does not exist, the recorder will create it, and must have permissions to do so.\r\n - If `--state` is unset, the state will be stored in the directory set using `--statedir`.\r\n- `--ui` Enables the recorder container web UI for viewing recorded SSH sessions. Defaults to `false` if this flag is not present. You can alternatively define this value as an environment variable, `TSRECORDER_UI`.\r\n - If you deploy the recorder with the UI, you must have HTTPS enabled in your tailnet.\r\n - If you enable the recorder container web UI, you should restrict access to port `443` on the recorder in your access control policies to prevent unauthorized members of your tailnet from viewing sensitive recordings.\r\n\r\nThere are multiple ways to define the AWS IAM credentials needed to connect to an S3 bucket. In order of precedence, they are:\r\n\r\n1. Specify `--access-key` and `--secret-key`\r\n2. Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`\r\n3. Specify none of the above, and be on an EC2 instance with the right permissions.\r\n\r\n#### [Cloudflare R2 Compatibility](https://tailscale.com/docs/features/tailscale-ssh/how-to/session-recording-s3\\#cloudflare-r2-compatibility)\r\n\r\nCloudflare R2 Storage provides an [S3-compatible API](https://developers.cloudflare.com/r2/api/s3/api); however, an additional setting is needed due to differences in their implementation. To use Cloudflare R2 as the storage service for session recordings set the environment variable `S3_SEND_CONTENT_MD5` to `true` in addition to any environment variables you are already passing.\r\n\r\n```shell\r\nS3_SEND_CONTENT_MD5=true\r\n```\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Send Tailscale SSH session recordings to S3

\n

Last validated: Jan 9, 2026

\n

By default, Tailscale SSH session recording will save recordings to the Docker host's filesystem. While this is a fast and straightforward way to deploy session recorders, you may want to use a more scalable and resilient storage solution like Amazon S3.

\n

Tailscale SSH session recordingis currently in beta. To try it, follow the steps below to enable it for your network using Tailscale v1.40.1 or later.

\n

Tailscale SSH session recordingis available for the Personal and Enterprise plans.

\n

You can configure session recorder nodes to send recordings to Amazon S3 or another S3-compatible object storage service such as MinIO, Wasabi, Google Cloud Storage, or Cloudflare R2.

\n

If you deploy recorder nodes with the built-in web UI enabled, users can access recordings stored in S3 in the web UI.

\n

Configure S3 as storage for session recording nodes

\n

Prerequisites

\n

To configure S3 as the backend storage for session recording, you must have access to an AWS account with permission to create:

\n
    \n
  • S3 buckets
    • \n
  • IAM policies
    • \n
\n

and either

\n
    \n
  • IAM users
    • \n
  • IAM user access keys
    • \n
\n

or

\n
    \n
  • an IAM role
    • \n
\n

Create an IAM policy and user/role

\n

Create the following IAM policy in your AWS account. Replace <bucket-name> with the name of your S3 bucket on both lines of the Resource section.

\n
{\r\n  \"Version\": \"2012-10-17\",\r\n  \"Statement\": [\\\r\n    {\\\r\n      \"Effect\": \"Allow\",\\\r\n      \"Action\": [\\\r\n        \"s3:PutObject\",\\\r\n        \"s3:GetBucketLocation\",\\\r\n        \"s3:GetObject\",\\\r\n        \"s3:ListBucket\"\\\r\n      ],\\\r\n      \"Resource\": [\\\r\n        \"arn:aws:s3:::<bucket-name>/*\",\\\r\n        \"arn:aws:s3:::<bucket-name>\"\\\r\n      ]\\\r\n    }\\\r\n  ]\r\n}\n
\n

If you are running the recorder nodes without the built-in web UI, you can omit s3:GetObject and s3:ListBucket from this policy. s3:PutObject and s3:GetBucketLocation are always required.

\n

If you plan to use IAM access keys for permission to write to the bucket, assign this policy a new IAM user, and create an access key for this user. If you plan to use an IAM role, create an IAM role and attach the previously defined policy to the role.

\n

Deploy the recorder node

\n

Deploying a recorder node with S3 as the storage backend is similar to the standard filesystem deployment. You'll need to add your IAM credentials or role, and the S3 bucket information.

\n

Deploy with AWS access keys

\n

For AWS access keys, specify the AWS access key and secret key:

\n
docker run --name tsrecorder --rm -it \\\r\n  -e TS_AUTHKEY=$TS_AUTHKEY \\\r\n  -e AWS_ACCESS_KEY=$AWS_ACCESS_KEY \\\r\n  -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \\\r\n  -v $HOME/tsrecorder:/data \\\r\n  tailscale/tsrecorder:stable \\\r\n  /tsrecorder --dst='s3://s3.us-east-2.amazonaws.com' --statedir=/data/state \\\r\n  --bucket=$S3_BUCKET_NAME --ui \\\n
\n

Deploy with attached IAM roles

\n

For IAM roles, the credentials are retrieved from the AWS metadata service. You'll need to assign an IAM role (and if using an EC2 instance, an IAM instance profile) to the container.

\n
docker run --name tsrecorder --rm -it \\\r\n  -e TS_AUTHKEY=$TS_AUTHKEY \\\r\n  -v $HOME/tsrecorder:/data \\\r\n  tailscale/tsrecorder:stable \\\r\n  /tsrecorder --dst='s3://s3.us-east-2.amazonaws.com' --statedir=/data/state \\\r\n  --bucket=$S3_BUCKET_NAME --ui \\\n
\n

If the instance you're provisioning the Docker container is using Instance Metadata v2, the default PUT response hop limit is 1 (that is, from the EC2 instance to the metadata service). For IAM instance profiles to work with Docker, you must first configure the limit to account for the extra hop through the EC2 instance, so 2 at minimum.

\n

Required flags:

\n
    \n
  • --dst Specifies where recordings will be saved. Accepts a local file path or an S3 region URL. The value must begin with s3:// if you intend to use S3 storage for storing the recordings. You can alternatively define the value as an environment variable, TSRECORDER_DST.
    • \n
  • --statedir Specifies where the recorder should store its internal state. Accepts a local file path.
    • \n
\n

Optional flags:

\n
    \n
  • --hostname Specifies a hostname to use for the recorder node. Defaults to recorder. You can alternatively define the value as an environment variable, TSRECORDER_HOSTNAME.
    • \n
  • --access-key The AWS access key for an IAM user that can upload recordings to an S3 bucket. Required when using S3 as a storage backend if no IAM role is passed to the instance. You can alternatively define the secret access key as an environment variable, AWS_ACCESS_KEY_ID.
    • \n
  • --secret-key The AWS secret access key for an IAM user that can upload recordings to an S3 bucket. Required when using S3 as a storage backend if no IAM role is passed to the instance. You can alternatively define the secret access key as an environment variable, AWS_SECRET_ACCESS_KEY.
    • \n
  • --bucket The name of the S3 bucket where the recorder should upload recordings. Required when using S3 as a storage backend. You can alternatively define the secret access key as an environment variable, TSRECORDER_BUCKET.
    • \n
  • --state Path to Tailscale state file, used to persist recorder state across container restarts. This can be a persistent volume or a Kubernetes Secret. You can alternatively define this value as an environment variable, TS_STATE.\n
      \n
    • To use a Secret, specify kube:<secret-name>. If set to use a Secret for state storage, the recorder must have permissions to read, update, and patch the Secret. If the Secret does not exist, the recorder will create it, and must have permissions to do so.
      • \n
    • If --state is unset, the state will be stored in the directory set using --statedir.
      • \n
    \n
    • \n
  • --ui Enables the recorder container web UI for viewing recorded SSH sessions. Defaults to false if this flag is not present. You can alternatively define this value as an environment variable, TSRECORDER_UI.\n
      \n
    • If you deploy the recorder with the UI, you must have HTTPS enabled in your tailnet.
      • \n
    • If you enable the recorder container web UI, you should restrict access to port 443 on the recorder in your access control policies to prevent unauthorized members of your tailnet from viewing sensitive recordings.
      • \n
    \n
    • \n
\n

There are multiple ways to define the AWS IAM credentials needed to connect to an S3 bucket. In order of precedence, they are:

\n
    \n
  1. Specify --access-key and --secret-key
    2. \n
  2. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
    3. \n
  3. Specify none of the above, and be on an EC2 instance with the right permissions.
    4. \n
\n

Cloudflare R2 Compatibility

\n

Cloudflare R2 Storage provides an S3-compatible API; however, an additional setting is needed due to differences in their implementation. To use Cloudflare R2 as the storage service for session recordings set the environment variable S3_SEND_CONTENT_MD5 to true in addition to any environment variables you are already passing.

\n
S3_SEND_CONTENT_MD5=true\n
\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}