
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.

    If IP address or host name is not specified the server will listen on all
    available interfaces.

  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 of the connecting client should be logged in
    the server log. Depending on legislation and regulations (e.g. GDPR) the
    IP address may be considered personal data and storing of the IP address
    maybe prohibited or restricted. Some error messages may contain the client
    IP address, in these cases if Server.LogClient is false the IP address
    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->???:36200: write: broken
      pipe

    The default value is false, to NOT log the incoming IP address.

  Quota.Slots: int

    This is the number of connection attempts an IP address can make to the
    server in a Quota.Window period. If an IP address uses up all of its slots
    within a Quota.Window period it will be banned from connecting until a
    slot expires after a Quota.Window period.

    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.

    Example configuration entry:

      Quota.Slots:   5
      Quota.Window:  10s

    This example would allow an IP address to connect to the server up to five
    times in a 10 second window. If the IP address tries to connect at a rate
    faster than 5 connections in 10 seconds then the additional connections
    after the first five will be disconnected with the message:

      "Too many connection attempts, please wait before trying again."

    If Quota.Slots is set to 0 then IP quotas are disabled. The default value
    for Quota.Slots is 0. The maximum value for Quota.Slots is limited to 63.

  Quota.Timeout: period

    This configuration value is no longer used.

  Quota.Window: period

    The Quota.Window period is used to limit the rate at which Quota.Slots can
    be used up by an IP address before connections to the server start being
    refused.

    Any single IP address can connect to the server up to Quota.Slots times
    within a Quota.Window period. Additional connections after Quota.Slots has
    been reached within the Quota.Window period will be disconnected with the
    message:

      "Too many connection attempts, please wait before trying again."

    If a persistent client still tries to connect repeatedly the expiry period
    will start again from the time of the last connection attempt. That is a
    client will have to wait a minimum time of Quota.Window before that IP
    address can connect again.

    For example:

      Quota.Slots:   5
      Quota.Window:  10s

    If an IP address tries to connect to the server more than five times in 10
    seconds the sixth attempt will fail. The client will then have to wait at
    least 10 seconds before they can try again to connect. If they try within
    10 seconds they will have to wait 10 seconds from the last attempt made.

    If Quota.Window is set to 0 then IP quotas are disabled. The default value
    for Quota.Window 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:

                    A[n] O[n ±n] T[n ±n] E[n ±n] P[n max]

    The values show the following data:

      A[    n] - runtime allocations since last collection
      O[n  ±n] - runtime objects / change since last collection
      T[n  ±n] - Thing in the world / change since last collection
      E[n  ±n] - in-flight active events / change since last collection
      P[n max] - current number of players / maximum number of players

  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 Inventory.CrowdSize players or more 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 11.

  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.

  Login.Timeout: period
    The amount of time of inactivity, while in the login or account creation
    menus, 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 1m - 1 minute.

  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.Events:
    This value determines if messages are written to the log when an event is
    scheduled, suspended, 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.

  Debug.Quota:
    This value determines if quota cache information is written to the server
    log or not. If enabled lines of the following format will be written to
    the log for each IP address in the quota cache:

      QC[1  ] M[00000000...000000001 ] X[18:17:55] A[127.0.0.1]
      QC[2  ] M[00000000...000000111*] X[18:17:56] A[127.0.0.2]

    The QC value is the cache line number, starting at 1 for each report. The
    M value shows the 64 bit slot mask with 0 being an unused slot and 1 a
    used slot. If the M value ends with an asterisk '*' the IP address shown
    in the A value is over quota and cannot connect. The X value is the expiry
    time for the cache entry. The A value shows the IP address for the cache
    entry. The default value for Debug.Quota is false.

    NOTE: The IP address will be shown even if Server.LogClient is set to
    false to not log IP addresses.

  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.Slots:          0
  Quota.Window:         0s
  Stats.Rate:           10s
  Stats.GC:             false
  Inventory.Compact:    8
  Inventory.CrowdSize:  11
  Login.AccountLength:  10
  Login.PasswordLength: 10
  Login.SaltLength:     32
  Login.Timeout:        1m
  Debug.Panic:          false
  Debug.Events:         false
  Debug.Things:         false
  Debug.Quota:          false


WolfMUD Copyright 1984-2022 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.

