J'ai cherché une solution pour partager facilement une session shell de ma workstation à un collègue.

Je connais les solutions suivantes :

• ngrok

$ ngrok tcp 22
Donne : tcp://0.tcp.ngrok.io:12345
# Connexion : ssh user@0.tcp.ngrok.io -p 12345

• Tmate, un fork de tmux patché, en C, projet qui a débuté en 2007
• cloudflared

#JaiDécouvert aujourd'hui les solutions upterm et bore.

Le projet upterm a commencé en 2019 et est codé en Golang. Le projet bore est plus jeune, il a commencé 2022 et est codé en rust.

J'ai testé bore puis upterm. J'ai retenu upterm pour les raisons suivantes :

• upterm propose directement un package rpm, contrairement à bore
• Le serveur relais public de upterm était significativement plus réactif que celui de bore lors de mes tests
• upterm propose nativement une session partagée entre deux utilisateurs, alors que bore est spécialisé dans la création de tunnels TCP. Il est possible de configurer bore pour lancer automatiquement des sessions partagées via un script tmux lancé par ssh, mais c'est moins pratique que upterm

Voici une démonstration de upterm :

$ sudo dnf install -y https://github.com/owenthereal/upterm/releases/download/v0.20.0/upterm_linux_amd64.rpm

Je peux ensuite autoriser la clé publique ssh de l'utilisateur invité :

$ upterm host --authorized-keys PATH_TO_PUBLIC_KEY

ou directement via son username GitHub :

$ upterm host --github-user username

Pour donner accès à une session terminal :

$ upterm host
The authenticity of host 'uptermd.upterm.dev (2a09:8280:1::3:4b89)' can't be established.
ED25519 key fingerprint is SHA256:9ajV8JqMe6jJE/s3TYjb/9xw7T0pfJ2+gADiBIJWDPE.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
╭─ Session: LiZaF6eKfCTxNeFSEt7B ─╮
┌──────────────────┬─────────────────────────────────────────────┐
│ Command:         │ /usr/bin/zsh                                │
│ Force Command:   │ n/a                                         │
│ Host:            │ ssh://uptermd.upterm.dev:22                 │
│ Authorized Keys: │ n/a                                         │
│                  │                                             │
│ ➤ SSH Command:   │ ssh LiZaF6eKfCTxNeFSEt7B@uptermd.upterm.dev │
└──────────────────┴─────────────────────────────────────────────┘

╰─ Run 'upterm session current' to display this again ─╯

🤝 Accept connections? [y/n] (or <ctrl-c> to force exit)
✅ Starting to accept connections...

L'utilisateur invité accède à ce terminal simplement avec :

$ ssh LiZaF6eKfCTxNeFSEt7B@uptermd.upterm.dev

upterm maintient une liste de sessions ouvertes, consultable avec :

$ upterm session list
📡 Active Sessions (1)
═══════════════════════
┌───┬──────────────────────┬──────────────┬─────────────────────────────┐
│   │      SESSION ID      │   COMMAND    │            HOST             │
├───┼──────────────────────┼──────────────┼─────────────────────────────┤
│ * │ DumRFGF6AuinQjzwBf0E │ /usr/bin/zsh │ ssh://uptermd.upterm.dev:22 │
└───┴──────────────────────┴──────────────┴─────────────────────────────┘

💡 Tips:
  • Use 'upterm session current' to see details
  • Use 'upterm session info <SESSION_ID>' for specific session

Dans cette note, je souhaite décrire et expliquer comment j'intègre des sessions de terminal dans des documentations.

Convention mainstream que j'ai adoptée

Je suis la convention mainstream suivante pour représenter des sessions terminal (de type bash, zsh…) :

Première partie :

$ echo "Hello, world!"
Hello, world!

$ ls -l
total 0
-rw-r--r-- 1 user user 0 Feb 25 10:00 file.txt

Seconde partie :

$ sudo su
# systemctl restart nginx 
$ exit

$ uptime # Affiche l'uptime
uptime 10:00:00 up 1 day, 2:45, 1 user, load average: 0.15, 0.10, 0.05

Les lignes commençant par $ ou # indiquent les commandes saisies par l'utilisateur, tandis que les autres correspondent aux sorties du terminal.
Il m'arrive également d'ajouter des commentaires en fin de ligne à l'aide de # ….

Origine de cette convention ?

J'ai cherché à retracer l'origine de cette pratique et elle semble très ancienne, probablement adoptée dès les débuts d'Unix en 1971.
On retrouve cette syntaxe notamment dans le livre The Unix Programming Environment (pdf), publié en 1984.

Ne pas inclure de $ si un bloc ne contient aucune sortie de commande

La règle MD014 de Markdownlint aborde ce sujet :

MD014 - Dollar signs used before commands without showing output

Tags: code

Aliases: commands-show-output

This rule is triggered when there are code blocks showing shell commands to be typed, and the shell commands are preceded by dollar signs ($):

$ ls
$ cat foo
$ less bar

The dollar signs are unnecessary in the above situation, and should not be included:

ls
cat foo
less bar

However, an exception is made when there is a need to distinguish between typed commands and command output, as in the following example:

$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz

Rationale: it is easier to copy and paste and less noisy if the dollar signs are omitted when they are not needed. See https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code for more information.

source

Pendant un certain temps, j’ai suivi la recommandation de ne pas inclure de $ dans un bloc de commande lorsqu’il n’affiche aucune sortie.

Après quelques années, j’ai décidé de ne plus appliquer cette règle pour la raison suivante :

• Lorsque la documentation mélange des fichiers de configuration et des commandes sans $, j’ai du mal à distinguer ce qui doit être exécuté dans un terminal et ce qui relève de la configuration.

Pour éviter toute ambiguïté, j’ai adopté une approche radicale : toujours utiliser $ pour indiquer une commande à exécuter, même si le bloc ne contient pas de sortie.

Je n'aime pas les $ dans les blocs de commande, car que je ne peux pas copier / coller facilement !

Je comprends tout à fait cette remarque. Cependant, ces "screenshots" de session de terminal n'ont pas vocation à être copiées / collées en masse.
Ils ont avant tout une fonction explicative.
Ce sont des sortes de "screenshot".

Si j'éprouve le besoin de faire souvent des "copier / coller" d'exemples de session terminal, alors je considère que c'est le signe qu'un script "helper" serait plus approprié pour exécuter ce groupe de commandes d’un seul coup.

Par exemple, je peux remplacer ce contenu :

Ensure that the following prerequisites have been installed: mise and direnv, see instruction in ../README.md.

$ mise trust
$ mise install
$ scw version
Version    2.34.0

Par celui-ci (qui indique l'existence du script ./scripts/mise-install.sh) :

Ensure that the following prerequisites have been installed: mise and direnv, see instruction in ../README.md (or execute ./scripts/mise-install.sh).

$ mise trust
$ mise install
$ scw version
Version    2.34.0

Cela évite les copier-coller répétitifs tout en conservant la clarté de l’explication.

Je viens de modifier ma configuration (dotfiles) tmux :

https://github.com/stephane-klein/dotfiles/commit/f370721781f6ea1b72c1954f43ce50196112e72e

La configuration suivante

set -g window-status-current-format "#[fg=colour231,bg=colour33,bold] #{?window_name,#{window_name},#{b:pane_current_path}} #[nobold]"
set -g window-status-format "#[fg=colour33,bg=colour254,bold] #{?window_name,#{window_name},#{b:pane_current_path}} #[nobold]"

permet de définir cette ligne status :

Pour chaque fenêtre est affichée soit le nom de la fenêtre, soit le nom du dossier courant du shell actif dans la fenêtre.

La syntaxe suivante est documentée ici :

#{?window_name,#{window_name},#{b:pane_current_path}}

Ce qui signife #{?condition,true_value,false_value}.

La configuration suivante

bind-key c new-window -c "#{pane_current_path}" -n ""

-n "" permet de définir par défaut le nom des nouvelles fenêtres avec un chaine vide.