Server Scripts

"This isn't rocket surgery." - Krenath

Admins have access to the server over SSH, and can make use of various bash and python scripts written to make server administration easier.

Do not attempt to use any of these unless you understand exactly what they do and how they work - many are capable of permanent and irreversible damage to the world and the backups. Some apparently innocuous commands can still produce excessive server lag if misused. If in doubt, don't hesitate to ask another admin for advice.

Needless to say, commands that violate the survival principles or manipulate players in any way without their consent must not be used under any circumstances.

Usage

To call a script, state its absolute path on the commandline. If you are in /home/minecraft (shown as ~ for short), you can simply prefix the script name with ./, for instance ./grieflogsearch. The majority of scripts will give correct usage directions if called with no commandline parameters.

A reasonable understanding of unix shell usage, as well as a and decent amount of common sense are assumed in this article.

System familiarisation

Locations

• /home/minecraft/ - the minecraft user's homedir, as well as the root directory of the server itself.
• /home/minecraft/logs/ - the server's standard logs. Filenames are the time of creation, in seconds since 1970 (seconds since epoch).
• /home/minecraft/griefAlertLogs/ - the server's grief alert logs. Filenames are the time of creation, in seconds since 1970 (seconds since epoch).
• /home/teamspeak/ - the teamspeak user's homedir, location of teamspeak server and configs.
• /home/map/ - the map user's homedir, location of map generation scripts and helper scripts, as well as versions of mapper repositories.
• /var/logs/ - general server logs
• /var/www/minecraftonline/pages/ - web content
• /var/www/minecraftonline/cgi-bin/ - web scripts
• /var/lib/mediawiki/ - wiki data
• /mnt/storage/map/ - map data
• /mnt/storage/backup/home - backups of the homedirs, the web content, as well as the world tarballs.

Screen sessions

A list of screen sessions can be obtained with screen -ls. A screen session can be attached to with screen -r <user>/<name>. A new session can be created with screen -S <name>. A session can be detached with ^A-D - that is, press ctrl-a, followed by d. The user is usually "minecraft".

• minecraft/server - the session for the minecraft server restarter script (/home/minecraft/minecraftstart.sh).
• minecraft/mapgen - the session for the map generator restarter script (/home/map/startmapgenloop.sh).
• minecraft/ircbot - the session for McObot's restarter script (/home/minecraft/startircbot.sh).
• minecraft/votifier - the session for our votifier protocol emulator for server lists that allow voting (./votifier_start.sh).
• teamspeak/server - the session for the teamspeak server control (/home/teamspeak/teamspeak3-server_linux-amd64/ts3server_startscript.sh start).

The following sessions are obsolete and not maintained currently, and listed here only for academic reference:

• minecraft/comicbot - the session for YourFaceBot which generates the irc webcomics on the website. Restarter script is /home/minecraft/comicbot/startcomicbot.sh.
• minecraft/minestatus - the session for minestatusstart.sh, SlowRiot's bash reimplementation of the somewhat insecure http://minestatus.net plugin.

Cron

Cron is a scheduling daemon that enables scripts and commands to be executed at regular intervals.

• crontab -l - shows the contents of the minecraft user's crontab (scheduled execution list).
• crontab -e - opens the minecraft user's crontab for editing. Please don't mess with this unless you know exactly how cron works.

Visual approximation of console work.

The prompt

The friendly green prompt has a built-in smiley face that reflects the exit status of the last command. If it completed successfully, you get a happy smiley. If an error was registered (or a search returned no results) you get a sad face, and if something went a little strangely or may not have given you the results you expected, you'll see a surprised face. One of SlowRiot's drunken additions. Classy, huh?

Scripts

General information

• checkminecraftversion.sh - tries to find out the latest version of minecraft's version number from the official tumblr
• getchunkcoords.sh - calculates coordinates from a chunk filename. Obsolete since the mcregion format, but still useful for some calculations.
• getchunkfile.sh - calculates chunk filename from coordinates. Obsolete since the mcregion format, but still useful for some calculations.
• getchunkrange.sh - gets a range of chunk filenames using the above script, from coordinate ranges. Obsolete since mcregion.
• getdonorinfo.sh - parses the donationlog.txt file into a human-readable format. Probably of no use to admins as the log file is not readable by the minecraft user for privacy reasons.
• getdonorinfo.sh - parses the donationlog.txt file to obtain emails associated with usernames. Probably of no use to admins as the log file is not readable by the minecraft user for privacy reasons.
• gethomedistances.sh - calculates the distances of each player's home from the spawn.
• getrangeregex.py - generate a regular expression to match a specified range of numbers. Useful for grepping the logs for a range of values.
• getmaxplayers.sh - get maximum simultaneous connected players on the specified date.
• getminplayers.sh - get minimum simultaneous connected players on the specified date.
• getuniqueplayers.sh - get total unique connected players within the specified date.
• getrendersat.sh - gets a list of renders within 100 blocks of specified coordinates.
• uptime.sh - tells you how long the server has been running since the last restart, in hours, minutes and seconds.
• NBT/nbtreader <AnyNBTfile.dat> - dumps out the raw decoded contents of any NBT file. Used as a low-level component of many other scripts.

Grief detection

• grieflogsearch.sh - the big one. Searches the grief alert logs for coordinates, names, or anything really. Put up to three search terms on the commandline in quotes - for instance ./grieflogsearch.sh "X=-143" torch to search for torch breakers in the great western tunnel.
  • Since the griefalert log format change, a new version of this script has been created which is much faster, but only works with the new log types. To search older logs, first set the relevant environment variable: export griefsearchclassic=true - this setting is maintained for the remainder of your session until you perform unset griefsearchclassic to revert to default operation again.
• whobrokethecactus.sh (--parallel) - tailored search script to search the spawn cactus and reed zone for glass and sign breakages, and filters out players who have already been banned, reporting only those who have yet to be banned. The optional --parallel commandline argument will force the script to use the older parallel mode rather than the new (in theory more efficient) simultaneous mode. In some cases, this may be faster.
• whobrokethelightstone.sh (--parallel) - tailored search script to search the lightstone tunnels for lightstone breakages, and filters out players who have already been banned, reporting only those who have yet to be banned. The optional --parallel commandline argument will force the script to use the older parallel mode rather than the new (in theory more efficient) simultaneous mode. Since the parallel mode returns 100 results for each tunnel, you will get more comprehensive historical results in this mode.
• whoplacedsign.sh - search for a complete sign, who placed it and where, based on a single line of text. Alternately, search for all signs placed by a player.
• ./exec_whobrokethis.sh --debug x1 y1 z1 x2 y2 z2 - call the /whobrokethis command from the console in debug mode, with a specified coordinate range. Returns the same thing it would in-game, but with no timeout period, and outputs debugging info about the range regex generated so you can use this regex yourself manually against the logs, or tweak it as necessary.
• ./exec_identifyarea.sh x [y] z [x2 y2 z2] - shows protected [LionsArea|areas] at given coordinates or within the given range of coordinates, with y coordinate being optional if only specifying one location.

Player information

• inventorycount1a.sh - rather heavy script to search all player inventories for a specific number of items. Was once useful for finding negative numbers of items when inventory had not yet become fully server-side. Now this has little use.
• inventorycountemptyslots.sh - find out number of empty slots in a specified player's inventory at their last logout. Used by the donation system.
• inventorydump1a.sh - dump out the raw data from a specific inventory file. Inventoryinspect is much more friendly.
• inventoryfindfirstfreeslot.sh - gets the slot number of the first empty inventory slot in a specified player's inventory. Used by the donation system.
• inventoryinspect1a.sh - displays the contents of a player's inventory in a friendly, human-readable format.
• enderchestinspect.sh - displays the contents of a player's enderchest in a friendly, human-readable format.
• inventoryscan1a.sh - rather heavy script to search all player inventories for a specific block type and return counts. Useful for finding forbidden block types such as grass, adminium etc - but don't run this without nice.
• whereisplayer.sh - finds the coordinates and dimension for where a player is or last logged off.
• NBT/slotinspect <freedonia/players/Player.dat> - returns contents of the specified slot in a player's inventory as of last logout. Used as a low-level component in the other inventory examination scripts.
• getplayernotes.sh playername - displays all info, ban and warning notes for a given player name. Not case sensitive.
• addplayernote.sh playername "message" - adds an info note for the given player name with the stated message.
• getgroups.sh playername - lists all groups playername is a direct member of.
  • getgroups_by_uuid.sh uuid - same as above but takes uuid as input.
• getgroupsrecursive.sh playername - lists all groups playername is a member of, including inherited groups.
  • getgroupsrecursive_by_uuid.sh uuid - same as above but takes uuid as input.

Game actions

• ban.sh - bans the specified player and kicks them from the game.
• giveall*.sh - give all players the specified gift. To be used only on temporary maps, and in absolutely exceptional circumstances!
• griefrepair.sh - repairs grief done by a specified banned player. Can repair in an area or all of what the player done.
• inventory_giveitems.sh - inserts specified item, in specified number, and specified damage value, to specified player's inventory. Used by the donation system to hand out purchased materials. Only works if the player is offline.
• inventory_repairhotbar.sh - repairs all the items in the player's hotbar. Used by the donation system - don't do this for players for free :) Only works if the player is offline.
• inventory_setblockashat.sh - sets the first block in the player's hotbar as their hat. Used by the donation system, and only works when players are offline.
• minecraftgift.sh - hands out a random gift to every player from a certain selection of allowable item types. Called hourly by cron as the hourly gift. Runs the Hourly gift plugin.
• remoteclient01a.py - sends the commandline arguments to the server console. Best if you quote the entire string, like ./remoteclient01a.py "give slowriot 64 4". You can also send it stdin. This is one of the most powerful commands, and most scripts use this as a building block. Game notification rely on using this with commands to send messages to players. It will return one line of stdout, hoping it's a response to your query - but server lag means this is not something that can be relied on. Combine this with the server console command "remotecommand" to execute any commands as any player, from the server console.
• spamitem.sh - gets a player to continuously vomit a specified item, with the specified interval. You probably don't have permission to run this.
• NBT/add_inv <freedonia/players/Player.dat> <Item ID> <Damage value> <Amount> <Slot> - modify an inventory slot directly. Only works if the player is offline. Used as a low-level component by the other inventory modification scripts.

Server-side actions

• cleanbackups.sh - this clears all but the most recent specified number of backups. This is called automatically by the backup system and should not be used by hand.
• listplayers.sh - updates playerlist.txt. Called every minute by cron.
• minecraftbackup.sh - the big backup script. Called by cron every six hours. Should also be called in advance of any major risky server operation or upgrade.
• minecraftstart.sh - the script that starts (and restarts) the server wrapper, and consequently the server. Don't run this if the server is already running, and only run it in the server screen session.
• cleanuptimeonline.sh - called by minecraftstart before bringing the server up, this checks for any tainted login sessions left by a previous server crash, calculates the time of death of that server, and adds the correct online time to the statistics of the players who were left dangling at the time of the crash. Needed for when OnLogout isn't called in CommandOn due to a server stopping before clients disconnect, see also exec_reportout.sh.
• startircbot.sh - script that starts (and restarts) the IRC bot. Don't run this if the irc bot is already running, and only run it in the ircbot screen session.
• minestatusstart.sh - script that starts the minestatus update listener. We didn't want to use the minestatus official plugin, as we felt it had a lot of potential vulnerabilities, so SlowRiot wrote a bash version which is far safer and more configurable, not to mention lightweight.
• minestatusreply.sh - script that listens for a minestatus type query and replies appropriately.
• whoedited.sh filename - script to access the audit logs to see who edited a given watched file.
• updatetorlist.sh - script run by cron every 6 hours to update the list of TOR exit nodes we check for.
• clearemailconfirmrequests.sh - used to clear email confirmation request from registering. Confirm with y or yes. Should be done regularly.

Messaging & notification

• informationbroadcast.sh - sends out one of several tips at random. Called by cron.
• mcron-*.sh - produces literary quotes in game on several pertinent subjects. Used to be called by an automated script - currently not hooked up.
• saybashquote.sh - screen-scrapes bash.org for oneliners and dumps them in game. Originally called by cron. Now disused.
• sendtoirc.sh - makes the bot say something in IRC. Used as a component in many other scripts.
• tempwarning.sh - spams out a warning that we are on a temporary world. Called by cron when we are on a temp world, don't use this unless we are.
• warningredirection.sh - spams out a warning to be used on the redirection map, when moving servers. Not to be used otherwise.
• warningtempworld.sh - as above.
• warningtest1.sh - as above, for a specific old build of hmod.

Web functionality

• addusertogroup.sh - Adds a user to a specified group. This is used by the donation system and registration.
• getbancounts.sh - generates ban data in a suitable format for the google charts on the website. Called by cron.
• getlastbancount.sh - calculates total bans as of yesterday and writes them to /var/www/minecraftonline/pages/banchartdata.txt. Do not call this manually!
• getlastplayercount.sh - as above, but with player counts. Also do not call this manually, as it writes directly to a file, rather than displaying output.
• getplayercounts.sh - generates player connection data in a suitable format for the google charts on the website. Called by cron.
• getuniquecounts.sh - same as above, for unique player counts
• whobrokeit.sh - the script called by whobrokemyblock.html. Searches for a specific block break at a particular location. It produces output in html but is still usable from the shell, although grieflogsearch is far more powerful.

In-game utility

• exec_privatemail.pl - Private mail script that can be used from the commandline. Use it like the ingame command, the sender will be MCO_SERVER.
• exec_*.sh - scripts for the exec plugin, referenced in exec.conf. Most of these will not work if called directly from the shell.

exec plugin variables

Main article: Exec

The following variables can be made available to exec scripts, if the requisite group is specified in exec.conf for a given command:

• none - No parameters
• playername - Player name and uuid only
  • $MCEXEC_PLAYERNAME
  • $MCEXEC_PLAYERUUID
• playercoords - Player name and coordinates, plus info about current held item
  • $MCEXEC_PLAYERX
  • $MCEXEC_PLAYERY
  • $MCEXEC_PLAYERZ
  • $MCEXEC_PLAYERPITCH
  • $MCEXEC_PLAYERROTATION
  • $MCEXEC_PLAYERWORLD
  • $MCEXEC_PLAYERITEMID
  • $MCEXEC_PLAYERITEMAMOUNT
  • $MCEXEC_PLAYERITEMDAMAGE
  • $MCEXEC_PLAYERITEMSLOT
• playerworldedit - Player name, coords, and WorldEdit selection coordinates, for start and finish (or first and second depending how you want to look at it)
  • $MCEXEC_WORLDEDIT_XF
  • $MCEXEC_WORLDEDIT_YF
  • $MCEXEC_WORLDEDIT_ZF
  • $MCEXEC_WORLDEDIT_XS
  • $MCEXEC_WORLDEDIT_YS
  • $MCEXEC_WORLDEDIT_ZS

Only one of the above can be specified, and each greater permission inherits the lesser. Select only the minimum you need to avoid having the exec plugin waste cpu cycles collecting data your script doesn't need.

exec plugin commands

These are the various commands that can be called using remoteclient (/home/minecraft/remoteclient01a.py "command") or by entering them manually on the console; given is both usage and expected return output:

• getinventory player - Gets a single string representation of an online player's entire inventory. For offline players, use the inventoryinspect NBT tools listed above instead.
  • returns: [INFO] [exec] Player playername inventory: slot|id:damage:count,slot|id:damage:count,slot|id:damage:count
• setinventory player inventorystring [notify] - As above, but sets an online player's entire inventory in a single shot to the inventorystring of the format specified above (comma-separated chains of slot|id:damage:count). This checks for validity of slots. If inventorystring is just the word clear, the inventory is wiped. If notify is anything at all, the player will receive a message saying "Your inventory has been altered by the server." in yellow.
  • returns: [INFO] [exec] setinventory completed succesfully.
• takefrominventory player id data amount - Try to take a specified item from the player's inventory, with given id, data (damage) value and amount. If data is -1, it will take any matching item of that id regardless of damage value, otherwise damage is respected (0 included).
  • returns: [INFO] [exec] Player playername has succesfully lost item: id damage count
  • or returns: [INFO] [exec] Player playername does not have that much asked items, none removed.
• dropitemat x y z id data [world] - Drops an item in the world, with specified id and data (damage) values. world is optional and can be nether or normal, if unspecified it defaults to normal. Only works in currently loaded chunks.
  • returns [INFO] [exec] dropitemat response:id:damage:x:y:z:world
• getblockat x y z [world] - Gets information about a single block in the world at the given coordinates. Returns 0 for id and data if the block is in an unloaded chunk (as if it were air). world is optional and can be nether or normal, if unspecified it defaults to normal. The command returns coordinates, which should always be the same as those specified. Out of bounds coordinates still query, and should just return 0 as for air.
  • returns: [INFO] [exec] getblockat response:id:damage:x:y:z:world
• setblockat x y z id data [world] - As above, but writes a block into the world. Will not do anything if the chunk is not currently loaded. May break the universe if used on out-of-bounds coordinates. world is optional and can be nether or normal, if unspecified it defaults to normal. It will only accept ids from 0 to 255, but specifying an id that does not correspond to a game block will crash any client that tries to load it; do not create non-existant id blocks! This and the command above can be used to test for loaded chunks, but this test is by definition a "destructive" one, and potentially dangerous.
  • returns: [INFO] [exec] setblockat response:id:damage:x:y:z:world
• getplayerinfo player - pulls a bundle of information about an online player's present state; this is a basic staple of exec.
  • returns: [INFO] [exec] getplayerinfo response:x:y:z:rotation:pitch:world:health:helditem
• setplayerhealth player [rel] amount - Adjusts the player's health, either sets it absolutely from 0 to 20 if rel is not specified, or adjusts it (if rel is used) by amount relative to existing player health.
  • returns: [INFO] [exec] setplayerhealth response: currenthealth
• sendmsgtoall message - Broadcasts the exact message to everyone in-game, without any prefix. Used by the IRC bot, amongst other things.
  • returns: [INFO] [exec] Message to all succesfully sent.]
• sendmsgtoplayer player message - like above, but send message' to specified player only.
  • returns: [INFO] [exec] Message to player playername succesfully sent.
• sendmsgtogroup group message - like above, but send message to specified group only.
  • returns: [INFO] [exec] Message to group groupname succesfully sent.
• spawnmonsterat x y z [monster] [world] - Spawns a specified monster at the given coordinates. If monster is not specified, a pig is spawned. World can be nether or normal, if unspecified it defaults to normal.
  • returns: [INFO] [exec] spawnmonsterat response:x:y:z:mobtype:world
• savetolog level message - Writes a custom log message. Level is one of info, severe or warning.
  • returns nothing, this is the one silent command. It would be silly to log use of the logging command.
• remotecommand player command - execute command as if player had typed it in chat. It can include chat itself; slash commands behave as expected, in full with parameters etc. This temporarily gives the player the right to execute whatever command he calls, if he did not otherwise have it. This can be used with other exec scripts for endless possible complexity.
  • returns: [INFO] [exec] Trying to execute "command" for user playername
• wrathofthunder x y z - This is provided by LionsCommands rather than exec. Same as /wrathofthunder in-game command with coordinates, it fires a bolt of lightning at the specified spot.
  • returns: [lionsCommands][ConsoleCommand] Server issued a thunderbolt at x y z

Control panel plugins

• cpplugin_* - scripts for the control panel api, as referenced in cpplugin.conf and demonstrated in cpplugin_example.sh. These are executed by the web user for different tabs of the control panel, as appropriate. Most of these will not work if called directly from the shell.

cpplugin variables

The following variables are made available to all cpplugin scripts:

• $WEBCP_ACTION - action requested (url subcode, i.e. "example")
• $WEBCP_USERNAME - username of the player browsing the control panel
• $WEBCP_ISMOD - true if browsing player is a mod, false otherwise
• $WEBCP_ISADMIN - true if browsing player is an admin, false otherwise
• $WEBCP_DATADIR - the player data directory (by default /home/minecraft/freedonia/playerdata) - this should always be used rather than manually specifying that dir
• $REMOTE_ADDR - the ip of the visiting player (all the other standard apache variables are available also)
• $REQUEST_METHOD - either GET or POST
• $QUERY_STRING - the GET request in full

Misc

• base36to10.sh - conversion of numbers in base36 to decimal, used for chunk location calculations.

Unusued

• banmessage.sh - unused ban message prototype script.
• blogspam.sh - obsolete script to notify in game when notch updates his tumblr.
• drawhomesmap01a.sh to drawhomesmap02a.sh - obsolete homes map plotter, now replaced with a proper live map.
• getmaplatlang.sh - incomplete script intended to convert world coordinates to map lat and lang.
• getmarkedchunks.sh - get list of chunk files between coordinates marked by the special warps marker1 and marker2. No longer has a use since mcregion.
• griefsummary.sh - obsolete grieflog processing script to obtain statistics from the previous day's log. Logs now are too complicated for such a simple script.
• lockmarkedchunks.sh - obsolete script to write-protect certain chunks, which no longer works since mcregion.
• unlockmarkedchunks.sh - obsolete script to un-write-protect certain chunks, which no longer works since mcregion.
• movechunks.sh - obsolete since mcregion
• populatebannednpcs.sh - creates npcs in the npc config file for every banned player. This breaks npc, and most clients viewing them.
• readlog.sh - obsolete log parser
• restorechunks.sh - restore selected chunks from backup - obsolete since mcregion.

Files and directories

This is a list of relevant configuration files and log locations that can be examined and manipulated manually if appropriate.

Most changes to these will require issue of the /reload command in-game by an admin or moderator. Plugin-specific config files will require /reloadplugin <plugin> by an admin. Please note not all plugins can be reloaded safely at runtime, and some require a full server restart instead - most notably GriefAlert, which produces log events in duplicate (resulting in double mob spawner drops), and WorldGuard (which has a tendency to drop creeper protection).

Configs

• antixray.txt - list of block ids for canary's xray protection to hide.
• allowedmobspawns.txt - list of mobs god donors can spawn.
• banned-ips.txt - ip ban file. Not generally used.
• banned-players.txt - Legacy list of banned players. Very frequently searched for griefer names. Player names are all lowercase.
• bans.txt - Canary's current list of banned players, in the format username:ban reason:time remaining (for temp bans, which we don't use).
• blockcolourids.txt - list of damage values and relative colour name for blocks like wool, carpet, stained clay, stained glass and stained glass pane.
• borderlands.properties - definition file for BorderLands plugin which prevents players exiting a set diameter circle.
• borders.txt - border centre and size definition for BorderLands plugin. Set to 18km diameter, centered on Central Nexus.
• cauldron-recipes.txt - unused, cauldron recipes list for Craftbook (which is disabled here)
• cb-cartcraft-recipes.txt - file for craftbook minecart crafting recipies
• CommandOnPlayers.txt - permissions definition file for CommandOn plugin, left as default
• CommandOn.properties - configuration file for CommandOn plugin, left as default
• CommandOn.txt - definitions file for CommandOn plugin, this defines all the PVP messages and admin god mode.
• craftbook-books.txt - default book lines for right-clicked bookshelves, used by Craftbook when no book sign is placed on the bookshelf.
• craftbook.properties - properties file for Craftbook, defines what may and may not be used, as well as minecart settings.
• cuboidPlugin.properties - properties file for Cuboid, many of these settings are unused.
• custom-ics.txt - custom IC definitions for Craftbook, not currently used.
• damagednames.txt - list of blocks and the names for specific damage values.
• donationerrorlog.txt - error log for donation system, written at time of donation. Not accessable by the minecraft user for privacy reasons.
• donationlog.txt - complete log for donation system, written at time of donation Not accessable by the minecraft user for privacy reasons.
• endermanblocks.txt - Canary's list of blocks the enderman may pick up, for the internal enderman nerf.
• exec.conf - definition file for the exec plugin, specifying what commands to listen for and what shell scripts or programs to execute.
• geardurability.txt - list of gear items and their max durability value.
• griefAlert.properties - settings for the GriefAlert plugin for what blocks are logged, see watchedBlocks.txt.
• groups.txt - definitions file for the different user groups, this defines moderator and donor permissions, commands and prefixes.
• homes.txt - list of player home coordinates used by Canary.
• items.txt - list of blocks and items, and their numerical and name IDs. Kept up to date with each release, this is the file that's referenced directly by Canary.
• kits.txt - definition file for donor and moderator kits obtained using the /kit command.
• lionsCommands.properties - configuration file for overrides by lionsCommands, specifically the /who command and additional /ban data.
• lionsMod.properties - configuration file for general properties in lionsMod. Most of this isn't used on this server.
• lionsShop.properties - configuration file for the LionsShop plugin, currently just defines shop tax details.
• lwc.properties - basic config file for LWC. Mainly default.
• lwc.db - chest locks data, and also limits settings for LWC. Sqlite format, openable with sqlite3 lwc.db "whatevercommand".
• minecraftgift_ids.txt - list of blocks and items (in name IDs) for minecraftgift.sh (hourly gifts) and exec_randomgift.sh (/randomgift).
• mineremote.ini - Configuration for the multiplexer, specifies which .jar to launch.
• motd.txt - Canary's current message of the day file, split out from server.properties.
• muted-players.txt - Canary's persistence file for player mutes. Not used at MCO.
• npcs.properties - config for NPCs plugin which is not currently used.
• ops.txt - official server ops, this is only used by notch's vanilla server.
• playerlist.txt - automatically generated file produced by listplayers.sh.
• server.properties - the main minecraft server config file, this defines behaviour for the vanilla server itself plus some canary details. Mob spawning, world name, etc are defined here. Most settings require a restart to take effect.
• stackableitems.txt - list of items which have a max stack count that is not 64.
• torlist.txt - list of known TOR exit node ips, kept updated automatically by updatetorlist.sh.
• teamspeaklist.txt - automatically generated file produced by listteamspeak.sh.
• warps.txt - definition file listing warp names and coordinates.
• watchedBlocks.txt - definitions file for what griefAlert should watch.
• white-list.txt - list of players who can log in when in whitelist mode. Only used for occasional server debugging.
• whitelist.txt - as above
• worldedit.properties - config file for WorldEdit plugin.
• worldedit-restrictions.txt - permissions definition file for WorldEdit. Not currently in use.
• worldguard-blacklist.txt - Block and item use blacklist and notification list. Not currently used, using GriefAlert instead.
• worldguard.properties - Configuration file for WorldGuard, which prevents fire spread, lava fire, tnt and creeper explosions, multiple logins, and a few other bits.
• world/craftbook/areas/~UserName/areaname.cbcopy - WorldEdit saved areas for toggleable areas with Craftbook.
• world/craftbook/warps.txt - list of craftbook cbwarps, mostly used for the nexus.
• /etc/mediawiki/LocalSettings.php - wiki configuration.
• /var/www/minecraftonline/cgi-bin/kitprices.txt - Donation kit definition file and price list.
• /var/www/minecraftonline/cgi-bin/materialprices.txt - Donation material definition file and price list.

Player info files

These are all files in the player data dir, by default /home/minecraft/freedonia/playerdata, this location is available to cpplugin scripts as the variable $DATADIR. Each of these files is player-specific, so there is no need to search for a particular file; to get SlowRiot's email address, you simply cat $DATADIR/email-SlowRiot.txt.

• deathlog-playername.txt - Chronological log of player deaths in the format YYYY-MM-DD hh:mm:ss:x:y:z:world:cause or YYYY-MM-DD hh:mm:ss:x:y:z:world:pvp_<killingplayername>.
• email-playername.txt - email address of the player.
• emailconfirmaddress-playername.txt - Temporary file used to hold pending email addresses waiting to be confirmed.
• emailconfirmhash-playername.txt - Temporary file holding a unique hash associated with an email address in order to confirm it.
• emailperms-playername.txt - Whether we have opt-out permission to email this player, either true' or false.
• facebook-birthday-playername.txt - Birthday of the player, if they have a facebook account linked, in the format MM/DD/YYYY (American date format)
• facebook-gender-playername.txt - Gender of the player, if specified on facebook and available to the facebook app.
• facebook-timezone-playername.txt - Time offset from GMT in hours for the player, according to facebook, if known
• facebook-uid-playername.txt - Facebook UID, everyone has one of these if they link their account, so this is the best file to check to see if they've linked with facebook.
• facebook-username-playername.txt - Facebook username, this is the optional quasi-url you can set (such as facebook.com/slowriot)
• firstjoin-playername - Date and time, in the format YYYY-MM-DD hh:mm:ss - note the lack of trailing .txt, as an artefact of previous bad programming
• friendlist-playername.txt - Line by line list of a player's friends, in order of addition.
• passhash-playername.txt - Salted hash of the player's control panel password, against which login attempts are checked. Not possible to reverse this to get a plain-text password.
• referrer-playername.txt - Web referrer as determined by the firstjoin portion of the exec_reportin.sh script.
• referringplayer-playername.txt - Name of a player they put as their referring player when registering.
• reputation-pos-playername.txt - Line by line list of the people who have given this player good reputation.
• reputation-neg-playername.txt - Line by line list of the people who have given this player bad reputation.
• session-playername.txt - Session id for a control panel login. Stored in a cookie given when logging in, this is tracked and rotated as a security measure.
• settings-privateprofile-playername.txt - Control panel setting toggle for whether to show a control panel profile to non-logged-in users, either true or false (CURRENTLY UNUSED - see below opt-out instead)
• settings-publicprofile-playername.txt - Control panel setting toggle for whether to hide a control panel profile from non-logged-in users, either true or false.
• settings-showemail-playername.txt - Control panel setting toggle for whether to show the player's email address on a control panel profile, either true or false.
• settings-showflag-playername.txt - Control panel setting toggle for whether to show the player's geo-ip country flag on their profile, either true or false.
• settings-showfriends-playername.txt - Control panel setting toggle for whether to show a player's friends list on their profile, either true or false.
• settings-showgeoip-playername.txt - Control panel setting toggle for whether to show geographical ip location in detail on their profile, either true or false.
• settings-showhome-playername.txt - Control panel setting toggle for whether to show the player's in-game home location on their profile, either true or false.
• smsperms-playername.txt - Whether we have permission to send the player SMS messages (not currently implemented), either true or false.
• tpaliases-playername.txt - Line by line list of /tpto aliases, in the format name:x:y:z:pitch:rotation:world where world is 0 for normal, -1 for Nether or 1 for End.

There are a number of subdirectories for specific subsystems also.  bastetfurry's banking system stores its data in its own directory:

• banking/accounts/accountnumber - Accounts may be shared between players, and are stored here by number.
• banking/players/playername - Each player file contains a line-by-line list of the accounts they can access.

The private messaging system by bastet stores its message data here:

• messaging/playername - email to playername. Please refrain from accessing this data or searching it automatically unless there is an actual bug to fix; this may contain sensitive private data, and it is our responsibility to protect the players' privacy.

Unused

• banned.txt - obsolete ban list for Notch's vanilla server
• botmacros.txt - obsolete list of server keyword tips
• itemids.txt - obsolete item list, instead use the file below...
• leafDropperItems.txt - obsolete file for a plugin we no longer use which used to fix leaf decay before notch finally got around to it.
• leafDropper.properties - as above.
• protectedCuboids.txt - obsolete cuboid data file (this data is now in ~/cuboids/)
• reservelist.txt - unused, list of players who have reserve slots even when the player limit is reached.
• sessionProtect.txt - obsolete, the settings file for a plugin we no longer use that used to prevent multiple logins.
• vanish.properties - obsolete config file for an invisibility plugin that never quite worked properly.
• white-list.txt - unused, server whitelist file for player names. Occasionally activated for debugging the server.

Tips and tricks

General

• Always use nice <command> if running any search or other cpu-intensive command that's likely to take more than a second or so. Otherwise you risk causing lag on the server for the duration of your command.
• Use the pager most to read and search through long output, for instance <grep command with many results> | most. You can search within the most buffer by pressing /, and going to the next and previous results with n and shift-n respectively.

grep

• Always use fgrep instead of grep unless you're specifically using regular expressions. It's somewhat faster.
• Don't use the -i (case insensitive) option for grep unless you specifically need it. It increases search time and workload exponentially to the length of your search string.

System monitoring

• Use top to see what's going on with the system.
• Use ps auxf to get a detailed process list. Works well if piped to most.

Sample one-liners

Here are some useful example one-liners that you can try pasting in the terminal and amending to suit your requirements for various kinds of data-gathering. Simply copy and paste these on one line.

• Search the new log format for griefstick use, and amount of each block broken, and return the results in natural language:

IFS=$'\n'; for blockid in `nice fgrep griefstick griefAlertLogs/*.log | cut -d : -f 7 | sort | uniq -c | sort -n | tr -s ' '`; do blockname=$(nice fgrep ${blockid##* } items.txt | head -n 1 | cut -d : -f 1); echo "$blockname broken${blockid% *} times"; done

• Search the new log format to see who's been naughty by breaking adminium with the modstick:

nice fgrep "griefstick:7:" griefAlertLogs/*.log | cut -d : -f 5 | sort | uniq -c | sort -n | tr -s ' '

• Search a combined pair of standard and grief logs, for just results for the players GodlyCheese and ralfie, and browse through them with a pager (useful for finding the events and interactions leading up to a ban, for instance):

cat logs/server_1306022688.log griefAlertLogs/1306022690.log | sort | grep "Godly\|ralf" | fgrep -v Connected | most

• Compare the online hours of all registered users (mods, admins and donors) and display the top ten (this takes a while to run!):

for name in `cut -d : -f 1 /home/minecraft/users.txt | fgrep -v '#'`; do echo $(egrep -h "\[INFO\] Connected players: .*$name" /home/minecraft/logs/*.log | cut -d ':' -f 1 | uniq | wc -l): $name; done | sort -n | head -n 10

• Scan all ban history, and display any error bans that have not been unbanned but have never visited Freedonia (this is VERY slow - expect ten minutes upwards):

IFS=$'\n'; for banline in $(fgrep "[lionsCommands][ADMIN] " logs/*.log); do ban=$(echo "$banline" | cut -d ' ' -f 7); banner=$(echo "$banline" | cut -d ' ' -f 5); if find freedonia/players/ | fgrep -iq $ban; then >/dev/null; else if fgrep -iq "$ban" "banned-players.txt"; then echo "$ban banned by $banner"; if grep -iPq "\b$ban\b \[.*\] logged in" logs/*.log; then echo "(but HAS visited)"; fi; fi; fi; done

• Scan donation log for material purchases, and display in ascending order of popularity:

for idline in $(/home/minecraft/getdonorinfo.sh | fgrep material | cut -d ' ' -f 7 | cut -d '_' -f 2 | cut -d '-' -f 2 | sort | uniq -c | tr -s ' ' | sort -n); do idcount=$(echo $idline | cut -d ' ' -f 2); id=$(echo $idline | cut -d ' ' -f 3); idname=$(grep ":$id$" /home/minecraft/items.txt | head -n 1); echo "$idname($id) x$idcount"; done

• Show all of a player's LWC-locked chests:

sqlite3 lwc.db "select * from protections where owner = 'playername';"

See also

• Plugins
• Canary