Introduction

This document covers information for keeping your system updated through periodic upgrades as well as version-to-version upgrade notes. Be sure to read these notes for any upgrade!

Before Upgrading

Always back up your system! (See Administration - Backing Up Your System)
Seriously, always back up your system!
Review the version to version release notes within this document.
Upgrade

The Upgrade Process

ENiGMA½ does not currently have much of a "release process" in that instead, it is expected that if you want new features, you will git pull them to your system.

Refer to Upgrading for details around this process.

Problems

Check TROUBLESHOOTING first.
Report your issue on Xibalba BBS, or file a issue on GitHub!

Version to Version Notes

⚠️ Be sure to inspect these notes during any upgrades!

0.5.0-beta to 0.5.1-beta

EchoMail exported to a node with no archiveType was silently never delivered (#722). A node with no archiveType configured exports bare packets instead of ArcMail bundles, and those were written to the outbound spool with a malformed name — the dot before the extension was missing (43792ae5cut rather than 43792ae5.cut). No mailer could match such a file, so the message stayed in the spool indefinitely with no error at any log level. This is fixed; un-archived packets now ship as flow file references like everything else, and no configuration change is required. Setting archiveType is no longer a workaround for anything, though it is still recommended for bandwidth.

Action required if you run a node without archiveType: stranded files are not migrated automatically, because their names carry no destination address. Find them:
```
#  the malformed direct-attach names
find mail/ftn_out -type f -regextype posix-extended \
    -regex '.*/[0-9a-fA-F]{8}(out|cut|iut|hut|dut)' -print

#  and, if you use fileCase: 'upper', names where the temp extension was never stripped
find mail/ftn_out -type f -iname '*.pk_*' -print
```
Each one is a complete FTS-0001 packet. The directory it sits in identifies the network and zone, and the destination net/node is in the packet header — normally just the uplink that area exports to, but you can read it directly:
```
node -e 'const b = require("fs").readFileSync(process.argv[1]);
         console.log(`dest = ${b.readUInt16LE(22)}/${b.readUInt16LE(2)}`)' \
    mail/ftn_out/outbound/43792ae5cut
```
To deliver one, give it a .pkt extension and reference it from that node's flow file, whose name is 4 hex digits of the destination net followed by 4 of its node:
```
mv mail/ftn_out/outbound/43792ae5cut mail/ftn_out/outbound/43792ae5.pkt
echo "^$(pwd)/mail/ftn_out/outbound/43792ae5.pkt" >> mail/ftn_out/outbound/00640000.clo
```
If the messages are old enough not to be worth recovering, deleting the files is safe — they are copies; the originals remain in your message base.
Outbound files are now matched case-insensitively. If you set fileCase: 'upper' on a node, the native BinkP mailer previously reported that node as having mail and then queued none of it — dialing every poll cycle and shipping nothing. The mailer now handles both cases, as FTS-5005.003 §2 asks. No action required; anything queued in upper case starts shipping on the next poll. This also applies to an outbound directory inherited from a DOS-era mailer, where upper case names are the norm.
Mail to point addresses is now shipped by the native BinkP mailer. ftn_bso has always written point mail to the NNNNnnnn.pnt subdirectory the spec requires, but the mailer did not look there, so it was never sent. If you carry points and have been running the built-in mailer, expect a backlog to go out on the next poll — check that the accumulated volume is something you are happy to send before starting up, and delete anything stale from mail/ftn_out/**/*.pnt/ first if not.
Direct-attach netmail packets are renamed when sent. A NNNNnnnn.?ut file in the outbound is now transmitted as a unique NNNNNNNN.pkt, per FTS-5005.003 §3.1. Previously it went out under its .?ut name and the receiving system's tosser ignored it. This only affects .?ut files placed in your outbound by something other than ENiGMA½ — a netmail tracker, another mailer, or by hand. No action required.
Multi-network BSO outbound directories are now consistent between ftn_bso and the native BinkP mailer (#719). The scanner/tosser and the mailer each used their own rule for deciding which FTN network owns the bare outbound/ directory, and the two disagreed whenever more than one network was configured. Both now use the documented rule: scannerTossers.ftn_bso.defaultNetwork when set, otherwise the first network listed in messageNetworks.ftn.networks.

If you have two or more FTN networks configured and have not set defaultNetwork, the first-listed network's outbound now lands in mail/ftn_out/outbound/ rather than mail/ftn_out/<networkName>/.
- Built-in BinkP mailer — no action required. Mail already queued under the previous layout is still found and sent; once that directory drains you may delete it. A startup log entry appears while this applies.
- External mailer (Binkd, Mystic, etc.) — action required. Either update the mailer's outbound path for that network to outbound/, or keep the previous layout by explicitly declaring that there is no default network:
```
scannerTossers: {
  ftn_bso: {
    //  no default network; every network uses its own subdirectory
    defaultNetwork: null
  }
}
```
Either way, explicitly setting defaultNetwork to a network name is recommended for multi-network systems: it pins the layout so that adding or reordering entries in messageNetworks.ftn.networks can never relocate a spool directory. See BSO Import / Export.
Network names are now matched case-insensitively when resolving outbound directories. Systems using a mixed-case key in messageNetworks.ftn.networks (e.g. fsxNet) on a case-sensitive filesystem could have outbound mail written to a directory the mailer never scanned. No action required.

0.4.0-beta to 0.5.0-beta

No breaking changes or required migrations.
DORINFO graphics field changed from 1 to 2 — ENiGMA½ now writes 2 (ANSI color) in the DORINFO graphics field instead of 1 (IBM high-bit chars). RBBS-mode doors such as TradeWars 2002 require 2 to enable ANSI color; other doors treat any non-zero value as graphics-capable and are unaffected. No configuration change required.
Optional: enable OSC 8 hyperlinks in message viewers — clickable URL support is now available for %MT views in preview or read-only mode. The default menu templates already include hyperlinks: true on the appropriate views. If you maintain a custom menu config, add hyperlinks: true to any message-body or NFO viewer %MT view where you want URL detection:
```
MT1: {
    mode: preview
    hyperlinks: true
}
```
No effect on terminals that do not support OSC 8 — it degrades silently to plain text.

Optional: expose the new user_status_config module — a new module lets users toggle their own availability and visibility. To add it to your menus, wire up a command or menu entry pointing to @menu:userStatusConfig. A minimal menu block is required in your menu config:

userStatusConfig: {
    desc: User Status
    module: user_status_config
    config: {
        art: {
            menu: user_status_config
        }
        enabledIndicator: "√"
        disabledIndicator: X
        menuInfoFormat10: "{availableIndicator}"
        menuInfoFormat11: "{visibleIndicator}"
    }
    form: {
        0: {
            mci: {
                TL10: {}
                TL11: {}
            }
            actionKeys: [
                { keys: [ "a", "shift + a" ]           action: @method:toggleAvailable }
                { keys: [ "v", "shift + v" ]           action: @method:toggleVisible }
                { keys: [ "escape", "q", "shift + q" ] action: @systemMethod:prevMenu }
            ]
        }
    }
}

You will also need to create an art file named user_status_config (.ans, .asc, etc.) containing TL10 and TL11 MCI codes for the availability and visibility indicators respectively. The menuInfoFormat10/menuInfoFormat11 format strings support {availableIndicator}, {visibleIndicator}, {isAvailable}, and {isVisible} tokens and can be styled with pipe codes in your theme.

Recommended: review any secrets currently stored as plain text in config.hjson (privateKeyPass, SMTP/IMAP passwords, BinkP sessionPassword, FTN packetPassword, TIC password, jwtSecret, door service credentials) and consider moving them to @file: or @environment: references. This is optional but strongly encouraged — existing plain-text values continue to work unchanged. See Security for examples.

0.3.0-beta to 0.4.0-beta

N/A

0.2.0-beta to 0.3.0-beta

ActivityPub data may need purged if you have utlized it. Easiest to just delete your activitypub.db file and start anew.

0.1.1-beta to 0.2.0-beta

N/A

0.1.0-beta to 0.1.1-beta

N/A

0.0.14-beta to 0.1.0-beta

We are nearing 1.0! Version numbers have changed.
⚠️ FSE editor footer art and menu config have changed. The full-screen editor's footerEditor form (form 2) previously used two separate %TL (Text Label) views — %TL1 for cursor position and %TL2 for INS/OVR mode — driven by a TLTL form config block. These have been replaced by a single %SB1 (StatusBarView) with named panels.

If you have a custom MSGEFTR art file or a customized createMessageEditor / readMessageEditor menu config:
1. Art file (MSGEFTR.ANS) — Replace any %TL1 + %TL2 pair with a single %SB1. Position it where you want the combined status indicator to appear (the default theme places it near the right side of the footer line). Remove any %TL2 entirely.
2. Menu config — In the createMessageEditor and readMessageEditor (or equivalent) menu entries, replace the old form 2 block:
```
// OLD — remove this:
2: {
    TLTL: {
        mci: {
            TL1: { width: 5 }
            TL2: { width: 4 }
        }
    }
}
```
  with the new panel-mode %SB1 config:
```
// NEW — use this:
2: {
    mci: {
        SB1: {
            width:     9
            anchor:    left
            justify:   left
            separator: " "
            panels: [
                {
                    name:    mode
                    width:   3
                    justify: right
                }
                {
                    name:    pos
                    width:   5
                    justify: left
                }
            ]
        }
    }
}
```
In all cases, diff the template against your existing config before applying changes — your config likely contains other customizations you don't want to lose:
```
diff ./misc/menu_templates/message_base.in.hjson ./config/menus/your_board-message_base.hjson
```
Apply only the form 2 changes shown above. See Configuration Files for details.
⚠️ New FSE keyboard shortcuts and find overlay require menu config updates. The following changes apply to all FSE menu entries (messageBaseNewPost, messageAreaViewPost, messageAreaReplyPost, and their private-mail equivalents).

New art file — MSGFND: A find-prompt footer art file is now required. Reference it in each FSE menu's config.art block:
```
config: {
    art: {
        // ... existing art keys ...
        footerFind: MSGFND
    }
}
```
The art file must contain a single %ET1 (EditTextView) input field. Create and theme it like your other footer art files.

Header form (form 0) — Escape key handler change: Replace @systemMethod:prevMenu with @method:headerEscapePressed in the header form's actionKeys. This is required so that Ctrl-A ("change subject") can return focus to the body without exiting the FSE:
```
// OLD — remove:
{ keys: [ "escape" ], action: @systemMethod:prevMenu }
// NEW — replace with:
{ keys: [ "escape" ], action: @method:headerEscapePressed }
```
Body editor (form 1) — new action keys: Add to the actionKeys array in the body (MT1) form:
```
{ keys: [ "ctrl + f" ], action: @method:editModeFind }       // open find prompt
{ keys: [ "ctrl + n" ], action: @method:editModeFindNext }   // find next match
{ keys: [ "ctrl + p" ], action: @method:editModeFindPrev }   // find previous match
{ keys: [ "ctrl + a" ], action: @method:editModeChangeSubject } // edit subject inline
```
View mode (form 4) — new action keys: Add to the view footer actionKeys array:
```
{ keys: [ "ctrl + f" ], action: @method:viewModeFind }
{ keys: [ "ctrl + n" ], action: @method:viewModeFindNext }
{ keys: [ "ctrl + p" ], action: @method:viewModeFindPrev }
```
New form 6 — find footer form: All FSE menu entries need a form 6 definition. The simplest approach is to use the shared reference added to the template:
```
6: @reference:common.fseFindFooterForm
```
You must also add the fseFindFooterForm fragment to your menu file's common: section. Copy it verbatim from misc/menu_templates/message_base.in.hjson (it is an ET1 input with Enter to submit and Escape to cancel).

Editor command menu (form 3) — upload item: The ESC command menu (HM1) now includes an "upload" item allowing users to upload a file as the message body (ANSI art or plain text). Add "upload" to the items array and the corresponding submit action:
```
HM1: { items: [ "save", "discard", "help", "upload" ] }   // post
HM1: { items: [ "save", "discard", "quote", "help", "upload" ] }  // reply
```
With matching submit entries:
```
{ value: { 1: N }, action: @method:editModeMenuUpload }
```
Where N is the zero-based index of "upload" in your items list. Upload access defaults to GM[users]; override per-menu via config.uploadAcs.

As always, diff the template against your config before applying changes:
```
diff ./misc/menu_templates/message_base.in.hjson ./config/menus/your_board-message_base.hjson
```
nodemailer upgraded to v8. If you have email.transport configured with AWS SES, you will need to update your transport config to use the SESv2 SDK — see the nodemailer SES docs. All other transports (SMTP, etc.) require no changes.
Pause prompt and TickerView enhancements — new pause: pageBreak pagination mode, pausePrompt, pausePosition, continuousKey/quitKey, and TickerView (%TK) support in pause prompts. Existing pause: true configs continue to work unchanged. See What's New and Pause Prompts for details.

0.0.13-beta to 0.0.14-beta

A new ActivityPub menu template has been created. Upgrades will not have this file present so you will need to copy the template to your config/menus directory and rename it appropriately (it must match the include statement in your main menu.hjson file). Example:

cp ./misc/menu_templates/activitypub.in.hjson ./config/menus/my_board_name-activitypub.hjson`

This will expose the default ActivityPub setup. Enabling ActivityPub functionality requires the web server enabled and ActivityPub itself enabled in your config.hjson. See Configuration Files Include Statements for more information on using include.

⚠ The menu flag noHistory has been revamped to work as expected. Some menu entires now need this flag. Look for any "NoResults" entries and remove menuFlags. For example, here is the (updated) default fileBaseListEntriesNoResults menu:

fileBaseListEntriesNoResults: {
    desc: Browsing Files
    art: FBNORES
    config: {
        pause: true
        // no menuFlags here
    }
}

0.0.12-beta to 0.0.13-beta

To enable the new Waiting for Caller (WFC) support, please see WFC.
❗ The SSH server's ssh2 module has gone through a major upgrade. Existing users will need to comment out two SSH KEX algorithms from their config.hjson if present else clients such as NetRunner will not be able to connect over SSH. Comment out diffie-hellman-group-exchange-sha256 and diffie-hellman-group-exchange-sha1
Gopher configuration change. See WHATSNEW
All features and changes are backwards compatible. There are a few new configuration options in a new term section in the configuration. These are all optional, but include the following options in case you use them:

{
  term: {
    // checkUtf8Encoding requires the use of cursor
    // position reports, which are not supported on all terminals.
    // Using this with a terminal that does not support cursor
    // position reports results in a 2 second delay during the
    // connect process, but provides better auto configuration of utf-8
    checkUtf8Encoding: true


    // Checking the ANSI home position also requires the use of
    // cursor position reports, which are not supported on all
    /// terminals. Using this with a terminal that does not support
    // cursor position reports results in a 3 second delay during
    // the connect process, but works around positioning problems with
    // non-standard terminals.
    checkAnsiHomePosition: true
  }
}

In addition to these, there are also new options for term.cp437TermList and term.utf8TermList. Under most circumstances these should not need to be changed. If you want to customize these lists, more information is available in config_default.js

0.0.11-beta to 0.0.12-beta

Be aware that master is now mainline! This means all git pull's will yield the latest version. See WHATSNEW for more information.
BREAKING CHANGE There is no longer a prompt.hjson file. Prompts are now simply part of the menu set in the prompts section. If you have an existing system you will need to add your prompt.hjson to your menu.hjson's includes section at a minimum. Example:

// menu.hjson
{
    includes: [
        my-prompts.hjson // ref your old prompts here
    ]
}

A set of database fixes were made that cause some records to be properly cleaned up when e.g. deleting a file. Existing file.db databases will need to be updated manually. Note that this applies to users upgrading within 0.0.12-beta as well:

Make a backup of your file.db!
Shut down ENiGMA.
From the enigma-bbs directory:

sqlite3 db/file.sqlite3 < ./misc/update/tables_update_2020-11-29.sql

0.0.10-alpha to 0.0.11-beta

Node.js 12.x LTS is now in use. Follow standard Node.js upgrade procedures (e.g.: nvm install 12 && nvm use 12).

0.0.9-alpha to 0.0.10-alpha

Security related files such as private keys and certs are now looked for in config/security by default.
Default archive handler for zip files has switched to InfoZip due to a bug in the latest p7Zip packages causing "volume not found" errors. Ensure you have the InfoZip zip and unzip commands in ENiGMA's path. You can switch back to 7Zip by overriding archiveHandler for application/zip in your config.hjson under fileTypes to 7Zip.

0.0.8-alpha to 0.0.9-alpha

Development is now against Node.js 10.x LTS. Follow your standard upgrade path to update to Node 10.x before using 0.0.9-alpha!
The property justify found on various views previously had left and right values swapped (oops!); you will need to adjust any custom theme.hjson that use one or the other and swap them as well.
Possible breaking changes in FSE: The MCI code %TL13 for error indicator is now %TL4. This is part of a cleanup and standardization on "custom ranges". You may need to update your theme.hjson and related artwork.
Removed view width auto-size: Some views still can auto-size their height, but in general you should be explicit in your themes
More standardization using "custom ranges" and itemFormat / focusItemFormat semantics. Update your themes!
In addition to using itemFormat, the onelinerz module uses userName vs username (note the case) to match other modules
loginServers.webSocket configuration block has changed to be more consistent with other servers. Example:

webSocket: {
    ws: {
        enabled: true
    }
    wss: {
        enabled: true
        port: 1234
    }
    proxied: true	//	X-Forwarded-Proto: https support
}

The module export registerEvents has been deprecated. If you have a module that depends on this, use the new more generic moduleInitialize export instead.
The system.db user_event_log table has been updated to include a unique session ID. Previously this table was not used, but you will need to perform a slight maintenance task before it can be properly used. After updating to 0.0.9-alpha, please run the following: sqlite3 db/system.db DROP TABLE user_event_log;. The new table format will be created and used at startup.
If you have art configured for message conference or area selection via the art configuration value, you will need to include a show_art menu reference. Defaulted to changeMessageConfPreArt for conferences and changeMessageAreaPreArt for areas & included in the example menu.hjson.
Config defaults section was theme related and as such, has been renamed to theme. defaults.theme is now theme.default, and preLoginTheme is now theme.preLogin. See config.js if this isn't clear as mud.
Similar to the last item, defaults.general.passwordChar in theme.hjson is now just defaults.passwordChar.

0.0.7-alpha to 0.0.8-alpha

ENiGMA 0.0.8-alpha comes with some structure changes:

Configuration files are defaulted to ./config. Related, the --config option now points to a configuration directory
./mods/art has been moved to ./art/general
./mods is now reserved for actual user addon modules
Themes have been moved from ./mods/themes to ./art/themes

With the change to the ./mods directory, @systemModule is now implied for module declarations in menu.hjson. To use a user module in ./mods you must specify @userModule!

With the above changes, you'll need to to at least:

Move your ~/.config/enigma-bbs/config.hjson to ./config/config.hjson or utlize the --config option.
Move your prompt.hjson and menu.hjson (e.g. myboardname.hjson) to ./config
Move any non-theme art files, and theme directories to their appropriate locations mentioned above
Move any module directories such as message_post_evt to ./mods/
Move any certificates, pub/private keys, etc. from ./misc to ./config
Specify user modules as @userModule:my_module_name

0.0.6-alpha to 0.0.7-alpha

No issues

0.0.5-alpha to 0.0.6-alpha

No issues

0.0.4-alpha to 0.0.5-alpha

No issues

0.0.1-alpha to 0.0.4-alpha

Node.js 6.x+ LTS is now required

You will need to upgrade Node.js to 6.x+. If using nvm (you should be!) the process will go something like this:

nvm install 6
nvm alias default 6

ES6

Newly written code will use ES6 and a lot of code has started the migration process. Of note is the MenuModule class. If you have created a mod that inherits from MenuModule, you will need to upgrade your class to ES6.

Manual Database Upgrade

A few upgrades need to be made to your SQLite databases:

rm db/file.sqltie3 # safe to delete this time as it was not used previously
sqlite3 db/message.sqlite
sqlite> INSERT INTO message_fts(message_fts) VALUES('rebuild');

Archiver Changes

If you have overridden or made additions to archivers in your config.hjson you will need to update them. See Archive Configuration and core/config.js

File Base Configuration

As 0.0.4-alpha contains file bases, you'll want to create a suitable configuration if you wish to use the feature. See File Base Configuration.

FilesExpand file tree

UPGRADE.md

Latest commit

History

UPGRADE.md

File metadata and controls

Introduction

Before Upgrading

The Upgrade Process

Problems

Version to Version Notes

0.5.0-beta to 0.5.1-beta

0.4.0-beta to 0.5.0-beta

0.3.0-beta to 0.4.0-beta

0.2.0-beta to 0.3.0-beta

0.1.1-beta to 0.2.0-beta

0.1.0-beta to 0.1.1-beta

0.0.14-beta to 0.1.0-beta

0.0.13-beta to 0.0.14-beta

0.0.12-beta to 0.0.13-beta

0.0.11-beta to 0.0.12-beta

0.0.10-alpha to 0.0.11-beta

0.0.9-alpha to 0.0.10-alpha

0.0.8-alpha to 0.0.9-alpha

0.0.7-alpha to 0.0.8-alpha

0.0.6-alpha to 0.0.7-alpha

0.0.5-alpha to 0.0.6-alpha

0.0.4-alpha to 0.0.5-alpha

0.0.1-alpha to 0.0.4-alpha

Node.js 6.x+ LTS is now required

ES6

Manual Database Upgrade

Archiver Changes

File Base Configuration