User Tools

Site Tools


mutil_howto

Introducing Mystic Utilities

Mystic Utilities, otherwise known as “MUTIL”, is an automated maintenance and utility program that is controlled by .ini configuration file(s).

Think of MUTIL as the Swiss Army Knife utility program for Mystic BBS. It can be tasked with running multiple functions at once or be configured in a far more granular fashion to do one task at a time when called.

Invoking MUTIL

The syntax to execute MUTIL is:

MUTIL <configuration-filename>[.ini]

If no configuration file is supplied, then MUTIL will look for mutil.ini in the same directory it resides.

You can also supply a second parameter -NOSCREEN that will turn off screen updates but the configuration file parameter MUST be supplied first e.g.

mutil msgmaint.ini -NOSCREEN

If no file extension is provided on the command line, MUTIL will append .ini onto it, meaning that executing the following command line will cause mutil to look for “msgmaint.ini”:

mutil msgmaint

Anatomy of the .INI File

MUTIL is completely driven by Sysop-created .ini files which contain general configuration options, and a list of functions in which MUTIL should perform. This allows a System Operator to easily create their own custom “commands” that can execute one or many tasks, simply by invoking MUTIL and passing it the .ini name.

For example, a SysOp may decide to create a “msgmaint.ini” file which instructs MUTIL to do various functions such as purging message bases by message age, renumbering and packing the message base data files, and so on. Once this .ini file is created, those configured functions can be performed simply my invoking MUTIL with the .ini filename as described above:

 mutil msgmaint

Each .ini file has a [General] stanza with some options, followed by a list of functions that can be enabled. Lets take a look at the general options before jumping into the specific functions:

General Options Stanza [GENERAL]

The general stanza contains several options you should consider and/or configure further:

Mystic Directory

This can be a handy option to set if you want to run MUTIL from a directory other than the root Mystic directory you have installed Mystic in to or from that which has been specified in the mysticbbs environment variable.

In most cases if you are running Mystic BBS in the default directory you won't want to change this. If you do opt to change this remember to uncomment it by removing the semicolon first!

; mystic_directory=c:\mystic\mystic.dat

Basic Logging

MUTIL offers many logging options, and contains the ability to perform two different types of log “rolling” techniques to automatically maintain your log files for you.

The first option allows name of the log file to be defined. If there is no path in the log file name, MUTIL will use the configured logs directory:

logfile=mutil.log

The next setting defines the level of detail to be contained within the MUTIL logs. Usually level 2 provides an acceptable level of detail but this can be changed to one of three options:

Level 1 = basic
Level 2 = verbose
Level 3 = debug

loglevel=2

Each entry in the log file is prefixed by a date/time stamp. This stamp by default uses the NNN DD HH:II:SS format (ie Mar 29 04:34:02) but this can be changed to support any desired date/time stamp by declaring a new format using the logstamp option. As an example, some System Operators prefer to have a date/time stamp that can be reliably sorted and would override the default using the logstamp option, as shown below:

logstamp = YYYYHHMMHHIISS

Log Rolling

MUTIL supports three settings to assist with automatically maintaining your log files. The logtype option can be set to one of three options, and depending on the option selected, some additional values may be required to be set with it.

Setting the logtype option to 0 will disable log management entirely. MUTIL will continue adding to the same log file indefinitely until it is manually moved or deleted. No other options are required for this logtype.

logtype = 0

Setting the option to 1 will build each log file until it reaches a configured size, and then it will create a new file. When the configured maximum number of log files is reached, the oldest will be deleted. 3 options need to be configured for this style of log rolling. For example the following options will keep the latest 3 log files of 1024 kilobytes each:

logtype     = 1
maxlogfiles = 3
maxlogsize  = 1024

Setting the option to 2 will perform log rolling by day. This option has no size limit to the log file; instead, a log file is created for each individual day and the number of days to keep log files is configured. When there are more days than the configured number, the oldest day's log file will be removed. This style requires two configured options. For example, the following options will keep the last 7 days of log files:

logtype     = 2
maxlogfiles = 7

Other Logging Considerations

Remember if you are going to create different .ini files for various functions listed below you may want to settle on standardizing your general options at the start of each .ini file.

Things can get rather confusing (unless you like it that way) when logging levels, logging file names etc. change between .ini files that MUTIL inspects when it is called.

In the end how you choose to set things up is entirely up to you. That's the beauty of Mystic - it's so flexible!

Available Functions

There are number of functions able to be called when using MUTIL.

Each function is enabled or disabled in the [general] stanza section of the .ini file by toggling the following switches to true or false.

[general]

Import_FIDONET.NA  = false
Import_MessageBase = false 
Import_FILEBONE.NA = false
Import_FILES.BBS   = false
MassUpload         = false
GenerateTopLists   = false
GenerateAllFiles   = false
PostTextFiles      = false
PurgeMessageBases  = false
PackMessageBases   = false
ImportEchoMail     = false
ExportEchoMail     = false
MergeNodeLists     = false 
FileToss           = false 
PackFileBases      = false 
LinkMessages	   = false 

NOTE: All options are assumed to be off (or false) by default. Only the options being executed in a particular .ini file are required to be found within the [general] stanza.

For each function enabled in the [general] stanza, a corresponding stanza with the same name must exist for that function. In order words, if you have “MassUpload = true” in your .ini file, then you must also have a “[MassUpload]” stanza in the same .ini file.

While the [general] stanza defines the general options such as logging and which functions to execute, the function-specific stanzas define the options specific to that particular function. These function-specific stanzas are defined in their own individual sections, with links found below or on the sidebar index.

Function Reference Links

mutil_howto.txt · Last modified: 2016/04/24 22:07 by avon