doc/source/admin.rst

   1 =============
   2  admin guide
   3 =============
   4
   5 .. Copyright (c) 2020 mudpy authors. Permission to use, copy,
   6    modify, and distribute this software is granted under terms
   7    provided in the LICENSE file distributed with this software.
   8
   9 This guide provides basic management, configuration and
  10 troubleshooting tips for mudpy administrators.
  11
  12 .. _admin-accounts:
  13
  14 admin accounts
  15 --------------
  16
  17 Either create an account named *admin* or modify the main
  18 configuration file (for example, :file:`etc/mudpy.yaml`) and change
  19 the ``.mudpy.limit.admins`` list to include the name of your initial
  20 admin user. Once you have at least one administrative user, that
  21 user can so something like :command:`set account.someuser
  22 administrator True` to elevate another account's access. It's
  23 probably best to empty or remove the ``.mudpy.limit.admins list``
  24 from the configuration before making the service publicly
  25 accessible.
  26
  27 While the service isn't running you can also edit the accounts.yaml
  28 file (probably :file:`data/accounts.yaml` unless you've changed the
  29 default data path) and add a line like
  30 ``account.someuser.administrator: true`` for any already existing
  31 account in that file. In future, a separate system command-line
  32 utility may be provided to make pre-seeding administrator accounts
  33 possible at time of installation so that the service doesn't need to
  34 be started with an initially insecure configuration.
  35
  36 content creation
  37 ----------------
  38
  39 Once you've created and awakened an avatar for an an
  40 :ref:`administrator <admin-accounts>`, you can use the interactive
  41 command-line interface to create or destroy elements and set or
  42 delete facets on them. A set of sample elements are available in the
  43 source tree and included by default from the sample configuration
  44 file (specified in its ``_load`` list). You can also just edit those
  45 files with a text editor or create a new directory with your own
  46 YAML file in it to load instead.
  47
  48 See the built-in :command:`help` as an administrator for the
  49 :command:`create`, :command:`destroy`, :command:`set` and
  50 :command:`delete` commands. For example, you can set an arbitrary
  51 value on a facet of any element like::
  52
  53     set account.someuser myperm True
  54
  55 This would add or update a *myperm* facet to the account element for
  56 the *someuser* user to have the value *True*.
  57
  58 troubleshooting
  59 ---------------
  60
  61 The administrative :command:`show` command provides a number of
  62 useful inspection tools. Here's an example testing with the
  63 :command:`evaluate` debug command from an active session with a
  64 couple of avatars awake, comparing with the output from related
  65 :command:`show group` and :command:`show element` invocations::
  66
  67     > show group actor
  68
  69     These are the elements in the "actor" group:
  70
  71        actor.avatar_admin_0
  72        actor.avatar_luser0_0
  73
  74     > evaluate actor.universe.groups['actor'].keys()
  75
  76     dict_keys(['avatar_admin_0', 'avatar_luser0_0'])
  77
  78     > show element actor.avatar_luser0_0
  79
  80     These are the properties of the "actor.avatar_luser0_0" element (in
  81     "/home/fungi/src/mudpy.org/mudpy/data/actor.yaml"):
  82
  83        gender: female
  84        inherit: ['archetype.avatar', 'archetype.actor']
  85        location: area.0,0,0
  86        name: Keyo
  87
  88     > evaluate actor.universe.contents['actor.avatar_luser0_0'].get('name')
  89
  90     'Keyo'
  91
  92 Note that for safety the :command:`evaluate` executes within the context of
  93 a command handler with limited Python :code:`__builtins__`, the
  94 :code:`mudpy` library package, and the active :code:`universe` available,
  95 and also blocks evaluation of any statement containing double-underscores
  96 (:code:`__`) as well as :code:`lambda` functions. For admins to gain access
  97 to unsafe debugging commands, the ``.mudpy.limit.debug`` option must be
  98 enabled in configuration first and the service completely restarted. It
  99 should still be considered unsafe, since the engine's file handling
 100 functions could easily alter accessible files or expressions like
 101 ``9**9**9`` could be used to hang the service for indeterminate periods.