From fd5b50fc08a141e40c3365d8403cade4858d1cbe Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Sat, 15 Dec 2018 21:41:58 -0700 Subject: [PATCH] Various doc updates --- docs/installation/install-script.md | 12 +++--- docs/messageareas/message-networks.md | 57 ++++++++++++++++++++----- docs/troubleshooting/monitoring-logs.md | 30 +++++++++++++ 3 files changed, 84 insertions(+), 15 deletions(-) diff --git a/docs/installation/install-script.md b/docs/installation/install-script.md index 6481360e..61930c93 100644 --- a/docs/installation/install-script.md +++ b/docs/installation/install-script.md @@ -2,15 +2,17 @@ layout: page title: Install Script --- -Under most Linux/UNIX like environments (Linux, BSD, OS X, ...) new users can simply execute the -`install.sh` script to get everything up and running. Cut + paste the following into your terminal: +## Install Script +Under most Linux/UNIX like environments (Linux, BSD, OS X, ...) new users can simply execute the `install.sh` script to get everything up and running. Cut + paste the following into your terminal: ``` curl -o- https://raw.githubusercontent.com/NuSkooler/enigma-bbs/0.0.9-alpha/misc/install.sh | bash ``` -It is recommended you review the [installation script](https://raw.githubusercontent.com/NuSkooler/enigma-bbs/0.0.9-alpha/misc/install.sh) +You may review the [installation script](https://raw.githubusercontent.com/NuSkooler/enigma-bbs/0.0.9-alpha/misc/install.sh) on GitHub before running it. -The script will install nvm, Node.js 6 and grab the latest ENiGMA BBS from GitHub. It will also guide you -through creating a basic configuration file, and recommend some packages to install. +The script will install nvm, Node.js 6 and grab the latest ENiGMA BBS from GitHub. It will also guide you through creating a basic configuration file, and recommend some packages to install. + +After installing, see [Updating](/docs/admin/updating.md). + diff --git a/docs/messageareas/message-networks.md b/docs/messageareas/message-networks.md index 84b7859e..5838da53 100644 --- a/docs/messageareas/message-networks.md +++ b/docs/messageareas/message-networks.md @@ -2,41 +2,44 @@ layout: page title: Message Networks --- +## Message Networks ENiGMA½ considers all non-ENiGMA½, non-local messages (and their networks, such as FTN "external". That is, messages are only imported and exported from/to such a networks. Configuring such external message networks in ENiGMA½ requires three sections in your `config.hjson`. 1. `messageNetworks..networks`: declares available networks. 2. `messageNetworks..areas`: establishes local area mappings and per-area specifics. 3. `scannerTossers.`: general configuration for the scanner/tosser (import/export). This is also where we configure per-node settings. -## FTN Networks +### FTN Networks FidoNet and FidoNet style (FTN) networks as well as a [FTN/BSO scanner/tosser](bso-import-export.md) (`ftn_bso` module) are configured via the `messageNetworks.ftn` and `scannerTossers.ftn_bso` blocks in `config.hjson`. -:information_source: ENiGMA½'s `ftn_bso` module is not a mailer and **makes no attempts** to perfrom packet transport! An external utility such as Binkd is required for this! +:information_source: ENiGMA½'s `ftn_bso` module is **not a mailer** and makes **no attempts** to perform packet transport! An external utility such as Binkd is required for this! -### Networks -The `networks` block a per-network configuration where each entry's key may be referenced elswhere in `config.hjson`. +#### Networks +The `networks` block a per-network configuration where each entry's key may be referenced elsewhere in `config.hjson`. -Example: the following example declares two networks: `agoranet` and `fsxnet`: +Example: the following example declares two networks: `araknet` and `fsxnet`: ```hjson { messageNetworks: { ftn: { networks: { - araknet: { - defaultZone: 10 - localAddress: "10:101/9" - } + // it is recommended to use lowercase network tags fsxnet: { defaultZone: 21 localAddress: "21:1/121" } + + araknet: { + defaultZone: 10 + localAddress: "10:101/9" + } } } } } ``` -### Areas +#### Areas The `areas` section describes a mapping of local **area tags** configured in your `messageConferences` (see [Configuring a Message Area](configuring-a-message-area.md)) to a message network (described above), a FTN specific area tag, and remote uplink address(s). This section can be thought of similar to the *AREAS.BBS* file used by other BBS packages. When ENiGMA½ imports messages, they will be placed in the local area that matches key under `areas` while exported messages will be sent to the relevant `network`. @@ -53,6 +56,7 @@ Example: messageNetworks: { ftn: { areas: { + // it is recommended to use lowercase area tags fsx_general: // *local* tag found within messageConferences network: fsxnet // that we are mapping to this network tag: FSX_GEN // ...and this remote FTN-specific tag @@ -64,5 +68,38 @@ Example: } ``` +:information_source: You can import `AREAS.BBS` or FTN style `.NA` files using [oputil](/docs/admin/oputil.md)! + +### A More Complete Example +Below is a more complete *example* illustrating some of the concepts above: + +```hjson +{ + messageNetworks: { + ftn: { + networks: { + fsxnet: { + defaultZone: 21 + localAddress: "21:1/121" + } + } + + areas: { + fsx_general: { + network: fsxnet + + // ie as found in your info packs .NA file + tag: FSX_GEN + + uplinks: [ "21:1/100" ] + } + } + } + } +} +``` + +:information_source: Remember for a complete FTN experience, you'll probably also want to configure [FTN/BSO scanner/tosser](bso-import-export.md) settings. + ### FTN/BSO Scanner Tosser Please see the [FTN/BSO Scanner/Tosser](bso-import-export.md) documentation for information on this area. diff --git a/docs/troubleshooting/monitoring-logs.md b/docs/troubleshooting/monitoring-logs.md index dd665f5c..28a3773a 100644 --- a/docs/troubleshooting/monitoring-logs.md +++ b/docs/troubleshooting/monitoring-logs.md @@ -2,6 +2,7 @@ layout: page title: Monitoring Logs --- +## Monitoring Logs ENiGMA½ does not produce much to stdout. Logs are produced by Bunyan which outputs each entry as a JSON object. Start by installing bunyan and making it available on your path: @@ -20,3 +21,32 @@ To tail logs in a colorized and pretty format, issue the following command: tail -F /path/to/enigma-bbs/logs/enigma-bbs.log | bunyan ``` +See `bunyan --help` for more information on what you can do! + +### Example +Logs _without_ Bunyan: +```bash +tail -F /path/to/enigma-bbs/logs/enigma-bbs.log +{"name":"ENiGMA½ BBS","hostname":"nu-dev","pid":25002,"level":30,"eventName":"updateFileAreaStats","action":{"type":"method","location":"core/file_base_area.js","what":"updateAreaStatsScheduledEvent","args":[]},"reason":"Schedule","msg":"Executing scheduled event action...","time":"2018-12-15T16:00:00.001Z","v":0} +{"name":"ENiGMA½ BBS","hostname":"nu-dev","pid":25002,"level":30,"module":"FTN BSO","msg":"Performing scheduled message import/toss...","time":"2018-12-15T16:00:00.002Z","v":0} +{"name":"ENiGMA½ BBS","hostname":"nu-dev","pid":25002,"level":30,"module":"FTN BSO","msg":"Performing scheduled message import/toss...","time":"2018-12-15T16:30:00.008Z","v":0} +``` + +Oof! + +Logs _with_ Bunyan: +```bash +tail -F /path/to/enigma-bbs/logs/enigma-bbs.log | bunyan +[2018-12-15T16:00:00.001Z] INFO: ENiGMA½ BBS/25002 on nu-dev: Executing scheduled event action... (eventName=updateFileAreaStats, reason=Schedule) + action: { + "type": "method", + "location": "core/file_base_area.js", + "what": "updateAreaStatsScheduledEvent", + "args": [] + } +[2018-12-15T16:00:00.002Z] INFO: ENiGMA½ BBS/25002 on nu-dev: Performing scheduled message import/toss... (module="FTN BSO") +[2018-12-15T16:30:00.008Z] INFO: ENiGMA½ BBS/25002 on nu-dev: Performing scheduled message import/toss... (module="FTN BSO") +``` + +Much better! +