moon
/
enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
enigma-bbs/configuration/config-files.html

2515 lines
26 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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.1" />
<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="2022-10-25T16:49:47+00:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Configuration Files" />
<script type="application/ld+json">
{"description":"General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format.","url":"/enigma-bbs/configuration/config-files.html","@type":"BlogPosting","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/enigma-bbs/assets/images/enigma-logo.png"}},"headline":"Configuration Files","dateModified":"2022-10-25T16:49:47+00:00","datePublished":"2022-10-25T16:49:47+00:00","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/configuration/config-files.html"},"@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>
</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>
</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 it’s 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 you’re 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>
Reference in New Issue View Git Blame Copy Permalink