crichardson/enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Automatically generate the navigation

Browse Source
This commit is contained in:
Nathan Byrd
2022-02-04 08:51:03 -06:00
parent 4793ad0492
commit b5b0cc3ac5
94 changed files with 236 additions and 335 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/_docs/filebase/acs.md Normal file
View File

@@ -0,0 +1,31 @@
---
layout: page
title: ACS
---
## File Base ACS
[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.
To override read and/or write ACS, supply a valid `acs` member.
## Example File Area Config with ACS
```hjson
areas: {
retro_pc: {
name: Retro PC
desc: Oldschool PC/DOS
storageTags: [ "retro_pc", "retro_pc_bbs" ]
acs: {
// only users of the "l33t" group or those who have
// uploaded 10+ files can download from here...
download: GM[l33t]|UP10
}
}
}
```
## See Also
[Access Condition System (ACS)](../configuration/acs.md)

101
docs/_docs/filebase/first-file-area.md Normal file
View File

@@ -0,0 +1,101 @@
---
layout: page
title: Configuring a File Base
---
## Configuring a File Base
ENiGMA½ offers a powerful and flexible file base. Configuration of file the file base and areas is handled via the `fileBase` section of `config.hjson`.
## ENiGMA½ File Base Key Concepts
First, there are some core concepts you should understand:
* Storage Tags
* Area Tags
### Storage Tags
*Storage Tags* define paths to physical (filesystem) 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 `fileBase.areaStoragePrefix` key (defaults to `/path/to/enigma-bbs/file_base`).
Below is an example defining some storage tags using the relative and fully qualified forms:
```hjson
storageTags: {
retro_pc_dos: "dos" // relative
retro_pc_bbs: "pc/bbs" // still relative!
bbs_stuff: "/path/to/bbs_stuff_storage" // fully qualified
}
```
:memo: On their own, storage tags don't do anything — they are simply pointers to storage locations on your system.
:warning: Remember that paths are case sensitive on most non-Windows systems!
### Areas
File base *Areas* are configured using the `fileBase.areas` configuration block in `config.hjson`. Each entry's block starts with an *area tag*. Valid members for an area are as follows:
| Item | Required | Description |
|--------|---------------|------------------|
| `name` | :+1: | Friendly area name. |
| `desc` | :-1: | Friendly area description. |
| `storageTags` | :+1: | An array of storage tags for physical storage backing of the files in this area. If uploads are enabled for this area, **first** storage tag location is utilized! |
| `sort` | :-1: | If present, provides the sort key for ordering. `name` is used otherwise. |
| `hashTags` | :-1: | Set to an array of strings or comma separated list to provide _default_ hash tags for this area. |
Example areas section:
```hjson
areas: {
retro_pc: { // an area tag!
name: Retro PC
desc: Oldschool PC/DOS
storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
hashTags: ["retro", "pc", "dos" ]
}
}
```
The above example defines an area called "Retro PC" which is referenced via the *area tag* of `retro_pc`. Two storage tags are used: `retro_pc_dos`, and `retro_pc_bbs`. These storage tags can be seen in the Storage Tags example above.
## Example Configuration
This combines the two concepts described above. When viewing the file areas from ENiGMA½ a user will only see the "Retro PC" area, but the files in the area are stored in the two locations defined in the `storageTags` section. We also show a uploads area. Uploads are allowed due to the [ACS](acs.md) block. See [Uploads](uploads.md) for more information.
```hjson
fileBase: {
// override the default relative location
areaStoragePrefix: /enigma-bbs/file_base
storageTags: {
retro_pc_dos: "dos"
retro_pc_bbs: "pc/bbs"
}
areas: {
retro_pc: {
name: Retro PC
desc: Oldschool PC/DOS
storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
}
uploads: {
name: Uploads
desc: User uploads
acs: {
// allow any user to upload here
write: GM[users]
}
storageTags: [ "user_uploads" ]
}
}
}
```
## Importing Areas
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](../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](../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](../admin/oputil.md) for more information.

28
docs/_docs/filebase/index.md Normal file
View File

@@ -0,0 +1,28 @@
---
layout: page
title: About File Areas
---
## About File Areas
### A Different Approach
ENiGMA½ has strayed away from the old familiar setup here and instead takes a more modern approach:
* [Gazelle](https://whatcd.github.io/Gazelle/) inspired system for searching & browsing files.
* No conferences (just areas!)
* File areas are still around but should *generally* be used less. Instead, files can have one or more tags. Think things like `dos.retro`, `pc.warez`, `games`, etc.
### Other bells and whistles
* Temporary web (http:// or https://) download links in additional to standard X/Y/Z protocol support. Batch downloads of many files can be downloaded as a single ZIP archive.
* Users can rate files & search/filter by ratings.
* Users can also create and save their own filters for later use such as "Latest Artscene Releases" or "C64 SIDs".
* A given area can span one to many physical storage locations.
* Upload processor can extract and use `FILE_ID.DIZ`/`DESC.SDI`, for standard descriptions as well as `README.TXT`, `*.NFO`, and so on for longer descriptions. The processor also attempts release year estimation by scanning aforementioned description file(s).
* Fast indexed [Full Text Search (FTS)](https://sqlite.org/fts3.html) across descriptions and filenames.
* Duplicates are checked for by cryptographically secure [SHA-256](https://en.wikipedia.org/wiki/SHA-2) hashes.
* Support for many archive and file formats. External utilities can easily be added to the configuration to extend for additional formats.
* Much, much more!
### Modding
The default ENiGMA½ approach for file areas may not be for everyone. Remember that you can mod everything your setup! Some inspirational examples:
* A more traditional set of areas and scrolling file listings.
* An S/X style integration of message areas and file areas.
* Something completely different! Some tweaks are possible without any code while others may require creating new JavaScript modules to use instead of the defaults.

24
docs/_docs/filebase/network-mounts-and-symlinks.md Normal file
View File

@@ -0,0 +1,24 @@
---
layout: page
title: Network Mounts & Symlinks
---
## Network Mounts & Symlinks
With many Bulletin Board Systems running on small headless boxes such as Raspberry Pis, it may not be practical to have all files you would like to make available in your file base. One solution to this is to utilize network mounts. Add in symbolic links to make things even easier!
### A Practical Example
The scenario: A Windows box containing a lot of files you'd like in your systems file base. The BBS itself is running on a Raspberry Pi with very limited space.
To solve this problem, we can perform the following steps:
1. Create a network mount in `/mnt/windows_box_share`.
2. Next, we can create a local file base area such as `/home/enigma/file_base`
3. Within the file base directory above, create some symbolic links to areas within our share:
```
cd /home/enigma/file_base
ln -s /mnt/windows_box_share/some/long/annoying/path area1
```
What we've done here is make `/home/enigma/file_base/area1` point to the Windows share within some nested directories. Of course we could have just pointed directly to the `/mnt/windows_box_share` area, but using symbolic links has some advantages:
* We can now set `/home/enigma/file_base` as our `areaStoragePrefix`. That is, the base path of all of our file base
* Since we have `areaStoragePrefix` set, we can now make storage tags relative to that path. For example, `leet_files1: "area1/leet_files"
There are **many** ways one can achieve the mounts between various operating systems. See your distros documentation.

101
docs/_docs/filebase/tic-support.md Normal file
View File

@@ -0,0 +1,101 @@
---
layout: page
title: TIC Support
---
## TIC Support
ENiGMA½ supports FidoNet-Style TIC file attachments by mapping TIC areas to local file areas.
Under a given node defined in the `ftn_bso` config section in `config.hjson` (see
[BSO Import/Export](../messageareas/bso-import-export.md)), TIC configuration may be supplied:
```hjson
{
scannerTossers: {
ftn_bso: {
nodes: {
"46:*": {
packetPassword: mypass
encoding: cp437
archiveType: zip
tic: {
password: TESTY-TEST
uploadBy: Agoranet TIC
allowReplace: true
}
}
}
}
}
}
```
You then need to configure the mapping between TIC areas you want to carry, and the file base area and storage tag for them to be tossed to. Optionally you can also add hashtags to the tossed files to assist users in searching for files:
```hjson
ticAreas: {
agn_node: {
areaTag: msgNetworks
storageTag: msg_network
hashTags: agoranet,nodelist
}
}
```
Multiple TIC areas can be mapped to a single file base area.
### Example Configuration
An example configuration linking file base areas, FTN BSO node configuration and TIC area configuration.
```hjson
fileBase: {
areaStoragePrefix: /home/bbs/file_areas/
storageTags: {
msg_network: "msg_network"
}
areas: {
msgNetworks: {
name: Message Networks
desc: Message networks news & info
storageTags: [
"msg_network"
]
}
}
}
scannerTossers: {
ftn_bso: {
nodes: {
"46:*": {
packetPassword: mypass
encoding: cp437
archiveType: zip
tic: {
password: TESTY-TEST
uploadBy: Agoranet TIC
allowReplace: true
}
}
}
}
}
ticAreas: {
agn_node: {
areaTag: msgNetworks
storageTag: msg_network
hashTags: agoranet,nodelist
}
agn_info: {
areaTag: msgNetworks
storageTag: msg_network
hashTags: agoranet,infopack
}
}
```
## See Also
[Message Networks](../messageareas/message-networks.md)

24
docs/_docs/filebase/uploads.md Normal file
View File

@@ -0,0 +1,24 @@
---
layout: page
title: Uploads
---
## Uploads
The default ACS for file areas in ENiGMA½ is to allow regular users 'read' and sysops 'read/write'. Read ACS includes listing and downloading while write allows for uploading. See [File Base ACS](acs.md) for more information.
Let's allow regular users (in the "users" group) to upload to an area:
```hjson
uploads: {
name: Uploads
desc: User Uploads
storageTags: [
"uploads"
]
acs: {
write: GM[users]
}
}
````
:information_source: Remember that uploads in a particular area are stored **using the first storage tag defined in that area.**
:bulb: Any ACS checks are allowed. See [ACS](../configuration/acs.md)

11
docs/_docs/filebase/web-access.md Normal file
View File

@@ -0,0 +1,11 @@
---
layout: page
title: Web Access
---
Temporary web HTTP(S) URLs can be used to download files using the built in web server. Temporary links
expire after `fileBase::web::expireMinutes` (default 24 hours). The full URL given to users is built
using `contentServers::web::domain` and will default to HTTPS (https://) if enabled with a fallback to
HTTP. The end result is users are given a temporary web link that may look something like this:
`https://xibalba.l33t.codes:44512/f/h7JK`
See [Web Server](../servers/web-server.md) for more information.