diff --git a/docs/explanation/port-number.md b/docs/explanation/port-number.md new file mode 100644 index 0000000..3e385c5 --- /dev/null +++ b/docs/explanation/port-number.md @@ -0,0 +1,3 @@ +# Port number + +The port 10022 has been chosen as port 22 is already used by juju for ssh access. diff --git a/docs/how-to/get-server-config.md b/docs/how-to/get-server-config.md new file mode 100644 index 0000000..a816818 --- /dev/null +++ b/docs/how-to/get-server-config.md @@ -0,0 +1,28 @@ +# How to get server config + +### Get server config + +To retrieve the server configuration for tmate client (contents of `.tmate.conf`), run the +following action. + +``` +juju run tmate-ssh-server/0 get-server-config +``` + +The output should look similar to the contents below: + +``` +Running operation 1 with 1 task + - task 1 on unit-tmate-ssh-server-0 + +Waiting for task 1... +tmate-config: |2 + + set -g tmate-server-host + set -g tmate-server-port 10022 + set -g tmate-server-rsa-fingerprint + set -g tmate-server-ed25519-fingerprint +``` + +You can use the output above as the tmate configuration file (`.tmate.conf`) contents on a tmate +client machine. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c76099b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,43 @@ +# Tmate-ssh-server Operator + +A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) +deploying and managing [Tmate self-hosted server](https://tmate.io/). Tmate is an +open source terminal multiplexer, providing instant terminal sharing capabilities. + +Tmate enables users to share their terminal session with other users over the internet, allowing +them to collaborate, provide technical support, or demonstrate commands and procedures in +real-time. + +This charm provides the tmate-ssh-server service, which is paired with the tmate client to provide +a self-hosted ssh relay server. + +For DevOps and SRE teams, this charm will make operating self hosted tmate-ssh-server simple and +straightforward through Juju's clean interface. Allowing machine relations to the +[Github runner](https://charmhub.io/github-runner), it supports SSH debug access to the runner VMs +managed by the charm. + +## Project and community + +The Tmate-ssh-server Operator is a member of the Ubuntu family. It's an open source project that +warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. + +- [Code of conduct](https://ubuntu.com/community/code-of-conduct) +- [Get support](https://discourse.charmhub.io/) +- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +- [Contribute](Contribute) + +Thinking about using the tmate-ssh-server Operator for your next project? +[Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! + +# Contents + +1. [Tutorial](tutorial) + 1. [Getting Started](tutorial/getting-started.md) +1. [How to](how-to) + 1. [Get server config](how-to/get-server-config.md) +1. [Reference](reference) + 1. [Actions](reference/actions.md) + 1. [Configurations](reference/configurations.md) + 1. [Integrations](reference/integrations.md) +1. [Explanation](explanation) + 1. [Port Number](explanation/port-number.md) diff --git a/docs/reference/actions.md b/docs/reference/actions.md new file mode 100644 index 0000000..f0efc77 --- /dev/null +++ b/docs/reference/actions.md @@ -0,0 +1,3 @@ +# Actions + +See [Actions](https://charmhub.io/tmate-ssh-server/actions). diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md new file mode 100644 index 0000000..61fbad1 --- /dev/null +++ b/docs/reference/configurations.md @@ -0,0 +1,3 @@ +# Configurations + +See [Configure](https://charmhub.io/tmate-ssh-server/configure). diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md new file mode 100644 index 0000000..d1e55fb --- /dev/null +++ b/docs/reference/integrations.md @@ -0,0 +1,12 @@ +# Integrations + +### agent + +_Interface_: debug-ssh +_Supported charms_: [GitHub Runner](https://charmhub.io/github-runner) + +The `debug-ssh` relation provides ssh information to the runner machines, allowing it to +automatically configure ssh debug access with tools such as +[action-tmate](https://github.com/canonical/action-tmate). + +Example debug-ssh relate command: `juju relate tmate-ssh-server github-runner` diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md new file mode 100644 index 0000000..55c3754 --- /dev/null +++ b/docs/tutorial/getting-started.md @@ -0,0 +1,137 @@ +# Getting Started + +## What you'll do + +- Deploy the [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server) +- Get the .tmate.conf through `get-server-config` action +- Create a tmate client machine and configure tmate client +- SSH into tmate terminal + +Tmate is a remote terminal sharing tool that allows users to securely share their terminal with +others in real-time, making it easy to collaborate, troubleshoot, and provide support across +different systems and networks. It provides a seamless way to establish SSH connections and enables +remote access without requiring complex network configurations. + +### Prerequisites + +To deploy a tmate-ssh-server charm, you will need a Juju controller bootstrapped with any machine +controller type. +To see how to bootstrap your Juju installation with LXD, please refer to the documentation +on LXD [installation](https://juju.is/docs/juju/lxd). + +### Setting up the tutorial model + +To easily clean up the resources and to separate your workload from the contents of this tutorial, +it is recommended to set up a new model with the following command. + +``` +$ juju add-model tmate-tutorial +``` + +### Deploy the tmate-ssh-server charm + +Use the following command to deploy the tmate-ssh-server charm. + +``` +$ juju deploy tmate-ssh-server +``` + +### Get the tmate configuration contents + +To get the contents of `.tmate.conf` file to register a tmate client, use the `get-server-config` +action to retrieve the configuration details. Save the output contents into `.tmate.conf` file for +later use. +``` +$ juju run tmate-ssh-server/0 get-server-config | grep -E set | sed 's/^[[:space:]]*//' > .tmate.conf +``` + +The output of .tmate.conf file generated from the command above will look something like the following: +``` +$ cat .tmate.conf +set -g tmate-server-host +set -g tmate-server-port 10022 +set -g tmate-server-rsa-fingerprint +set -g tmate-server-ed25519-fingerprint +``` + +### Create a tmate client machine + +To imitate a tmate client, we can add a machine on Juju and install tmate. + +``` +$ juju add-machine +created machine 1 + +$ juju ssh 1 -- "sudo apt update && sudo apt install -y tmate" +``` + +Copy the .tmate.conf file retrieved from the +[Get the tmate configuration contents](#get-the-tmate-configuration-contents) above to the client +machine. + +Then, register the public key of the current machine (use `ssh-keygen` to generate key files if +none exist yet). + +``` +$ juju scp .tmate.conf 1:~/.tmate.conf +$ juju ssh 1 -- "echo $(~/.ssh/id_rsa.pub) >> ~/.ssh/authorized_keys" +``` + +Start the tmate client & get the ssh command. +``` +# start a new tmate session +$ juju ssh 1 -- "tmate -a ~/.ssh/authorized_keys -S /tmp/tmate.sock new-session -d" +# wait until the tmate session is ready +$ juju ssh 1 -- "tmate -S /tmp/tmate.sock wait tmate-ready" +# print tmate ssh details +$ juju ssh 1 -- "tmate -S /tmp/tmate.sock display -p '#{tmate_ssh}'" +ssh -p10022 @0.0.0.0 +``` + +### SSH into the tmate terminal + +Use `juju status` command to find out the unit ip address. + +``` +$ juju status +Model Controller Cloud/Region Version SLA Timestamp +tmate-tutorial localhost localhost/localhost 3.1.6 unsupported + +App Version Status Scale Charm Channel Rev Exposed Message +tmate-ssh-server active 1 tmate-ssh-server 0 no + +Unit Workload Agent Machine Public address Ports Message +tmate-ssh-server/0* active idle 0 + +Machine State Address Inst id Base AZ Message +0 started juju-92dc13-0 ubuntu@22.04 Running +1 started juju-92dc13-1 ubuntu@22.04 Running +``` + +Then use the ssh command output from the previous step and replace `0.0.0.0` address to the unit +IP of tmate-ssh-server unit. + +``` +$ ssh @ + +Tip: if you wish to use tmate only for remote access, run: tmate -F +To see the following messages again, run in a tmate session: tmate show-messages +Press or to continue +--------------------------------------------------------------------- +Connecting to ... +Note: clear your terminal before sharing readonly access +ssh session read only: ssh -p10022 ro-@ +ssh session: ssh -p10022 @ +``` + + +### Cleaning up the environment + +Congratulations! You have successfully finished the tmate-ssh-server tutorial. You can now remove +the `.tmate.conf` file and the juju model environment that you’ve created using the following +command. + +``` +$ rm .tmate.conf +$ juju destroy-model tmate-tutorial -y +```