starbinder.sh_README.txt

# starbinder.sh_README.txt for v20140208.2214

SUMMARY:

Starbinder is a Starbound game server control system for the GNU/Linux command line. It is written as a bash shell script and requires BASH version 4 or later. It was written for Debian GNU/Linux, but should work on other Linux varieties without too much trouble. A number of BASH4-isms have been used, but most bash versions from the last five years should work.



FEATURES AND THEORY OF OPERATION:

Understanding how Starbinder works is vital to using it.

Starbinder was made for people who want to operate multiple instances of Starbound on a single Linux host, though you can use it with just one server if you want to.

It features a single "master" installation and one or more "linked" subordinate installations, using symbolic links. This allows for near-instant installation of new servers, saves disk space, makes downloading updates faster, makes backups easier, and has a number of other advantages.

Because we only have one master installation from which all other installations are based, we only need to download updates from SteamCMD once, instead of multiplied by the number of servers installed.

The linking process is very fast (nearly instantaneous), so installing a new server is very quick. Copy over your existing configuration and universe files and you can be up and running in a few seconds.

Because your master server is separate from the actively managed servers, you can exclude it from backups. The data is public and you can always download it again. This also makes it easy to size up the files in your servers and move them around.

At the time of this writing, the Starbound server installation is nearly 2GB in size. If you have six Starbound installations, you will save 10GB of disk space.

Downloading updates is faster and easier, since you only need to update one installation.

Finally, because the master installation files are used as reference only, we can mark the entire directory as read-only. This has security advantages and assures you that your installation hasn't been tampered with by accident or malice.

Another notable feature of Starbinder is that it uses tmux instead of screen as a terminal manager/multiplexer. While screen is great, I consider tmux to be a modern superior replacement. If you want to learn more about tmux, search it.

Starbinder offers simple commands to perform basic management:
 start -- start a server.
 stop -- stop a server.
 restart -- restart a server.
 status -- show detailed status information about the server process.
 list -- show all server installations and their current running/stopped status.
 update -- update the master installation and automatically stop/update all of the linked servers automatically.
 update-validate -- the same as "update", except use the SteamCMD "validate" option to validate your master installation.
 console -- get the tmux terminal for the specified server.
 install -- do everything needed to install a new linked server.
 bootstrap -- a first-time "setup" proceedure to get Starbinder up running; includes installing the Starbound master installation for the first time.
 And more...

Starbinder was written in bash and should be fairly easy for non-develloper power users to modify. I purposefully avoided certain advanced features both because it makes the script easier to interpret/modify and also because they were unnecessary (not a single array!). We don't use an external database for any configuration, and currently don't have any outside configuration. A few variables offer most of the needed customization that your average user will need.

The script has a feature to use use PAM's limits.conf configuration to allow the running user to raise the Starbound server process priority, so that it gets better treatment on the system. This can reduce lag and jitter in some games, though I am skeptical of it's usefulness in Starbound. Most modern systems have PAM limits configured and installed, so try doing "man limits.conf" and add your user to have permissions to raise it's process priority.



LIMITATIONS:

Starbinder wasn't made to be a multi-user system. It runs under a single user. This will not change.

Starbinder has not been tested for Mac OS X, but should probably work with a few modifications. Note that Mac ships with an ancient version of BASH v3 due to Apple's war on the GPL 3, so you should probably install a newer bash before trying.

We don't support multi-masters. That is, the ability to have different master template directories chained together.

We don't currently support starbound_server binary command arguments, mostly because there are very few at this time. It is likely that this will be added in the future, which means that we will need to store that information for each installation in a confgiuration file somewhere.

We don't have any crash auto-recovery at this time, but it will probably be added in the near future. I have yet to experience a Starbound server crash anyway.

The script was written to run primarily on Debian GNU/Linux. If you find a bug in your distro, contact me about it.

Starbinder can't do any in-game management, such as listing users, kicking/banning users, monitoring chat, or item/event management. Look to mods for this.



FIRST-TIME SETUP:

The first step to getting Starbinder working is getting SteamCMD installed. Please look elsewhere for instructions on how to do this.

Next, Starbinder has a number of dependacies which must be met...

The first, and most significant dependancy, is a tool named "lns". This is a link management tool. Unfortunately, you won't find it in almost any distribution and you will have to get it yourself here: http://www.chiark.greenend.org.uk/~sgtatham/utils/

Just stick lns somewhere in your path, like /usr/local/bin/.

On Debian-based distros, the following packages should handle everything else: "symlinks bsdutils coreutils grep lsof procps sudo tmux".

Next, there are a couple of variable parameters which MUST be configured before Starbinder will work. Some of these have defaults, some don't.

[email protected] # Your email address goes here.

STEAMCMD_DIR=~/bin/steamcmd # You must put your real SteamCMD installation directory here. I keep mine under ~/bin. This should be a directory.

STEAMCMD_USER="foo" # Your Steam account user. I strongly recommend opening a new Steam account and buying another copy of Starbound with it. This will isolate your primary Steam account from being attacked. EXPLOITS IN THE GAME WILL BE FOUND, YOU WERE WARNED.

STEAMCMD_PASSWD="bar" # Your Steam account password goes here.

APPDIR=~/starbinder # This is the default location where Starbinder will install servers. You might want to use /srv/starbinder instead.

BINDIR=$APPDIR/$SERVNAME/linux64 # If you are using a 32bit Linux you are sad and dumb.

INSTALL_PREFIX="starbound-" # You don't have to change this, but if you don't want a name prefix for your servers, just set this to "".

Finally, run the command "starbinder bootstrap". It will run you through some requirements checking. Fix any problems you find.

If the bootstrap process completed, you should have your setup ready for your first installation and startup.



CONFIGURATION VARIABLES:

AVAIL_ACTIONS are used mostly in the command helper display, but are also used to validate input. The INSTALL_ACTIONS1 group is single-command arguments and the INSTALL_ACTIONS2 group is dual-command arguments which require a server target.

The IN_ACTION and IN_SERVNAME variables capture the first and second arguments to the command. IN_ = raw input.

The INSTALL_PREFIX is a string which will be prepended to the names of linked server installations upon creation. The primary reason is to avoid tmux window name conflicts with the existing user environment. However, you can set it blank if you want and everything should work fine. if "starbound-" is too long, try "sbs-" for "StarBound Server".

Note that we do a bit of input validation to server names. We only allow a-z, A-Z, and 0-9 as characters. No dashes, underscores, and definitely no periods.

In fact, if you want to take a server offline and make Starbinder ignore it, just rename it to "servername.bak" or anything else with a dot in the name.

The MAIL variables are all related to email notifications, which is disabled by default. When crash recovery monitoring and automatic updates are added, this information will be used to notify upon crashes and automatic updates.

STEAMCMD_DIR provides the path to the SteamCMD installation, which STEAMCMD_BIN specifies the binary for steamcmd. Note that SteamCMD is NOT multi-user safe.

STEAMCMD_SERVER_APPID=211820 : This is the SteamCMD APPID for Starbound. You should not ever need to touch this. This tells SteamCMD what application to download/update/use.

The STEAMCMD_USER and STEAMCMD_PASSWORD are necessary beacuse SteamCMD requires user authentication for Starbound. You can not use Annonymous authentication at this time. Hopefully, this will change, because having your regular user account information in this script is a big security problem. If an exploit is found in the Starbound server or a user gains read access to your script, kiss your TF2 unusual hats inventory.

APPDIR is the base APPlication DIRectory where Starbinder installs it's master and linked servers. You can put this in your home directory, in /srv/ or wherever you want it.

MASTER_INSTALLID is simply the name of the directory for the master installation. You should never need to touch anything in this directory, as updates are handled automatically by the script.

APPBIN is the file name of the Starbound server application, usually found under the linux64/32 directory.

BINDIR is the path to where the application binary is. Unless you are running a 32bit Linux, you don't need to change this. In the future, I may set this automatically.

SBCFGFILE is the StarBound Configuration FILE location. The only reason I use this right now is to find out if the server is a new installation which has never before been configured.

LOCKFILE is used to lock the master installation during updates. This prevents more than one update command being run at the same time.

PIDFILE The process ID file for an induvidual running Starbound server. This should match the "starbound_server" binary running in memory. Note that starbound_server can't currently write it's own PID file, so we get it via tmux, which is a pain.

NICECMD is prepended to certain tasks to make them have less impact on the running system.



OTHER NOTES:

Getting the process ID of the starbound_server process is a real pain. This is because the server currently doesn't write it's PID to a file, and bash has limited easy options to get it, since we can't use $?. Hopefully Chucklefish will fix this.

Right now, if you do a ctrl+c on the console, starbound_server will shut down normally but it won't clean up it's PID file. I can't fix this, but the script automatically cleans itself up if a dead PID file is found. If Chucklefish fixed the issue with the server not writing a PID file, this won't be a problem anymore.

Starbinder currently does not automatically install SteamCMD. This is intentional and won't change. I don't want people who can't handle installing SteamCMD trying to use my script.

Starbinder does a lot of sanity checking during operations to prevent damage to itself. You will be warned if you do something weird.

Starbinder is public domain. Do what you will with it.