enigma-bbs/configuration/config-files.html

2565 lines
26 KiB
HTML
Raw Permalink Normal View History

<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/png" sizes="16x16" href="/enigma-bbs/assets/images/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="stylesheet" href="/enigma-bbs/assets/css/style.css?v=">
<!-- Begin Jekyll SEO tag v2.7.1 -->
<title>Configuration Files | ENiGMA½ BBS Software</title>
<meta name="generator" content="Jekyll v4.2.2" />
<meta property="og:title" content="Configuration Files" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format." />
<meta property="og:description" content="General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format." />
<meta property="og:site_name" content="ENiGMA½ BBS Software" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2023-10-15T23:34:51+00:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Configuration Files" />
<script type="application/ld+json">
{"datePublished":"2023-10-15T23:34:51+00:00","description":"General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format.","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/configuration/config-files.html"},"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/enigma-bbs/assets/images/enigma-logo.png"}},"url":"/enigma-bbs/configuration/config-files.html","@type":"BlogPosting","headline":"Configuration Files","dateModified":"2023-10-15T23:34:51+00:00","@context":"https://schema.org"}</script>
<!-- End Jekyll SEO tag -->
</head>
<body>
<div id="container">
<div class="sidebar" id="sidebar">
<hr class="mobile-divide">
<div class="container">
<a href="/enigma-bbs/"><img src="/enigma-bbs/assets/images/enigma-logo.png" class="logo" alt="Enigma logo"></a>
</div>
<ul>
<li>Installation</li>
<ul>
<li><a href="/enigma-bbs/installation/installation-methods.html">Installation Methods</a></li>
<li><a href="/enigma-bbs/installation/install-script.html">Install Script</a></li>
<li><a href="/enigma-bbs/installation/docker.html">Docker</a></li>
<li><a href="/enigma-bbs/installation/manual.html">Manual Installation</a></li>
<li>OS / Hardware Specific</li>
<ul>
<li><a href="/enigma-bbs/installation/hardware/rpi.html">Raspberry Pi</a></li>
<li><a href="/enigma-bbs/installation/hardware/windows.html">Installation Under Windows</a></li>
</ul>
<li><a href="/enigma-bbs/installation/network.html">Network Setup</a></li>
<li><a href="/enigma-bbs/installation/testing.html">Testing Your Installation</a></li>
<li><a href="/enigma-bbs/installation/production.html">Production Installation</a></li>
<li><a href="/enigma-bbs/installation/development.html">Development Environment Setup</a></li>
</ul>
<li>Configuration</li>
<ul>
<li><a href="/enigma-bbs/configuration/creating-config.html">Creating Initial Config Files</a></li>
<li><a href="/enigma-bbs/configuration/sysop-setup.html">SysOp Setup</a></li>
<li class="active-nav">Configuration Files</li>
<li><a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a></li>
<li><a href="/enigma-bbs/configuration/hjson.html">HJSON Config Files</a></li>
<li><a href="/enigma-bbs/configuration/menu-hjson.html">Menu HSJON</a></li>
<li><a href="/enigma-bbs/configuration/directory-structure.html">Directory Structure</a></li>
<li><a href="/enigma-bbs/configuration/external-binaries.html">External Support Binaries</a></li>
<li><a href="/enigma-bbs/configuration/archivers.html">Archivers</a></li>
<li><a href="/enigma-bbs/configuration/file-transfer-protocols.html">File Transfer Protocols</a></li>
<li><a href="/enigma-bbs/configuration/email.html">Email</a></li>
<li><a href="/enigma-bbs/configuration/colour-codes.html">Colour Codes</a></li>
<li><a href="/enigma-bbs/configuration/event-scheduler.html">Event Scheduler</a></li>
<li><a href="/enigma-bbs/configuration/acs.html">Access Condition System (ACS)</a></li>
<li><a href="/enigma-bbs/configuration/security.html">Security</a></li>
</ul>
<li>Miscellaneous</li>
<ul>
<li><a href="/enigma-bbs/misc/user-interrupt.html">User Interruptions</a></li>
</ul>
<li>File Base</li>
<ul>
<li><a href="/enigma-bbs/filebase/index.html">About File Areas</a></li>
<li><a href="/enigma-bbs/filebase/first-file-area.html">Configuring a File Base</a></li>
<li><a href="/enigma-bbs/filebase/acs.html">ACS</a></li>
<li><a href="/enigma-bbs/filebase/uploads.html">Uploads</a></li>
<li><a href="/enigma-bbs/filebase/web-access.html">Web Access</a></li>
<li><a href="/enigma-bbs/filebase/tic-support.html">TIC Support</a></li>
<li><a href="/enigma-bbs/filebase/network-mounts-and-symlinks.html">Network Mounts &amp; Symlinks</a></li>
</ul>
<li>Message Areas</li>
<ul>
<li><a href="/enigma-bbs/messageareas/configuring-a-message-area.html">Message Base</a></li>
<li><a href="/enigma-bbs/messageareas/message-networks.html">Message Networks</a></li>
<li><a href="/enigma-bbs/messageareas/bso-import-export.html">BSO Import / Export</a></li>
<li><a href="/enigma-bbs/messageareas/netmail.html">Netmail</a></li>
<li><a href="/enigma-bbs/messageareas/qwk.html">QWK Support</a></li>
<li><a href="/enigma-bbs/messageareas/ftn.html">FidoNet-Style Networks (FTN)</a></li>
</ul>
<li>Art</li>
<ul>
<li><a href="/enigma-bbs/art/general.html">General Art Information</a></li>
<li><a href="/enigma-bbs/art/themes.html">Themes</a></li>
<li><a href="/enigma-bbs/art/mci.html">MCI Codes</a></li>
<li>Views</li>
<ul>
<li><a href="/enigma-bbs/art/views/button_view.html">Button View</a></li>
<li><a href="/enigma-bbs/art/views/edit_text_view.html">Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/full_menu_view.html">Full Menu View</a></li>
<li><a href="/enigma-bbs/art/views/horizontal_menu_view.html">Horizontal Menu View</a></li>
<li><a href="/enigma-bbs/art/views/mask_edit_text_view.html">Mask Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/multi_line_edit_text_view.html">Multi Line Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/spinner_menu_view.html">Spinner Menu View</a></li>
<li><a href="/enigma-bbs/art/views/text_view.html">Text View</a></li>
<li><a href="/enigma-bbs/art/views/toggle_menu_view.html">Toggle Menu View</a></li>
<li><a href="/enigma-bbs/art/views/vertical_menu_view.html">Vertical Menu View</a></li>
</ul>
</ul>
<li>Servers</li>
<ul>
<li>Login Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/loginservers/telnet.html">Telnet Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/ssh.html">SSH Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/websocket.html">Web Socket / Web Interface Server</a></li>
</ul>
<li>Content Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/contentservers/web-server.html">Web Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/gopher.html">Gopher Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/nntp.html">NNTP Server</a></li>
</ul>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/local-doors.html">Local Doors</a></li>
<li><a href="/enigma-bbs/modding/door-servers.html">Door Servers</a></li>
<li><a href="/enigma-bbs/modding/telnet-bridge.html">Telnet Bridge</a></li>
<li><a href="/enigma-bbs/modding/existing-mods.html">Existing Mods</a></li>
<li><a href="/enigma-bbs/modding/file-area-list.html">File Area List</a></li>
<li><a href="/enigma-bbs/modding/last-callers.html">Last Callers</a></li>
<li><a href="/enigma-bbs/modding/whos-online.html">Who's Online</a></li>
<li><a href="/enigma-bbs/modding/user-list.html">User List</a></li>
<li><a href="/enigma-bbs/modding/msg-conf-list.html">Message Conference List</a></li>
<li><a href="/enigma-bbs/modding/msg-area-list.html">Message Area List</a></li>
<li><a href="/enigma-bbs/modding/bbs-list.html">BBS List</a></li>
<li><a href="/enigma-bbs/modding/rumorz.html">Rumorz</a></li>
<li><a href="/enigma-bbs/modding/file-transfer-protocol-select.html">File Transfer Protocol Select</a></li>
<li><a href="/enigma-bbs/modding/onelinerz.html">Onelinerz</a></li>
<li><a href="/enigma-bbs/modding/show-art.html">The Show Art Module</a></li>
<li><a href="/enigma-bbs/modding/file-base-download-manager.html">File Base Download Manager</a></li>
<li><a href="/enigma-bbs/modding/file-base-web-download-manager.html">File Base Web Download Manager</a></li>
<li><a href="/enigma-bbs/modding/set-newscan-date.html">Set Newscan Date Module</a></li>
<li><a href="/enigma-bbs/modding/node-msg.html">Node to Node Messaging</a></li>
<li><a href="/enigma-bbs/modding/top-x.html">TopX</a></li>
<li><a href="/enigma-bbs/modding/user-2fa-otp-config.html">2FA/OTP Config</a></li>
<li><a href="/enigma-bbs/modding/autosig-edit.html">Auto Signature Editor</a></li>
<li><a href="/enigma-bbs/modding/menu-modules.html">Menu Modules</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/administration.html">Administration</a></li>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/wfc.html">Waiting For Caller (WFC)</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/oputil.html">oputil</a></li>
<li><a href="/enigma-bbs/admin/updating.html">Updating</a></li>
</ul>
<li>Troubleshooting</li>
<ul>
<li><a href="/enigma-bbs/troubleshooting/monitoring-logs.html">Monitoring Logs</a></li>
<li><a href="/enigma-bbs/troubleshooting/ssh-troubleshooting.html">Troubleshooting SSH</a></li>
</ul>
</ul>
</div>
<div class="main_area">
<div class="container">
<section id="main_content">
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/configuration/sysop-setup.html">« SysOp Setup</a>
<a href="#sidebar" class="btn menu_button">MENU</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/configuration/config-hjson.html">System Configuration »</a>
<br clear="both">
</div>
<div class="page">
<h1 class="page-title">Configuration Files</h1>
<h2 id="general-information">General Information</h2>
<p>ENiGMA½ configuration files such as the <a href="/enigma-bbs/configuration/config-hjson.html">system config</a>, <a href="/enigma-bbs/configuration/menu-hjson.html">menus</a> and <a href="/enigma-bbs/art/themes.html">themes</a> are formatted in the <a href="/enigma-bbs/configuration/hjson.html">HJSON format</a>.</p>
<h2 id="hot-reload">Hot-Reload</h2>
<p>Nearly all of ENiGMA½s configuration can be hot-reloaded. That is, a live system can have its configuration modified and it will be loaded in place.</p>
<blockquote>
<p><img class="emoji" title=":bulb:" alt=":bulb:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png" height="20" width="20"> <a href="/enigma-bbs/troubleshooting/monitoring-logs.html">Monitoring live logs</a> is useful when making live changes. The system will complain if something is wrong!</p>
</blockquote>
<h2 id="common-directives">Common Directives</h2>
<h3 id="includes">Includes</h3>
<p>Most configuration files offer an <code class="language-plaintext highlighter-rouge">includes</code> directive that allows users to break up large configuration files into smaller and organized parts. For example, consider a system with many menus/screens. Instead of a single <code class="language-plaintext highlighter-rouge">menu.hjson</code>, the SysOp may break this into <code class="language-plaintext highlighter-rouge">message-base.hjson</code>, <code class="language-plaintext highlighter-rouge">file-base.hjson</code>, etc.</p>
<p>The <code class="language-plaintext highlighter-rouge">includes</code> directive may be used the top-level scope of a configuration file:</p>
<pre><code class="language-hjson">// menu.hjson
{
includes: [
message-base.hjson
file-base.hjson
]
menus: {
someOtherMenu: {
// ...
}
}
}
</code></pre>
<pre><code class="language-hjson">// message-base.hjson
{
menus: {
someMessageMenu: {
// ...
}
}
}
</code></pre>
<h3 id="references">References</h3>
<p>Often times in a configuration you will find that youre repeating yourself quite a bit. ENiGMA½ provides an <code class="language-plaintext highlighter-rouge">@reference</code> that can help with this in the form of <code class="language-plaintext highlighter-rouge">@reference:dot.path.to.section</code>.</p>
<p>Consider <code class="language-plaintext highlighter-rouge">actionKeys</code> in a menu. Often times you may show a screen and the user presses <code class="language-plaintext highlighter-rouge">Q</code> or <code class="language-plaintext highlighter-rouge">ESC</code> to fall back to the previous. Instead of repeating this in many menus, a generic block can be referenced:</p>
<pre><code class="language-hjson">{
// note that 'recycle' here is arbitrary;
// only 'menus' and 'prompts' is reserved at this level.
recycle: {
prevMenu: [
{
keys: [ "escape" ]
action: @systemMethod:prevMenu
}
]
}
menus: {
someMenu: {
form: {
0: {
actionKeys: @reference:recycle.prevMenu
}
}
}
}
}
</code></pre>
<blockquote>
<p><img class="emoji" title=":information_source:" alt=":information_source:" src="https://github.githubassets.com/images/icons/emoji/unicode/2139.png" height="20" width="20"> An unresolved <code class="language-plaintext highlighter-rouge">@reference</code> will be left intact.</p>
</blockquote>
<h3 id="environment-variables">Environment Variables</h3>
<p>Especially in a container environment such as <a href="/enigma-bbs/installation/docker.html">Docker</a>, environment variable access in configuration files can become very handy. ENiGMA½ provides a flexible way to access variables using the <code class="language-plaintext highlighter-rouge">@environment</code> directive. The most basic form of <code class="language-plaintext highlighter-rouge">@environment:VAR_NAME</code> produces a string value. Additionally a <code class="language-plaintext highlighter-rouge">:type</code> 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 <code class="language-plaintext highlighter-rouge">:array</code> suffix.</p>
<p>Below is a table of the various forms:</p>
<table>
<thead>
<tr>
<th>Form</th>
<th>Variable Value</th>
<th>Produces</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR</code></td>
<td>“Foo”</td>
<td>
<code class="language-plaintext highlighter-rouge">"Foo"</code> (without quotes)</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR</code></td>
<td>“123”</td>
<td>
<code class="language-plaintext highlighter-rouge">"123"</code> (without quotes)</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:string</code></td>
<td>“Bar”</td>
<td>
<code class="language-plaintext highlighter-rouge">"Bar"</code> (without quotes)</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:string:array</code></td>
<td>“Foo,Bar”</td>
<td><code class="language-plaintext highlighter-rouge">[ 'Foo', 'Bar' ]</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:boolean</code></td>
<td>“1”</td>
<td><code class="language-plaintext highlighter-rouge">true</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:boolean</code></td>
<td>“True”</td>
<td><code class="language-plaintext highlighter-rouge">true</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:boolean</code></td>
<td>“false”</td>
<td><code class="language-plaintext highlighter-rouge">false</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:boolean</code></td>
<td>“cat”</td>
<td><code class="language-plaintext highlighter-rouge">false</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:boolean:array</code></td>
<td>“True,false,TRUE”</td>
<td><code class="language-plaintext highlighter-rouge">[ true, false, true ]</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:number</code></td>
<td>“123”</td>
<td><code class="language-plaintext highlighter-rouge">123</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:number:array</code></td>
<td>“123,456”</td>
<td><code class="language-plaintext highlighter-rouge">[ 123, 456 ]</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:number</code></td>
<td>“kitten”</td>
<td>(invalid)</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:object</code></td>
<td>{“a”:”b”}</td>
<td><code class="language-plaintext highlighter-rouge">{ 'a' : 'b' }</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:object:array</code></td>
<td>{“a”:”b”},{“c”:”d”}</td>
<td><code class="language-plaintext highlighter-rouge">[ { 'a' : 'b' }, { 'c' : 'd' } ]</code></td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:timestamp</code></td>
<td>“2020-01-05”</td>
<td>A <a href="https://momentjs.com/">moment</a> object representing 2020-01-05</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">@environment:SOME_VAR:timestamp:array</code></td>
<td>“2020-01-05,2016-05-16T01:15:37</td>
<td>An array of <a href="https://momentjs.com/">moment</a> objects representing 2020-01-05 and 2016-05-16T01:15:37</td>
</tr>
</tbody>
</table>
<blockquote>
<p><img class="emoji" title=":bulb:" alt=":bulb:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png" height="20" width="20"> <code class="language-plaintext highlighter-rouge">bool</code> may be used as an alias to <code class="language-plaintext highlighter-rouge">boolean</code>.</p>
</blockquote>
<blockquote>
<p><img class="emoji" title=":bulb:" alt=":bulb:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png" height="20" width="20"> <code class="language-plaintext highlighter-rouge">timestamp</code> values can be in any form that <a href="https://momentjs.com/docs/#/parsing/">moment can parse</a>.</p>
</blockquote>
<blockquote>
<p><img class="emoji" title=":information_source:" alt=":information_source:" src="https://github.githubassets.com/images/icons/emoji/unicode/2139.png" height="20" width="20"> An unresolved or invalid <code class="language-plaintext highlighter-rouge">@environment</code> will be left intact.</p>
</blockquote>
<p>Consider the following fragment:</p>
<pre><code class="language-hjson">{
foo: {
bar: @environment:BAR_VAR:number
}
}
</code></pre>
<p>If the environment has <code class="language-plaintext highlighter-rouge">BAR_VAR=1337</code>, this would produce:</p>
<pre><code class="language-hjson">{
foo: {
bar: 1337
}
}
</code></pre>
<h2 id="see-also">See Also</h2>
<ul>
<li><a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a></li>
<li><a href="/enigma-bbs/configuration/menu-hjson.html">Menu Configuration</a></li>
<li><a href="/enigma-bbs/configuration/hjson.html">The HJSON Format</a></li>
</ul>
</div>
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/configuration/sysop-setup.html">« SysOp Setup</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/configuration/config-hjson.html">System Configuration »</a>
<br clear="both">
</div>
</section>
</div>
</div>
</div>
</body>
</html>