Hostkeeper version 1.1.2 README
-------------------------------

Hostkeeper is a Palace server plugin that controls the server commands that
groups of users can issue to the server. It also provides control for small
set of palace protocol messages.  The plugin functions as front end filter
to the servers's normal privilege mechanism.  When the user issues a
command, Hostkeeper determines which groups(s) the user bongs to, and which
commands those groups are permitted to issue.  If the command is permitted
in any of the user's groups, Hostkeeper passes it on to the server.  If
not, Hostkeeper returns an appropriate error message.  Hostkeeper filters
only users whose rank is guest, member or wizard.  It does not filter gods.


Group privileges are defined in a control file called the group file.
Individual users are placed in one or more groups through use of the
"`hostkeeper bless ..." command.  All users are, by default, members of a
special group called "member".

It should be noted that the server may forbid commands to certain users
based on the user's rank (guest, member, wizard, or god).  The server's
"member" rank is distinct from Hostkeeper's "member" group.  Hostkeeper
does not make use of server "rank". Thus a Hostkeeper 'member" may be
permitted to issue a command which the server then forbids, based on the
user's rank.  The `setrank server command may be used to change the default
rank for a command.


Changes in Version 1.1.2
------------------------

Bug fixes
---------

* A bug where three extra *'s where displayed in a warning
message when a user that isn't authorized to wear a badge
attempts to is fixed.


Changes in Version 1.1.1
------------------------

Bug fixes
---------

* A bug where a blank line in the group file would cause an error
is fixed..
* `opcount is now an alias for `operatorcount without having to add
it manually.
* A bug where "***;`help hoskeeper - help on hostkeeper" would show
up whenever you typed `help for any command is fixed.

New Features
------------

* You can now add a user without them being online.
`hostkeeper bless <group> [wizCode] [name]

New Wizard Command
------------------

* `hlist list the blessed users online.


Installation
------------

The following installation instructions assume that the Palace server
has been installed in /usr/local/palace.
Hostkeeper is a standard Palace server plugin, consisting of a plugin file
and two supporting files, the group file and the bless file.  This package
includes the plugin and an initial group file.  The bless file is designed
to be created and maintained through Hostkeeper commands, however it may be
useful to build an initial bless file before
installing Hostkeeper. See the section on the Bless File Format for detail.
Hostkeeper is installed by placing the plugin file, hostkeeper.so, in the
palace binary folder, /usr/local/palace/bin, and adding the following line
to the plugin configuration file,

/usr/local/palace/<palace-name>/psdata/plugin.conf

../bin/hostkeeper.so psdata/hostkeeper.group psdata/hostkeeper.bless

The group and bless control files are placed in the
/usr/local/palace/<palace-name>/psdata/ directory.   Note that Hostkeeper
only reads the group file.  Therefore, it can be edited while the server is
running and reloaded with a command to Hostkeeper.  The bless file will be
written by Hostkeeper every time a "`hostkeeper bless ..." or "`hostkeeper
unbless ..." command is executed.  The bless file should not be edited
while the server is running.


Group File Format
-----------------

There are two entry types in the group file.  The "command" entry, and
multiple "group" entries.

The "command" entry defines commands other than the standard Palace server
commands that will be controlled by hostkeeper. Typically, these are
commands defined in other plugins.  There can be only one "command" entry
and it must be first.  It's syntax is:

  command: command1[,] ...[,] commandn

The "command:" must be at the start of a line.  The command entry may be
split onto multiple lines by starting lines after the first with one or
more spaces.

The "group" entries define the command groups. There is one "group" entry
for each group being defined.  The "group" entry lists all of the commands
which members of that group are permitted to issue. The group entry cam
also list controlled Palace Protocol Messages. Hostkeeper supports a
maximum of 31 groups.  The group entry's syntax is:

  group <name>: command1[,] ...[,] commandn

Command and group names must be alphanumeric and are not case sensitive.


Special Commands and Groups
---------------------------

There is one special command, "badge" which controls whether the user can
include a * in the screen name.  Some Iptscrae scripts grant additional
privileges to wizards and gods who include a * in their screen names.  If
badge is included in a group's commands, then the users in that group can
wear the star.

There is a special group, "member" to which all users on the server
automatically belong.  Its command list may be used to change the default
commands available to general users.


Interaction with Other Plugins
------------------------------

Hostkeeper can control access to commands supported by other plugins which
are loaded after it is, namely those which follow it in the plugin
configuration file, plugin.conf.
For example, the Plugall plugin implements the `rnolooseprops and `rpage
commands, as well as modifying the function of the `respond command.
Member rooms can be controlled so only members of the memberroom group can
create and control member rooms, while all users can still use the `respond
command as well as page the room owner with the `rpage command.

Set up the plugin.conf file:

../bin/hostkeeper.so psdata/hostkeeper.group psdata/hostkeeper.bless

../bin/plugall.so psdata/plugall.txt

And the hostkeeper.group file (note `respond is already permitted by the
member group):

command: rnolooseprops, rpage

...

group member:   help, hide, hidefrom, mute, newroom, page,
  password, rclose, rdelete, rejectesp, rejectprivate, respond,
  rguests, rhide, rkick, rname, ropen, rowner, rpainting,
  rpassword, rpicture, rscripts, runhide, runkick, sitepage,
  tock, unhide, unhidefrom, unmute,
  offer, accept,  rpage 

group memberroom: rnolooseprops, rpage, newroom, rclose, rdelete, rhide,
  rkick, rname, ropen, rowner, rpainting, rpassword, rscripts, runhide,
  runkick

This set of groups allows anyone to use the `rpage and `respond commands
while only members of the "memberroom" group can create and control member
rooms.  Users are added to this group by whispering, "`hostkeeper bless
memberroom" to them.


Bless File Format
-----------------

The format of the bless file is:

<wizcode> <group> "Screen Name"

There is one line for each user-group combination, so users who are members
of more than one group will be represented by more than one line. In normal
operations, Hostkeeper determines the user's <wizcode> and the "Screen
Name" when the "hostkeeper bless" command is issued.  If you are manually
building a Bless File, you can obtain the <wizcode> from standard server
logs.  <group> is the name of the group, and "Screen Name" is the name the
user usually uses on the Palace. If "Screen Name"  contains double quotes
or back slashes, they must be escaped with a back slash.  For example the
second entry is for the screen name SNERT "Zapper":

{PIHABIFFH} author "Hodag"
{HPIBAIHFH} cop "SNERT \"Zapper\""


Wizard and god commands
-----------------------

Hostkeeper accepts several commands from users with wizard or god status.
Access to these commands may be controlled by the standard group mechanism.
The hostkeeper command has several subcommands.  The standard group
mechanism does not permit the subcommands to be controlled separately

`hostkeeper bless <group> [wizCode] [name]
                            - Add a user to a group.  The command may
                              be whispered to the user, the user's
                              screen name may be entered as part
                              of the command, or the wizCode for the
                              user may be used.  If <wizcode> is used,
                              the enclosing braces ({}) are required
                              and the user need not be online.  Users
                              must be separately blessed for each group
                              they are to join.

`hostkeeper list            - List the blessed users and their group(s).

`hostkeeper reload          - Causes the group and bless files to
                              be read.  If there is no serious errors,
                              the new files will replace the old files.

`hostkeeper unbless [<wizcode>] [<group>]
                            - Remove a user from one or all groups.  If
                              the command is whispered, the <wizcode> is
                              optional.  If <wizcode> is entered, the
                              enclosing braces ({}) are required.  If
                              <group> is omitted, the user is removed
                              from all groups, otherwise only from the
                              specified group.

In addition, the hostkeeper provides the following command (which is part
of the managing group in the help system):
`hlist [<group>]            - List the blessed users online in <group>,
                              or all blessed users.


Special Help Command Processing
-------------------------------

If a user uses the server `help <groupOfCommands> (for example `help
rooms), Hostkeeper will respond with only those commands which are valid
for that user.  Hostkeeper does not handle other help commands.  As a
result, users can get help on specific commands that Hostkeeper prevents
them from using with `help <commandName>.


Palace Protocol Messages Handled
--------------------------------

In addition to filtering Palace and plugin commands, Hostkeeper filters a
limited set of palace Protocol Messages.  Messages which are not on this
list, and ore not generated by commands, are not subject to filtering.
Hostkeeper     Protocol       Function

  Name           Name

ppgmsg        MSG_GMSG        Global messages
ppkill        MSG_KILLUSER    Kill (of some form) a user
pppictmove    MSG_PICTMOVE    Move a picture in a room
ppnewroom     MSG_ROOMNEW     Create a new room.
ppchangeroom  MSG_ROOMSETDESC Send new room description to the server
ppspotdel     MSG_SPOTDEL     Delete a hotspot/door
ppspotmove    MSG_SPOTMOVE    Move a hotspot/door
ppspotnew     MSG_SPOTNEW     Create a new hotspot/door


Commands Handled
----------------

The Palace server permits users to issue commands based on their rank.  By
default, these permissions are granted in accordance with the following
lists, and these commands do not have to be included in the "command" entry
of the Group File in order to be included in the "group" entries.

Default Guest and Member Ranked Commands

`help [<what>] -- Provide information about server commands.
`hide [on|off] -- Control hiding yourself from other users.
`hidefrom <user> -- Hide from another user.
`mute <user> -- Mute another user.
`newroom [<name>] -- Create a new room (one allowed per user).
`page <msg> -- Summon help from an operator with message <msg>.
`password <password> -- Set your navigation password to <password>.
`rclose  -- Close this (member-created) room to further visitors
`rdelete  -- Delete this (member-created) room
`rejectesp [on|off] -- Control rejection of ESP messages.
`rejectprivate [on|off] -- Control rejection of private messages (whispers and ESP).
`respond <msg> -- Reply to the last sender of an ESP message with message <msg>.
`rguests [on|off] -- Control whether guests are allowed in this (member-created) room.
`rhide [on|off] -- Control hiding the current (member-created) room from users.
`rkick <user> -- Kick a user out of the current (member-created) room.
`rname <title> -- Rename the current (member-created) room to <title>.
`ropen  -- Open the current (member-created) room to visitors
`rowner <user> -- Transfer ownership of the current (member-created) room to <user>.
`rpainting [on|off] -- Control painting in the current (member-created) room.
`rpassword [<password>] -- Control password protection for the current (member-created) room.
`rpicture [<filename>] -- Control this (member-created) room's background image.
`rscripts [on|off] -- Control use of scripts in the current (member-created) room.
`runhide  -- Cease hiding the current (member-created) room from users.
`runkick <user> -- Cancel the kicking out of <user> from this (member-created) room.
`sitepage  -- Display the URL of this server's site page.
`tock  -- Announce the server's local time.
`unhide  -- Cease hiding from other users.
`unhidefrom <user> -- Cease hiding from another user previously hidden from.
`unmute <user> -- Cease muting another user previously muted via the `mute command.

Wizard Commands (which aren't member commands)
`autoannounce [<msg>] -- Control the greeting message sent to users when they logon.
`banip [<dur>] <ip> -- Ban all logins from an IP address.
`banlist [-a][-t][<ip>|<name>] -- Display a list of the currently banned users.
`bots [on|off] -- Control whether cyborgs (user-originated scripts) are allowed.
`comment <who> <comment> -- Add a comment to a ban record.
`death [<dur>] -- Set the default death penalty.
`defaultpaneurl [-d] [<pane> [<url>]] -- Set the default pane URL for pane <pane> to <url> (DEPRECATED).
`delete [<roomnum>] -- Delete a room.
`displayurl [<pane>] <url> [<user>] -- Display a URL to a user or the room (DEPRECATED).
`duplicate [<roomnum>] -- Duplicate a room.
`er  -- Go to the room of last (non-operator) page sender.
`extend <who> <dur> -- Modify the duration of an existing ban.
`flood [<n>|off] -- Control automatic killing of flooders.
`gag <user> -- Gag currently connected user <user>.
`glist [-kopw] [<user>] -- List information about all users currently on the server.
`kill <user> -- Kill a currently connected user.
`killfor <dur> <user> -- Kill a currently connected user for a specified duration.
`list [-kopw] [<user>] -- List information about all users in the current room.
`operatorcount  -- Show the number of operators currently logged on.
`paint [on|off] -- Control whether painting is allowed on this server.
`paneurl [-d] <roomID> [<pane> [<url>]] -- Set pane URL for pane <pane> in room <roomID> to <url> (DEPRECATED)
`pin <user> -- Pin <user> so that he or she can't move.
`propgag <user> -- Propgag a currently connected user.
`purgebanlist  -- Purge elapsed ban records.
`purgeprops [<age>] -- Purge old props from the prop file.
`repage <msg> -- Respond to the last (non-operator) page sender with message <msg>.
`roommaxguests [<n>|unlimited] -- Control the maximum guest occupancy limit for the current room.
`roommaxocc [<n>|default] -- Control the maximum occupancy limit for the current room.
`sortprops  -- Sort the props in the props file for quicker access.
`track <user> -- Track logons from a currently connected user.
`trackfor <dur> <name> -- Track logons from a currently connected user.
`trackip [<dur>] <ip> -- Track all logins from an IP address.
`unban <user> -- Unban a previously banned user (see the `ban command).
`ungag <name> -- Ungag a previously gagged user.
`unpin <user> -- Release a previously pinned user (see the `pin command).
`unpropgag <user> -- Unpropgag a previously propgagged user (see the `propgag command).
`untrack <user> -- Cease tracking a previously tracked user (see the `track command).

God Commands (which aren't wizard or member commands)
`allowedurls [on|off|<urls>] -- Control web domains allowed to use a browser client on this server.
`allowoperators [on|off] -- Control whether this server allows operators.
`authoring [on|off] -- Control whether operators and owners may author.
`avatardirectory [user|system <pathname>] -- Control the directories in which Type 1 avatars will be kept.
`avatardiskcachelimit [<size>] -- Control the size of the on-disk Type 1 avatar image data cache.
`avatarformats [<format>...] -- Control the permitted Type 1 avatar image formats.
`avatarmaxdimensions [<width> <height>] -- Control the maximum allowed dimensions of a Type 1 avatar image.
`avatarmaxsize [<size>] -- Control the maximum allowed size of a Type 1 avatar image.
`avatarmemorycachelimit [<size>] -- Control the size of the in-memory Type 1 avatar image data cache.
`avatarurl [on|off|<url>] -- Control the URL whence browser clients will fetch avatar images.
`ban <user> -- Permanently ban <user> from the server.
`botkill [on|off] -- Control whether cyborgs (user-originated scripts) may kill.
`chatlog [<filename>|off] -- Control server chat logging.
`customprops [on|off] -- Control the use of custom props on this server.
`defaultroomocc [<n>] -- Control the default room occupancy limit.
`downlist [<n>] -- Move the current room down in the room list.
`dropzone [on|off] -- Control whether the current room is a drop zone (front gate).
`entrypage [<url>] -- Control the URL to enter this server via the web browser client.
`fileserver [<url>|off] -- Control the use of an external file server.
`flushavatarcache  -- Make sure everything in the avatar cache is saved to disk.
`flushprops <days> -- Flush props older than <days> days from the prop file.
`forward [[<fromroom>] <toroom>]|off -- Control a room's forward room.
`guestaccess [on|off] -- Control whether guest users are allowed to logon to this server.
`killprop  -- Remove any and all props you are wearing from the server.
`maxocc [<n>] -- Control the maximum server occupancy limit.
`memberrooms [on|off] -- Control whether members may create their own rooms.
`nowhisper [on|off] -- Control whether whispering is allowed.
`operatorkill [on|off] -- Control whether operators may kill.
`operatorpassword <password> -- Set the operator password to <password>.
`operatorsonly [on|off] -- Control whether the current room is operators-only.
`ownerpassword <password> -- Set the owner password to <password>.
`passwordsecurity [on|off] -- Control password security.
`picdir [<pathname>] -- Control the directory from which files will be transferred.
`pinprop [on|off] -- Control usage of the pin prop.
`playerkill [on|off] -- Control whether members may kill.
`poundcheckinterval [<intv>] -- Control the pound-check interval.
`poundprotect [on|off] -- Control the operation of the pound protection feature.
`propcontrol [on|off|<rank>] -- Control the prop control feature.
`purgelimit [<age>] -- Control the prop purge limit.
`recycle [<n>] -- Control reuse of guest ID numbers.
`reportprefs  -- Show the current preference settings.
`revision [-f] -- Show revision number and other server version information.
`roomsfile [<filename>] -- Control the rooms file to be loaded when the server starts up.
`savesessionkeys [on|off] -- Control whether session keys are saved in the server log.
`securejavaaccess [on|off] -- Control if older Java clients must authenticate on closed servers.
`securelogoff [on|off] -- Control whether the authentication server tracks logoffs.
`securesite [on|off] -- Control use of an external authorization server.
`security [<authhost>[:<authport>] [<retries>] | off] -- Control the configuration of the external authorization server.
`servername <name> -- Set the server name to <name>.
`setrank <command> [<rank>] -- Control the rank setting for <command>.
`showranks  -- Display the rank settings of the various server commands.
`shutdown  -- Shut down the server.
`spoof [on|off] -- Control whether or not members may spoof.
`uplist [<n>] -- Move the current room up in the room list.
`url [<url>] -- Control the URL to advertise for clients to access this server.


Error Handling
--------------

If Hostkeeper blocks a user command, Hostkeeper may return an informative
message, such as "invalid command", or it may consume the command and do
nothing.  The behavior will be similar to what the server would do under
the same circumstances.

When the Group and Bless files are loaded, they are checked for internal
consistency.  If problems which can be safely ignored are found, an error
message is issued, and the plugin continues.  An example is the use of a
command in a "group" entry which was not declared in the "command" entry.
In this case, the command is simply ignored.  If the error is more serious,
processing is halted with a descriptive error message.

If you have any questions you can email me at joe@avatarpalace.net