From e0f6847581c30fb2e1a922b3e9172aae82eb4396 Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Mon, 17 Dec 2018 11:09:42 -0700 Subject: [PATCH] + NNTP docs + Gopher docs * Minor doc cleanup --- WHATSNEW.md | 2 ++ docs/_includes/nav.md | 2 ++ docs/modding/file-area-list.md | 2 +- docs/servers/gopher.md | 40 +++++++++++++++++++++ docs/servers/nntp.md | 66 ++++++++++++++++++++++++++++++++++ docs/servers/ssh.md | 47 ++++++++++++------------ docs/servers/telnet.md | 30 +++++++++------- docs/servers/websocket.md | 3 ++ 8 files changed, 156 insertions(+), 36 deletions(-) create mode 100644 docs/servers/gopher.md create mode 100644 docs/servers/nntp.md diff --git a/WHATSNEW.md b/WHATSNEW.md index f78bf6c3..d7c26361 100644 --- a/WHATSNEW.md +++ b/WHATSNEW.md @@ -22,6 +22,8 @@ This document attempts to track **major** changes and additions in ENiGMA½. For * `install.sh` will now attempt to use NPM's `--build-from-source` option when ARM is detected. * `oputil.js config new` will now generate a much more complete configuration file with comments, examples, etc. `oputil.js config cat` dumps your current config to stdout. * Handling of failed login attempts is now fully in. Disconnect clients, lock out accounts, ability to auto or unlock at (email-driven) password reset, etc. See `users.failedLogin` in `config.hjson`. +* NNTP support! See [NNTP docs](/docs/servers/nntp.md) for more information. +* `oputil.js user rm` and `oputil.js user info` are in! See [oputil CLI](/docs/admin/oputil.md). ## 0.0.8-alpha diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md index 326ebaad..79ce2f31 100644 --- a/docs/_includes/nav.md +++ b/docs/_includes/nav.md @@ -56,6 +56,8 @@ - Build your own - Content Servers - [Web]({{ site.baseurl }}{% link servers/web-server.md %}) + - [Gopher]({{ site.baseurl }}{% link servers/gopher.md %}) + - [NNTP]({{ site.baseurl }}{% link servers/nntp.md %}) - Modding - [Local Doors]({{ site.baseurl }}{% link modding/local-doors.md %}) diff --git a/docs/modding/file-area-list.md b/docs/modding/file-area-list.md index 735986a0..dcc0b958 100644 --- a/docs/modding/file-area-list.md +++ b/docs/modding/file-area-list.md @@ -6,7 +6,7 @@ title: File Area List The built in `file_area_list` module provides a very flexible file listing UI. ## Configuration -## Config Block +### Config Block Available `config` block entries: * `art`: Sub-configuration block used to establish art files used for file browsing: * `browse`: The main browse screen. diff --git a/docs/servers/gopher.md b/docs/servers/gopher.md new file mode 100644 index 00000000..343c7d80 --- /dev/null +++ b/docs/servers/gopher.md @@ -0,0 +1,40 @@ +--- +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://). + +## Configuration +Gopher configuration is found in `contentServers.gopher` in `config.hjson`. + +| Item | Required | Description | +|------|----------|-------------| +| `enabled` | :+1: | Set to `true` to enable Gopher | +| `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! + +### 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 + + messageConferences: { + fsxnet: { // fsxNet's conf tag + // Areas of fsxNet we want to expose: + "fsx_gen", "fsx_bbs" + } + } + } +} +``` diff --git a/docs/servers/nntp.md b/docs/servers/nntp.md new file mode 100644 index 00000000..c6ceaf2e --- /dev/null +++ b/docs/servers/nntp.md @@ -0,0 +1,66 @@ +--- +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 + } + } +} +``` diff --git a/docs/servers/ssh.md b/docs/servers/ssh.md index 51471e28..a71f8250 100644 --- a/docs/servers/ssh.md +++ b/docs/servers/ssh.md @@ -2,38 +2,41 @@ layout: page title: SSH Server --- -## Generate a SSH Private Key +## SSH Login Server +The ENiGMA½ SSH *login server* allows secure user logins over SSH (ssh://). -To utilize the SSH server, an SSH Private Key will need generated. From the ENiGMA installation directory: +## Configuration +Entries available under `config.loginServers.ssh`: -```bash -openssl genrsa -des3 -out ./config/ssh_private_key.pem 2048 -``` +| 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`. | +| `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.js`. +| `traceConnections` | :-1: | Set to `true` to enable full trace-level information on SSH connections. -You then need to enable the SSH server in your `config.hjson`: +### Example Configuration ```hjson { - loginServers: { - ssh: { + loginServers: { + ssh: { enabled: true - port: 8889 - privateKeyPem: /path/to/ssh_private_key.pem - privateKeyPass: YOUR_PK_PASS + port: 8889 + privateKeyPem: /path/to/ssh_private_key.pem + privateKeyPass: sup3rs3kr3tpa55 } } } ``` -### SSH Server Options +## Generate a SSH Private Key +To utilize the SSH server, an SSH Private Key will need generated. OpenSSL can be used for this task: -| Option | Description -|---------------------|--------------------------------------------------------------------------------------| -| `privateKeyPem` | Path to private key file. -| `privateKeyPass` | Password to private key file. -| `firstMenu` | First menu an SSH connected user is presented with. -| `firstMenuNewUser` | Menu presented to user when logging in with `users::newUserNames` in your config.hjson (defaults to `new` and `apply`). -| `enabled` | Enable/disable SSH server. -| `port` | Configure a custom port for the SSH server. -| `algorithms` | Configuration block for SSH algoritms. Includes arrays with 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.js`. -| `traceConnections` | Set to `true` to enable full trace-level information on SSH connections. +```bash +openssl genrsa -des3 -out ./config/ssh_private_key.pem 2048 +``` diff --git a/docs/servers/telnet.md b/docs/servers/telnet.md index 47aba591..ccefc966 100644 --- a/docs/servers/telnet.md +++ b/docs/servers/telnet.md @@ -2,24 +2,28 @@ layout: page title: Telnet Server --- +## Telnet Login Server +The Telnet *login server* provides a standard **non-secure** Telnet login experience. -Telnet is enabled by default on port `8888` in `config.hjson`: +## Configuration +The following configuration can be made in `config.hjson` under the `loginServers.telnet` block: +| Item | Required | Description | +|------|----------|-------------| +| `enabled` | :-1: Defaults to `true`. Set to `false` to disable Telnet | +| `port` | :-1: | Override the default port of `8888`. | +| `firstMenu` | :-1: | First menu a telnet connected user is presented with. Defaults to `telnetConnected`. | + +### Example Configuration ```hjson { - loginServers: { - telnet: { - enabled: true - port: 8888 - } - } + loginServers: { + telnet: { + enabled: true + port: 8888 + } + } } ``` -### Telnet Server Options -| Option | Description -|---------------------|--------------------------------------------------------------------------------------| -| `firstMenu` | First menu a telnet connected user is presented with -| `enabled` | Enable/disable telnet server -| `port` | Configure a custom port for the telnet server diff --git a/docs/servers/websocket.md b/docs/servers/websocket.md index 18271d6f..98f867e7 100644 --- a/docs/servers/websocket.md +++ b/docs/servers/websocket.md @@ -2,6 +2,9 @@ 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://l33t.codes/vtx/xibalba.html) and [fORCE9](https://bbs.force9.org/vtx/force9.html).