Skip to content

Commit

Permalink
fix: documentation + other install stuff
Browse files Browse the repository at this point in the history
  • Loading branch information
@libvoid
libvoid committed Sep 1, 2023
1 parent f94cbd5 commit 9f1fb94
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 115 deletions.
Binary file modified .assets/bastion.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
172 changes: 64 additions & 108 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
<div align="center">
<img src="https://raw.githubusercontent.com/alterway/sshportal/master/.assets/bastion.jpg" width="35%">
</div>

# sshportal

[![Go Report Card](https://goreportcard.com/badge/moul.io/sshportal)](https://goreportcard.com/report/moul.io/sshportal)
[![License](https://img.shields.io/github/license/alterway/sshportal.svg)](https://github.com/alterway/sshportal/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/v/release/alterway/sshportal.svg)](https://github.com/alterway/sshportal/releases)

Jump host/Jump server without the jump, a.k.a Transparent SSH bastion

## IMPORTANT NOTE

**The [original project](https://github.com/moul/sshportal) is no longer being maintained. This fork includes important security fixes, some bugfixes and features but it is on MAINTENANCE mode and only security issues and major bugs will be fixed. You should consider using [Teleport](https://github.com/gravitational/teleport) instead.**

<p align="center">
<img src="https://raw.githubusercontent.com/alterway/sshportal/master/.assets/bastion.jpg" width="45%">
</p>
---



![Flow Diagram](https://raw.githubusercontent.com/alterway/sshportal/master/.assets/flow-diagram.png)

Expand All @@ -36,43 +38,60 @@ Jump host/Jump server without the jump, a.k.a Transparent SSH bastion

---

## Installation and usage
## Installation

Packaged installation (`.deb` & `.rpm`) is privileged as it comes with a hardened systemd service and a SELinux module if you have enfored SELinux on your GNU/Linux distribution.

Packaged installation is privileged as it comes with a hardened systemd service config.
Get the latest version [here](https://github.com/alterway/sshportal/releases)

### Debian-based distributions
**Note :** By default, your package manager will automatically install `sqlite` (recommended dependency)

1) Get the latest version from https://github.com/alterway/sshportal/releases
This installation will install sshportal as a systemd service, configure logrotate to keep 1 year of audit logs and add a dedicated cron for session logs. See [`packaging`](https://github.com/alterway/sshportal/tree/master/packaging).

If mariadb is selected during the install, it will also automatically create the `sshportal` database if it doesn't exist.

<details>
<summary>Show Debian-based distributions instructions</summary>

```bash
apt install ./sshportal.deb
apt install ./sshportal_x.x.x_xxx.deb
```
You will be asked if you want to use `mariadb` instead of `sqlite` (default). Make sure to install `mariadb-server` before as the package is not listed as a hard dependency in the [control file](https://github.com/alterway/sshportal/blob/debian/.goreleaser.yml#L31).

This will install sshportal as a systemd service, configure logrotate to keep 1 year of audit logs and add a dedicated cron for session logs. See [`packaging`](https://github.com/alterway/sshportal/tree/master/packaging).
One liner non-interactive install with mariadb :

```bash
DEBIAN_FRONTEND=noninteractive SSHPORTAL_MARIADB_SETUP=true apt install --no-install-recommends -y mariadb-server ./sshportal_x.x.x_xxx.deb
```

2) Get the invite token
If you want to stick with sqlite, you just have to do this :

```bash
cat /var/log/sshportal/audit/audit.log
DEBIAN_FRONTEND=noninteractive apt install -y ./sshportal_x.x.x_xxx.deb
```

3) Make sure you have a ssh key pair and associate your public key to the bastion
</details>

```bash
ssh localhost -p 2222 -l invite:xxxxxxx
<details>
<summary>Show RedHat-based distributions instructions</summary>

Welcome sshportal!

Your key is now associated with the user "sshportal@localhost".
Make sure to install `mariadb-server` before if you want to use it as this package is not listed as a hard dependency in the [control file](https://github.com/alterway/sshportal/blob/debian/.goreleaser.yml#L31).

There is no debconf in RedHat distribution so if you want an automatic mariadb setup you need to install `sshportal` with :

```bash
SSHPORTAL_MARIADB_SETUP=true dnf install --setopt=install_weak_deps=False -y mariadb-server ./sshportal_x.x.x_xxx.rpm
```

4) Your first user is the admin. To access to the console, connect like a normal server
If you want to stick with sqlite, you just have to do this :

```bash
ssh sshportal@localhost -p 2222
dnf install -y ./sshportal_x.x.x_xxx.rpm
```

</details>

### Docker

An [automated build is setup on the Github registry](https://github.com/alterway/sshportal/pkgs/container/sshportal).
Expand All @@ -88,6 +107,28 @@ docker logs -f sshportal

### Quick start

Get the invite token in stdout or in the sshportal audit log if installed from a package manager :

```bash
cat /var/log/sshportal/audit/audit.log
```

3) Make sure you have a ssh key pair and associate your public key to the bastion

```bash
ssh localhost -p 2222 -l invite:xxxxxxx

Welcome sshportal!

Your key is now associated with the user "sshportal@localhost".
```

4) Your first user is the admin. To access to the console, connect like a normal server

```bash
ssh sshportal@localhost -p 2222
```

Create your first host

```console
Expand Down Expand Up @@ -237,78 +278,7 @@ You can enter in interactive mode using this syntax: `ssh root@portal.example.or

## Shell commands

```sh
# acl management
acl help
acl create [-h] [--hostgroup=HOSTGROUP...] [--usergroup=USERGROUP...] [--pattern=<value>] [--comment=<value>] [--action=<value>] [--weight=value]
acl inspect [-h] ACL...
acl ls [-h] [--latest] [--quiet]
acl rm [-h] ACL...
acl update [-h] [--comment=<value>] [--action=<value>] [--weight=<value>] [--assign-hostgroup=HOSTGROUP...] [--unassign-hostgroup=HOSTGROUP...] [--assign-usergroup=USERGROUP...] [--unassign-usergroup=USERGROUP...] ACL...

# config management
config help
config backup [-h] [--indent] [--decrypt]
config restore [-h] [--confirm] [--decrypt]

# event management
event help
event ls [-h] [--latest] [--quiet]
event inspect [-h] EVENT...

# host management
host help
host create [-h] [--name=<value>] [--password=<value>] [--comment=<value>] [--key=KEY] [--group=HOSTGROUP...] [--hop=HOST] [--logging=MODE] <username>[:<password>]@<host>[:<port>]
host inspect [-h] [--decrypt] HOST...
host ls [-h] [--latest] [--quiet]
host rm [-h] HOST...
host update [-h] [--name=<value>] [--comment=<value>] [--key=KEY] [--assign-group=HOSTGROUP...] [--unassign-group=HOSTGROUP...] [--logging-MODE] [--set-hop=HOST] [--unset-hop] [--reset] HOST...

# hostgroup management
hostgroup help
hostgroup create [-h] [--name=<value>] [--comment=<value>]
hostgroup inspect [-h] HOSTGROUP...
hostgroup ls [-h] [--latest] [--quiet]
hostgroup rm [-h] HOSTGROUP...

# key management
key help
key create [-h] [--name=<value>] [--type=<value>] [--length=<value>] [--comment=<value>]
key import [-h] [--name=<value>] [--comment=<value>]
key inspect [-h] [--decrypt] KEY...
key ls [-h] [--latest] [--quiet]
key rm [-h] KEY...
key setup [-h] KEY
key show [-h] KEY

# session management
session help
session ls [-h] [--latest] [--quiet]
session inspect [-h] SESSION...

# user management
user help
user invite [-h] [--name=<value>] [--comment=<value>] [--group=USERGROUP...] <email>
user inspect [-h] USER...
user ls [-h] [--latest] [--quiet]
user rm [-h] USER...
user kick [-h] USER
user ban [-h] USER
user update [-h] [--name=<value>] [--email=<value>] [--set-admin] [--unset-admin] [--assign-group=USERGROUP...] [--unassign-group=USERGROUP...] USER...

# usergroup management
usergroup help
usergroup create [-h] [--name=<value>] [--comment=<value>]
usergroup inspect [-h] USERGROUP...
usergroup ls [-h] [--latest] [--quiet]
usergroup rm [-h] USERGROUP...

# other
exit [-h]
help, h
info [-h]
version [-h]
```
See [Documentation](https://github.com/alterway/sshportal/wiki/Documentation)

---

Expand Down Expand Up @@ -351,7 +321,7 @@ Edit your `~/.ssh/config` file (create it first if needed)

```ini
Host portal
User root # or 'sshportal' if you use the packaged binary
User root # or 'sshportal' if you use the packaged sshportal
Port 2222 # portal port
HostName 127.0.0.1 # portal hostname
```
Expand All @@ -370,20 +340,6 @@ ssh localhost -p 2222 -l hostname

---

## Scaling

`sshportal` is stateless but relies on a database to store configuration and logs.

By default, `sshportal` uses a local [sqlite](https://www.sqlite.org/) database which isn't scalable by design.

You can run multiple instances of `sshportal` sharing the same [MySQL](https://www.mysql.com) database, using `sshportal --db-conn=user:pass@host/dbname?parseTime=true --db-driver=mysql`.

![sshportal cluster with MySQL backend](https://raw.github.com/alterway/sshportal/master/.assets/cluster-mysql.png)

See [examples/mysql](http://github.com/alterway/sshportal/tree/master/examples/mysql).

---

## Under the hood

* Docker first (used in dev, tests, by the CI and in production)
Expand Down
13 changes: 10 additions & 3 deletions packaging/postinstall.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,21 @@ if [ -f /tmp/sshportal_mariadb ]; then
SOCKET="$(mysqladmin variables | grep ".sock " | awk '{print $4}')"
readonly SOCKET

tee /etc/systemd/system/sshportal.service.d/mariadb.conf >/dev/null 2>&1 << END
tee /etc/systemd/system/sshportal.service.d/user_env.conf >/dev/null 2>&1 << END
[Service]
StateDirectory=
Environment=SSHPORTAL_DB_DRIVER=mysql
Environment=SSHPORTAL_LOGS_LOCATION=/var/log/sshportal/session
Environment=SSHPORTAL_DATABASE_URL=sshportal@unix($SOCKET)/sshportal?charset=utf8&parseTime=true&loc=Local
END
rm -f /tmp/sshportal_mariadb
else

tee /etc/systemd/system/sshportal.service.d/custom_db.conf >/dev/null 2>&1 << END
[Service]
Environment=SSHPORTAL_DB_DRIVER=sqlite3
Environment=SSHPORTAL_DATABASE_URL=/var/lib/sshportal/sshportal.db
END

fi

if command -v selinuxenabled >/dev/null 2>&1; then
Expand All @@ -25,7 +32,7 @@ fi
mkdir -p /var/log/sshportal/audit
systemctl daemon-reload

# LogsDirectory, StateDirectory & ConfigurationDirectory are created by systemd
# LogsDirectory, StateDirectory are created by systemd
if command -v selinuxenabled >/dev/null 2>&1; then
systemctl enable --now sshportal >/dev/null 2>&1 # this will fail because of SELinux on first install
restorecon -F -R /var/log/sshportal
Expand Down
12 changes: 8 additions & 4 deletions packaging/preinstall.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

MARIADB_INSTALLED="false"
RET="false"
readonly BYELLOW='\033[1;33m'
readonly BRED='\033[1;31m'
readonly NC='\033[0m'

if grep -q "fedora" /etc/os-release; then
[ "$1" -ne 1 ] && exit 0 # run this script only on install
Expand All @@ -20,14 +23,15 @@ if grep -q "debian" /etc/os-release; then
db_get sshportal_mariadb_database
fi

if [ "$RET" = "true" ] || [ "$ENV_SETUP_MYSQL" = "true" ]; then
if [ "$RET" = "true" ] || [ "$SSHPORTAL_MARIADB_SETUP" = "true" ]; then

if [ "$MARIADB_INSTALLED" = "false" ]; then
echo "ERROR: Mariadb is not installed"
exit 1
printf "${BRED}%s %s${NC}\n" "ERROR: Please install mariadb-server if you don't want to use Sqlite"
exit 2
fi

useradd -rd /nonexistent -s /usr/sbin/nologin sshportal # can't use systemd dynamic user to access the unix socket
mariadb -e "CREATE DATABASE sshportal CHARACTER SET utf8;"
mariadb -e "CREATE DATABASE sshportal CHARACTER SET utf8;" || printf "${BYELLOW}%s %s${NC}\n" "WARNING: sshportal database already exists"
mariadb -e "GRANT ALL on sshportal.* to 'sshportal'@'localhost' identified via unix_socket;"

if grep -q "Debian" /etc/os-release; then
Expand Down

0 comments on commit 9f1fb94

Please sign in to comment.