From: Jeremy Stanley Date: Mon, 30 Apr 2018 17:43:17 +0000 (+0000) Subject: Add configuration guide X-Git-Tag: 0.0.1~102 X-Git-Url: https://mudpy.org/gitweb?p=mudpy.git;a=commitdiff_plain;h=15479b4d263b222bed3f544f67f4d70d24ab37a7 Add configuration guide Document the current configuration options along with their data types and examples use. --- diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000..f2641d4 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,425 @@ +=============== + configuration +=============== + +.. Copyright (c) 2004-2018 Jeremy Stanley . + Permission to use, copy, modify, and distribute this software is + granted under terms provided in the LICENSE file distributed with + this software. + +.mudpy.filing +------------- + +.mudpy.filing.groups +~~~~~~~~~~~~~~~~~~~~ + +dict, optional + +Each item in the dict identifies options for the default backing +file of the group named in its key. The value is itself a dict with +its keys and values corresponding to those options (for now, only +``flags`` is implemented, with a value of ``private`` indicating it +should be readable only by the system user under which the mudpy +process is running). + +Example:: + + .mudpy.filing.groups: + account: + flags: + - private + +.mudpy.filing.prefix +~~~~~~~~~~~~~~~~~~~~ + +string, optional + +This is the root path beneath which all relative file references, +including directories comprising the search path, are assumed to be +found. The default value of ``.`` indicates the current working +directory at the time the service was initially started. + +Example:: + + .mudpy.filing.prefix: . + +.mudpy.filing.search +~~~~~~~~~~~~~~~~~~~~ + +list, required + +Directories to search for expected data files. If not a fully +canonical path, this is assumed to be relative to the ``prefix``. + +Example:: + + .mudpy.filing.search: + - "" + - etc + - share + - data + +.mudpy.filing.stash +~~~~~~~~~~~~~~~~~~~ + +string, required + +This is the default directory where new data files will be written +if their full paths are not specified and they aren't already found +in the ``search`` list. If not a fully canonical path, this is +assumed to be relative to the ``prefix``. + +Example:: + + .mudpy.filing.stash: data + +.mudpy.linguistic +----------------- + +.mudpy.linguistic.actions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +dict, optional + +This is used to tailor the appearance of output generated by the +``say`` command and its relatives, so as to add some readability and +flavor. It matches a visible action to punctuation (ask, exclaim, et +cetera). + +Example:: + + .mudpy.linguistic.actions: + ?: ask + ",": begin + -: begin + :: begin + ;: begin + "!": exclaim + ...: muse + .: say + +.mudpy.linguistic.default_punctuation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +string, optional + +Unpunctuated statements made by actors should be assumed to +terminate with this value. + +Example:: + + .mudpy.linguistic.default_punctuation: . + +.mudpy.linguistic.typos +~~~~~~~~~~~~~~~~~~~~~~~ + +dict, optional + +Replacements for common typographical and capitalization errors. + +Example:: + + .mudpy.linguistic.typos: + i: I + i'd: I'd + i'll: I'll + i'm: I'm + teh: the + theyre: they're + youre: you're + +.mudpy.limit +------------ + +.mudpy.limit.admins +~~~~~~~~~~~~~~~~~~~ + +list, optional + +The first users to create accounts with names in this list will +automatically be given full administrative privileges. + +Example:: + + .mudpy.limit.admins: + - admin + +.mudpy.limit.avatars +~~~~~~~~~~~~~~~~~~~~ + +int, required + +This is the maximum number of avatars allowed for each account. + +Example:: + + .mudpy.limit.avatars: 7 + +.mudpy.limit.backups +~~~~~~~~~~~~~~~~~~~~ + +int, optional + +This is the number of backups to keep and rotate when overwriting +data files. If unspecified or set to 0, no backup copies will be +made. + +Example:: + + .mudpy.limit.backups: 10 + +.mudpy.limit.password_tries +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +int, required + +This is the maximum number of password failures allowed during the +login process. Once exceeded, the user will be disconnected. + +Example:: + + .mudpy.limit.password_tries: 3 + +.mudpy.log +---------- + +.mudpy.log.file +~~~~~~~~~~~~~~~ + +string, optional + +If set, log messages will be recorded to this file. + +Example:: + + .mudpy.log.file: var/mudpy.log + +.mudpy.log.lines +~~~~~~~~~~~~~~~~ + +int, optional + +Number of log entries to keep in memory (the oldest are +discarded)... If unset or 0, none will be written to mudpy's +internal memory. + +Example:: + + .mudpy.log.lines: 1000 + +.mudpy.log.stdout +~~~~~~~~~~~~~~~~~ + +bool, optional + +If set to ``yes``, messages will be logged to the standard output of +the mudpy process. If unspecified, the default is ``no``. + +Example:: + + .mudpy.log.stdout: true + +.mudpy.log.syslog +~~~~~~~~~~~~~~~~~ + +string, optional + +If set, mudpy will send messages to the system log, and under the +name specified by this value (Unix derivatives only). + +Example:: + + .mudpy.log.syslog: mudpy + +.mudpy.movement +--------------- + +.mudpy.movement.*.enter_term +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +string, multiple + +Word or words describing the direction from where you are seen to +enter the next room when moving. + +Example:: + + .mudpy.movement.down.enter_term: above + .mudpy.movement.east.enter_term: the west + .mudpy.movement.north.enter_term: the south + .mudpy.movement.south.enter_term: the north + .mudpy.movement.up.enter_term: below + .mudpy.movement.west.enter_term: the east + +.mudpy.movement.*.exit_term +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +string, multiple + +Word or words describing the direction where you are seen to exit +the current room when moving. + +Example:: + + .mudpy.movement.down.exit_term: downward + .mudpy.movement.east.exit_term: to the east + .mudpy.movement.north.exit_term: to the north + .mudpy.movement.south.exit_term: to the south + .mudpy.movement.up.exit_term: upward + .mudpy.movement.west.exit_term: to the west + +.mudpy.movement.*.vector +~~~~~~~~~~~~~~~~~~~~~~~~ + +triplet, multiple + +Vector of signed integer units for use in vector addition to derive +the destination coordinates from the current coordinates when moving +through a gridlink exit. The example coordinate system used is left +handed (east, north and up are positive, west, south and down are +negative) and three-dimensional with a tuple component order of +(longitude, latitude, altitude). + +Example:: + + .mudpy.movement.down.vector: [0, 0, -1] + .mudpy.movement.east.vector: [1, 0, 0] + .mudpy.movement.north.vector: [0, 1, 0] + .mudpy.movement.south.vector: [0, -1, 0] + .mudpy.movement.up.vector: [0, 0, 1] + .mudpy.movement.west.vector: [-1, 0, 0] + +.mudpy.network +-------------- + +.mudpy.network.host +~~~~~~~~~~~~~~~~~~~ + +string, optional + +The IP address on which to listen. If unspecified, the default is +all available addresses. + +Example:: + + .mudpy.network.host: ::1 + +.mudpy.network.port +~~~~~~~~~~~~~~~~~~~ + +int, required + +The TCP port on which to listen. + +Example:: + + .mudpy.network.port: 4000 + +.mudpy.process +-------------- + +.mudpy.process.daemon +~~~~~~~~~~~~~~~~~~~~~ + +bool, optional + +If set to ``yes``, mudpy will immediately fork and detach a child to +become a daemon process, then close all open file descriptors and +terminate the parent process (Unix derivatives only). The default +value is ``no``. + +Example:: + + .mudpy.process.daemon: true + +.mudpy.process.pidfile +~~~~~~~~~~~~~~~~~~~~~~ + +string, optional + +If set, this filename will contain the daemon's process ID (Unix +derivatives only). + +Example:: + + .mudpy.process.pidfile: var/mudpy.pid + +.mudpy.timing +------------- + +.mudpy.timing.idle.disconnect.* +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +int, multiple + +This value indicates the number of increments allowed to pass +without input on a socket connection before it is terminated. This +avoids accumulation of dead sockets which could otherwise max out +allowed file descriptors. The differentiators are either ``default`` +or a state name used to override the default value for that specific +state (``active``, ``entering_account_name``, et cetera). + +Example:: + + .mudpy.timing.idle.disconnect.active: 6048000 + .mudpy.timing.idle.disconnect.default: 6000 + .mudpy.timing.idle.disconnect.entering_account_name: 600 + +.mudpy.timing.idle.warn.* +~~~~~~~~~~~~~~~~~~~~~~~~~ + +int, multiple + +This value indicates the number of increments allowed to pass +without input on a socket connection before it is warned that +termination is imminent. The differentiators are either +``default`` or a state name used to override the default value +for that specific state. It is recommended that this be less than +the corresponding ``.mudpy.timing.idle.disconnect.*`` value. + +Example:: + + .mudpy.timing.idle.warn.active: 5040000 + .mudpy.timing.idle.warn.default: 5000 + .mudpy.timing.idle.warn.entering_account_name: 500 + +.mudpy.timing.increment +~~~~~~~~~~~~~~~~~~~~~~~ + +float, required + +This value indicates the number of real system clock seconds (or +more commonly, fraction thereof) each pass through the main loop is +intended to take. This roughly sets the frequency with which queued +socket I/O operations are performed, pending events are triggered, +and directly impacts the speed at which virtual time passes within +the simulation. + +Example:: + + .mudpy.timing.increment: 0.1 + +.mudpy.timing.save +~~~~~~~~~~~~~~~~~~ + +int, required + +Number of increments between updates of changed persistent data +storage. + +Example:: + + .mudpy.timing.save: 600 + +.mudpy.timing.status +~~~~~~~~~~~~~~~~~~~~ + +int, optional + +Number of increments to wait between logging mudpy status messages. +If unspecified or set to 0, no mudpy status messages will be +written. + +Example:: + + .mudpy.timing.status: 6000