Permissions.xml
If you are already an senior Simple Server user, you might wonder, where the half of your configuration files are gone and what the hell this new permissions.xml is. The simple answer is - permissions.xml IS your old configuration - packaged in a new format (plus some extras, but that comes later). The permissions.xml was probably the biggest change that came with Simple Server 8.0, so you should take some time to become familiar with it.
The first striking fact is - permissions.xml is, as already the filename says, an XML file. If you have no idea what this is, you might like to read about it. If you are lazy, here a Mini-Tutorial:
What you need to know is that XML consists of elements enclosed in <> (brackets). Some of these elements might have a body in between an opening and closing tag. Example:
<a> some text </a>. <a> is the opening tag, some text is the body and </a> is the closing tag. A closing tag is always the name of the opening tag, prepended with a slash. Elements without a body can be combined into a notation like <a />, making a closing tag unnecessary - you see, that the slash now is before the closing bracket. The body can also contain more such elements, so that XML allows to structure data precisely in a more or less human readable way by putting elements within elements (this is especially useful for the area permissions described below - it also was the reason for the format change in the first place). Elements can also have attributes - fields holding some value. Example: <person firstname="adam" lastname="smith" />. Here the attributes are firstname and lastname. You MUST put the values of attributes in double quotes (two of these: "), otherwise it won't work.
This quick information should be enough to get you started working with your permissions.xml, so now lets examine the different parts of permissions.xml...
Global settings work on the whole world map, opposed to area settings (see below).
The groups are specified within the <groups> element. A group has the form:
<group name="groupName" id="Number" color="clrStr" showTitle="true|false" ignoreChestlocks="true|false" forwardUnknownCommands="true|false" />
groupName can hold any name you want the group to have (shown if showTitle="true")
The id must be a regular integer number, like 0,1,2,3,4,5...
The color determines the color a player's name is seen in the chat depending of his group and has to be a hexadecimal digit - so valid values are 0-9 and a-f for the different colors. You may refer to this page to get an idea about the color encodig.
showTitle decides whether the group name is shown beside the player's name and can have one of the values true or false
ignoreChestlocks should only be true for admin or mod groups. These have access to ALL chests, disregarding their locking state. It can also have a value of either true or false.
forwardUnknownCommands will not have any effect on the official vanilla server. This setting determines if unknown commands (commands that are not specified in commands element; see below) should be forwarded to the server (e.g. Bukkit) automatically.
Example for the default mod group: <group id="3" name="Mod" color="9" showTitle="true" ignoreChestlocks="true" forwardUnknownCommands="true" />
Members are specified in the <members> element. A member definition tells Simple Server which group the player is in. There are two types of members you can define here - based on username or based on the IP address. Those two definitions are:
<player name="username" group="id" />
<ip address="X.X.X.X" group="id" />
Where group shall be a valid ID from a group you specified in the <groups> section, name shall be the lowercase nickname of the player and address shall be a well-formed IP address.
If a player is defined in both IP and username settings, the higher group is used.
The <permissions> element is just a container grouping the permission-related settings based on the group and member specifications above. It can contain one <commands> and one <blocks> element.
The <commands> element contains the permissions and settings for all available commands. This is an example for a command:
<command name="commandName" aliases="cmd,cmnd" allow="permissionString" />
name must be the real command name (without the / or ! prefix).
The aliases attribute is optional and can be set to a list of comma separated names, which should also refer to this command (in this example - cmd and cmnd will both call the commandName command).
the <command> element can also have 2 optional attributes, which are set to false by default - you can set hidden="true" and forward="true" or forward="only". If you set hidden, the command will not be shown, when using the /help command (but it is still useable). If you set forward, the command will be forwarded to the mod you are using (e.g. Bukkit). The difference between forward="true" and forward="only" is, that with forward="true" the command is still executed by Simple Server, whereas with forward="only", the execution on Simple Server is completely disabled and only the mod is responsible for parsing and execution.
Now let's look in detail at the obligatory allow attribute (permissionString). It tells Simple Server which groups are allowed to use this command. This attribute is actually very flexible, here are some examples of how it should be used:
allow="1,3,5" - Only allow the groups with IDs 1, 3 and 5 to use this command.
allow="2-3,5+" - The groups with IDs in range 2-3 and all groups with IDs higher than 5 can use this command. If you have groups 1,2,3,4,5,7,8 then groups 2,3,5,7,8 will be able to use this command.
allow="-" and allow="" mean the same thing - that no group can use the command.
But that's not all about the syntax - since Simple Server 8.0 you can allow commands even to specific players! Again, some examples:
allow="3+;foo,bar" - Groups with IDs higher than 3 AND the players foo and bar are allowed to use this command. That means, that it does not matter which group those players are in.
So you see, you can specify a comma-separated list of individual players after a semicolon following the group listing.
You can also leave out the group listing all together, but you have to type a semicolon, for example if you want a command to be usable by the admin with the name baz you would write: allow=";baz"
If you like, you can write allow="-;baz" instead, if that looks nicer to you, because - and an empty group list mean the same thing.
Now, every time you see permissionString in the following example, you know that you can insert a group and/or nickname list as described here.
The <blocks> element can have following optional attributes:
allowPlace="permissionString", allowDestroy="permissionString" and allowUse="permissionString".
If one of those is missing, Simple Server assumes, that there are no restrictions concerning the action in question (block placement, digging and usage). The default global blocks setting looks like this:
<blocks allowPlace="1+" allowDestroy="1+" allowUse="1+">
<block id="7" allow="-" />
</blocks>
As you see, only players in the groups with IDs higher than 1 can interact with the world and no one is allowed to place bedrock (id="7"). (All block IDs can be found here)
Here you also see how to make exceptions to specific block types - you add a <block> element into the <blocks> container and override the setting for block placement. Note that you can not override the other actions for different block types, because Simple Server does not know what kind of block the block being digged or used is.
Now, for the single <block> elements you can also add the additional attribute disallow="permissionString", to indicate who is explicitly not allowed to place such a block. Example:
<block id="1" allow="2+" disallow="10,12;foo" /> - here all groups higher than 2 can place stone (id="1") except the groups 10 and 12 and the player foo. As you see, the disallow attribute overrides the allow-attribute. You can use a combination of both attributes to achieve quite complex permission settings, which might be especially useful, if you want to create areas...
Now, with everything you learned above, we can move on to the probably most powerful and fun feature the permissions.xml has to offer - area permissions.
Now first a definition of "area" - an area, in the Simple Server jargon, is a part of the world where the permissions differ from the rest. The main purpose of areas is to make a kind of ownership for parts of the world possible. E.g. you have playerA who built a castle and doesn't want anyone else to mess with it and playerB who built a statue and is afraid of griefers.
Now there are two solutions: The simple one:
Both of them would probably use the /myarea command to define 2 diagonally opposed corners of the rectangle they want to claim. The space in between would be marked in a way that no one else can do anything inside except themselves. This requires no further steps by the server administrator. Simple Server ensures that such player areas can not be created within existing areas and only grants a single area with a size of max. 50x50x50 blocks. This way players can not do harm with areas by spamming them everywhere, etc.
If a player saves an area with /myarea, an <area> entry within the <areas> element is created. The special thing about such areas is that they have an owner attribute containing the nickname of the creator. If you encounter such an area in your configuration, do not touch areas with a specified owner if you are not sure about what you do, or you might break the /myarea command. (If e.g. you remove the owner attribute, the player who created it will not be able to remove it anymore, as /myarea will think that he is not owning an area, this area effectively becoming an admin-managed area)
The powerful solution:
You as the server administrator, with full access to this configuration file, can create very interesting permission layouts - you can create huge areas for cities, put small areas for houses and their owners inside and set permissions for each of them exactly as you like. To do it, you need to know the anatomy of the <area> element (which is to be placed within the <areas> element). Lets look at yet another example:
<area name="A cool name" start="0,0" end="100,100">
<permissions>
<commands>
<command name="teleport" allow="4+" disallow=";moron" />
</commands>
<blocks allowPlace="3" allowDestroy="4">
<block id="1" allow="2+;mason" disallow="5" />
</blocks>
</permissions>
<areas>
<area name="A subarea" start="10,10" end="30,40">
<permissions>
<blocks allowDestroy="2" />
</permissions>
</area>
</areas>
</area>
Looks quite difficult, doesn't it? But now let's take it apart. The start and end attributes are obligatory for an area and can either be in the format "x,z", "x,y,z", "x,z;Dimension" or "x,y,z;Dimension". If you provide just 2 numbers, omitting the y value, the area will be declared on any height - from bedrock up into the sky. But if you provide a y-coordinate in both required attributes, the area will be a cube. And if there is no Dimension value provided, Earth will be selected.
The start and end coordinates shall be any two corners that would be NOT directly connected if you'd draw the rectangle you want to protect. 5,0 to 10,20 means that the area is from 5 to 10 on the x-axis and from 0 to 20 on the z-axis (this is important, so make sure you get it!).
The name attribute is what is shown, if a player issues the /area command while being within this area. You can have spaces in the name (so an area can also be called like name="North Pole").
The <area> element itself can contain one <permissions> block as you know it from the global settings, with some minor differences, and another <areas> block, containing more areas which are seen as subareas of this area. Subareas inherit the settings from the parent area if not overridden, so you only need to specify the difference between the subarea and the parent in the subarea settings.
The <command> elements within areas are only there to indicate permission state changes, so the only allowed attributes are name, allow and disallow. The disallow attribute can be used with commands within areas for the ability to negate the settings of a parent area, but note that you can not use disallow in the global command settings. Stuff like aliases, hidden and forward can not be changed within areas (that would not even make sense), so these attributes should not be set in areas.
Another interesting feature is that areas do not need to have subareas or permissions, so <area name="My house" start="0,0" end="10,10" /> is also a perfectly valid area. The permissions are the same as in the parent area (or the global settings, if that area is top-level), so this area works just like a tag for players using the /area command, to inform them where they are.
Now that should be everything you need to know to be able to decipher the given area example above and to create your own awesome area structures!
Happy tinkering :)