crichardson/enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated the SSH version, config, and documentation

Browse Source
This commit is contained in:
Nathan Byrd
2023-10-11 00:19:43 +00:00
parent db8bd2f80f
commit f5b0a8bb60
9 changed files with 277 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/Gemfile.lock
View File

@@ -77,6 +77,8 @@ GEM
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.4.0)
minitest (5.19.0)
nokogiri (1.15.4-aarch64-linux)
racc (~> 1.4)
nokogiri (1.15.4-x86_64-linux)
racc (~> 1.4)
pathutil (0.16.2)
@@ -101,6 +103,7 @@ GEM
webrick (1.8.1)
PLATFORMS
aarch64-linux
x86_64-linux
DEPENDENCIES

1
docs/_config.yml
View File

@@ -131,4 +131,5 @@ collections:
- admin/oputil.md
- admin/updating.md
- troubleshooting/monitoring-logs.md
- troubleshooting/ssh-troubleshooting.md

81
docs/_docs/servers/loginservers/ssh.md
View File

@@ -3,9 +3,13 @@ layout: page
title: SSH Server
---
## SSH Login Server
The ENiGMA½ SSH *login server* allows secure user logins over SSH (ssh://).
*Note:* If you run into any troubles during SSH setup, please see [Troubleshooting SSH](../../troubleshooting/ssh-troubleshooting.md)
## Configuration
Entries available under `config.loginServers.ssh`:
| Item | Required | Description |
@@ -20,10 +24,8 @@ Entries available under `config.loginServers.ssh`:
| `algorithms` | :-1: | Configuration block for SSH algorithms. Includes keys of `kex`, `cipher`, `hmac`, and `compress`. See the algorithms section in the [ssh2-streams](https://github.com/mscdex/ssh2-streams#ssh2stream-methods) documentation for details. For defaults set by ENiGMA½, see `core/config_default.js`.
| `traceConnections` | :-1: | Set to `true` to enable full trace-level information on SSH connections.
* *IMPORTANT* With the `privateKeyPass` option set, make sure that you verify that the config file is not readable by other users!
### Example Configuration
```hjson
@@ -40,43 +42,94 @@ Entries available under `config.loginServers.ssh`:
```
## Generate a SSH Private Key
To utilize the SSH server, an SSH Private Key (PK) will need generated. OpenSSH or (with some versions) OpenSSL can be used for this task:
### OpenSSH
### OpenSSH (Preferred)
```bash
ssh-keygen -m PEM -h -f config/ssh_private_key.pem
#### OpenSSH Install - Linux / Mac
If it is not already available, install OpenSSH using the package manager of your choice (should be pre-installed on most distributions.)
#### Running OpenSSH - Linux / Mac
From the root directory of the Enigma BBS, run the following:
```shell
mkdir -p config/security
ssh-keygen -t rsa -m PEM -h -f config/security/ssh_private_key.pem
```
#### Windows Install - OpenSSH
OpenSSH may already be installed, try running `ssh-keygen.exe`. If not, see this page: [Install OpenSSH for Windows](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui)
#### Running OpenSSH - Windows
After installation, go to the root directory of your enigma project and run:
```powershell
mkdir .\config\security -ErrorAction SilentlyContinue
ssh-keygen.exe -t rsa -m PEM -h -f .\config\security\ssh_private_key.pem
```
#### ssh-keygen options
Option descriptions:
| Option | Description |
|------|-------------|
| `-t rsa` | Use the RSA algorithm needed for the `ssh2` library |
| `-m PEM` | Set the output format to `PEM`, compatible with the `ssh2` library |
| `-h` | Generate a host key |
| `-f config/ssh_private_key.pem` | Filename for the private key. Used in the `privateKeyPem` option in the configuration |
When you execute the `ssh-keygen` command it will ask for a passphrase (and a confirmation.) This should then be used as the value for `privateKeyPass` in the configuration.
### OpenSSL
If you do not have OpenSSH installed or if you have trouble with the above OpenSSH commands, using some versions for OpenSSL (before version 3) the following commands may work as well:
#### Open SSL Install - Linux / Mac
If not already installed, install via the `openssl` package on most package managers.
```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 | openssl rsa -out ./config/ssh_private_key.pem -aes128
#### Open SSL Install - Windows
```powershell
winget install -e --id ShiningLight.OpenSSL
```
Or for even older OpenSSL versions:
#### Running OpenSSL
```bash
*Note:* Using `ssh-keygen` from OpenSSL is recommended where possible. If you have trouble with the above OpenSSH commands, using some versions for OpenSSL (before version 3) the following commands may work as well:
#### Running OpenSSL - Linux / Mac
Run the following from the root directory of Enigma
```shell
mkdir -p config/security
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 | openssl rsa -out ./config/security/ssh_private_key.pem -aes128
```
#### Running OpenSSL - Windows
Run the following from the root directory of Enigma (note: you may need to specify the full path to openssl.exe if it isn't in your system path, on my system it was `C:\Program Files\OpenSSL-Win64\bin\openssl.exe`):
```powershell
mkdir .\config\security -ErrorAction SilentlyContinue
openssl.exe genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 | openssl.exe rsa -out ./config/security/ssh_private_key.pem -aes128
```
#### Running Older OpenSSL
For older OpenSSL versions, the following command has been known to work:
```shell
openssl genrsa -aes128 -out ./config/ssh_private_key.pem 2048
```
Note that you may need `-3des` for very old implementations or SSH clients!
*Note:* that you may need `-3des` for very old implementations or SSH clients!
## Prompt
The keyboard interactive prompt can be customized using a `SSHPMPT.ASC` art file. See [art](../../art/general.md) for more information on configuring. This prompt includes a `newUserNames` variable to show the list of allowed new user names (see `firstMenuNewUser` above.) See [mci](../../art/mci.md) for information about formatting this string. Note: Regardless of the content of the `SSHPMPT.ASC` file, the prompt is surrounded by "Access denied", a newline, the prompt, another newline, and then the string "\[username]'s password: ". This normally occurs after the first password prompt (no art is shown before the first password attempt is made.)
The keyboard interactive prompt can be customized using a `SSHPMPT.ASC` art file. See [art](../../art/general.md) for more information on configuring. This prompt includes a `newUserNames` variable to show the list of allowed new user names (see `firstMenuNewUser` above.) See [mci](../../art/mci.md) for information about formatting this string. Note: Regardless of the content of the `SSHPMPT.ASC` file, the prompt is surrounded by "Access denied", a newline, the prompt, another newline, and then the string "\[username]'s password: ". This normally occurs after the first password prompt (no art is shown before the first password attempt is made.)

41
docs/_docs/troubleshooting/ssh-troubleshooting.md Normal file
View File

@@ -0,0 +1,41 @@
---
layout: page
title: Troubleshooting SSH
---
Stuck with errors trying to get your SSH setup configured? See below for some common problems. Or as always, reach out to us by creating an [Issue](https://github.com/NuSkooler/enigma-bbs/issues) or start a [Discussion](https://github.com/NuSkooler/enigma-bbs/discussions)
## No Such File or Directory
***Symptom:***
BBS not starting with an error similar to the following:
```shell
Error initializing: Error: ENOENT: no such file or directory, open '<path>/config/security/ssh_private_key.pem'
```
***Solution:***
Several things can cause this:
1. `ssh_private_key.pem` was installed to the wrong location. Make sure that it is in the `config/security` directory and has the name matching the error message. You can also change your `config.hjson` if you prefer to point to the location of the key file.
2. `ssh_private_key.pem` has the wrong file permissions. Verify that the file will be readable by the user that the BBS is running as. Because it is a cryptographic key however, we do recommend that access is restricted only to that user.
## Error With Netrunner
***Symptom:***
Some ssh clients connect, but Netrunner (and other older clients) get a connection failed message and the following is in the log:
```shell
"level":40,"error":"Handshake failed","code":2,"msg":"SSH connection error"
```
***Solution:***
The key was most likely not generated with the `-t rsa` option, and is using a newer algorithm that is not supported by Netrunner and similar clients. Regenerate the certificate with the `-t rsa` option.
***Symptom:***
Some ssh clients connect, but Netrunner (and other older clients) get a connection failed message and the following is in the log:
```shell
"level":40,"error":"Group exchange not implemented for server","msg":"SSH connection error"
```