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

Automatically generate the navigation

Browse Source
This commit is contained in:
Nathan Byrd
2022-02-04 08:51:03 -06:00
parent 4793ad0492
commit b5b0cc3ac5
94 changed files with 236 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/_docs/servers/gopher.md Normal file
View File

@@ -0,0 +1,65 @@
---
layout: page
title: Gopher Server
---
## The Gopher Content Server
The Gopher *content server* provides access to publicly exposed message conferences and areas over Gopher (gopher://) as well as any other content you wish to serve in your Gopher Hole!
## Configuration
Gopher configuration is found in `contentServers.gopher` in `config.hjson`.
| Item | Required | Description |
|------|----------|-------------|
| `enabled` | :+1: | Set to `true` to enable Gopher |
| `staticRoot` | :+1: | Sets the path serving as the static root path for all Gopher content. Defaults to `enigma-bbs/gopher`.<br>See also **Gophermap's** below |
| `port` | :-1: | Override the default port of `8070` |
| `publicHostname` | :+1: | Set the **public** hostname/domain that Gopher will serve to the outside world. Example: `myfancybbs.com` |
| `publicPort` | :+1: | Set the **public** port that Gopher will serve to the outside world. |
| `messageConferences` | :-1: | An map of *conference tags* to *area tags* that are publicly exposed via Gopher. See example below. |
Notes on `publicHostname` and `publicPort`:
The Gopher protocol serves content that contains host/domain and port even when referencing it's own documents. Due to this, these members must be set to your publicly addressable Gopher server!
## Gophermap's
[Gophermap's](https://en.wikipedia.org/wiki/Gopher_(protocol)#Source_code_of_a_menu) are how to build menus for your Gopher Hole. Each map is a simple text file named `gophermap` (all lowercase, no extension) with DOS style CRLF endings.
Within any directory nested within your `staticRoot` may live a `gophermap`. A template may be found in the `enigma-bbsmisc` directory.
ENiGMA will pre-process `gophermap` files replacing in following variables:
* `{publicHostname}`: The public hostname from your config.
* `{publicPort}`: The public port from your config.
:information_source: See [Wikipedia](https://en.wikipedia.org/wiki/Gopher_(protocol)#Source_code_of_a_menu) for more information on the `gophermap` format.
:information_source: See [RFC 1436](https://tools.ietf.org/html/rfc1436) for the original Gopher spec.
:bulb: Tools such as [gfu](https://rawtext.club/~sloum/gfu.html) may help you with `gophermap`'s
### Example Gophermap
An example `gophermap` living in `enigma-bbs/gopher`:
```
iWelcome to a Gopher server! {publicHostname} {publicPort}
1Public Message Area /msgarea {publicHostname} {publicPort}
.
```
### Example
Let's suppose you are serving Gopher for your BBS at `myfancybbs.com`. Your ENiGMA½ system is listening on the default Gopher `port` of 8070 but you're behind a firewall and want port 70 exposed to the public. Lastly, you want to expose some fsxNet areas:
```hjson
contentServers: {
gopher: {
enabled: true
publicHostname: myfancybbs.com
publicPort: 70
// Expose some public message conferences/areas
messageConferences: {
fsxnet: { // fsxNet's conf tag
// Areas of fsxNet we want to expose:
"fsx_gen", "fsx_bbs"
}
}
}
}
```

67
docs/_docs/servers/nntp.md Normal file
View File

@@ -0,0 +1,67 @@
---
layout: page
title: NNTP Server
---
## The NNTP Content Server
The NNTP *content server* provides access to publicly exposed message conferences and areas over either **secure** NNTPS (NNTP over TLS or nttps://) and/or non-secure NNTP (nntp://).
## Configuration
| Item | Required | Description |
|------|----------|-------------|
| `nntp` | :-1: | Configuration block for non-secure NNTP. See Non-Secure NNTP Configuration below. |
| `nntps` | :-1: | Configuration block for secure NNTP. See Secure NNTPS Configuration below. |
| `publicMessageConferences` | :+1: | A map of *conference tags* to *area tags* that are publicly exposed over NNTP. Anonymous users will get read-only access to these areas. |
### See Non-Secure NNTP Configuration
Under `contentServers.nntp.nntp` the following configuration is allowed:
| Item | Required | Description |
|------|----------|-------------|
| `enabled` | :+1: | Set to `true` to enable non-secure NNTP access. |
| `port` | :-1: | Override the default port of `8119`. |
### Secure NNTPS Configuration
Under `contentServers.nntp.nntps` the following configuration is allowed:
| Item | Required | Description |
|------|----------|-------------|
| `enabled` | :+1: | Set to `true` to enable secure NNTPS access. |
| `port` | :-1: | Override the default port of `8565`. |
| `certPem` | :-1: | Override the default certificate file path of `./config/nntps_cert.pem` |
| `keyPem` | :-1: | Override the default certificate key file path of `./config/nntps_key.pem` |
#### Certificates and Keys
In order to use secure NNTPS, a TLS certificate and key pair must be provided. You may generate your own but most clients **will not trust** them. A certificate and key from a trusted Certificate Authority is recommended. [Let's Encrypt](https://letsencrypt.org/) provides free TLS certificates. Certificates and private keys must be in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
##### Generating Your Own
An example of generating your own cert/key pair:
```bash
openssl req -newkey rsa:2048 -nodes -keyout ./config/nntps_key.pem -x509 -days 3050 -out ./config/nntps_cert.pem
```
### Example Configuration
```hjson
contentServers: {
nntp: {
publicMessageConferences: {
fsxnet: [
// Expose these areas of fsxNet
"fsx_gen", "fsx_bbs"
]
}
nntp: {
enabled: true
}
nntps: {
enabled: true
// These could point to Let's Encrypt provided pairs for example:
certPem: /path/to/some/tls_cert.pem
keyPem: /path/to/some/tls_private_key.pem
}
}
}
```

52
docs/_docs/servers/ssh.md Normal file
View File

@@ -0,0 +1,52 @@
---
layout: page
title: SSH Server
---
## SSH Login Server
The ENiGMA½ SSH *login server* allows secure user logins over SSH (ssh://).
## Configuration
Entries available under `config.loginServers.ssh`:
| Item | Required | Description |
|------|----------|-------------|
| `privateKeyPem` | :-1: | Path to private key file. If not set, defaults to `./config/ssh_private_key.pem` |
| `privateKeyPass` | :+1: | Password to private key file.
| `firstMenu` | :-1: | First menu an SSH connected user is presented with. Defaults to `sshConnected`. |
| `firstMenuNewUser` | :-1: | Menu presented to user when logging in with one of the usernames found within `users.newUserNames` in your `config.hjson`. Examples include `new` and `apply`. |
| `enabled` | :+1: | Set to `true` to enable the SSH server. |
| `port` | :-1: | Override the default port of `8443`. |
| `address` | :-1: | Sets an explicit bind address. |
| `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.
### Example Configuration
```hjson
{
loginServers: {
ssh: {
enabled: true
port: 8889
privateKeyPem: /path/to/ssh_private_key.pem
privateKeyPass: sup3rs3kr3tpa55
}
}
}
```
## Generate a SSH Private Key
To utilize the SSH server, an SSH Private Key (PK) will need generated. OpenSSL can be used for this task:
### Modern OpenSSL
```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 | openssl rsa -out ./config/ssh_private_key.pem -aes128
```
### Legacy OpenSSL
```bash
openssl genrsa -aes128 -out ./config/ssh_private_key.pem 2048
```
Note that you may need `-3des` for every old implementations or SSH clients!

30
docs/_docs/servers/telnet.md Normal file
View File

@@ -0,0 +1,30 @@
---
layout: page
title: Telnet Server
---
## Telnet Login Server
The Telnet *login server* provides a standard **non-secure** Telnet login experience.
## Configuration
The following configuration can be made in `config.hjson` under the `loginServers.telnet` block:
| Key | Required | Description |
|------|----------|-------------|
| `enabled` | :-1: Defaults to `true`. Set to `false` to disable Telnet |
| `port` | :-1: | Override the default port of `8888`. |
| `address` | :-1: | Sets an explicit bind address. |
| `firstMenu` | :-1: | First menu a telnet connected user is presented with. Defaults to `telnetConnected`. |
### Example Configuration
```hjson
{
loginServers: {
telnet: {
enabled: true
port: 8888
}
}
}
```

72
docs/_docs/servers/web-server.md Normal file
View File

@@ -0,0 +1,72 @@
---
layout: page
title: Web Server
---
ENiGMA½ comes with a built in *content server* for supporting both HTTP and HTTPS. Currently the [File Bases](../modding/file-base-web-download-manager.md) registers routes for file downloads, password reset email links are handled via the server, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!
# Configuration
By default the web server is not enabled. To enable it, you will need to at a minimum configure two keys in the `contentServers.web` section of `config.hjson`:
```hjson
contentServers: {
web: {
domain: bbs.yourdomain.com
http: {
enabled: true
port: 8080
}
}
}
```
The following is a table of all configuration keys available under `contentServers.web`:
| Key | Required | Description |
|------|----------|-------------|
| `domain` | :+1: | Sets the domain, e.g. `bbs.yourdomain.com`. |
| `http` | :-1: | Sub configuration for HTTP (non-secure) connections. See **HTTP Configuration** below. |
| `overrideUrlPrefix` | :-1: | Instructs the system to be explicit when handing out URLs. Useful if your server is behind a transparent proxy. |
### HTTP Configuration
Entries available under `contentServers.web.http`:
| Key | Required | Description |
|------|----------|-------------|
| `enable` | :+1: | Set to `true` to enable this server.
| `port` | :-1: | Override the default port of `8080`. |
| `address` | :-1: | Sets an explicit bind address. |
### HTTPS Configuration
Entries available under `contentServers.web.https`:
| Key | Required | Description |
|------|----------|-------------|
| `enable` | :+1: | Set to `true` to enable this server.
| `port` | :-1: | Override the default port of `8080`. |
| `address` | :-1: | Sets an explicit bind address. |
| `certPem` | :+1: | Overrides the default certificate path of `/config/https_cert.pem`. Certificate must be in PEM format. See **Certificates** below. |
| `keyPem` | :+1: | Overrides the default certificate key path of `/config/https_cert_key.pem`. Key must be in PEM format. See **Certificates** below. |
#### Certificates
If you don't have a TLS certificate for your domain, a good source for a certificate can be [Let's Encrypt](https://letsencrypt.org/) who supplies free and trusted TLS certificates. A common strategy is to place another web server such as [Caddy](https://caddyserver.com/) in front of ENiGMA½ acting as a transparent proxy and TLS termination point.
:information_source: Keep in mind that the SSL certificate provided by Let's Encrypt's Certbot is by default stored in a privileged location; if your ENIGMA instance is not running as root (which it should not be!), you'll need to copy the SSL certificate somewhere else in order for ENIGMA to use it.
## Static Routes
Static files live relative to the `contentServers.web.staticRoot` path which defaults to `enigma-bbs/www`.
`index.html, favicon.ico`, and any error pages like `404.html` are accessible from the route path. Other static assets hosted by the web server must be referenced from `/static/`, for example:
```html
<a href="/static/about.html"> Example Link
```
## Custom Error Pages
Customized error pages can be created for [HTTP error codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) by providing a `<error_code>.html` file in the *static routes* area. For example: `404.html`.

106
docs/_docs/servers/websocket.md Normal file
View File

@@ -0,0 +1,106 @@
---
layout: page
title: Web Socket / Web Interface Server
---
## WebSocket Login Server
The WebSocket Login Server provides **secure** (wss://) as well as non-secure (ws://) WebSocket login access. This is often combined with a browser based WebSocket client such as VTX or fTelnet.
# VTX Web Client
ENiGMA supports the VTX WebSocket client for connecting to your BBS from a web page. Example usage can be found at [Xibalba](https://xibalba.l33t.codes) and [fORCE9](https://bbs.force9.org/vtx/force9.html) amongst others.
## Before You Start
There are a few things out of scope of this document:
- You'll need a web server for hosting the files - this can be anywhere, but it obviously makes sense to host it
somewhere with a hostname relevant to your BBS!
- It's not required, but you should use SSL certificates to secure your website, and for supplying to ENiGMA to
secure the websocket connections. [Let's Encrypt](https://letsencrypt.org/) provide a free well-respected service.
- How you make the websocket service available on the internet is up to you, but it'll likely by forwarding ports on
your router to the box hosting ENiGMA. Use the same method you did for forwarding the telnet port.
## Setup
1. Enable the websocket in ENiGMA, by adding `webSocket` configuration to the `loginServers` block in `config.hjson` (create it if you
don't already have it defined).
````hjson
loginServers: {
webSocket : {
ws: {
// non-secure ws://
port: 8810
enabled: true
// optional bind address
address: 127.0.0.1
}
wss: {
// secure-over-tls wss://
port: 8811
enabled: true
certPem: /path/to/https_cert.pem
keyPem: /path/to/https_cert_key.pem
}
// set proxied to true to allow TLS-terminated proxied connections
// containing the "X-Forwarded-Proto: https" header to be treated
// as secure
proxied: true
}
}
````
2. Restart ENiGMA and check the logs to ensure the websocket service starts successfully, you'll see something like the
following:
````
[2017-10-29T12:13:30.668Z] INFO: ENiGMA½ BBS/30978 on force9: Listening for connections (server="WebSocket (insecure)", port=8810)
[2017-10-29T12:13:30.669Z] INFO: ENiGMA½ BBS/30978 on force9: Listening for connections (server="WebSocket (secure)", port=8811)
````
3. Download the [VTX_ClientServer](https://github.com/codewar65/VTX_ClientServer/archive/master.zip) to your
webserver, and unpack it to a temporary directory.
4. Download the example [VTX client HTML file](https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/vtx/vtx.html) and save it to your webserver root.
5. Create an `assets/vtx` directory within your webserver root, so you have a structure like the following:
````text
├── assets
│   └── vtx
└── vtx.html
````
6. From the VTX_ClientServer package unpacked earlier, copy the contents of the `www` directory into `assets/vtx` directory.
7. Create a vtxdata.js file, and save it to `assets/vtx`:
````javascript
var vtxdata = {
sysName: "Your Awesome BBS",
wsConnect: "wss://your-hostname.here:8811",
term: "ansi-bbs",
codePage: "CP437",
fontName: "UVGA16",
fontSize: "24px",
crtCols: 80,
crtRows: 25,
crtHistory: 500,
xScale: 1,
initStr: "",
defPageAttr: 0x1010,
defCrsrAttr: 0x0207,
defCellAttr: 0x0007,
telnet: 1,
autoConnect: 0
};
````
8. Update `sysName` and `wsConnect` accordingly. Use `wss://` if you set up the websocket service with SSL, `ws://`
otherwise.
9. If you navigate to http://your-hostname.here/vtx.html, you should see a splash screen like the following:
![VTXClient](../assets/images/vtxclient.png "VTXClient")