diff --git a/README.md b/README.md index a3013a0c..ca3b7412 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ENiGMA½ is a modern BBS software with a nostalgic flair! * [CP437](http://www.ascii-codes.com/) and UTF-8 output * [SyncTERM](http://syncterm.bbsdev.net/) style font and baud emulation support. Display PC/DOS and Amiga style artwork as it's intended! In general, ANSI-BBS / [cterm.txt](http://cvs.synchro.net/cgi-bin/viewcvs.cgi/*checkout*/src/conio/cterm.txt?content-type=text%2Fplain&revision=HEAD) / [bansi.txt](http://www.bbsdocumentary.com/library/PROGRAMS/GRAPHICS/ANSI/bansi.txt) are followed for expected BBS behavior. * Full [SAUCE](http://www.acid.org/info/sauce/sauce.htm) support. - * Renegade style [pipe color codes](/docs/configuration/colour-codes.md). + * Renegade style [pipe color codes](./docs/configuration/colour-codes.md). * [SQLite](http://sqlite.org/) storage of users, message areas, etc. * Strong [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) backed password encryption. * Support for 2-Factor Authentication with One-Time-Passwords @@ -28,7 +28,7 @@ ENiGMA½ is a modern BBS software with a nostalgic flair! ...and much much more. Please check out [the issue tracker](https://github.com/NuSkooler/enigma-bbs/issues) and feel free to request features (or contribute!) features! ## Documentation -[Browse the docs online](https://nuskooler.github.io/enigma-bbs/). Be sure to checkout the [/docs/](/docs/) folder as well for the latest and greatest documentation. +[Browse the docs online](https://nuskooler.github.io/enigma-bbs/). Be sure to checkout the [/docs/](./docs/) folder as well for the latest and greatest documentation. ## Installation On most *nix systems simply run the following from your terminal: diff --git a/UPGRADE.md b/UPGRADE.md index 7e352c31..117b4bff 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -2,7 +2,7 @@ This document covers basic upgrade notes for major ENiGMA½ version updates. # Before Upgrading -* Always back up your system! (See [Administration](/docs/admin/administration.md)) +* Always back up your system! (See [Administration](./docs/admin/administration.md)) * Seriously, always back up your system! # General Notes @@ -12,7 +12,7 @@ In general, look at template menu files in `misc/menu_templates`, and `config_te ### Menus & Theme Updates Upgrades often come with changes to the default menu templates found in `misc/menu_tempaltes`. You can use these as references for changes and additions to the default menu sets. This also applies to the default `luciano_blocktronics` theme and it's `theme.hjson` file. -See [Updating](/docs/admin/updating.md) for details on menu files/etc. +See [Updating](./docs/admin/updating.md) for details on menu files/etc. # Upgrading the Code Upgrading from GitHub is easy: diff --git a/WHATSNEW.md b/WHATSNEW.md index a0d48acf..484755ab 100644 --- a/WHATSNEW.md +++ b/WHATSNEW.md @@ -2,18 +2,18 @@ This document attempts to track **major** changes and additions in ENiGMA½. For details, see GitHub. ## 0.0.12-beta -* The `master` branch has become mainline. What this means to users is `git pull` will always give you the latest and greatest. Make sure to read [Updating](/docs/admin/updating.md) and keep an eye on `WHATSNEW.md` (this file) and [UPGRADE](UPGRADE.md)! See also [ticket #276](https://github.com/NuSkooler/enigma-bbs/issues/276). +* The `master` branch has become mainline. What this means to users is `git pull` will always give you the latest and greatest. Make sure to read [Updating](./docs/admin/updating.md) and keep an eye on `WHATSNEW.md` (this file) and [UPGRADE](UPGRADE.md)! See also [ticket #276](https://github.com/NuSkooler/enigma-bbs/issues/276). * The default configuration has been moved to [config_default.js](/core/config_default.js). * A full configuration revamp has taken place. Configuration files such as `config.hjson`, `menu.hjson`, and `theme.hjson` can now utilize includes via the `includes` directive, reference 'self' sections using `@reference:` and import environment variables with `@environment`. * An explicit prompt file previously specified by `general.promptFile` in `config.hjson` is no longer necessary. Instead, this now simply part of the `prompts` section in `menu.hjson`. The default setup still creates a separate prompt HJSON file, but it is `includes`ed in `menu.hjson`. With the removal of prompts the `PromptsChanged` event will no longer be fired. -* New `PV` ACS check for arbitrary user properties. See [ACS](/docs/configuration/acs.md) for details. +* New `PV` ACS check for arbitrary user properties. See [ACS](./docs/configuration/acs.md) for details. * The `message` arg used by `msg_list` has been deprecated. Please starting using `messageIndex` for this purpose. Support for `message` will be removed in the future. * A number of new MCI codes (see [MCI](./docs/art/mci.md)) ## 0.0.11-beta * Upgraded from `alpha` to `beta` -- The software is far along and mature enough at this point! * Development is now against Node.js 12.x LTS. Other versions may work but are not currently supported! -* [QWK support](/docs/messageareas/qwk.md) +* [QWK support](./docs/messageareas/qwk.md) * `oputil fb scan *areaTagWildcard*` scans all areas in which wildcard is matched. * The archiver configuration `escapeTelnet` has been renamed `escapeIACs`. Support for the old value will be removed in the future. @@ -21,8 +21,8 @@ This document attempts to track **major** changes and additions in ENiGMA½. For + `oputil.js user rename USERNAME NEWNAME` + `my_messages.js` module (defaulted to "m" at the message menu) to list public messages addressed to the currently logged in user. Takes into account their username and `real_name` property. + SSH Public Key Authentication has been added. The system uses a OpenSSH style public key set on the `ssh_public_key` user property. -+ 2-Factor (2FA) authentication is now available using [RFC-4266 - HOTP: HMAC-Based One-Time Password Algorithm)](https://tools.ietf.org/html/rfc4226), [RFC-6238 - TOTP: Time-Based One-Time Password Algorithm](https://tools.ietf.org/html/rfc6238), or [Google Authenticator](http://google-authenticator.com/). QR codes for activation are available as well. One-time backup aka recovery codes can also be used. See [Security](/docs/configuration/security.md) for more info! -* New ACS codes for new 2FA/OTP: `AR` and `AF`. See [ACS](/docs/configuration/acs.md) for details. ++ 2-Factor (2FA) authentication is now available using [RFC-4266 - HOTP: HMAC-Based One-Time Password Algorithm)](https://tools.ietf.org/html/rfc4226), [RFC-6238 - TOTP: Time-Based One-Time Password Algorithm](https://tools.ietf.org/html/rfc6238), or [Google Authenticator](http://google-authenticator.com/). QR codes for activation are available as well. One-time backup aka recovery codes can also be used. See [Security](./docs/configuration/security.md) for more info! +* New ACS codes for new 2FA/OTP: `AR` and `AF`. See [ACS](./docs/configuration/acs.md) for details. + `oputil.js user 2fa USERNAME TYPE` enables 2-factor authentication for a user. * `oputil.js user info USERNAME --security` can now display additional security information such as 2FA/OTP. * `oputil.js fb scan --quick` is now the default. Override with `--full`. @@ -85,8 +85,8 @@ submit: [ * `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). +* 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). * Performing a file scan/import using `oputil.js fb scan` now recognizes various `FILES.BBS` formats. * Usernames found in the `config.users.badUserNames` are now not only disallowed from applying, but disconnected at any login attempt. * Total minutes online is now tracked for users. Of course, it only starts after you get the update :) diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md index 1f8e27c7..42cc7bff 100644 --- a/docs/_includes/nav.md +++ b/docs/_includes/nav.md @@ -18,6 +18,7 @@ - [HJSON Config Files]({{ site.baseurl }}{% link configuration/hjson.md %}) - [Menus]({{ site.baseurl }}{% link configuration/menu-hjson.md %}) - [Directory Structure]({{ site.baseurl }}{% link configuration/directory-structure.md %}) + - [External Binaries]({{ site.baseurl }}{% link configuration/external-binaries.md %}) - [Archivers]({{ site.baseurl }}{% link configuration/archivers.md %}) - [File Transfer Protocols]({{ site.baseurl }}{% link configuration/file-transfer-protocols.md %}) - [Email]({{ site.baseurl }}{% link configuration/email.md %}) diff --git a/docs/admin/administration.md b/docs/admin/administration.md index 8d15fba5..0b960246 100644 --- a/docs/admin/administration.md +++ b/docs/admin/administration.md @@ -9,7 +9,7 @@ title: Administration See [Updating](updating.md). ## Viewing Logs -See [Monitoring Logs](/docs/troubleshooting/monitoring-logs.md). +See [Monitoring Logs](../troubleshooting/monitoring-logs.md). ## Managing Users User management is currently handled via the [oputil CLI](oputil.md). diff --git a/docs/admin/oputil.md b/docs/admin/oputil.md index e591de9f..49e7039c 100644 --- a/docs/admin/oputil.md +++ b/docs/admin/oputil.md @@ -107,7 +107,7 @@ info arguments: | `group` | Modifies users group membership | Add to group: `./oputil.js user group joeuser +derp`
Remove from group: `./oputil.js user group joeuser -derp` | N/A | #### Manage 2FA/OTP -While `oputil.js` can be used to manage a user's 2FA/OTP, it is highly recommended to require users to opt-in themselves. See [Security](/docs/configuration/security.md) for details. +While `oputil.js` can be used to manage a user's 2FA/OTP, it is highly recommended to require users to opt-in themselves. See [Security](../configuration/security.md) for details. ## Configuration The `config` command allows sysops to perform various system configuration and maintenance tasks. diff --git a/docs/admin/updating.md b/docs/admin/updating.md index 59ab3111..ae9412e4 100644 --- a/docs/admin/updating.md +++ b/docs/admin/updating.md @@ -25,7 +25,7 @@ npm install # or 'yarn' :information_source: Visual diff tools such as [DiffMerge](https://www.sourcegear.com/diffmerge/downloads.php) (free, works on all major platforms) can be very helpful for the tasks outlined above! -:bulb: It is recommended to [monitor logs](/docs/troubleshooting/monitoring-logs.md) and poke around a bit after an update! +:bulb: It is recommended to [monitor logs](../troubleshooting/monitoring-logs.md) and poke around a bit after an update! diff --git a/docs/art/general.md b/docs/art/general.md index 18c438ec..551d231e 100644 --- a/docs/art/general.md +++ b/docs/art/general.md @@ -5,15 +5,20 @@ title: General Art Information ## General Art Information One of the most basic elements of BBS customization is through it's artwork. ENiGMA½ supports a variety of ways to select, display, and manage art. +### Art File Locations As a general rule, art files live in one of two places: 1. The `art/general` directory. This is where you place common/non-themed art files. 2. Within a _theme_ such as `art/themes/super_fancy_theme`. -### Art in Menus -While art can be displayed programmatically such as from a custom module, the most basic and common form is via `menu.hjson` entries. This usually falls into one of two forms. +### MCI Codes +All art can contain [MCI Codes](mci.md). -**Form 1**: A "standard" entry where a single `art` spec is utilized: +### Art in Menus +While art can be displayed programmatically such as from a custom module, the most basic and common form is via `menu.hjson` entries. This usually falls into one of two forms: + +#### Standard +A "standard" entry where a single `art` spec is utilized: ```hjson { mainMenu: { @@ -22,7 +27,8 @@ While art can be displayed programmatically such as from a custom module, the mo } ``` -**Form 2**: An entry for a custom module where multiple pieces are declared and used. The second style usually takes the form of a `config.art` block with two or more entries: +#### Module Specific / Multiple Art +An entry for a custom module where multiple pieces are declared and used. The second style usually takes the form of a `config.art` block with two or more entries: ```hjson { nodeMessage: { @@ -64,7 +70,7 @@ ENiGMA½ uses a fallback system for art selection. When a menu entry calls for a 4. In the `art/general` directory. #### ACS-Driven Conditionals -The [ACS](/docs/configuration/acs.md) system can be used to make conditional art selection choices. To do this, provide an array of possible values in your art spec. As an example: +The [ACS](../configuration/acs.md) system can be used to make conditional art selection choices. To do this, provide an array of possible values in your art spec. As an example: ```hjson { fancyMenu: { @@ -100,7 +106,17 @@ The most common fonts are probably as follows: * `microknight` * `topaz` -Other fonts fonts also available: +...and some examples: + + ![cp437](../assets/images/cp437.png "cp437")
+ ![pot_noodle](../assets/images/pot_noodle.png "pot_noodle")
+ ![mo_soul](../assets/images/mo_soul.png "mo_soul")
+ ![microknight_plus](../assets/images/microknight_plus.png "microknight_plus")
+ ![topaz_plus](../assets/images/topaz_plus.png "topaz_plus")
+ ![microknight](../assets/images/microknight.png "microknight")
+ ![topaz](../assets/images/topaz.png "topaz")
+ +Other "fonts" also available: * `cp1251` * `koi8_r` * `iso8859_2` @@ -133,10 +149,12 @@ Other fonts fonts also available: * `iso8859_1` * `cp1131` -See [this specification](https://github.com/protomouse/synchronet/blob/master/src/conio/cterm.txt) for more information. +:information_source: See [this specification](https://github.com/protomouse/synchronet/blob/master/src/conio/cterm.txt) for more information. #### SyncTERM Style Baud Rates -The `baudRate` member can set a [SyncTERM](http://syncterm.bbsdev.net/) style emulated baud rate. May be `300`, `600`, `1200`, `2400`, `4800`, `9600`, `19200`, `38400`, `57600`, `76800`, or `115200`. A value of `ulimited`, `off`, or `0` resets (disables) the rate. See [this specification](https://github.com/protomouse/synchronet/blob/master/src/conio/cterm.txt) for more information. +The `baudRate` member can set a [SyncTERM](http://syncterm.bbsdev.net/) style emulated baud rate. May be `300`, `600`, `1200`, `2400`, `4800`, `9600`, `19200`, `38400`, `57600`, `76800`, or `115200`. A value of `ulimited`, `off`, or `0` resets (disables) the rate. + +:information_source: See [this specification](https://github.com/protomouse/synchronet/blob/master/src/conio/cterm.txt) for more information. ### Common Example ```hjson @@ -153,4 +171,4 @@ fullLogoffSequenceRandomBoardAd: { ``` ### See Also -See also the [Show Art Module](/docs/modding/show-art.md) for more advanced art display! \ No newline at end of file +See also the [Show Art Module](../modding/show-art.md) for more advanced art display! \ No newline at end of file diff --git a/docs/art/mci.md b/docs/art/mci.md index 099c5f04..394f39ee 100644 --- a/docs/art/mci.md +++ b/docs/art/mci.md @@ -2,16 +2,27 @@ layout: page title: MCI Codes --- -ENiGMA½ supports a variety of MCI codes. Some **predefined** codes produce information about the current user, system, -or other statistics while others are used to instantiate a **View**. MCI codes are two characters in length and are -prefixed with a percent (%) symbol. Some MCI codes have additional options that may be set directly from the code itself -while others -- and more advanced options -- are controlled via the current theme. Standard (non-focus) and focus colors -are set by placing duplicate codes back to back in art files. +## MCI Codes +ENiGMA½ supports a variety of MCI codes. Some **predefined** codes produce information about the current user, system, or other statistics while others are used to instantiate a **View**. -## Predefined MCI Codes -There are many predefined MCI codes that can be used anywhere on the system (placed in any art file). More are added all -the time so also check out [core/predefined_mci.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) -for a full listing. Many codes attempt to pay homage to Oblivion/2, iNiQUiTY, etc. +## General Information +MCI codes are composed of two characters and are prefixed with a percent (%) symbol. + +:information_source: To explicitly tie a MCI to a specific View ID, suffix the MCI code with a number. For example: `%BN1`. + +:information_source: Standard (non-focus) and focus colors are set by placing duplicate codes back to back in art files: + +![Example](../assets/images/mci-example1.png "MCI Colors") + +Some MCI codes have additional options that may be set directly from the code itself while others -- and more advanced options -- are controlled via the current theme. + +## Relationship with Menus, Art, and Themes +A MCI code that appears in a `menu.hjson` entry corresponds to that found in it's associated art file. This same MCI code can be referenced in the `theme.hjson` in order to apply a theme. + +See [Menus](../docs/configuration/menu-hjson.md) and [Themes](themes.md) for more information. + +## Predefined Codes +There are many predefined MCI codes that can be used anywhere on the system (placed in any art file). | Code | Description | |------|--------------| @@ -98,6 +109,13 @@ Some additional special case codes also exist: | `XY` | A special code that may be utilized for placement identification when creating menus or to extend an otherwise empty space in an art file down the screen. | +:information_source: More are added all +the time so also check out [core/predefined_mci.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) +for a full listing. + +:note: Many codes attempt to pay homage to Oblivion/2, iNiQUiTY, etc. + + ## Views A **View** is a control placed on a **form** that can display variable data or collect input. One example of a View is a Vertical Menu (`%VM`): Old-school BBSers may recognize this as a lightbar menu. @@ -115,10 +133,11 @@ a Vertical Menu (`%VM`): Old-school BBSers may recognize this as a lightbar menu | `TM` | Toggle Menu | A toggle menu commonly used for Yes/No style input | | `KE` | Key Entry | A *single* key input control | - -Peek at [/core/mci_view_factory.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) to +:information_source: Peek at [/core/mci_view_factory.js](https://github.com/NuSkooler/enigma-bbs/blob/master/core/mci_view_factory.js) to see additional information. +### View Identifiers +As mentioned above, MCI codes can (and often should) be explicitly tied to a *View Identifier*. Simply speaking this is a number representing the particular view. These can be useful to reference in code, apply themes, etc. ## Properties & Theming Predefined MCI codes and other Views can have properties set via `menu.hjson` and further *themed* via `theme.hjson`. See [Themes](themes.md) for more information on this subject. @@ -138,8 +157,7 @@ Predefined MCI codes and other Views can have properties set via `menu.hjson` an | `itemFormat` | Sets the format for a list entry. See **Entry Formatting** below | | `focusItemFormat` | Sets the format for a focused list entry. See **Entry Formatting** below | -These are just a few of the properties set on various views. *Use the source Luke*, as well as taking a look at the default -`menu.hjson` and `theme.hjson` files! +These are just a few of the properties set on various views. *Use the source Luke*, as well as taking a look at the default `menu.hjson` and `theme.hjson` files! ### Custom Properties Often a module will provide custom properties that receive format objects (See **Entry Formatting** below). Custom property formatting can be declared in the `config` block. For example, `browseInfoFormat10`..._N_ (where _N_ is up to 99) in the `file_area_list` module received a fairly extensive format object that contains `{fileName}`, `{estReleaseYear}`, etc. @@ -196,6 +214,8 @@ Additional text styles are available for numbers: #### Examples -Suppose a format object contains the following elements: `userName` and `affils`. We could create a `itemFormat` entry that builds a item to our specifications: `|04{userName!styleFirstLower} |08- |13{affils}`. This may produce a string such as "eVIL cURRENT - Razor 1911". +Suppose a format object contains the following elements: `userName` and `affils`. We could create a `itemFormat` entry that builds a item to our specifications: `|04{userName!styleFirstLower} |08- |13{affils}`. This may produce a string such as this: -Remember that a Python [string format mini language](https://docs.python.org/3/library/string.html#format-specification-mini-language) style syntax is available for widths, alignment, number prevision, etc. as well. A number can be made to be more human readable for example: `{byteSize:,}` may yield "1,123,456". \ No newline at end of file +![Example](../assets/images/text-format-example1.png "Text Format") + +:bulb: Remember that a Python [string format mini language](https://docs.python.org/3/library/string.html#format-specification-mini-language) style syntax is available for widths, alignment, number prevision, etc. as well. A number can be made to be more human readable for example: `{byteSize:,}` may yield "1,123,456". \ No newline at end of file diff --git a/docs/art/themes.md b/docs/art/themes.md index 9c9087e1..f7b234de 100644 --- a/docs/art/themes.md +++ b/docs/art/themes.md @@ -6,10 +6,12 @@ title: Themes ENiGMA½ comes with an advanced theming system allowing system operators to highly customize the look and feel of their boards. A given installation can have as many themes as you like for your users to choose from. ## General Information -Themes live in `art/themes/`. Each theme (and thus it's *theme ID*) is a directory within the `themes` directory. The theme itself is simply a collection of art files, and a `theme.hjson` file that further defines layout, colors & formatting, etc. ENiGMA½ comes with a default theme by [Luciano Ayres](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) called Mystery Skull. This theme is in `art/themes/luciano_blocktronics`, and thus it's *theme ID* is `luciano_blocktronics`. +Themes live in `art/themes/`. Each theme (and thus it's *theme ID*) is a directory within the `themes` directory. The theme itself is simply a collection of art files, and a `theme.hjson` file that further defines layout, colors & formatting, etc. + +ENiGMA½ comes with a default theme by [Luciano Ayres](http://blocktronics.org/tag/luciano-ayres/) of [Blocktronics](http://blocktronics.org/) called Mystery Skull. This theme is in `art/themes/luciano_blocktronics`, and thus it's *theme ID* is `luciano_blocktronics`. ## Art -For information on art files, see [General Art Information](general.md). TL;DR: In general, to theme a piece of art, create a version of it in your themes directory. +For information on art files, see [General Art Information](general.md). In general, to theme a piece of art, create a version of it in your themes directory. :memo: Remember that by default, the system will allow for randomly selecting art (in one of the directories mentioned above) by numbering it: `FOO1.ANS`, `FOO2.ANS`, etc.! @@ -67,8 +69,20 @@ Major areas to override/theme: * `mci`: Set per-MCI code properties such as `height`, `width`, text styles, etc. See [MCI Codes](mci.md) for a more information. Two formats for `mci` blocks are allowed: -* Verbose where a form ID(s) are supplied. * Shorthand if only a single/first form is needed. +* Verbose where a form ID(s) are supplied (required if multiple forms are used) + +Example: Shorthand `mci` format: +```hjson +matrix: { + mci: { + VM1: { + itemFormat: "|03{text}" + focusItemFormat: "|11{text!styleFirstLower}" + } + } +} +``` Example: Verbose `mci` with form IDs: ```hjson @@ -88,18 +102,6 @@ newUserFeedbackToSysOp: { } ``` -Example: Shorthand `mci` format: -```hjson -matrix: { - mci: { - VM1: { - itemFormat: "|03{text}" - focusItemFormat: "|11{text!styleFirstLower}" - } - } -} -``` - ##### Custom Range Info Formatting Many modules support "custom range" MCI items. These are MCI codes that are left to the user to define using a format object specific to the module. For example, consider the `msg_area_list` module: This module sets MCI codes 10+ (`%TL10`, `%TL11`, etc.) as "custom range". When theming you can place these MCI codes in your artwork then define the format in `theme.hjson`: @@ -112,7 +114,7 @@ messageAreaChangeCurrentArea: { ``` ## Creating Your Own -:warning: ***IMPORTANT!*** It is recommended you don't make any customisations to the included `luciano_blocktronics' theme. Instead, create your own and make changes to that instead: +:warning: ***IMPORTANT!*** Do not make any customizations to the included `luciano_blocktronics' theme. Instead, create your own and make changes to that instead: 1. Copy `/art/themes/luciano_blocktronics` to `art/themes/your_board_theme` 2. Update the `info` block at the top of the theme.hjson file: @@ -125,10 +127,41 @@ info: { } ``` -3. If desired, you may make this the default system theme in `config.hjson` via `theme.default`. `theme.preLogin` may be set if you want this theme used for pre-authenticated users. Both of these values also accept `*` if you want the system to radomly pick. +3. If desired, you may make this the default system theme in `config.hjson` via `theme.default`. `theme.preLogin` may be set if you want this theme used for pre-authenticated users. Both of these values also accept `*` if you want the system to randomly pick. ``` hjson theme: { default: your_board_theme preLogin: * } ``` + +## Theming Example +Let's run through an example! + +Consider the following `menu.hjson` entry: +```hjson +superFancyMenu: { + art: FANCY.ANS + // ...some other stuff... +} +``` + +With a file of `FANCY.ANS` in `art/themes/fancy_theme` containing the following MCI codes: +* TL1 (Generic text label) +* BN2 (Predefined: Board Name) + +An entry in your `theme.hjson` could look like this: +```hjson +superFancyMenu: { + mci: { + TL1: { + // supply the full format of the TL1 View + text: |02ENiGMA|10½ |08v|03|VN + } + BN2: { + // Make Board Name l33t style + style: l33t + } + } +} +``` \ No newline at end of file diff --git a/docs/assets/images/cp437.png b/docs/assets/images/cp437.png new file mode 100644 index 00000000..fa0a511f Binary files /dev/null and b/docs/assets/images/cp437.png differ diff --git a/docs/assets/images/mci-example1.png b/docs/assets/images/mci-example1.png new file mode 100644 index 00000000..ca3ffbcb Binary files /dev/null and b/docs/assets/images/mci-example1.png differ diff --git a/docs/assets/images/microknight.png b/docs/assets/images/microknight.png new file mode 100644 index 00000000..831bde19 Binary files /dev/null and b/docs/assets/images/microknight.png differ diff --git a/docs/assets/images/microknight_plus.png b/docs/assets/images/microknight_plus.png new file mode 100644 index 00000000..9bfb7e5a Binary files /dev/null and b/docs/assets/images/microknight_plus.png differ diff --git a/docs/assets/images/mo_soul.png b/docs/assets/images/mo_soul.png new file mode 100644 index 00000000..80dcd60b Binary files /dev/null and b/docs/assets/images/mo_soul.png differ diff --git a/docs/assets/images/pot_noodle.png b/docs/assets/images/pot_noodle.png new file mode 100644 index 00000000..aebfb146 Binary files /dev/null and b/docs/assets/images/pot_noodle.png differ diff --git a/docs/assets/images/text-format-example1.png b/docs/assets/images/text-format-example1.png new file mode 100644 index 00000000..387786f2 Binary files /dev/null and b/docs/assets/images/text-format-example1.png differ diff --git a/docs/assets/images/topaz.png b/docs/assets/images/topaz.png new file mode 100644 index 00000000..839e6ce4 Binary files /dev/null and b/docs/assets/images/topaz.png differ diff --git a/docs/assets/images/topaz_plus.png b/docs/assets/images/topaz_plus.png new file mode 100644 index 00000000..ba8a1304 Binary files /dev/null and b/docs/assets/images/topaz_plus.png differ diff --git a/docs/configuration/acs.md b/docs/configuration/acs.md index decb3267..782bc8ec 100644 --- a/docs/configuration/acs.md +++ b/docs/configuration/acs.md @@ -73,8 +73,8 @@ All `users` can read (see) the area, `sysops` and `co-ops` can write (upload), a ## ACS Touch Points The following touch points exist in the system. Many more are planned: -* [Message conferences and areas](/docs/messageareas/configuring-a-message-area.md) -* [File base areas](/docs/filebase/first-file-area.md) and [Uploads](/docs/filebase/uploads.md) +* [Message conferences and areas](../messageareas/configuring-a-message-area.md) +* [File base areas](../filebase/first-file-area.md) and [Uploads](../filebase/uploads.md) * Menus within [Menu HJSON (menu.hjson)](menu-hjson.md) See the specific areas documentation for information on available ACS checks. diff --git a/docs/configuration/archivers.md b/docs/configuration/archivers.md index 5433caf0..0f55a58b 100644 --- a/docs/configuration/archivers.md +++ b/docs/configuration/archivers.md @@ -2,44 +2,13 @@ layout: page title: Archivers --- -ENiGMA½ can detect and process various archive formats such as zip and arj for a variety of tasks from file upload processing to EchoMail bundle compress/decompression. The `archives` section of `config.hjson` is used to override defaults, add new handlers, and so on. ## Archivers +ENiGMA½ can detect and process various archive formats such as zip and arj for a variety of tasks from file upload processing to EchoMail bundle compress/decompression. The `archives` section of `config.hjson` is used to override defaults, add new handlers, and so on. + Archivers are manged via the `archives:archivers` configuration block of `config.hjson`. Each entry in this section defines an **external archiver** that can be referenced in other sections of `config.hjson` as and in code. Entries define how to `compress`, `decompress` (a full archive), `list`, and `extract` (specific files from an archive). -### Predefined Archivers -The following archivers are pre-configured in ENiGMA½ as of this writing. Remember that you can override settings or add new handlers! - -#### ZZip -* Formats: .7z, .bzip2, .gzip/.gz, and more -* Key: `7Zip` -* Homepage/package: [7-zip.org](http://www.7-zip.org/). Generally obtained from a `p7zip` package in UNIX-like environments. See http://p7zip.sourceforge.net/ for details. -* Notes: Versions previous to 0.0.10-alpha defaulted to using 7zip for .zip files as well, but newer versions of the package give "volume" errors at times. See InfoZip below. - -#### InfoZip -* Formats: .zip -* Key: InfoZip -* Homepage/package: http://infozip.sourceforge.net/. Often already available in Linux. You will need `zip` and `unzip` in ENiGMA's path. - -#### Lha -* Formats: LHA files such as .lzh. -* Key: `Lha` -* Homepage/package: `lhasa` on most UNIX-like environments. See also https://fragglet.github.io/lhasa/ and https://web.archive.org/web/20191023045303/http://www2m.biglobe.ne.jp/~dolphin/lha/lha-unix.htm - -#### Lzx -* Formats: Amiga LZX -* Key: `Lzx` -* Homepage/package: `unlzx` under most UNIX-like platforms ([Debian/Ubuntu](https://launchpad.net/~rzr/+archive/ubuntu/ppa/+build/2486127), [RedHat](https://fedora.pkgs.org/32/rpm-sphere-x86_64/unlzx-1.1-4.1.x86_64.rpm.html), [Source](http://xavprods.free.fr/lzx/)) - -#### Arj -* Formats: .arj -* Key: `Arj` -* Homepage/package: `arj` on most UNIX-like environments. - -#### Rar -* Formats: .Rar -* Key: `Rar` -* Homepage/package: `unrar` on most UNIX-like environments. See also https://blog.hostonnet.com/unrar +:bulb: Generally you do not need to anything beyond installing supporting binaries. No `config.hjson` editing necessary; Please see [External Binaries](external-binaries.md)! ### Archiver Configuration Archiver entries in `config.hjson` are mostly self explanatory with the exception of `list` commands that require some additional information. The `args` member for an entry is an array of arguments to pass to `cmd`. Some variables are available to `args` that will be expanded by the system: diff --git a/docs/configuration/config-files.md b/docs/configuration/config-files.md index 565b9b10..dbba9816 100644 --- a/docs/configuration/config-files.md +++ b/docs/configuration/config-files.md @@ -8,7 +8,7 @@ ENiGMA½ configuration files such as the [system config](config-hjson.md), [menu ## Hot-Reload Nearly all of ENiGMA½'s configuration can be hot-reloaded. That is, a live system can have it's configuration modified and it will be loaded in place. -:bulb: [Monitoring live logs](/docs/troubleshooting/monitoring-logs.md) is useful when making live changes. The system will complain if something is wrong! +:bulb: [Monitoring live logs](../troubleshooting/monitoring-logs.md) is useful when making live changes. The system will complain if something is wrong! ## Common Directives ### Includes @@ -74,7 +74,7 @@ Consider `actionKeys` in a menu. Often times you may show a screen and the user :information_source: An unresolved `@reference` will be left intact. ### Environment Variables -Especially in a container environment such as [Docker](/docs/installation/docker.md), environment variable access in configuration files can become very handy. ENiGMA½ provides a flexible way to access variables using the `@environment` directive. The most basic form of `@environment:VAR_NAME` produces a string value. Additionally a `:type` suffix can be supplied to coerece the value to a particular type. Variables pointing to a comma separated list can be turned to arrays using an additional `:array` suffix. +Especially in a container environment such as [Docker](../installation/docker.md), environment variable access in configuration files can become very handy. ENiGMA½ provides a flexible way to access variables using the `@environment` directive. The most basic form of `@environment:VAR_NAME` produces a string value. Additionally a `:type` suffix can be supplied to coerece the value to a particular type. Variables pointing to a comma separated list can be turned to arrays using an additional `:array` suffix. Below is a table of the various forms: diff --git a/docs/configuration/config-hjson.md b/docs/configuration/config-hjson.md index 65c6c4e9..28d379c5 100644 --- a/docs/configuration/config-hjson.md +++ b/docs/configuration/config-hjson.md @@ -43,8 +43,8 @@ Below is a list of various configuration sections. There are many more, but this * [Archivers](archivers.md): Set up external archive utilities for handling things like ZIP, ARJ, RAR, and so on. * [Email](email.md): System email support. * [Event Scheduler](event-scheduler.md): Set up events as you see fit! -* [File Base](/docs/filebase/index.md) +* [File Base](../filebase/index.md) * [File Transfer Protocols](file-transfer-protocols.md): Oldschool file transfer protocols such as X/Y/Z-Modem! -* [Message Areas](/docs/messageareas/configuring-a-message-area.md), [Networks](/docs/messageareas/message-networks.md), [NetMail](/docs/messageareas/netmail.md), etc. +* [Message Areas](../messageareas/configuring-a-message-area.md), [Networks](../messageareas/message-networks.md), [NetMail](../messageareas/netmail.md), etc. * ...and a **lot** more! Explore the docs! If you can't find something, please contact us! diff --git a/docs/configuration/external-binaries.md b/docs/configuration/external-binaries.md new file mode 100644 index 00000000..1932a963 --- /dev/null +++ b/docs/configuration/external-binaries.md @@ -0,0 +1,44 @@ +--- +layout: page +title: External Support Binaries +--- + +## External Support Binaries +ENiGMA½ relies on various external binaries in order to perform common tasks such as processing file archives and extracting information from uploads/file imports, some legacy transfer protocols, etc. + +:correct: Before using features such as the [File Base](../filebase/index.md) or [File Transfer Protocols](../configuration/file-transfer-protocols.md) it is highly recommended to install support binaries! + +## Archivers +Below is a table of pre-configured archivers. Remember that you can override settings or add new handlers! See [Archivers](archivers.md). + +| Archiver (Key) | File Types | More Info | Debian/Ubuntu (apt/dep) | Red Hat (yum/rpm) | Windows | +|----------|---------|-----------|-------------------------|-------------------|---------| +| `Arj` | .arj | [Wikipedia](https://en.wikipedia.org/wiki/ARJ) | `arj` | `arj` | [ARJ](http://arj.sourceforge.net/) | +| `7Zip` | .7z, .bzip2, .gzip/.gz, etc.
:warning: Does not attempt to handle zip files! See `InfoZip`! | http://www.7-zip.org | `p7zip-full` | `p7zip-full` | [7-zip](http://www.7-zip.org/) | +| `InfoZip` | .zip | http://infozip.sourceforge.net
`zip` and `unzip` will need to be en ENiGMA's PATH | `zip` and `unzip` | `zip` and `unzip` | [InfoZip](http://infozip.sourceforge.net/) | +| `Lha` | .lza, .lzh, etc. | [Wikipedia](https://en.wikipedia.org/wiki/LHA_(file_format))
https://fragglet.github.io/lhasa/ | `lhasa` | `lhasa` | [Win32 binaries](https://soulsphere.org/projects/lhasa/win32/) | +| `Lzx` | .lzx | [Amiga LZX](https://en.wikipedia.org/wiki/LZX_(algorithm)#Amiga_LZX) | `unlzx` | `unlzx` | [Source](http://xavprods.free.fr/lzx/) | +| `Rar` | .rar | [Wikipedia](https://en.wikipedia.org/wiki/RAR_(file_format)) | `unrar` | `unrar`| [RARLAB](https://www.rarlab.com/) | +| `TarGz` | .tar.gz, .gzip | [Wikipedia](https://en.wikipedia.org/wiki/Gzip) | `tar` | `tar` | [TAR.EXE](https://ss64.com/nt/tar.html) + + +:information_source: For more information see `core/config_default.js` + +:information_source: For information on changing configuration or adding more archivers see [Archivers](archivers.md). + +## File Transfer Protocols +Handlers for legacy file transfer protocols such as Z-Modem and Y-Modem. + +| Handler (Key) | Protocol | More Info | Debian/Ubuntu (apt/dep) | Red Hat (yum/rpm) | Windows | +|----------|---------|-----------|-------------------------|-------------------|---------| +| `xmodemSexyz`
`ymodemSexyz`
`zmodem8kSexyz` | X-Modem, Y-Modem and Z-Modem SEXYZ | [SEXYZ](http://www.synchro.net/docs/sexyz.txt) | [x86_64 Binary](https://l33t.codes/outgoing/sexyz) | [x86_64 Binary](https://l33t.codes/outgoing/sexyz) | [Synchronet FTP](ftp://ftp.synchro.net/) | +| `zmodem8kSz` | Z-Modem 8K | [Wikipedia](https://en.wikipedia.org/wiki/ZMODEM) | `lrzsz` | `lrzsz` | Unknown | + + +## Information Extractors +Information extraction utilities can extract information from various file types such as PDF in order to (attempt) to come up with a good default description. + +| Extractor | File Types | More Info | Debian/Ubuntu (apt/dep) | Red Hat (yum/rpm) | Windows | +|----------|---------|-----------|-------------------------|-------------------|---------| +| ExifTool | .mp3, .pdf, .mp4, .jpg, .gif, .png, many more | [ExifTool](https://www.sno.phy.queensu.ca/~phil/) | `libimage-exiftool-perl` | `perl-Image-ExifTool` | Unknown | +| XDMS | Amiga DiskMasher images | | `xdms` | `xdms` | Unknown diff --git a/docs/configuration/file-transfer-protocols.md b/docs/configuration/file-transfer-protocols.md index a7dec599..d9c05983 100644 --- a/docs/configuration/file-transfer-protocols.md +++ b/docs/configuration/file-transfer-protocols.md @@ -8,8 +8,7 @@ ENiGMA½ currently relies on external executable binaries for "legacy" file tran File transfer protocols are managed via the `fileTransferProtocols` configuration block of `config.hjson`. Each entry defines an **external** protocol handler that can be used for uploads (recv), downloads (send), or both. Depending on the protocol and handler, batch receiving of files (uploads) may also be available. ### Predefined File Transfer Protocols -The following file transfer protocols are pre-configured in ENiGMA½ as of this writing. System operators may override or extend this list. PRs are welcome for pre-configured additions! - +Please see [External Binaries](external-binaries.md) for a table of built in / predefined protocol handlers. You will need to have the binaries in ENiGMA's PATH. #### SEXYZ [SEXYZ from Synchronet](http://wiki.synchro.net/util:sexyz) offers a nice X, Y, and ZModem implementation including ZModem-8k & works under *nix and Windows based systems. As of this writing, ENiGMA½ is pre-configured to support ZModem-8k, XModem, and YModem using SEXYZ. An x86_64 Linux binary, and hopefully more in the future, [can be downloaded here](https://l33t.codes/bbs-linux-binaries/). diff --git a/docs/configuration/hjson.md b/docs/configuration/hjson.md index 7bfb8ddf..98aef757 100644 --- a/docs/configuration/hjson.md +++ b/docs/configuration/hjson.md @@ -40,7 +40,7 @@ See https://hjson.org/users.html for more more editors & plugins. ### Hot-Reload A.K.A. Live Editing ENiGMA½'s configuration, menu, and theme files can edited while your BBS is running. When a file is saved, it is hot-reloaded into the running system. If users are currently connected and you change a menu for example, the next reload of that menu will show the changes. -:information_source: See also [Configuration Files](/docs/configuration/config-files.md) +:information_source: See also [Configuration Files](../configuration/config-files.md) ### CaSe SeNsiTiVE Configuration keys are **case sensitive**. That means if a configuration key is `boardName` for example, `boardname`, or `BOARDNAME` **will not work**. diff --git a/docs/configuration/menu-hjson.md b/docs/configuration/menu-hjson.md index b3eb14ca..0c409d2f 100644 --- a/docs/configuration/menu-hjson.md +++ b/docs/configuration/menu-hjson.md @@ -20,7 +20,7 @@ showSomeArt: { config: { pause: true } } ``` -As you can see a menu can be very simple. +As you can see a menu can be very simple. :information_source: Remember that the top level menu may include additional files using the `includes` directive. See [Configuration Files](config-files.md) for more information on this. @@ -30,7 +30,7 @@ Below is a table of **common** menu entry members. These members apply to most e | Item | Description | |--------|--------------| | `desc` | A friendly description that can be found in places such as "Who's Online" or wherever the `%MD` MCI code is used. | -| `art` | An art file *spec*. See [General Art Information](/docs/art/general.md). | +| `art` | An art file *spec*. See [General Art Information](../art/general.md). | | `next` | Specifies the next menu entry to go to next. Can be explicit or an array of possibilities dependent on ACS. See **Flow Control** in the **ACS Checks** section below. If `next` is not supplied, the next menu is this menus parent. Note that special built in methods such as `@systemMethod:logoff` can also be utilized here. | | `prompt` | Specifies a prompt, by name, to use along with this menu. Prompts are configured in the `prompts` section. See **Prompts** for more information. | | `submit` | Defines a submit handler when using `prompt`. @@ -41,7 +41,7 @@ Below is a table of **common** menu entry members. These members apply to most e ### Menu Modules A given menu entry is backed by a *menu module*. That is, the code behind it. Menus are considered "standard" if the `module` member is not specified (and therefore backed by `core/standard_menu.js`). -See [Menu Modules](/docs/modding/menu-modules.md) for more information. +See [Menu Modules](../modding/menu-modules.md) for more information. ### Config Block The `config` block for a menu entry can contain common members as well as a per-module (when `module` is used) settings. @@ -51,8 +51,8 @@ The `config` block for a menu entry can contain common members as well as a per- | `cls` | If `true` the screen will be cleared before showing this menu. | | `pause` | If `true` a pause will occur after showing this menu. Useful for simple menus such as displaying art or status screens. | | `nextTimeout` | Sets the number of **milliseconds** before the system will automatically advanced to the `next` menu. | -| `baudRate` | See baud rate information in [General Art Information](/docs/art/general.md). | -| `font` | Sets a SyncTERM style font to use when displaying this menus `art`. See font listing in [General Art Information](/docs/art/general.md). | +| `baudRate` | See baud rate information in [General Art Information](../art/general.md). | +| `font` | Sets a SyncTERM style font to use when displaying this menus `art`. See font listing in [General Art Information](../art/general.md). | | `menuFlags` | An array of menu flag(s) controlling menu behavior. See **Menu Flags** below. #### Menu Flags @@ -70,7 +70,7 @@ ENiGMA½ uses a concept of *forms* in menus. A form is a collection of associate Menus may also support more than one layout type by using a *MCI key*. A MCI key is a alpha-numerically sorted key made from 1:n MCI codes. This lets the system choose the appropriate set of form(s) based on theme or random art. An example of this may be a matrix menu: Perhaps one style of your matrix uses a vertical light bar (`VM` key) while another uses a horizontal (`HM` key). The system can discover the correct form to use by matching MCI codes found in the art to that of the available forms defined in `menu.hjson`. -For more information on views and associated MCI codes, see [MCI Codes](/docs/art/mci.md). +For more information on views and associated MCI codes, see [MCI Codes](../art/mci.md). ## Submit Handlers When a form is submitted, it's data is matched against a *submit handler*. When a match is found, it's *action* is performed. @@ -135,7 +135,7 @@ telnetConnected: { ``` The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in the Telnet server's config). The entry sets up a few things: -* A `art` spec of `CONNECT`. (See [General Art Information](/docs/art/general.md)). +* A `art` spec of `CONNECT`. (See [General Art Information](../art/general.md)). * A `next` entry up the next menu, by name, in the stack (`matrix`) that we'll go to after `telnetConnected`. * An `config` block containing a single `nextTimeout` field telling the system to proceed to the `next` (`matrix`) entry automatically after 1500ms. diff --git a/docs/configuration/security.md b/docs/configuration/security.md index 8461a381..49870f17 100644 --- a/docs/configuration/security.md +++ b/docs/configuration/security.md @@ -11,9 +11,9 @@ Unlike in the golden era of BBSing, modern Internet-connected systems are prone ## Two-Factor Authentication via One-Time Password Enabling Two-Factor Authentication via One-Time-Password (2FA/OTP) on an account adds an extra layer of security ("_something a user has_") in addition to their password ("_something a user knows_"). Providing 2FA/OTP to your users has some prerequisites: -* [A configured email gateway](/docs/configuration/email.md) such that the system can send out emails. -* One or more secure servers enabled such as [SSH](/docs/servers/ssh.md) or secure [WebSockets](/docs/servers/websocket.md) (that is, WebSockets over a secure connection such as TLS). -* The [web server](/docs/servers/web-server.md) enabled and exposed over TLS (HTTPS). +* [A configured email gateway](../configuration/email.md) such that the system can send out emails. +* One or more secure servers enabled such as [SSH](../servers/ssh.md) or secure [WebSockets](../servers/websocket.md) (that is, WebSockets over a secure connection such as TLS). +* The [web server](../servers/web-server.md) enabled and exposed over TLS (HTTPS). :information_source: For WebSockets and the web server, ENiGMA½ _may_ listen on insecure channels if behind a secure web proxy. @@ -26,7 +26,7 @@ Due to the nature of 2FA/OTP, even if enabled on your system, users must opt-in :warning: Serving 2FA/OTP registration links over insecure (HTTP) can expose secrets intended for the user and is **highly** discouraged! -:memo: +ops can also manually enable or disable 2FA/OTP for a user using [oputil](/docs/admin/oputil.md), but this is generally discouraged. +:memo: +ops can also manually enable or disable 2FA/OTP for a user using [oputil](../admin/oputil.md), but this is generally discouraged. #### Recovery In the situation that a user loses their 2FA/OTP device (such as a lost phone with Google Auth), there are some options: @@ -36,11 +36,11 @@ In the situation that a user loses their 2FA/OTP device (such as a lost phone wi :warning: There is no way for a user to disable 2FA/OTP without first fully logging in! This is by design as a security measure. ### ACS Checks -Various places throughout the system that implement [ACS](/docs/configuration/acs.md) can make 2FA specific checks: +Various places throughout the system that implement [ACS](../configuration/acs.md) can make 2FA specific checks: * `AR#`: Current users **required** authentication factor. `AR2` for example means 2FA/OTP is required for this user. * `AF#`: Current users **active** authentication factor. `AF2` means the user is authenticated with some sort of 2FA (such as One-Time-Password). -See [ACS](/docs/configuration/acs.md) for more information. +See [ACS](../configuration/acs.md) for more information. #### Example The following example illustrates using an `AR` ACS check to require applicable users to go through an additional 2FA/OTP process during login: diff --git a/docs/filebase/acs.md b/docs/filebase/acs.md index 618c1843..4a886163 100644 --- a/docs/filebase/acs.md +++ b/docs/filebase/acs.md @@ -3,7 +3,7 @@ layout: page title: ACS --- ## File Base ACS -[ACS Codes](/docs/configuration/acs.md) may be used to control access to File Base areas by specifying an `acs` string in a file area's definition. If no `acs` is supplied in a file area definition, the following defaults apply to an area: +[ACS Codes](../configuration/acs.md) may be used to control access to File Base areas by specifying an `acs` string in a file area's definition. If no `acs` is supplied in a file area definition, the following defaults apply to an area: * `read` : `GM[users]`: List/view the area and it's contents. * `write` : `GM[sysops]`: Upload. * `download` : `GM[users]`: Download. @@ -28,4 +28,4 @@ areas: { ``` ## See Also -[Access Condition System (ACS)](/docs/configuration/acs.md) +[Access Condition System (ACS)](../configuration/acs.md) diff --git a/docs/filebase/first-file-area.md b/docs/filebase/first-file-area.md index c561b055..ae9e0fd2 100644 --- a/docs/filebase/first-file-area.md +++ b/docs/filebase/first-file-area.md @@ -84,16 +84,16 @@ fileBase: { ``` ## Importing Areas -Areas can also be imported using [oputil](/docs/admin/oputil.md) using proper FileGate "RAID" aka `FILEBONE.NA` style files. After importing areas, you may wish to tweak configuration such as better `desc` fields, ACS, or sorting. +Areas can also be imported using [oputil](../admin/oputil.md) using proper FileGate "RAID" aka `FILEBONE.NA` style files. After importing areas, you may wish to tweak configuration such as better `desc` fields, ACS, or sorting. ## Importing Files (Scan For New Files) -A common task is to *import* existing files to area(s). Consider a collection of retro BBS files in the area "Retro PC" (tag: `retro_pc` above) under the storage tag of `retro_pc_bbs`. You might choose to scan for new files in this area (and thus import new entries) as follows with [oputil](/docs/admin/oputil.md)'s `fb scan`: +A common task is to *import* existing files to area(s). Consider a collection of retro BBS files in the area "Retro PC" (tag: `retro_pc` above) under the storage tag of `retro_pc_bbs`. You might choose to scan for new files in this area (and thus import new entries) as follows with [oputil](../admin/oputil.md)'s `fb scan`: ```bash ./oputil.js fb scan --quick --tags retro,bbs,pc retro_pc@retro_pc_bbs ``` -Here we have asked [oputil](/docs/admin/oputil.md) to scan the file base area by it's tag `retro_pc` and only include the storage tag of `retro_pc_bbs`. Note that the storage tag could be omitted, and if so, all of `retro_pc` would be scanned. We have also indicated to #hashtag new entries with the tags "retro", "bbs", and "pc". +Here we have asked [oputil](../admin/oputil.md) to scan the file base area by it's tag `retro_pc` and only include the storage tag of `retro_pc_bbs`. Note that the storage tag could be omitted, and if so, all of `retro_pc` would be scanned. We have also indicated to #hashtag new entries with the tags "retro", "bbs", and "pc". -Please see [oputil](/docs/admin/oputil.md) for more information. +Please see [oputil](../admin/oputil.md) for more information. diff --git a/docs/filebase/tic-support.md b/docs/filebase/tic-support.md index 0970ef5e..e1d01ffb 100644 --- a/docs/filebase/tic-support.md +++ b/docs/filebase/tic-support.md @@ -98,4 +98,4 @@ ticAreas: { ``` ## See Also -[Message Networks](/docs/messageareas/message-networks.md) +[Message Networks](../messageareas/message-networks.md) diff --git a/docs/index.md b/docs/index.md index 1f5eba1d..1c374690 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ ENiGMA½ is a modern BBS software with a nostalgic flair! * [CP437](http://www.ascii-codes.com/) and UTF-8 output * [SyncTERM](http://syncterm.bbsdev.net/) style font and baud emulation support. Display PC/DOS and Amiga style artwork as it's intended! In general, ANSI-BBS / [cterm.txt](http://cvs.synchro.net/cgi-bin/viewcvs.cgi/*checkout*/src/conio/cterm.txt?content-type=text%2Fplain&revision=HEAD) / [bansi.txt](http://www.bbsdocumentary.com/library/PROGRAMS/GRAPHICS/ANSI/bansi.txt) are followed for expected BBS behavior. * Full [SAUCE](http://www.acid.org/info/sauce/sauce.htm) support. - * Renegade style [pipe color codes](/docs/configuration/colour-codes.md). + * Renegade style [pipe color codes](./configuration/colour-codes.md). * [SQLite](http://sqlite.org/) storage of users, message areas, etc. * Strong [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) backed password encryption. * Support for 2-Factor Authentication with One-Time-Passwords diff --git a/docs/installation/install-script.md b/docs/installation/install-script.md index e6a3a445..809d38db 100644 --- a/docs/installation/install-script.md +++ b/docs/installation/install-script.md @@ -9,10 +9,12 @@ Under most Linux/UNIX like environments (Linux, BSD, OS X, ...) new users can s curl -o- https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/install.sh | bash ``` -:heavy_check_mark: You may wish to review the [installation script](https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/install.sh) +:eyes: You may wish to review the [installation script](https://raw.githubusercontent.com/NuSkooler/enigma-bbs/master/misc/install.sh) on GitHub before running it! The script will install `nvm`, Node.js 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). +:information_source: After installing: +* Read [External Binaries](../configuration/external-binaries.md) +* Read [Updating](../admin/updating.md) diff --git a/docs/installation/installation-methods.md b/docs/installation/installation-methods.md index 1b2f64e4..38fa4975 100644 --- a/docs/installation/installation-methods.md +++ b/docs/installation/installation-methods.md @@ -15,4 +15,4 @@ There are multiple ways of installing ENiGMA BBS, depending on your level of exp :scroll: Check out [this awesome video on installation and basic configuration](https://youtu.be/WnN-ucVi3ZU) from Al's Geek Lab! ## Keeping Up To Date -After installing, you'll want to [keep your system updated](/docs/admin/updating.md). \ No newline at end of file +After installing, you'll want to [keep your system updated](../admin/updating.md). \ No newline at end of file diff --git a/docs/installation/manual.md b/docs/installation/manual.md index 2dcbfca7..cb463d81 100644 --- a/docs/installation/manual.md +++ b/docs/installation/manual.md @@ -50,23 +50,14 @@ npm install # yarn also works ``` ## Other Recommended Packages -ENiGMA BBS makes use of a few packages for archive and legacy protocol support. They're not pre-requisites for running ENiGMA, but without them you'll miss certain functionality. Once installed, they should be made available on your system path. +ENiGMA BBS makes use of a few packages for archive and legacy protocol support. They're not pre-requisites for running ENiGMA, but without them you'll miss certain functionality. Once installed, they should be made available on your systems `PATH`. -| Package | Description | Debian/Ubuntu Package (APT/DEP) | Red Hat Package (YUM/RPM) | Windows Package | -|------------|-----------------------------------|--------------------------------------------|---------------------------------------------------|------------------------------------------------------------------| -| arj | Unpacking arj archives | `arj` | n/a, binaries [here](http://arj.sourceforge.net/) | [ARJ](http://arj.sourceforge.net/) | -| 7zip | Unpacking zip, rar, archives | `p7zip-full` | `p7zip-full` | [7-zip](http://www.7-zip.org/) | -| lha | Unpacking lha archives | `lhasa` | n/a, source [here](https://web.archive.org/web/20200301124852/http://www2m.biglobe.ne.jp/~dolphin/lha/lha.htm) | Unknown | -| Rar | Unpacking rar archives | `unrar` | n/a, binaries [here](https://www.rarlab.com/download.htm) | Unknown | -| lrzsz | sz/rz: X/Y/Z protocol support | `lrzsz` | `lrzsz` | Unknown | -| sexyz | SexyZ protocol support | [sexyz](https://l33t.codes/outgoing/sexyz) | [sexyz](https://l33t.codes/outgoing/sexyz) | Available with [Synchronet](http://wiki.synchro.net/install:win) | -| exiftool | [ExifTool](https://www.sno.phy.queensu.ca/~phil/exiftool/) | libimage-exiftool-perl | perl-Image-ExifTool | Unknown -| xdms | Unpack/view Amiga DMS | [xdms](http://manpages.ubuntu.com/manpages/trusty/man1/xdms.1.html) | xdms | Unknown +:information_source: Please see [External Binaries](../configuration/external-binaries.md) for information on setting these up. -:information_source: Please see also [Archivers](/docs/configuration/archivers.md) and [File Transfer Protocols](/docs/configuration/file-transfer-protocols.md) for additional recommended binaries and configuration. +:information_source: Additional information in [Archivers](../configuration/archivers.md) and [File Transfer Protocols](../configuration/file-transfer-protocols.md) ## Config Files -You'll need a basic configuration to get started. The main system configuration is handled via `config/config.hjson`. This is an [HJSON](http://hjson.org/) file (compiliant JSON is also OK). See [Configuration](../configuration/) for more information. +You'll need a basic configuration to get started. The main system configuration is handled via `config/config.hjson`. This is an [HJSON](http://hjson.org/) file (compliant JSON is also OK). See [Configuration](../configuration/) for more information. Use `oputil.js` to generate your **initial** configuration: diff --git a/docs/messageareas/bso-import-export.md b/docs/messageareas/bso-import-export.md index a7c49c10..bf6ecc03 100644 --- a/docs/messageareas/bso-import-export.md +++ b/docs/messageareas/bso-import-export.md @@ -5,7 +5,7 @@ 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. +: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: @@ -27,7 +27,7 @@ A node entry starts with a [FTN address](http://ftsc.org/docs/old/fsp-1028.001) | Config Item | Required | Description | |------------------|----------|---------------------------------------------------------------------------------| -| `packetType` | :-1: | `2`, `2.2`, or `2+`. Defaults to `2+` for modern mailer compatiability. | +| `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. | @@ -134,7 +134,68 @@ scannerTossers: { ``` ## Binkd -Since Binkd is a very common mailer, a few tips on integrating it with ENiGMA½: +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: @@ -163,4 +224,5 @@ eventScheduler: { ``` ## 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! +* [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. \ No newline at end of file diff --git a/docs/messageareas/configuring-a-message-area.md b/docs/messageareas/configuring-a-message-area.md index 74c7dcb5..b8d3f5a5 100644 --- a/docs/messageareas/configuring-a-message-area.md +++ b/docs/messageareas/configuring-a-message-area.md @@ -19,10 +19,10 @@ Each conference is represented by a entry under `messageConferences`. Each entri | `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](/docs/configuration/acs.md) block. See **ACS** below. | +| `acs` | :-1: | A standard [ACS](../configuration/acs.md) block. See **ACS** below. | ### ACS -An optional standard [ACS](/docs/configuration/acs.md) block can be supplied with the following rules: +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]`. @@ -53,12 +53,12 @@ Message Areas are topic specific containers for messages that live within a part | `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](/docs/configuration/acs.md) block. See **ACS** below. | +| `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](/docs/configuration/acs.md) block can be supplied with the following rules: +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]`. @@ -85,4 +85,4 @@ messageConferences: { ``` ## 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](/docs/admin/oputil.md) for more information and usage. +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. diff --git a/docs/messageareas/ftn.md b/docs/messageareas/ftn.md index f3d1237a..794b76c2 100644 --- a/docs/messageareas/ftn.md +++ b/docs/messageareas/ftn.md @@ -70,7 +70,7 @@ Example: } ``` -:bulb: You can import `AREAS.BBS` or FTN style `.NA` files using [oputil](/docs/admin/oputil.md)! +: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: diff --git a/docs/messageareas/qwk.md b/docs/messageareas/qwk.md index 964551a3..140180f5 100644 --- a/docs/messageareas/qwk.md +++ b/docs/messageareas/qwk.md @@ -34,7 +34,7 @@ Example: ``` ### oputil -The `oputil.js` utility can export packet files, dump the messages of a packet to stdout, etc. See [the oputil documentation](/docs/admin/oputil.md) for more information. +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½: diff --git a/docs/misc/user-interrupt.md b/docs/misc/user-interrupt.md index fe20fdd9..4afcd8d8 100644 --- a/docs/misc/user-interrupt.md +++ b/docs/misc/user-interrupt.md @@ -3,7 +3,7 @@ layout: page title: User Interruptions --- ## User Interruptions -ENiGMA½ provides functionality to "interrupt" a user for various purposes such as a [node-to-node message](/docs/modding/node-msg.md). User interruptions can be queued and displayed at the next opportune time such as when switching to a new menu, or realtime if appropriate. +ENiGMA½ provides functionality to "interrupt" a user for various purposes such as a [node-to-node message](../modding/node-msg.md). User interruptions can be queued and displayed at the next opportune time such as when switching to a new menu, or realtime if appropriate. ## Standard Menu Behavior Standard menus control interruption by the `interrupt` config block option, which may be set to one of the following values: diff --git a/docs/modding/node-msg.md b/docs/modding/node-msg.md index 5377e68a..8a89ef5f 100644 --- a/docs/modding/node-msg.md +++ b/docs/modding/node-msg.md @@ -3,7 +3,7 @@ layout: page title: Node to Node Messaging --- ## The Node to Node Messaging Module -The node to node messaging (`node_msg`) module allows users to send messages to one or more users on different nodes. Messages delivered to nodes follow standard [User Interruption](/docs/misc/user-interrupt.md) rules. +The node to node messaging (`node_msg`) module allows users to send messages to one or more users on different nodes. Messages delivered to nodes follow standard [User Interruption](../misc/user-interrupt.md) rules. ## Configuration ### Config Block diff --git a/docs/modding/telnet-bridge.md b/docs/modding/telnet-bridge.md index 36e1b3e6..3e091b5e 100644 --- a/docs/modding/telnet-bridge.md +++ b/docs/modding/telnet-bridge.md @@ -10,7 +10,7 @@ The `telnet_bridge` module allows "bridged" Telnet connections from your board t Available `config` entries: * `host`: Hostname or IP address to connect to. * `port`: Port to connect to. Defaults to the standard Telnet port of `23`. -* `font`: A SyncTERM style font. Useful for example if you would like to connect form a "DOS" style BBS to an Amiga. See [the general art documentation on SyncTERM Style Fonts](/docs/art/general.md). +* `font`: A SyncTERM style font. Useful for example if you would like to connect form a "DOS" style BBS to an Amiga. See [the general art documentation on SyncTERM Style Fonts](../art/general.md). ### Example Below is an example `menu.hjson` entry that would connect to [Xibalba](https://xibalba.l33t.codes): diff --git a/docs/modding/top-x.md b/docs/modding/top-x.md index 41ac5ab7..dc2b319b 100644 --- a/docs/modding/top-x.md +++ b/docs/modding/top-x.md @@ -57,4 +57,4 @@ Generally `mciMap` entries will point to a Vertical List View Menu (`%VM1`, `%VM * `affils` or `affiliation`: Users affiliations. * `position`: Rank position (numeric). -Remember that string format rules apply, so for example, if displaying top uploaded bytes (`ul_file_bytes`), a `itemFormat` may be `{userName} - {value!sizeWithAbbr}` yielding something like "TopDude - 4 GB". See [MCI](/docs/art/mci.md) for additional information. +Remember that string format rules apply, so for example, if displaying top uploaded bytes (`ul_file_bytes`), a `itemFormat` may be `{userName} - {value!sizeWithAbbr}` yielding something like "TopDude - 4 GB". See [MCI](../art/mci.md) for additional information. diff --git a/docs/modding/user-2fa-otp-config.md b/docs/modding/user-2fa-otp-config.md index 7b41939f..4ef12687 100644 --- a/docs/modding/user-2fa-otp-config.md +++ b/docs/modding/user-2fa-otp-config.md @@ -3,7 +3,7 @@ layout: page title: TopX --- ## The 2FA/OTP Config Module -The `user_2fa_otp_config` module provides opt-in, configuration, and viewing of Two-Factor Authentication via One-Time-Password (2FA/OTP) settings. In order to allow users access to 2FA/OTP, the system must be properly configured. See [Security](/docs/configuration/security.md) for more information. +The `user_2fa_otp_config` module provides opt-in, configuration, and viewing of Two-Factor Authentication via One-Time-Password (2FA/OTP) settings. In order to allow users access to 2FA/OTP, the system must be properly configured. See [Security](../configuration/security.md) for more information. :information_source: By default, the 2FA/OTP configuration menu may only be accessed by users connected securely (ACS `SC`). It is highly recommended to leave this default as accessing these settings over a plain-text connection could expose private secrets!