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:`show result` subcommand 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     > show result 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     > show result actor.universe.contents['actor.avatar_luser0_0'].get('name')
  89
  90     'Keyo'
  91
  92 Note that for safety the :command:`show result` executes within the context of
  93 a command handler with only Python's :code:`__builtins__`, the :code:`mudpy`
  94 library package, and the active :code:`universe` available.