mirror of
https://github.com/NuSkooler/enigma-bbs.git
synced 2025-08-04 17:01:33 +02:00
* Docs theme to match ENiGMA website
* New docs layout ready for github pages serving * Tonnes of new docs * Update gitignore * Probably other stuff too
This commit is contained in:
David Stephens
parent
06ea2d1600
commit
26849ba4fa
62 changed files with 1974 additions and 810 deletions
77
docs/configuration/archivers.md
Normal file
77
docs/configuration/archivers.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
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
|
||||
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, .zip, .gzip/.gz, and more
|
||||
* Key: `7Zip`
|
||||
* Homepage/package: [7-zip.org](http://www.7-zip.org/). Generally obtained from a `p7zip` package in *nix environments. See http://p7zip.sourceforge.net/ for details.
|
||||
|
||||
#### Lha
|
||||
* Formats: <a href="https://en.wikipedia.org/wiki/LHA_(file_format)">LHA</a> files such as .lzh.
|
||||
* Key: `Lha`
|
||||
* Homepage/package: `lhasa` on most *nix environments. See also https://fragglet.github.io/lhasa/ and http://www2m.biglobe.ne.jp/~dolphin/lha/lha-unix.htm
|
||||
|
||||
#### Arj
|
||||
* Formats: .arj
|
||||
* Key: `Arj`
|
||||
* Homepage/package: `arj` on most *nix environments.
|
||||
|
||||
#### Rar
|
||||
* Formats: .Rar
|
||||
* Key: `Rar`
|
||||
* Homepage/package: `unrar` on most *nix environments. See also https://blog.hostonnet.com/unrar
|
||||
|
||||
### 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:
|
||||
|
||||
* `{archivePath}` (all): Path to the archive
|
||||
* `{fileList}` (compress, extract): List of file(s) to compress or extract
|
||||
* `{extractPath}` (decompress, extract): Path to extract *to*
|
||||
|
||||
For `list` commands, the `entryMatch` key must be provided. This key should provide a regular expression that matches two sub groups: One for uncompressed file byte sizes (sub group 1) and the other for file names (sub group 2). An optional `entryGroupOrder` can be supplied to change the default sub group order.
|
||||
|
||||
#### Example Archiver Configuration
|
||||
```
|
||||
7Zip: {
|
||||
compress: {
|
||||
cmd: 7za,
|
||||
args: [ "a", "-tzip", "{archivePath}", "{fileList}" ]
|
||||
}
|
||||
decompress: {
|
||||
cmd: 7za,
|
||||
args: [ "e", "-o{extractPath}", "{archivePath}" ]
|
||||
}
|
||||
list: {
|
||||
cmd: 7za,
|
||||
args: [ "l", "{archivePath}" ]
|
||||
entryMatch: "^[0-9]{4}-[0-9]{2}-[0-9]{2}\\s[0-9]{2}:[0-9]{2}:[0-9]{2}\\s[A-Za-z\\.]{5}\\s+([0-9]+)\\s+[0-9]+\\s+([^\\r\\n]+)$",
|
||||
}
|
||||
extract: {
|
||||
cmd: 7za,
|
||||
args [ "e", "-o{extractPath}", "{archivePath}", "{fileList}" ]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Archive Formats
|
||||
Archive formats can be defined such that ENiGMA½ can detect them by signature or extension, then utilize the correct *archiver* to process them. Formats are defined in the `archives:formats` key in `config.hjson`. Many differnet types come pre-configured (see `core/config.js`).
|
||||
|
||||
### Example Archive Format Configuration
|
||||
```
|
||||
zip: {
|
||||
sig: "504b0304" /* byte signature in HEX */
|
||||
offset: 0
|
||||
exts: [ "zip" ]
|
||||
handler: 7Zip /* points to a defined archiver */
|
||||
desc: "ZIP Archive"
|
||||
}
|
||||
```
|
||||
122
docs/configuration/config-hjson.md
Normal file
122
docs/configuration/config-hjson.md
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
---
|
||||
layout: page
|
||||
title: config.hjson
|
||||
---
|
||||
## System Configuration
|
||||
The main system configuration file, `config.hjson` both overrides defaults and provides additional configuration such as message areas. The default path is `/enigma-bbs-install-path/config/config.hjson` though you can override the `config.hjson` location with the `--config` parameter when invoking `main.js`. Values found in `core/config.js` may be overridden by simply providing the object members you wish replace.
|
||||
|
||||
### Creating a Configuration
|
||||
Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your enigma-bbs root directory:
|
||||
```
|
||||
./oputil.js config new
|
||||
```
|
||||
|
||||
You will be asked a series of questions to create an initial configuration.
|
||||
|
||||
### Overriding Defaults
|
||||
The file `core/config.js` provides various defaults to the system that you can override via `config.hjson`. For example, the default system name is defined as follows:
|
||||
```javascript
|
||||
general : {
|
||||
boardName : 'Another Fine ENiGMA½ System'
|
||||
}
|
||||
```
|
||||
|
||||
To override this for your own board, in `config.hjson`:
|
||||
```hjson
|
||||
general: {
|
||||
boardName: Super Fancy BBS
|
||||
}
|
||||
```
|
||||
|
||||
(Note the very slightly different syntax. **You can use standard JSON if you wish**)
|
||||
|
||||
While not everything that is available in your `config.hjson` file can be found defaulted in `core/config.js`, a lot is. [Poke around and see what you can find](https://github.com/NuSkooler/enigma-bbs/blob/master/core/config.js)!
|
||||
|
||||
|
||||
### A Sample Configuration
|
||||
Below is a **sample** `config.hjson` illustrating various (but certainly not all!) elements that can be configured / tweaked.
|
||||
|
||||
**This is for illustration purposes! Do not cut & paste this configuration!**
|
||||
|
||||
|
||||
```hjson
|
||||
{
|
||||
general: {
|
||||
boardName: A Sample BBS
|
||||
menuFile: "your_bbs.hjson" // copy of menu.hjson file (and adapt to your needs)
|
||||
}
|
||||
|
||||
defaults: {
|
||||
theme: "super-fancy-theme" // default-assigned theme (for new users)
|
||||
}
|
||||
|
||||
preLoginTheme: "luciano_blocktronics" // theme used before a user logs in (matrix, NUA, etc.)
|
||||
|
||||
messageConferences: {
|
||||
local_general: {
|
||||
name: Local
|
||||
desc: Local Discussions
|
||||
default: true
|
||||
|
||||
areas: {
|
||||
local_enigma_dev: {
|
||||
name: ENiGMA 1/2 Development
|
||||
desc: Discussion related to development and features of ENiGMA 1/2!
|
||||
default: true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
agoranet: {
|
||||
name: Agoranet
|
||||
desc: This network is for blatant exploitation of the greatest BBS scene art group ever.. ACiD.
|
||||
|
||||
areas: {
|
||||
agoranet_bbs: {
|
||||
name: BBS Discussion
|
||||
desc: Discussion related to BBSs
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
messageNetworks: {
|
||||
ftn: {
|
||||
areas: {
|
||||
agoranet_bbs: { /* hey kids, this matches above! */
|
||||
|
||||
// oh oh oh, and this one pairs up with a network below
|
||||
network: agoranet
|
||||
tag: AGN_BBS
|
||||
uplinks: "46:1/100"
|
||||
}
|
||||
}
|
||||
|
||||
networks: {
|
||||
agoranet: {
|
||||
localAddress: "46:3/102"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
scannerTossers: {
|
||||
ftn_bso: {
|
||||
schedule: {
|
||||
import: every 1 hours or @watch:/home/enigma/bink/watchfile.txt
|
||||
export: every 1 hours or @immediate
|
||||
}
|
||||
|
||||
defaultZone: 46
|
||||
defaultNetwork: agoranet
|
||||
|
||||
nodes: {
|
||||
"46:*": {
|
||||
archiveType: ZIP
|
||||
encoding: utf8
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
27
docs/configuration/creating-config.md
Normal file
27
docs/configuration/creating-config.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
layout: page
|
||||
title: Creating Initial Config Files
|
||||
---
|
||||
Configuration files in ENiGMA½ are simple UTF-8 encoded [HJSON](http://hjson.org/) files. HJSON is just
|
||||
like JSON but simplified and much more resilient to human error.
|
||||
|
||||
## config.hjson
|
||||
Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your
|
||||
enigma-bbs root directory:
|
||||
```
|
||||
./oputil.js config new
|
||||
```
|
||||
|
||||
You will be asked a series of questions to create an initial configuration.
|
||||
|
||||
## menu.hjson and prompt.hjson
|
||||
|
||||
Create your own copy of `/config/menu.hjson` and `/config/prompt.hjson`, and specify it in the
|
||||
`general` section of `config.hjson`:
|
||||
|
||||
````hjson
|
||||
general: {
|
||||
menuFile: my-menu.hjson
|
||||
promptFile: my-prompt.hjson
|
||||
}
|
||||
````
|
||||
20
docs/configuration/directory-structure.md
Normal file
20
docs/configuration/directory-structure.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
layout: page
|
||||
title: Directory Structure
|
||||
---
|
||||
All paths mentioned here are relative to the ENiGMA½ checkout directory.
|
||||
|
||||
| Directory | Description |
|
||||
|---------------------|-----------------------------------------------------------------------------------------------------------|
|
||||
| `/art/general` | Non-theme art - welcome ANSI, logoff ANSI, etc. See [General Art](/art/general).
|
||||
| `/art/themes` | Theme art. Themes should be in their own subdirectory and contain a theme.hjson. See [Themes](/art/themes).
|
||||
| `/config` | config.hjson, [menu.hjson](/configuration/menu-hjson) and prompt.hjson storage. Also default path for SSL certs and public/private keys
|
||||
| `/db` | All ENiGMA½ databases in Sqlite3 format
|
||||
| `/docs` | These docs ;-)
|
||||
| `/dropfiles` | Dropfiles created for [local doors](/modding/local-doors)
|
||||
| `/logs` | Logs. See [Monitoring Logs](/troubleshooting/monitoring-logs)
|
||||
| `/misc` | Stuff with no other home; reset password templates, common password lists, other random bits
|
||||
| `/mods` | User mods. See [Modding](/modding/existing-mods)
|
||||
| `/node_modules` | External libraries required by ENiGMA½, installed when you run `npm install`
|
||||
| `/util` | Various tools used in running/debugging ENiGMA½
|
||||
| `/www` | ENiGMA½'s built in webserver root directory
|
||||
16
docs/configuration/editing-hjson.md
Normal file
16
docs/configuration/editing-hjson.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
layout: page
|
||||
title: Editing Hjson
|
||||
---
|
||||
Hjson is a syntax extension to JSON. It's NOT a proposal to replace JSON or to incorporate it into the JSON spec itself.
|
||||
It's intended to be used like a user interface for humans, to read and edit before passing the JSON data to the machine.
|
||||
|
||||
You can find more info at the [Hjson.org website](http://hjson.org/).
|
||||
|
||||
## Editor Plugins
|
||||
### Visual Studio Code
|
||||
|
||||
[Visual Studio Code](https://code.visualstudio.com/) has a nice Hjson extension that can be installed from
|
||||
within the IDE. It provides syntax highlighting to make it clear when you've made a syntax mistake within
|
||||
a config file.
|
||||
|
||||
101
docs/configuration/menu-hjson.md
Normal file
101
docs/configuration/menu-hjson.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
layout: page
|
||||
title: menu.hjson
|
||||
---
|
||||
:warning: ***IMPORTANT!*** Before making any customisations, create your own copy of `/config/menu.hjson`, and specify it in the
|
||||
`general` section of `config.hjson`:
|
||||
|
||||
````hjson
|
||||
general: {
|
||||
menuFile: my-menu.hjson
|
||||
}
|
||||
````
|
||||
This document and others will refer to `menu.hjson`. This should be seen as an alias to `yourboardname.hjson`
|
||||
|
||||
## The Basics
|
||||
Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format.
|
||||
|
||||
Entries in `menu.hjson` are objects defining a menu. A menu in this sense is something the user can see
|
||||
or visit. Examples include but are not limited to:
|
||||
|
||||
* Classical Main, Messages, and File menus
|
||||
* Art file display
|
||||
* Module driven menus such as door launchers
|
||||
|
||||
|
||||
Each entry in `menu.hjson` defines an object that represents a menu. These objects live within the `menus`
|
||||
parent object. Each object's *key* is a menu name you can reference within other menus in the system.
|
||||
|
||||
## Example
|
||||
Let's look a couple basic menu entries:
|
||||
|
||||
```hjson
|
||||
telnetConnected: {
|
||||
art: CONNECT
|
||||
next: matrix
|
||||
options: { nextTimeout: 1500 }
|
||||
}
|
||||
```
|
||||
|
||||
The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in
|
||||
the Telnet server's config).
|
||||
|
||||
An art pattern of `CONNECT` is set telling the system to look for `CONNECT<n>.*` where `<n>` represents
|
||||
a optional integer in art files to cause randomness, e.g. `CONNECT1.ANS`, `CONNECT2.ANS`, and so on. If
|
||||
desired, you can also be explicit by supplying a full filename with an extention such as `CONNECT.ANS`.
|
||||
|
||||
The entry `next` sets up the next menu, by name, in the stack (`matrix`) that we'll go to after
|
||||
`telnetConnected`.
|
||||
|
||||
Finally, an `options` object may contain various common options for menus. In this case, `nextTimeout`
|
||||
tells the system to proceed to the `next` entry automatically after 1500ms.
|
||||
|
||||
Now let's look at `matrix`, the `next` entry from `telnetConnected`:
|
||||
|
||||
```hjson
|
||||
matrix: {
|
||||
art: matrix
|
||||
desc: Login Matrix
|
||||
form: {
|
||||
0: {
|
||||
VM: {
|
||||
mci: {
|
||||
VM1: {
|
||||
submit: true
|
||||
focus: true
|
||||
items: [ "login", "apply", "log off" ]
|
||||
argName: matrixSubmit
|
||||
}
|
||||
}
|
||||
submit: {
|
||||
*: [
|
||||
{
|
||||
value: { matrixSubmit: 0 }
|
||||
action: @menu:login
|
||||
}
|
||||
{
|
||||
value: { matrixSubmit: 1 },
|
||||
action: @menu:newUserApplication
|
||||
}
|
||||
{
|
||||
value: { matrixSubmit: 2 },
|
||||
action: @menu:logoff
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the above entry, you'll notice `form`. This defines a form(s) object. In this case, a single form
|
||||
by ID of `0`. The system is then told to use a block only when the resulting art provides a `VM`
|
||||
(*VerticalMenuView*) MCI entry. `VM1` is then setup to `submit` and start focused via `focus: true`
|
||||
as well as have some menu entries ("login", "apply", ...) defined. We provide an `argName` for this
|
||||
action as `matrixSubmit`.
|
||||
|
||||
The `submit` object tells the system to attempt to apply provided match entries from any view ID (`*`).
|
||||
Upon submit, the first match will be executed. For example, if the user selects "login", the first entry
|
||||
with a value of `{ matrixSubmit: 0 }` will match causing `action` of `@menu:login` to be executed (go
|
||||
to `login` menu).
|
||||
6
docs/configuration/sysop-setup.md
Normal file
6
docs/configuration/sysop-setup.md
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
layout: page
|
||||
title: SysOp Setup
|
||||
---
|
||||
SySop privileges will be granted to the first user to log into a fresh ENiGMA½ installation.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue