diff --git a/README.md b/README.md index 3a2cc7c3..7c1870ce 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # ENiGMA½ BBS Software -![ENiGMA½ BBS](docs/images/enigma-bbs.png "ENiGMA½ BBS") +![ENiGMA½ BBS](docs/assets/images/enigma-bbs.png "ENiGMA½ BBS") ENiGMA½ is a modern BBS software with a nostalgic flair! diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md index c8af1abc..168e1cf5 100644 --- a/docs/_includes/nav.md +++ b/docs/_includes/nav.md @@ -16,11 +16,15 @@ - [Editing hjson]({{ site.baseurl }}{% link configuration/editing-hjson.md %}) - [config.hjson]({{ site.baseurl }}{% link configuration/config-hjson.md %}) - [menu.hjson]({{ site.baseurl }}{% link configuration/menu-hjson.md %}) - - prompt.hjson + - [prompt.hjson]({{ site.baseurl }}{% link configuration/prompt-hjson.md %}) - [Directory Structure]({{ site.baseurl }}{% link configuration/directory-structure.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 %}) + - [Colour Codes]({{ site.baseurl }}{% link configuration/colour-codes.md %}) + - [Access Condition System (ACS)]({{ site.baseurl }}{% link configuration/acs.md %}) - Scheduled jobs - - SMTP + - File Base - [About]({{ site.baseurl }}{% link filebase/index.md %}) @@ -30,7 +34,7 @@ - [Web Access]({{ site.baseurl }}{% link filebase/web-access.md %}) - [TIC Support]({{ site.baseurl }}{% link filebase/tic-support.md %}) (Importing from FTN networks) - Tips and tricks - - Network mounts and symlinks + - [Network mounts and symlinks]({{ site.baseurl }}{% link filebase/network-mounts-and-symlinks.md %}) - Message Areas - [Configuring a Message Area]({{ site.baseurl }}{% link messageareas/configuring-a-message-area.md %}) diff --git a/docs/assets/images/colour-codes.png b/docs/assets/images/colour-codes.png new file mode 100644 index 00000000..83267a62 Binary files /dev/null and b/docs/assets/images/colour-codes.png differ diff --git a/docs/images/enigma-bbs.png b/docs/assets/images/enigma-bbs.png similarity index 100% rename from docs/images/enigma-bbs.png rename to docs/assets/images/enigma-bbs.png diff --git a/docs/images/vtxclient.png b/docs/assets/images/vtxclient.png similarity index 100% rename from docs/images/vtxclient.png rename to docs/assets/images/vtxclient.png diff --git a/docs/configuration/colour-codes.md b/docs/configuration/colour-codes.md new file mode 100644 index 00000000..9ad9abdd --- /dev/null +++ b/docs/configuration/colour-codes.md @@ -0,0 +1,25 @@ +--- +layout: page +title: Colour Codes +--- +ENiGMA½ supports Renegade-style pipe colour codes for formatting strings. You'll see them used in [`config.hjson`](config-hjson), +[`prompt.hjson`](prompt-hjson), [`menu.hjson`](menu-hjson), and can also be used in places like the oneliner, rumour mod, +full screen editor etc. + +## Usage +When ENiGMA½ encounters colour codes in strings, they'll be processed in order and combined where possible. + +For example: + +`|15|17Example` - white text on a blue background + +`|10|23Example` - light green text on a light grey background + + +## Colour Code Reference + +:warning: Colour codes |24 to |31 are considered "blinking" or "iCE" colour codes. On terminals that support them they'll +be shown as the correct colours - for terminals that don't, or are that are set to "blinking" mode - they'll blink! + +![Regegade style colour codes](../assets/images/colour-codes.png "Colour Codes") + diff --git a/docs/configuration/editing-hjson.md b/docs/configuration/editing-hjson.md index fde61290..0a752178 100644 --- a/docs/configuration/editing-hjson.md +++ b/docs/configuration/editing-hjson.md @@ -14,3 +14,7 @@ You can find more info at the [Hjson.org website](http://hjson.org/). within the IDE. It provides syntax highlighting to make it clear when you've made a syntax mistake within a config file. +### Notepad++ + +[Notepad++](https://notepad-plus-plus.org) has an Hjson plugin that provides syntax highlighting and other +usual text editor features. The plugin can be found [here](https://github.com/laktak/npp-hjson). \ No newline at end of file diff --git a/docs/configuration/email.md b/docs/configuration/email.md new file mode 100644 index 00000000..1677eb11 --- /dev/null +++ b/docs/configuration/email.md @@ -0,0 +1,30 @@ +--- +layout: page +title: Email +--- +ENiGMA½ uses email to send password reset information to users. For it to work, you need to provide valid SMTP +config in your [config.hjson]({{ site.baseurl }}{% link configuration/config-hjson.md %}) + +## SMTP Services + +If you don't have an SMTP server to send from, [Sendgrid](https://sendgrid.com/) provide a reliable free +service. + +## Example SMTP Configuration + +```hjson +email: { + defaultFrom: sysop@bbs.awesome.com + + transport: { + host: smtp.awesomeserver.com + port: 587 + secure: false + auth: { + user: leisuresuitlarry + pass: sierra123 + } + } + } +} +``` \ No newline at end of file diff --git a/docs/configuration/file-transfer-protocols.md b/docs/configuration/file-transfer-protocols.md new file mode 100644 index 00000000..da5697c7 --- /dev/null +++ b/docs/configuration/file-transfer-protocols.md @@ -0,0 +1,49 @@ +--- +layout: page +title: File Transfer Protocols +--- +ENiGMA½ currently relies on external executables for "legacy" file transfer protocols such as X, Y, and ZModem. The `fileTransferProtocols` section of `config.hjson` is used to override defaults, add new handlers, etc. Remember that ENiGMA½ also support modern web (HTTP/HTTPS) downloads! + +## File Transfer Protocols +File transfer protocols are managed via the `fileTransferProtocols` configuration block of `config.hjson`. Each entry defines an **external** protocol 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! + +#### 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](http://132.0.0.249/bbs-linux-binaries/). + +#### sz/rz +ZModem-8k is configured using the standard Linux [sz(1)](https://linux.die.net/man/1/sz) and [rz(1)](https://linux.die.net/man/1/rz) binaries. Note that these binaries also support XModem and YModem, and as such adding the configurations to your system should be fairly straight forward. + +Generally available as `lrzsz` under Apt or Yum type packaging. + +### File Transfer Protocol Configuration +The following top-level members are available to an external protocol configuration: +* `name`: Required; Display name of the protocol +* `type`: Required; Currently must be `external`. This will be expanded upon in the future with built in protocols. +* `sort`: Optional; Sort key. If not provided, `name` will be used for sorting. + +For protocols of type `external` the following members may be defined: +* `sendCmd`: Required for protocols that can send (allow user downloads); The command/binary to execute. +* `sendArgs`: Required if using `sendCmd`; An array of arguments. A placeholder of `{fileListPath}` may be used to supply a path to a **file containing** a list of files to send, or `{filePaths}` to supply *1:n* individual file paths to send. +* `recvCmd`: Required for protocols that can receive (allow user uploads); The command/binary to execute. +* `recvArgs`: Required if using `recvCmd` and supporting **batch** uploads; An array of arguments. A placeholder of `{uploadDir}` may be used to supply the system provided upload directory. If `{uploadDir}` is not present, the system expects uploaded files to be placed in CWD which will be set to the upload directory. +* `recvArgsNonBatch`: Required if using `recvCmd` and supporting non-batch (single file) uploads; A placeholder of `{fileName}` may be supplied to indicate to the protocol what the uploaded file should be named (this will be collected from the user before the upload starts). +* `escapeTelnet`: Optional; If set to `true`, escape all internal Telnet related codes such as IAC's. This option is required for external protocol handlers such as `sz` and `rz` that do not escape themselves. + +#### Example File Transfer Protocol Configuration +``` +zmodem8kSexyz : { + name : 'ZModem 8k (SEXYZ)', + type : 'external', + sort : 1, + external : { + sendCmd : 'sexyz', + sendArgs : [ '-telnet', '-8', 'sz', '@{fileListPath}' ], + recvCmd : 'sexyz', + recvArgs : [ '-telnet', '-8', 'rz', '{uploadDir}' ], + recvArgsNonBatch : [ '-telnet', '-8', 'rz', '{fileName}' ], + } +} +``` \ No newline at end of file diff --git a/docs/configuration/prompt-hjson.md b/docs/configuration/prompt-hjson.md new file mode 100644 index 00000000..7b7a3ab5 --- /dev/null +++ b/docs/configuration/prompt-hjson.md @@ -0,0 +1,6 @@ +--- +layout: page +title: prompt.hjson +--- +:zap: This page is to describe general information the `prompt.hjson` file. It +needs fleshing out, please submit a PR if you'd like to help! \ No newline at end of file diff --git a/docs/filebase/first-file-area.md b/docs/filebase/first-file-area.md index 58d4a5c1..5e83e8d7 100644 --- a/docs/filebase/first-file-area.md +++ b/docs/filebase/first-file-area.md @@ -3,13 +3,13 @@ layout: page title: Configuring a File Base --- ## ENiGMA½ File Base Key Concepts -Like many things in ENiGMA½, configuration of file base(s) is handled via `config.hjson` -- specifically -in the `fileBase` section. First, there are a couple of concepts you should understand. +Like many things in ENiGMA½, configuration of file base(s) is handled via `config.hjson` — specifically +in the `fileBase` section. First, there are a couple of concepts you should understand: ### Storage tags -**Storage Tags** define paths to a physical (file) storage locations that are referenced in a +**Storage Tags** define paths to physical (file) storage locations that are referenced in a file *Area* entry. Each entry may be either a fully qualified path or a relative path. Relative paths are relative to the value set by the `areaStoragePrefix` key (defaults to `