Man Linux: Main Page and Category List


       hearse - exchange Nethack bones files with other players


       hearse [-b | --bones-dir dir] [--bones-mode mode] [-c | --config-file
       file] [--cron] [--debug] [--delete-uploaded] [--help] [--lock-file
       file] [-q | --quiet] [--run-as-me] [--run-as-user user] [--run-as-group
       group] [--server-url url] [--stamp-file file] [--user-email address]
       [--user-token token] [--user-token-file file] [--version]


       Nethack sometimes saves the level on which you die (including your
       stuff, what killed you, and your ghost) in a "bones file".  These files
       get loaded into later Nethack games.  If you’re the only Nethack player
       on your system you’ll only get bones files you created yourself.

       hearse lets you automatically exchange Nethack bones file with other
       players.  When run it uploads any new bones files it finds on your
       system, then downloads any bones files the server feels like giving it.
       See <> for more information.

       An important thing to note is that by default using hearse will cause
       you to end up with more bones than you otherwise would have.  This
       changes the game’s balance and is considered by many players to be a
       mild form of cheating.  You can address this by turning on the
       --delete-uploaded option, but the down side is you’ll never encounter
       your own bones files.

       In order to use the Hearse server, you’ve got to supply your email
       address.  Do this by using the --user-email switch the first time you
       use the program, or by putting "user-email address" in the config file.
       Your email address will only be used to contact you about Hearse, and
       will never be given to any third party.  If you enter an invalid
       address, the server won’t be able to support you if you download a bad
       bones file, and will be forced to ban you if any of your uploaded files
       are bad.

       Hearse was set up as a service to the Nethack community.  Please
       respect that; abuse of the service can only lead to it being removed.


       The defaults are set up for a Linux system using a nethack binary which
       is either set-uid or set-gid games.  If this is what you’ve got, as
       root run

           # hearse --user-email

       one time by hand, then put

           0 3 * * * root perl -we 'sleep rand 3600'; hearse --quiet

       in /etc/crontab.


       hearse comes with default values for its various configuration settings
       which match the way many Linux systems are set up.  If any of them
       don’t match your system, you can either change them in a configuration
       file, or you can specify the right values via command line switches.
       This last isn’t as onerous as it sounds, because most people run it
       from cron.  You can put the switches in the crontab file and leave it
       at that.  If you’d rather use a configuration file, you can use the
       default location (/etc/nethack/hearse.conf), or use the -c (aka
       --config-file) switch to specify the file you’d like to use.

       The configuration file can specify all of the options for which it
       makes sense, using the long version of the option name followed by the
       value.  Blank and commented lines are ignored in the usual fashion.  A
       string value can be given as "-" to mean the empty string.  Booleans
       can use on/off/true/false/yes/no/1/0.  A sample hearse.conf is included
       with the distribution.  Eg,

           bones-dir           /local/games/nethackdir
           bones-mode          600
           quiet               on
           run-as-user         daemon
           run-as-group        -
           user-token-file     /local/games/nethackdir/hearse.user-token


       hearse needs to run with permissions like those used by Nethack itself,
       so that it can read and write the bones files.  It should not be made
       set-uid or set-gid, though; it hasn’t been audited for that.

       The default configuration will try to set both the user and group ids
       to "games".  Nethack itself will generally only be set-id to either one
       or the other, but using both hurts nothing and allows hearse to run as-
       is on more systems.  This will only work if you run hearse as root.

       If you want to disable hearse’s id setting and take care of it
       externally you can use the --run-as-me switch to turn it off, or the
       --run-as-user and --run-as-group switches for finer grained control.
       Specify '' or "-" for either of the latter to disable just that thing.


       If you’re using the pre-packaged .deb or .rpm version of hearse, the
       program is already set up to run automatically (both daily and when you
       connect to the Internet).  You don’t have to do anything unless you
       want to change this behavior.  If you’re installing hearse by hand,
       read on.

       The normal way to use the program is to run it from cron, either daily
       or on whatever schedule you like.  (There’s no harm in running it
       often, if it doesn’t find any new bones files it doesn’t even contact
       the server.)  If letting it manage its own permissions, you’d just run
       it as root.  Eg, to run it some time in the 3:00 hour, put something

           0 3 * * * root perl -we 'sleep rand 3600'; hearse --quiet

       in /etc/crontab.  The randomization is to prevent the server from
       getting hammered at the top of each time zone’s 3:00 hour.

       If you’d like to see what the server’s doing, you can use --cron rather
       than --quiet.  This will cause it to output its status message, but
       only when it actually transfers a bones file.


       If you use multiple Nethack variants which are supported by the Hearse
       server, you can run hearse for all of them.  The normal way to do this
       is to run hearse once for each variant, specifying the bones directory
       on the command line

           # hearse -b /var/games/slashem

       leaving the rest of the configuration settings to be read from the
       configuration file.  The last upload time is by default stored in the
       bones directory, so everything just works.

       The Hearse protocol requires that you have only a single concurrent
       connection for each user account (it decides what kind of bones file to
       send you based on the kind you most recently uploaded), so hearse does
       locking on the user token file in order to ensure this.  See the
       --lock-file switch for more info.


       -b, --bones-dir dir
           Specify the bones directory.  By default the program uses the first
           of /var/games/nethack, /usr/games/lib/nethackdir, and the current
           directory which contains a file called record.

       --bones-mode mode
           Specify the mode for the bones files hearse creates.  The default
           is 660.

       -c, --config-file file
           Specify an alternative configuration file.  The default is

           Suppress the "no bones to upload" message.  This makes it so that
           there’s no output at all when there’s nothing to do, but you still
           see what’s going on when bones files are transfered.  This is a
           nice way to run it from cron if you want to keep an eye on it.

           Turn debugging on.

           Delete locally generated bones files after uploading them.  Some
           people might want to do this in order to avoid changing the game’s
           balance.  Since the server normally gives you 1 bones file for each
           one you upload, if you delete your local bones after uploading them
           you’ll end up with the same number of bones you otherwise would
           have had, but they’ll be somebody else’s rather than your own.

           Show the usage message and die.

       --lock-file file
           The Hearse protocol requires that hearse do locking to be sure that
           only a single connection per user can happen at a time.  It does
           this by locking the --user-token-file.  You should not generally
           change this, but if you have special requirements (that that file
           be read only, eg), you can override it with this switch.  Use '' to
           disable locking (which I do not recommend).

       -q, --quiet
           Don’t output information messages.

           Turn off both --run-as-user and --run-as-group.

       --run-as-user user
           Use user as the real and effecitve user id, default "games".
           You’ve generally got to be root for this to work.

       --run-as-group group
           Use group as the real and effecitve group id, default "games".
           You’ve generally got to be root for this to work.

       --server-url url
           Specify the URL for the server program.  See the source or the
           --help message for the default.

       --stamp-file file
           hearse only tries to upload bones files which were created since
           the last time it sucessfully talked to the server.  The
           modification time of the --stamp-file (.hearse.timestamp by
           default) tells it when that was.  This path is taken relative to
           the --bones-dir (unless it’s absolute).

       --user-email address
           Specify your email address.  You only have to do this the first
           time you run hearse.

       --user-token token
           Specify your user token directly.  You won’t normally need to do
           this, as hearse requests the token from the server and stores it in
           the --user-token-file for later retrieval.

       --user-token-file file
           Specify the file used to store the user token, by default

           Show the version number and exit.


       The code is licensed under the GNU GPL.  Check
       <> for updated versions.


       This Unix client was written by Roderick Schertler
       <>.  The Hearse protocol, server, and Windows client
       were written by Alexis Manning <>.