
NAME

  config.wrj - WolfMUD's default configuration file

SYNOPSIS

  DATA_DIR/config.wrj

DESCRIPTION

  config.wrj is the default configuration file looked for by the WolfMUD
  server. An alternative file can be passed to the server on the command line
  making it possible to have multiple configuration files. For example one for
  a testing configuration and one for a live configuration.

  The configuration file is a plain text file laid out using the WolfMUD
  record jar format.

FIELDS & VALUES

  Below is a list of expected fields for the configuration file and the values
  those fields expect. The field names are case insensitive.


  Server.Host: IP address | host name
    The IP address or host name identifying the network interface the server
    should listen on for incoming client connections. The default is 127.0.0.1
    for local connections only.

  Server.Port: port number | service name
    The port the server should listen on for incoming client connections. The
    port can be specified as an integer number, e.g. 4001, or as a service
    name, e.g. TELNET.

    Ports in the range 0 to 1024 are usually restricted and require special
    permissions. For example running a server on port 23 (TELNET) would
    require special permissions. The default port is 4001.

  Server.IdleTimeout: period
    The amount of time of inactivity after which the server should close an
    idle connection. The period can use a combination of hours (h), minutes
    (m) and seconds (s). The following are examples of valid values: 10s, 10m,
    1h, 1h30m. The default timeout for idle connections is 10m - 10 minutes.

  Server.MaxPlayers: count
    The maximum number of players allowed to be connected to the server at the
    same time. Count can be any integer from 0 to 4,294,967,295 although the
    number of players a server can actually support will be system specific.
    The default maximum number of players is 1024.

  Server.LogClient
    Determines if the IP address and source port number of the connecting
    client should be logged in the server log. Depending on legislation and
    regulations it may be prohibited to log and save this information. Some
    error messages may contain the client IP address and source port number.
    In these cases if Server.LogClient is false the IP address and port will
    be replaced with '???' instead:

      connection error: write tcp 127.0.0.1:4001->127.0.0.1:36200: write:
      broken pipe

    becomes:

      connection error: write tcp 127.0.0.1:4001->???: write: broken pipe

    The default value is false, to NOT log the incoming IP address and source
    port number.

  Quota.Window: period

    Every IP address connecting to the server has a quota of 4 connection
    attempts unless quotas are disabled. If an IP address uses up its quota it
    will be banned from connecting until its quota expire.

    Every time an IP address connects to the server it uses one of its quota.
    While the IP address is not over its quota each quota will expire after
    the Quota.Window period has passed.

    If an IP address goes over its quota then quota are expired based on the
    setting of Quote.Timeout instead. See Quota.Timeout for details.

    Example configuration entry:

      Quota.Window:  10s

    In this example if an IP address uses up its quota of 4 connections within
    10 seconds it will be banned from connecting to the server.

    Limiting connections from a client does not restrict the number of allowed
    connections. It only limits how quickly the connections are allowed to be
    made. For example an IP address could have hundreds of connections, so
    long as they are not made in rapid succession.

    If Quota.Window is set to 0 then quotas are disabled. The default value
    for Quota.Window is 0.

    NOTE: For performance reasons the number of quota per IP address is fixed
          at 4 at compile time. (See comms/ring.go, ringSize)

  Quota.Timeout: period

    When an IP address goes over its quota of connection attempts it will be
    banned from connecting to the server until its used quota expire. The
    length of time it takes for the used quota to expire is determined by the
    Quota.Timeout setting.

    If Quota.Timeout is not zero then the time taken for the used quota to
    expire is the Quote.Timeout period. If Quota.Timeout is 0 then the time
    taken for the used quota to expire is the Quote.Window period. However, if
    the IP address tries to connect during this period it will be banned for a
    further Quote.Window period from the time of the connection attempt. This
    means that if the IP address persistently tries connecting to the server
    when over its quota it will be persistently banned.

    For example:

      Quota.Window:  10s
      Quota.Timeout: 30m

    In this example an IP address can connect to the server up to 4 times
    within a 10 second window. If the IP address connects to the server more
    than 4 times within 10 seconds it will be banned from connecting to the
    server for 30 minutes.

    Another example:

      Quota.Window:  30s
      Quota.Timeout: 0

    In this example an IP address can connect to the server up to 4 times
    within a 30 second window. If the IP address connects to the server more
    than 4 times within 30 seconds it will be banned from connecting to the
    server for 30 seconds. If the IP address tries connecting to the server
    within the 30 second timeout window the 30 second timeout window will
    start over again from the time of the connection attempt.

    The default value for Quota.Timeout is 0.

  Quota.Stats: period

    The period is the minimum amount of time between logging of quota
    statistics. If Quota.Stats is set to 0 no statistics will be logged. If
    Quota.Stats is not 0 then statistics will be logged showing the current
    quota cache state. Logging is performed the next time an IP address
    connects, that is not banned, after the Quota.Stats period as elapsed:

      quota cache: 6 entries [3 evicted, 2 over quota, 1 recent]

    This shows the total number of IP addresses cached (6) of which 3 are
    stale and have just been evicted, 2 are currently over quota and banned,
    and 1 IP address has recently connected but still has a quota of
    connection attempts left.

    The default value for Quota.Stats is 0.

  Stats.Rate: period
    The period is the frequency at which statistics are collected and
    displayed by the server. The period can use a combination of hours (h),
    minutes (m) and seconds (s). The following are examples of valid values:
    10s, 10m, 1h, 1h30m. The default rate is 10s - every 10 seconds.

    Statistics will appear in the server log with the following format:

           U[n ±n] A[±n] O[n ±n] T[n ±n] G[n ±n] W[n max] P[n max]

    The values show the following data:

      U[n  ±n] - used memory, change since last collection
      A[   ±n] - number of memory allocations since last collection
      O[n  ±n] - heap objects, change since last collection
      T[n  ±n] - number of things in the world, change since last collection
      G[n  ±n] - number of goroutines, change since last collection
      W[n max] - Lock wait time since last collection / max wait since start
      P[n max] - Current number of players / maximum players since start

  Stats.GC: true | false
    This value specifies whether garbage collection should be performed just
    before server statics are collected and displayed. The default value is
    false. Note that setting this to true causes garbage collection to run at
    the same frequency as the Stats.Rate period in addition to the normal
    garbage collection.

  Inventory.Compact:
    Old setting, now unused and can be safely removed from the configuration
    file.

  Inventory.CrowdSize:
    This value determines how many players are considered to be a crowd. If
    there are more than Inventory.CrowdSize players at the same location the
    location is said to be crowded. If a location is crowded the individual
    players are not listed, instead players are informed that there is a crowd
    there. Also if a player performs an action observing players are not
    notified, but if a player is interacted with directly they will still be
    notified. The default value for Inventory.CrowdSize is 10.

  Login.AccountLength:
    This value is the minimum number of characters allowed for account IDs
    when creating new accounts. The default value is 10.

  Login.PasswordLength:
    This value is the minimum number of characters allowed for account
    passwords when creating new accounts. The default value is 10.

  Login.SaltLength:
    This value is the default length of salts generated for passwords when
    accounts are created. The default value is 32. You should not need to
    change this value.

  Debug.LongLog
    This value determines whether the long logging format is used or a shorter
    one. If set to true the log will contain times with millisecond precision
    and the file name and line number from where the log message was written
    for each message written. If set to false the log will contain times with
    a precision of seconds and no file names or line numbers. It should be
    noted that generating the file name and line numbers for each log message
    can be an expensive operation. The default value for Debug.LongLog is
    false.

    NOTE: The log will use the long format until the configuration file has
    been read and processed, at which point the short format will be switched
    to if Debug.LongLog is false. The decision to start the server with long
    logging is to aid debugging and provide more information if problems arise
    during the loading and processing of the configuration file.

  Debug.Panic:
    This value determines whether panics that occur in the client or event
    goroutines are allowed to terminate the server. Setting this value to true
    will cause the server to terminate, if set to false only the panicking
    goroutines will terminate. In either case a stack trace will be written to
    the log. The default value for Debug.Panic is false.

  Debug.AllowDump:
    This value determines if the #DUMP, #UDUMP and #LDUMP commands are
    available to players. These commands are for debugging and dump the state
    of an object to the player's terminal (#DUMP and #UDUMP) or the server log
    (#LDUMP). If set to true the commands are available, if set to false they
    are not. The default value for Debug.AllowDump is false.

  Debug.AllowDebug:
    This value determines if the #DEBUG command is available to players. The
    #DEBUG command should only be enabled for development and debugging. If
    set to true the #DEBUG command is available, if set to false it is not.
    The default value for Debug.AllowDebug is false.

  Debug.Events
    This value determines if messages are written to the log when an event is
    queued, cancelled or delivered. This can make the log very noisy and is
    usually only required for development and debugging. If set to true event
    messages will be written to the log, if set to false they will not. The
    default value for Debug.Events is false.

  Debug.Things
    This value determines if messages are written to the log pertaining to
    Things. If set to true messages will be written when a Thing is created,
    disposed of, and finalized. These messages can make the log very noisy so
    setting this value to true is only recommended when developing or
    debugging. The default value for Debug.Things is false.

  Free text block:
    The free text block contains text that is displayed as soon as a player
    connects to the server.

EXAMPLES

  The example below shows a default configuration file using default values.
  The example starts with a comment - the line starting with '//' and ends on
  the end of record marker '%%'.


// config.wrj - Default configuration file with default values.
  Server.Host:          127.0.0.1
  Server.Port:          4001
  Server.IdleTimeout:   10m
  Server.MaxPlayers:    1024
  Server.LogClient:     false
  Quota.Window:         0
  Quota.Timeout:        0
  Quota.Stats:          0
  Stats.Rate:           10s
  Stats.GC:             false
  Inventory.Compact:    8
  Inventory.CrowdSize:  10
  Login.AccountLength:  10
  Login.PasswordLength: 10
  Login.SaltLength:     32
  Debug.Panic:          false
  Debug.AllowDump:      false
  Debug.AllowDebug:     false
  Debug.Events:         false
  Debug.Things:         false


WolfMUD Copyright 1984-2016 Andrew 'Diddymus' Rolfe

    World
    Of
    Living
    Fantasy

Welcome to WolfMUD!

%%


FILES

  DATA_DIR/
    Can be any directory holding WolfMUD data files.

  DATA_DIR/config.wrj
    Default configuration file.

SEE ALSO

  configuration-file.txt, zone-files.txt

BUGS

  Some documented, some yet to be written.

COPYRIGHT

  Copyright 2017 Andrew 'Diddymus' Rolfe. All rights reserved.

  Use of this source code is governed by the license in the LICENSE file
  included with the source code.

