Table of Contents
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
MUTIL can also execute specific functions from the command line if they are not enabled in the .ini file. This is done by using the -RUN or -EXEC or -EXECUTE option (they all do the same thing) followed by a comma separated list of headers that should be executed.
If you are using a non-default .ini file then you mustr specify the execute command before the ini filename. For example:
mutil -run PackMessageBases (Run [PackMessageBases] from mutil.ini) mutil -run PackMessageBases pack.ini (Run [PackMessageBases] from pack.ini)
An example of calling multiple headers from the command line (using multi.ini):
mutil -exec ImportEchoMail,LinkMessages
Running MUTIL -l or -list from the command line will print a list of all available functions that MUTIL can do to the screen for reference.
If you run MUTIL -help you will get the full list of options
MUTIL Execute using mutil.ini fil MUTIL [IniFile] Execute using a custom INI MUTIL -LIST List all MUTIL functions MUTIL -RUN [Command] Execute one or more (comma MUTIL [IniFile] -RUN [Command] Execute specific functions MUTIL -NOSCREEN Execute without outputting MUTIL -VER Show version information
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
Following next is a cache setting which if set to TRUE (*HIGHLY* recommended for MUTIL) then MUTIL will write the log file in increments of 8KB at a time. If set to FALSE it will write each individual line as it is logged. This will significantly reduce MUTIL performance if set to FALSE.
logcache=true
Next up is a setting that 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
Note that the loglevel can also be set in any specific function stanza and that value will override the default value defined here, but only for that specific stanza where a different setting has been applied.
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.
; Log roller type: ; 0 = Do not roll log files ; 1 = Roll by number of files/filesize ; 2 = Roll by number of days
Setting the logtype option to 0 will disable log rolling 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 Export_FILEBONE.NA = false Export_AREAS.BBS = false Export_GOLDED = false Import_FILES.BBS = false MassUpload = false GenerateTopLists = false GenerateAllFiles = false PurgeMessageBases = false PostTextFiles = false PackMessageBases = false ImportEchoMail = false ExportEchoMail = false MergeNodeLists = false FileToss = false PackFileBases = false FileSort = false LinkMessages = false PurgeUserBase = false PackUserBase = false AutoHatch = false EchoNodeTracker = false EchoUnlink = 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.