zydronium/enigma-bbs
1
0
Fork 0
mirror of https://github.com/NuSkooler/enigma-bbs.git synced 2025-08-04 00:41:56 +02:00
Code Issues Projects Releases Packages 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

228
docs/_docs/messageareas/bso-import-export.md Normal file
View file

@ -0,0 +1,228 @@
---
layout: page
title: BSO Import / Export
---
## BSO Import / Export
The scanner/tosser module `ftn_bso` provides **B**inkley **S**tyle **O**utbound (BSO) import/toss and scan/export of messages EchoMail and NetMail messages. Configuration is supplied in `config.hjson` under `scannerTossers.ftn_bso`.
:information_source: ENiGMA½'s `ftn_bso` module is not a mailer and **makes no attempts to perform packet transport**! An external [mailer](http://www.filegate.net/bbsmailers.htm) such as [Binkd](https://github.com/pgul/binkd) is required for this task!
### Configuration
Let's look at some of the basic configuration:
| Config Item | Required | Description |
|-------------|----------|----------------------------------------------------------|
| `schedule` | :+1: | Sets `import` and `export` schedules. [Later style text parsing](https://bunkat.github.io/later/parsers.html#text) supported. `import` also can utilize a `@watch:<path/to/file>` syntax while `export` additionally supports `@immediate`. |
| `packetMsgEncoding` | :-1: | Override default `utf8` encoding.
| `defaultNetwork` | :-1: | Explicitly set default network (by tag found within `messageNetworks.ftn.networks`). If not set, the first found is used. |
| `nodes` | :+1: | Per-node settings. Entries (keys) here support wildcards for a portion of the FTN-style address (e.g.: `21:1/*`). See **Nodes** below.
| `paths` | :-1: | An optional configuration block that can set a additional paths or override defaults. See **Paths** below. |
| `packetTargetByteSize` | :-1: | Overrides the system *target* packet (.pkt) size of 512000 bytes (512k) |
| `bundleTargetByteSize` | :-1: | Overrides the system *target* ArcMail bundle size of 2048000 bytes (2M) |
#### Nodes
The `nodes` section defines how to export messages for one or more uplinks.
A node entry starts with a [FTN address](http://ftsc.org/docs/old/fsp-1028.001) (up to 5D) **as a key** in `config.hjson`. This key may contain wildcard(s) for net/zone/node/point/domain.
| Config Item | Required | Description |
|------------------|----------|---------------------------------------------------------------------------------|
| `packetType` | :-1: | `2`, `2.2`, or `2+`. Defaults to `2+` for modern mailer compatibility. |
| `packetPassword` | :-1: | Optional password for the packet |
| `encoding` | :-1: | Encoding to use for message bodies; Defaults to `utf-8`. |
| `archiveType` | :-1: | Specifies the archive type (by extension or MIME type) for ArcMail bundles. This should be `zip` (or `application/zip`) for most setups. Other valid examples include `arc`, `arj`, `lhz`, `pak`, `sqz`, or `zoo`. See [Archivers](../configuration/archivers.md) for more information. |
**Example**:
```hjson
{
scannerTossers: {
ftn_bso: {
nodes: {
"21:*": { // wildcard address
packetType: 2+
packetPassword: D@TP4SS
encoding: cp437
archiveType: zip
}
}
}
}
}
```
#### Paths
Paths for packet files work out of the box and are relative to your install directory. If you want to configure `reject` or `retain` to keep rejected/imported packet files respectively, set those values. You may override defaults as well.
| Key | Description | Default |
|-----|-------------|---------|
| `outbound` | *Base* path to write outbound (exported) packet files and bundles. | `enigma-bbs/mail/ftn_out/` |
| `inbound` | *Base* path to write inbound (ie: those written by an external mailer) packet files an bundles. | `enigma-bbs/mail/ftn_in/` |
| `secInbound` | *Base* path to write **secure** inbound packet files and bundles. | `enigma-bbs/mail/ftn_secin/` |
| `reject` | Path in which to write rejected packet files. | No default |
| `retain` | Path in which to write imported packet files. Useful for debugging or if you wish to archive the raw .pkt files. | No default |
### Scheduling
Schedules can be defined for importing and exporting via `import` and `export` under `schedule`. Each entry is allowed a "free form" text and/or special indicators for immediate export or watch file triggers.
* `@immediate`: A message will be immediately exported if this trigger is defined in a schedule. Only used for `export`.
* `@watch:/path/to/file`: This trigger watches the path specified for changes and will trigger an import or export when such events occur. Only used for `import`.
* Free form [Later style](https://bunkat.github.io/later/parsers.html#text) text — can be things like `at 5:00 pm` or `every 2 hours`.
See [Later text parsing documentation](http://bunkat.github.io/later/parsers.html#text) for more information.
#### Example Schedule Configuration
```hjson
{
scannerTossers: {
ftn_bso: {
schedule: {
import: every 1 hours or @watch:/path/to/watchfile.ext
export: every 1 hours or @immediate
}
}
}
}
```
### A More Complete Example
Below is a more complete example showing the sections described above.
```hjson
scannerTossers: {
ftn_bso: {
schedule: {
// Check every 30m, or whenever the "toss!.now" file is touched (ie: by Binkd)
import: every 30 minutes or @watch:/enigma-bbs/mail/ftn_in/toss!.now
// Export immediately, but also check every 15m to be sure
export: every 15 minutes or @immediate
}
// optional
paths: {
reject: /path/to/store/bad/packets/
retain: /path/to/store/good/packets/
}
// Override default FTN/BSO packet encoding. Defaults to 'utf8'
packetMsgEncoding: utf8
defaultNetwork: fsxnet
nodes: {
"21:1/100" : { // May also contain wildcards, ie: "21:1/*"
archiveType: ZIP // By-ext archive type: ZIP, ARJ, ..., optional.
encoding: utf8 // Encoding for exported messages
packetPassword: MUHPA55 // FTN .PKT password, optional
tic: {
// See TIC docs
}
}
}
netMail: {
// See NetMail docs
}
ticAreas: {
// See TIC docs
}
}
}
```
## Binkd
Since Binkd is a very common mailer, a few tips on integrating it with ENiGMA½.
### Example Binkd Configuration
Below is an **example** Binkd configuration file that may help serve as a reference.
```bash
# Number @ end is the root zone
# Note that fsxNet is our *default* FTN so we use "outbound" here!
domain fsxnet /home/enigma/enigma-bbs/mail/ftn_out/outbound 21
domain araknet /home/enigma/enigma-bbs/mail/ftn_out/araknet 10
# Our assigned addresses
address 21:1/1234@fsxnet
address 10:101/1234@araknet
# Info about our board/op
sysname "My BBS"
location "Somewhere Out There"
sysop "SysOp"
nodeinfo 115200,TCP,BINKP
try 10
hold 600
send-if-pwd
log /var/log/binkd/binkd.log
loglevel 4
conlog 4
percents
printq
backresolv
inbound /home/enigma/enigma-bbs/mail/ftn_in
temp-inbound /home/enigma/enigma-bbs/mail/ftn_in_temp
minfree 2048
minfree-nonsecure 2048
kill-dup-partial-files
kill-old-partial-files 86400
prescan
# fsxNet - Agency HUB
node 21:1/100@fsxnet -md agency.bbs.nz:24556 SOMEPASS c
# ArakNet
node 10:101/0@araknet -md whq.araknet.xyz:24556 SOMEPASS c
# our listening port (default=24554)
iport 54554
pid-file /var/run/binkd/binkd.pid
# touch a watch file when files are received to kick of toss
# ENiGMA can monitor this (see @watch information above)
flag /home/enigma/enigma-bbs/mail/ftn_in/toss!.now *.su? *.mo? *.tu? *.we? *.th? *.fr? *.sa? *.pkt *.tic
# nuke old .bsy/.csy files after 24 hours
kill-old-bsy 43200
```
### Scheduling Polls
Binkd does not have it's own scheduler. Instead, you'll need to set up an Event Scheduler entry or perhaps a cron job:
First, create a script that runs through all of your uplinks. For example:
```bash
#!/bin/bash
UPLINKS=("21:1/100@fsxnet" "80:774/1@retronet" "10:101/0@araknet")
for uplink in "${UPLINKS[@]}"
do
/usr/local/sbin/binkd -p -P $uplink /home/enigma/xibalba/misc/binkd_xibalba.conf
done
```
Now, create an Event Scheduler entry in your `config.hjson`. As an example:
```hjson
eventScheduler: {
events: {
pollWithBink: {
// execute the script above very 1 hours
schedule: every 1 hours
action: @execute:/path/to/poll_bink.sh
}
}
}
```
## Additional Resources
* [Blog entry on setting up ENiGMA + Binkd on CentOS7](https://l33t.codes/enigma-12-binkd-on-centos-7/). Note that this references an **older version**, so be wary of the `config.hjson` references!
* [Setting up FTN-style message networks with ENiGMA½ BBS](https://medium.com/@alpha_11845/setting-up-ftn-style-message-networks-with-enigma%C2%BD-bbs-709b22a1ae0d) by Alpha.

88
docs/_docs/messageareas/configuring-a-message-area.md Normal file
View file

@ -0,0 +1,88 @@
---
layout: page
title: Message Base
---
## General Information
In ENiGMA½, a message base is divided into two logical grouping components: **Message Conferences** and **Areas**. Message conferences are top level containers while areas are for a specific topic. Messages are always stored internally with a area tag.
## Conferences
Message Conferences are the top level container for *1:n* Message *Areas* via the `messageConferences` block in `config.hjson`. A common setup may include a local conference and one or more conferences each dedicated to a particular message network such as fsxNet, ArakNet, etc.
Each conference is represented by a entry under `messageConferences`. Each entries top level key is it's *conference tag*.
:bulb: It is **highly** recommended to use snake_case style message *conference tags* and *area tags*!
| Config Item | Required | Description |
|-------------|----------|-------------|
| `name` | :+1: | Friendly conference name |
| `desc` | :+1: | Friendly conference description. |
| `sort` | :-1: | Set to a number to override the default alpha-numeric sort order based on the `name` field. |
| `default` | :-1: | Specify `true` to make this the default conference (e.g. assigned to new users) |
| `areas` | :+1: | Container of 1:n areas described below |
| `acs` | :-1: | A standard [ACS](../configuration/acs.md) block. See **ACS** below. |
### ACS
An optional standard [ACS](../configuration/acs.md) block can be supplied with the following rules:
* `read`: ACS required to read (see) this conference. Defaults to `GM[users]`.
* `write`: ACS required to write (post) to this conference. Defaults to `GM[users]`.
### Example
```hjson
{
messageConferences: {
local: { // conference tag
name: Local
desc: Local discussion
sort: 1
default: true
acs: {
read: GM[users] // default
}
}
}
}
```
## Message Areas
Message Areas are topic specific containers for messages that live within a particular conference. The top level key for an area sets it's *area tag*. For example, "General Discussion" may live under a Local conference while an fsxNet conference may contain "BBS Discussion".
| Config Item | Required | Description |
|-------------|----------|---------------------------------------------------------------------------------|
| `name` | :+1: | Friendly area name. |
| `desc` | :+1: | Friendly area description. |
| `sort` | :-1: | Set to a number to override the default alpha-numeric sort order based on the `name` field. |
| `default` | :-1: | Specify `true` to make this the default area (e.g. assigned to new users) |
| `acs` | :-1: | A standard [ACS](../configuration/acs.md) block. See **ACS** below. |
| `autoSignatures` | :-1: | Set to `false` to disable auto-signatures in this area. |
| `realNames` | :-1: | Set to `true` to use real names in this area. |
### ACS
An optional standard [ACS](../configuration/acs.md) block can be supplied with the following rules:
* `read`: ACS required to read (see) this area. Defaults to `GM[users]`.
* `write`: ACS required to write (post) to this area. Defaults to `GM[users]`.
### Example
```hjson
messageConferences: {
local: {
// ... see above ...
areas: {
enigma_dev: { // Area tag - required elsewhere!
name: ENiGMA 1/2 Development
desc: ENiGMA 1/2 development and discussion!
sort: 1
default: true
acs: {
read: GM[users] // default
write: GM[l33t] // super elite ENiGMA 1/2 users!
}
}
}
}
}
```
## Importing
FidoNet style `.na` files as well as legacy `AREAS.BBS` files in common formats can be imported using `oputil.js mb import-areas`. See [The oputil CLI](../admin/oputil.md) for more information and usage.

107
docs/_docs/messageareas/ftn.md Normal file
View file

@ -0,0 +1,107 @@
---
layout: page
title: FidoNet-Style Networks (FTN)
---
## FidoNet-Style Networks (FTN)
[FidoNet](https://en.wikipedia.org/wiki/FidoNet) proper and other FidoNet-Style networks are supported by ENiGMA½. A bit of configuration and you'll be up and running in no time!
:scroll: Before proceeding you may wish to check [Setting up FTN-style message networks with ENiGMA½ BBS](https://medium.com/@alpha_11845/setting-up-ftn-style-message-networks-with-enigma%C2%BD-bbs-709b22a1ae0d) by Alpha. An excellent guide detailing some of the setup described here!
### Configuration
Getting a fully running FTN enabled system requires a few configuration points:
1. `messageNetworks.ftn.networks`: Declares available networks. That is, networks you wish to sync up with.
2. `messageNetworks.ftn.areas`: Establishes local area mappings (ENiGMA½ to/from FTN area tags) and per-area specific configurations.
3. `scannerTossers.ftn_bso`: General configuration for the scanner/tosser (import/export) process. This is also where we configure per-node (uplink) settings.
: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 task.
#### Networks
The `networks` block is a per-network configuration where each entry's ID (or "key") may be referenced elsewhere in `config.hjson`. For example, consider two networks: ArakNet (`araknet`) and fsxNet (`fsxnet`):
```hjson
{
messageNetworks: {
ftn: {
networks: {
// it is recommended to use lowercase network tags
fsxnet: {
defaultZone: 21
localAddress: "21:1/121"
}
araknet: {
defaultZone: 10
localAddress: "10:101/9"
}
}
}
}
}
```
#### 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`.
| Config Item | Required | Description |
|-------------|----------|----------------------------------------------------------|
| `network` | :+1: | Associated network from the `networks` section above |
| `tag` | :+1: | FTN area tag (ie: `FSX_GEN`) |
| `uplinks` | :+1: | An array of FTN address uplink(s) for this network |
Example:
```hjson
{
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
uplinks: [ "21:1/100" ] // a single string also allowed here
}
}
}
}
}
```
:bulb: You can import `AREAS.BBS` or FTN style `.NA` files using [oputil](../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.

24
docs/_docs/messageareas/message-networks.md Normal file
View file

@ -0,0 +1,24 @@
---
layout: page
title: Message Networks
---
## Message Networks
ENiGMA½ supports external networks such as FidoNet-Style (FTN) and QWK by the way of importing and exporting to/from it's own internal format. This allows for a very flexible system that can easily be extended by creating new network modules.
All message network configuration occurs under the `messageNetworks.<name>` block in `config.hjson` (where name is something such as `ftn` or `qwk`). The most basic of external message network configurations generally comprises of two sections:
1. `messageNetworks.<name>.networks`: Global/general configuration for a particular network where `<name>` is for example `ftn` or `qwk`.
2. `messageNetworks.<name>.areas`: Provides mapping of ENiGMA½ **area tags** to their external counterparts.
:information_source: A related section under `scannerTossers.<name>` may provide configuration for scanning (importing) and tossing (exporting) messages for a particular network type. As an example, FidoNet-Style networks often work with BinkleyTerm Style Outbound (BSO) and thus the [FTN/BSO scanner/tosser](bso-import-export.md) (`ftn_bso`) module.
### Currently Supported Networks
The following networks are supported out of the box. Remember that you can create modules to add others if desired!
#### FidoNet-Style (FTN)
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`.
See [FidoNet-Style Networks](ftn.md) for more information.
#### QWK
See [QWK and QWK-Net Style Networks](qwk.md) for more information.

35
docs/_docs/messageareas/netmail.md Normal file
View file

@ -0,0 +1,35 @@
---
layout: page
title: Netmail
---
ENiGMA support import and export of Netmail from the Private Mail area. `RiPuk @ 21:1/136` and `RiPuk <21:1/136>` 'To' address formats are supported.
## Netmail Routing
A configuration block must be added to the `scannerTossers::ftn_bso` `config.hjson` section to tell the ENiGMA½ tosser where to route NetMail.
The following configuration would tell ENiGMA½ to route all netmail addressed to 21:* through 21:1/100, and all 46:* netmail through 46:1/100:
````hjson
scannerTossers: {
/* other scannerTosser config removed for clarity */
ftn_bso: {
netMail: {
routes: {
"21:*" : {
address: "21:1/100"
network: fsxnet
}
"46:*" : {
address: "46:1/100"
network: agoranet
}
}
}
}
}
````
The `network` tag must match the networks defined in `messageNetworks::ftn::networks` within `config.hjson`.

47
docs/_docs/messageareas/qwk.md Normal file
View file

@ -0,0 +1,47 @@
---
layout: page
title: QWK Support
---
## QWK and QWK-Net Style Networks
As like all other networks such as FidoNet-Style (FTN) networks, ENiGMA½ considers QWK external to the system but can import and export the format.
### Supported Standards
QWK must be considered a semi-standard as there are many implementations. What follows is a short & incomplete list of such standards ENiGMA½ supports:
* The basic [QWK packet format](http://fileformats.archiveteam.org/wiki/QWK).
* [QWKE extensions](https://github.com/wwivbbs/wwiv/blob/master/specs/qwk/qwke.txt).
* [Synchronet BBS style extensions](http://wiki.synchro.net/ref:qwk) such as `HEADERS.DAT`, `@` kludges, and UTF-8 handling.
### Configuration
QWK configuration occurs in the `messageNetworks.qwk` config block of `config.hjson`. As QWK wants to deal with conference numbers and ENiGMA½ uses area tags (conferences and conference tags are only used for logical grouping), a mapping can be made.
:information_source: During a regular, non QWK-Net exports, conference numbers can be auto-generated. Note that for QWK-Net style networks, you will need to create mappings however.
Example:
```hjson
{
messageNetworks: {
qwk: {
areas: {
general: { // local ENiGMA½ area tag
conference: 1 // conference number to map to
}
}
}
}
}
```
### oputil
The `oputil.js` utility can export packet files, dump the messages of a packet to stdout, etc. See [the oputil documentation](../admin/oputil.md) for more information.
### Offline Readers
A few of the offline readers that have been tested with QWK packet files produced by ENiGMA½:
| Software | Status | Notes |
|----------|--------|-------|
| MultiMail/Win v0.52 | Supported | Private mail seems to break even with bundles from other systems |
| SkyReader/W32 v1.00 | Supported | Works well. No QWKE or HEADERS.DAT support. Gets confused with low conference numbers. |
There are also [many other readers](https://www.softwolves.pp.se/old/2000/faq/bwprod) for various systems.