wiki/docs/SSH/sshportal.md

categories: ssh
title: SSHPortal - Installation et exploitation

#### Pré-requis

_Docker_ doit être installé sur le serveur qui accueillera _SSHPortal_.

Les lignes pré-fixées de "~" sont à exécuter via SSH.

Les lignes pré-fixées de "config> " sont à exécuter dans la console d'administration de SSPortal.

#### Installation

L'installation se fait via _Docker_ , avec l'image [officielle](https://hub.docker.com/r/moul/sshportal).

```bash
~ mkdir -p /etc/docker/compose/sshportal/{data,log}
~ cat <<EOF >> /etc/docker/compose/sshportal/docker-compose.yml
version: "3"

services:
  sshportal:
    image: moul/sshportal
    container_name: sshportal
    restart: unless-stopped
    environment:
      SSHPORTAL_DEFAULT_ADMIN_INVITE_TOKEN: 'XXXXX'
      SSHPORTAL_DB_DRIVER: 'sqlite3'
      SSHPORTAL_DATABASE_URL: '/var/lib/sshportal/sshportal.db'
    ports:
      - 2222:2222
    volumes:
      - ./log:/log
      - ./data:/var/lib/sshportal/
      - /etc/hosts:/etc/hosts:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      sshportal:
        ipv4_address: 172.19.0.2

networks:
  sshportal:
    ipam:
      driver: default
      config:
        - subnet: 172.19.0.0/24
EOF
~ docker-compose pull
~ docker-compose up -d
```

> A noter qu'il est possible d'utiliser un backend de base de données différents, selon votre choix / goût (MySQL, PostgreSQL, etc).

#### Initialisation du compte admin

Pour initialiser le compte _admin_, il faut :

1. se connecter une première fois avec le token d'invitation _SSHPORTAL_DEFAULT_ADMIN_INVITE_TOKEN_ (défini dans le fichier `docker-compose.yml`)
2. lui fournir une clé SSH qui servira à identifier le compte _admin_

> Attention: il est indispensable de créer un clé SSH dédiée à l'administration de _SSHPortal_.

Nous commencons par générer une clé SSH :

```bash
~ ssh-keygen -t ed25519 -f ed25519_sshportal_admin
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ed25519_sshportal_admin.
Your public key has been saved in ed25519_sshportal_admin.pub.
The key fingerprint is:
SHA256:69qOmaargSULBB1xdG3SlfRsAmoiSdPwBTotnlW6lUI ludal@mbp-ludal-1.home
The key's randomart image is:
+--[ED25519 256]--+
|..**E.+o.oo.     |
|...O.=.o+..o     |
| .* B =o  . +    |
|.. * *     o     |
|o + .   S        |
|.=       .       |
|o .     .        |
|   .  .*         |
|  ..o+=o+        |
+----[SHA256]-----+
```

Puis, on se connecter avec la clé SSH et le token d'invitation (pour rappel, qui est défini dans le fichier `docker-compose.yml`) :

```bash
~ ssh <HOST> -i ed25519_sshportal_admin -p 2222 -l invite:XXXXX
```

Cela va donc enregistrer la clé SSH "ed25519_sshportal_admin" pour le compte admin de SSHPortal.

Pour se connecter à la console d'administration de SSHPortal, il faudra donc faire :

```bash 
~ ssh <HOST> -i ed25519_sshportal_admin -p 2222 -l admin
```

#### Configuration

Pré-requis: pour réaliser toutes les commandes de configuration, il est nécessaire de se connecter à _SSHPortal_ avec le compte _admin_ :

```bash
~ ssh <HOST> -i ed25519_sshportal_admin -p 2222 -l admin
```

##### Création d'une clé SSH dédiée

```bash
config> key create --name my-project
3
```

Cette clé sera à copier sur les serveurs cibles, pour permettra la connexion.

##### Créer les _hostgroup_

```bash
config> hostgroup create --name preprod
config> hostgroup create --name prod
```

Vérification :

```bash
config> hostgroup ls
  ID |  NAME   | HOSTS | ACLS |    UPDATED    |    CREATED    |       COMMENT
-----+---------+-------+------+---------------+---------------+-----------------------
   3 | prod    |     0 |    0 | 6 seconds ago | 6 seconds ago |
   2 | preprod |     0 |    0 | 9 seconds ago | 9 seconds ago |
   1 | default |     0 |    1 | 2 minutes ago | 2 minutes ago | created by sshportal
Total: 3 host groups.
```

##### Créer les _hosts_

```bash
config> host create --name=preprod1 --group=preprod --logging=everything --key my-project root@W.X.Y.Z
config> host create --name=prod1 --group=prod --logging=everything --key my-project root@W.X.Y.Z
```

Vérification :

```bash
config> host ls
  ID |  NAME    |        URL         |   KEY   |   GROUPS    |    UPDATED     |    CREATED     | COMMENT | HOP |  LOGGING
-----+----------+--------------------+---------+-------------+----------------+----------------+---------+-----+-------------
   2 | prod1    | ssh://root@W.X.Y.Z | default | prod        | 16 seconds ago | 16 seconds ago |         |     | everything
   1 | preprod1 | ssh://root@W.X.Y.Z | default | preprod    c| 29 seconds ago | 29 seconds ago |         |     | everything
Total: 2 hosts.
```

##### Créer les _usergroup_

```bash
config> usergroup create --name foo
config> usergroup create --name bar
```

Vérification :

```bash
config> usergroup ls
  ID |   NAME   | USERS | ACLS |    UPDATE     |    CREATE     |       COMMENT
-----+----------+-------+------+---------------+---------------+-----------------------
   3 | bar      |     1 |    0 | 6 seconds ago | 6 seconds ago |
   2 | foo      |     1 |    0 | 9 seconds ago | 9 seconds ago |
   1 | default  |     1 |    1 | 5 minutes ago | 5 minutes ago | created by sshportal
Total: 3 user groups.
```

##### Créer les _utilisateurs_

> Il faut 'inviter' les utilisateurs à rejoindre notre instance de SSHPortal, via la commande suivante :

```bash
config> user invite --name="John Doe" --group foo john.doe@domain.com
User 2 created.
```

En retour, SSHPortal va nous fournir un token à utiliser à la première connexion :

```bash
To associate this account with a key, use the following SSH user: 'invite:XXXXXXXX'.
```

Se connecter ensuite une première fois:

```bash
~ ssh <HOST> -i my-ssh-key -p 2222 -l invite:XXXXXXX
The authenticity of host '[<HOST>]:2222 ([<HOST>]:2222)' can't be established.
ED25519 key fingerprint is SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX..
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '[<HOST>]:2222' (ED25519) to the list of known hosts.
Welcome Jon Doe!

Your key is now associated with the user "john.doe@domain.com".
Connection to <HOST> closed.
```

Cela aura alors pour conséquence de copier la clé SSH publique sur le compte SSHPortal associé.

##### Gérer les _clés SSH_

Il est également possible d'ajouter une clé SSH directement à l'utilisateur:

```bash
config> userkey create john.doe@domain.com
```

Nous pouvons ensuite avoir la liste de toutes les clés:

```bash
config> userkey ls
  ID |         USER        |   UPDATED   |   CREATED   |       COMMENT
-----+---------------------+-------------+-------------+-----------------------
   2 | john.doe@domain.com | 1 hour ago  | 1 hour ago  |
   1 | admin@localhost     | 2 hours ago | 2 hours ago | created by sshportal
Total: 2 userkeys.
```

##### Passer un utilisateur en admin

Il faut commencer par récupérer la liste des utilisateurs et leur id :

```bash
config> user ls
  ID |   NAME   |        EMAIL        | ROLES | KEYS |             GROUPS             |    UPDATED     |    CREATED     |       COMMENT
-----+----------+---------------------+-------+------+--------------------------------+----------------+----------------+-----------------------
   2 | John Doe | john.doe@domain.com |       |    0 | default                        | 4 seconds ago  | 3 minutes ago  |
   1 | admin    | admin@localhost     | admin |    1 | default                        | 5 minutes ago  | 46 minutes ago | created by sshportal
```

Nous pouvons maintenant mettre à jour l'utilisateur et le passer en administrateur :

```
config> user update --email john.doe@domain.com --assign-role admin 2
```

Vérification :

```bash
config> user ls
  ID |   NAME   |        EMAIL        | ROLES | KEYS |             GROUPS             |    UPDATED     |    CREATED     |       COMMENT
-----+----------+---------------------+-------+------+--------------------------------+----------------+----------------+-----------------------
   2 | John Doe | john.doe@domain.com | admin |    0 | default                        | 9 seconds ago  | 3 minutes ago  |
   1 | admin    | admin@localhost     | admin |    1 | default                        | 5 minutes ago  | 46 minutes ago | created by sshportal
```

##### Création des ACL

_SSHPortal_ permet de gérer finement les accès à chaque host en fonction d'un utilisateur, ou d'un groupe d'utilisateur.

Pour créer une ACL qui permettra à un groupe d'utilisateur de se connecter à un groupe d'hôte :

```bash
config> acl create --usergroup foo --hostgroup prod --action allow
config> acl create --usergroup foo --hostgroup preprod --action allow
```

Vérification :

```bash
config> acl ls
  ID | WEIGHT | USER GROUPS | HOST GROUPS | HOST PATTERN | ACTION | INCEPTION | EXPIRATION |    UPDATED    |    CREATED    |       COMMENT
-----+--------+-------------+-------------+--------------+--------+-----------+------------+---------------+---------------+-----------------------
   3 |      0 | foo         | preprod     |              | allow  |           |            | 4 minutes ago | 4 minutes ago |
   2 |      0 | foo         | prod        |              | allow  |           |            | 4 minutes ago | 4 minutes ago |
   1 |      0 | default     | default     |              | allow  |           |            | 1 hour ago    | 1 hour ago    | created by sshportal
Total: 3 ACLs.
```

#### Préparation des hosts

Pour se connecter aux hosts "finaux", il convient de copier la clé SSH de SSHPortal sur le compte _unix_ de votre choix sur chaque host.

1. on peut ensuite inspecter la clé 

```bash
config> key show my-project
General
=======
Name: my-project
Type: ed25519
Length: 1
Comment:

Relationships
=============
Linked hosts:  (0)

Crypto
======
authorized_key format: ssh-ed25519 XXXXXXXXX
Private Key:
-----BEGIN PRIVATE KEY-----
XXXXXXXXXXXXXXXXXXXXXXXXXXX
-----END PRIVATE KEY-----


Help
====
inspect: ssh sshportal key inspect my-project
setup: ssh user@example.com "$(ssh sshportal key setup my-project)"
```

2. il faut ensuite récupérer la clé

```bash
config> key setup my-project
umask 077; mkdir -p .ssh; echo ssh-ed25519 XXXXXXXXXXXXXXXX  sshportal >> .ssh/authorized_keys
```

3. se connecter sur chaque host et ajouter la clé SSH précédemment récupérée:

```bash
~ ssh <host>
~ sudo su -
~ umask 077; mkdir -p .ssh; echo ssh-ed25519 XXXXXXXXXXXXXXXX  sshportal >> .ssh/authorized_keys
```

4. si besoin, adapter la conf de SSH `/etc/ssh/sshd_config`

```bash
Match Address 1.2.3.4/24
  PermitRootLogin without-password
Match User root
  AllowTcpForwarding yes

AllowUsers      root (ne pas effacer les autres entrées !)
```

```bash
~ systemctl reload sshd.service
```

#### Utilisation de SSHPortal

Pour se connecter aux hosts via SSHPortal, il suffit de faire :

```bash
~ ssh -i my-sshportal-key -p 2222 <HOST> -l <HOST>
```

A noter qu'il serait possible de rajouter une configuration dans votre fichier ".ssh/config" pour faciler les choses :

```bash
Host portal
Port 2222
Hostname <HOST>
IdentityFile my-sshportal-key
```

Couplé à un _alias_ dans votre `.bashrc` :

```bash
alias sshportal="sshportal portal -l $1"
```

Cela vous permettra d'utiliser SSHPortal ainsi :

```bash
~ portal <host>
```

#### Sauvegarde

Il existe deux méthodes de sauvegardes de SSHPortal:

1. Exporter la configuration au format JSON

```bash
ssh <HOST> -i ed25519_sshportal_admin -p 2222 config backup > sshportal.config.<DATE>.json
```

2. Dump la base de données sqlite3 (si configuration par défaut)

```bash
sqlite3 /var/lib/docker/volumes/sshportal__var_lib_sshportal/_data/sshportal.db .dump > sshportal.sqlite3.<DATE>.db
```

#### Référence

https://github.com/moul/sshportal

https://hub.docker.com/r/moul/sshportal