containing various sports news and statistics. The goal of \fBhtsn\fR
is to watch the XML feed and parse the individual XML documents into
files.
+.P
+Once started, we will choose an XML feed host to connect to. The
+choice is made from a list in a round-robin fashion, and by default,
+the list contains all known TSN feed hosts. Once we have a connection,
+your username and password are sent. If they are accepted, we begin to
+parse the feed saving all XML files to the configured output directory
+(see \fI\-\-output\-directory\fR).
+.P
+If we encounter an error (say, the connection is dropped), then we
+will attempt to connect to the next host in the list after waiting
+five seconds. This process continues indefinitely.
+.P
+The program can run either interactively (i.e. outputting to the
+console), or as a daemon with the \fI\-\-daemonize\fR flag.
.SH INPUT
.SH OUTPUT
.P
-Standard out and standard error are fairly noisy. All traffic between
-htsn and the feed server is displayed on stdout. Status messages are
-interspersed when they are generated.
+Output is not generated when running as a daemon; otherwise, standard
+out and standard error are fairly noisy. All traffic between htsn and
+the feed server is displayed on stdout. Status messages are
+interspersed when they are generated with warnings and errors going to
+stderr. The following can be expected:
.IP \[bu] 2
The only data we send to the feed are the username and password. These
will be highlighted in green on stdout.
.SH LOGGING
Logging is done either to syslog or a file. The destination and
-verbosity are controlled by the \fIlog_file\fR, \fIlog_level\fR, and
-\fIsyslog\fR parameters which may be specified either on the
-command line or in the configuration file.
+verbosity are controlled by the \fI\-\-log_file\fR,
+\fI\-\-log_level\fR, and \fI\-\-syslog\fR parameters which may be
+specified either on the command line or in the configuration file.
.SH OPTIONS
+.IP \fB\-\-daemonize\fR
+Run as a daemon, in the background. When running as a daemon the
+\fI\-\-pidfile\fR, \fI\-\-run\-as\-group\fR, and
+\fI\-\-run\-as\-user\fR flags become relevant.
+
+Default: disabled
+
.IP \fB\-\-log-file\fR
If you specify a file here, logs will be written to it (possibly in
addition to syslog). Can be either a relative or absolute path. It
Default: INFO
-.IP \fB\-\-password\fR,\ \fB\-p\fR
+.IP \fB\-\-output\-directory\fR,\ \fB\-o\fR
+To which directory should we write the XML files?
+
+Default: .
+
+.IP \fB\-\-password\fR
The password associated with your TSN username. A password is
required, so you must supply one either on the command line or in a
configuration file.
Default: none
-.IP \fB\-\-output_directory\fR,\ \fB\-o\fR
-To which directory should we write the XML files?
+.IP \fB\-\-pidfile\fR
+(Daemon mode only) Create a PID file in the given location. This is
+used by the init system on Unix to keep track of the running daemon.
-Default: .
+Default: /run/htsn.pid
+
+.IP \fB\-\-run\-as\-group\fR
+(Daemon mode only) Run as the given system group. The PID file is
+written before privileges are dropped, so the only privileges needed
+by htsn are those necessary to write the XML files and (optionally)
+the log file.
+
+Default: the current group
+
+.IP \fB\-\-run\-as\-user\fR
+(Daemon mode only) Run as the given system user. The PID file is
+written before privileges are dropped, so the only privileges needed
+by htsn are those necessary to write the XML files and (optionally)
+the log file.
+
+Default: the current user
.IP \fB\-\-syslog\fR,\ \fB\-s\fR
Enable logging to syslog. On Windows this will attempt to communicate
(over UDP) with a syslog daemon on localhost, which will most likely
not work.
+Default: disabled
+
.IP \fB\-\-username\fR,\ \fB\-u\fR
Your TSN username. A username is required, so you must supply one
either on the command line or in a configuration file.
projects / dead / htsn.git / blobdiff