.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HEARSE 1" .TH HEARSE 1 "2016-03-21" "perl v5.22.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" hearse \- exchange Nethack bones files with other players .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBhearse\fR [\fB\-b\fR | \fB\-\-bones\-dir\fR \fIdir\fR] [\fB\-\-bones\-mode\fR \fImode\fR] [\fB\-c\fR | \fB\-\-config\-file\fR \fIfile\fR] [\fB\-\-cron\fR] [\fB\-\-debug\fR] [\fB\-\-delete\-uploaded\fR] [\fB\-\-help\fR] [\fB\-\-lock\-file\fR \fIfile\fR] [\fB\-q\fR | \fB\-\-quiet\fR] [\fB\-\-run\-as\-me\fR] [\fB\-\-run\-as\-user\fR \fIuser\fR] [\fB\-\-run\-as\-group\fR \fIgroup\fR] [\fB\-\-server\-url\fR \fIurl\fR] [\fB\-\-stamp\-file\fR \fIfile\fR] [\fB\-\-user\-email\fR \fIaddress\fR] [\fB\-\-user\-token\fR \fItoken\fR] [\fB\-\-user\-token\-file\fR \fIfile\fR] [\fB\-\-version\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" Nethack sometimes saves the level on which you die (including your stuff, what killed you, and your ghost) in a \*(L"bones file\*(R". 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. .PP \&\fBhearse\fR 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. .PP An important thing to note is that by default using \fBhearse\fR 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 \fB\-\-delete\-uploaded\fR option, but the down side is you'll never encounter your own bones files. .PP In order to use the Hearse server, you've got to supply your email address. Do this by using the \fB\-\-user\-email\fR switch the first time you use the program, or by putting \f(CW\*(C`user\-email \f(CIaddress\f(CW\*(C'\fR 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. .PP 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. .SH "QUICK START" .IX Header "QUICK START" 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 .PP .Vb 1 \& # hearse \-\-user\-email your@address.com .Ve .PP one time by hand, then put .PP .Vb 1 \& 0 3 * * * root perl \-we \*(Aqsleep rand 3600\*(Aq; hearse \-\-quiet .Ve .PP in \fI/etc/crontab\fR. .SH "CONFIGURATION" .IX Header "CONFIGURATION" \&\fBhearse\fR 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 (\fI/etc/nethack/hearse.conf\fR), or use the \fB\-c\fR (aka \fB\-\-config\-file\fR) switch to specify the file you'd like to use. .PP 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 \f(CW\*(C`\-\*(C'\fR to mean the empty string. Booleans can use on/off/true/false/yes/no/1/0. A sample \fIhearse.conf\fR is included with the distribution. Eg, .PP .Vb 6 \& 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 .Ve .SH "PRIVILEGES" .IX Header "PRIVILEGES" \&\fBhearse\fR 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. .PP The default configuration will try to set both the user and group ids to \&\f(CW\*(C`games\*(C'\fR. Nethack itself will generally only be set-id to either one or the other, but using both hurts nothing and allows \fBhearse\fR to run as-is on more systems. This will only work if you run \fBhearse\fR as root. .PP If you want to disable \fBhearse\fR's id setting and take care of it externally you can use the \fB\-\-run\-as\-me\fR switch to turn it off, or the \fB\-\-run\-as\-user\fR and \fB\-\-run\-as\-group\fR switches for finer grained control. Specify \f(CW\*(Aq\*(Aq\fR or \f(CW\*(C`\-\*(C'\fR for either of the latter to disable just that thing. .SH "RUNNING FROM CRON" .IX Header "RUNNING FROM CRON" If you're using the pre-packaged \fI.deb\fR or \fI.rpm\fR version of \fBhearse\fR, 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 \fBhearse\fR by hand, read on. .PP 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 like .PP .Vb 1 \& 0 3 * * * root perl \-we \*(Aqsleep rand 3600\*(Aq; hearse \-\-quiet .Ve .PP in \fI/etc/crontab\fR. The randomization is to prevent the server from getting hammered at the top of each time zone's 3:00 hour. .PP If you'd like to see what the server's doing, you can use \fB\-\-cron\fR rather than \fB\-\-quiet\fR. This will cause it to output its status message, but only when it actually transfers a bones file. .SH "RUNNING FOR MULTIPLE NETHACK VARIANTS" .IX Header "RUNNING FOR MULTIPLE NETHACK VARIANTS" If you use multiple Nethack variants which are supported by the Hearse server, you can run \fBhearse\fR for all of them. The normal way to do this is to run \fBhearse\fR once for each variant, specifying the bones directory on the command line .PP .Vb 1 \& # hearse \-b /var/games/slashem .Ve .PP 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. .PP 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 \fBhearse\fR does locking on the user token file in order to ensure this. See the \&\fB\-\-lock\-file\fR switch for more info. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-b\fR, \fB\-\-bones\-dir\fR \fIdir\fR" 4 .IX Item "-b, --bones-dir dir" Specify the bones directory. By default the program uses the first of \&\fI/var/games/nethack\fR, \fI/usr/games/lib/nethackdir\fR, and the current directory which contains a file called \fIrecord\fR. .IP "\fB\-\-bones\-mode\fR \fImode\fR" 4 .IX Item "--bones-mode mode" Specify the mode for the bones files \fBhearse\fR creates. The default is 660. .IP "\fB\-c\fR, \fB\-\-config\-file\fR \fIfile\fR" 4 .IX Item "-c, --config-file file" Specify an alternative configuration file. The default is \&\fI/etc/nethack/hearse.conf\fR. .IP "\fB\-\-cron\fR" 4 .IX Item "--cron" Suppress the \*(L"no bones to upload\*(R" 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. .IP "\fB\-\-debug\fR" 4 .IX Item "--debug" Turn debugging on. .IP "\fB\-\-delete\-uploaded\fR" 4 .IX Item "--delete-uploaded" 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. .IP "\fB\-\-help\fR" 4 .IX Item "--help" Show the usage message and die. .IP "\fB\-\-lock\-file\fR \fIfile\fR" 4 .IX Item "--lock-file file" The Hearse protocol requires that \fBhearse\fR do locking to be sure that only a single connection per user can happen at a time. It does this by locking the \fB\-\-user\-token\-file\fR. 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 \f(CW\*(Aq\*(Aq\fR to disable locking (which I do not recommend). .IP "\fB\-q\fR, \fB\-\-quiet\fR" 4 .IX Item "-q, --quiet" Don't output information messages. .IP "\fB\-\-run\-as\-me\fR" 4 .IX Item "--run-as-me" Turn off both \fB\-\-run\-as\-user\fR and \fB\-\-run\-as\-group\fR. .IP "\fB\-\-run\-as\-user\fR \fIuser\fR" 4 .IX Item "--run-as-user user" Use \fIuser\fR as the real and effecitve user id, default \f(CW\*(C`games\*(C'\fR. You've generally got to be root for this to work. .IP "\fB\-\-run\-as\-group\fR \fIgroup\fR" 4 .IX Item "--run-as-group group" Use \fIgroup\fR as the real and effecitve group id, default \f(CW\*(C`games\*(C'\fR. You've generally got to be root for this to work. .IP "\fB\-\-server\-url\fR \fIurl\fR" 4 .IX Item "--server-url url" Specify the \s-1URL\s0 for the server program. See the source or the \fB\-\-help\fR message for the default. .IP "\fB\-\-stamp\-file\fR \fIfile\fR" 4 .IX Item "--stamp-file file" \&\fBhearse\fR only tries to upload bones files which were created since the last time it sucessfully talked to the server. The modification time of the \fB\-\-stamp\-file\fR (\fI.hearse.timestamp\fR by default) tells it when that was. This path is taken relative to the \fB\-\-bones\-dir\fR (unless it's absolute). .IP "\fB\-\-user\-email\fR \fIaddress\fR" 4 .IX Item "--user-email address" Specify your email address. You only have to do this the first time you run \fBhearse\fR. .IP "\fB\-\-user\-token\fR \fItoken\fR" 4 .IX Item "--user-token token" Specify your user token directly. You won't normally need to do this, as \fBhearse\fR requests the token from the server and stores it in the \&\fB\-\-user\-token\-file\fR for later retrieval. .IP "\fB\-\-user\-token\-file\fR \fIfile\fR" 4 .IX Item "--user-token-file file" Specify the file used to store the user token, by default \&\fI/etc/nethack/hearse.user\-token\fR. .IP "\fB\-\-version\fR" 4 .IX Item "--version" Show the version number and exit. .SH "AVAILABILITY" .IX Header "AVAILABILITY" The code is licensed under the \s-1GNU GPL. \s0 Check for updated versions. .SH "AUTHOR" .IX Header "AUTHOR" This Unix client was written by Roderick Schertler . The Hearse protocol, server, and Windows client were written by Alexis Manning .