4 htsn \- Parse XML files from The Sports Network feed.
8 \fBhtsn\fR [OPTIONS] [HOSTNAMES]
12 The Sports Network <http://www.sportsnetwork.com> offers an XML feed
13 containing various sports news and statistics. The goal of \fBhtsn\fR
14 is to watch the XML feed and parse the individual XML documents into
17 Once started, we will choose an XML feed host to connect to. The
18 choice is made from a list in a round-robin fashion, and by default,
19 the list contains all known TSN feed hosts. Once we have a connection,
20 your username and password are sent. If they are accepted, we begin to
21 parse the feed saving all XML files to the configured output directory
22 (see \fI\-\-output\-directory\fR).
24 If we encounter an error (say, the connection is dropped), then we
25 will attempt to connect to the next host in the list after waiting
26 five seconds. This process continues indefinitely.
28 The program can run either interactively (that is, outputting to the
29 console), or as a daemon with the \fI\-\-daemonize\fR flag.
33 The program takes no input; a username and password must be supplied
34 on the command-line or in a configuration file.
38 Output is not generated when running as a daemon; otherwise, standard
39 out and standard error are fairly noisy. All traffic between htsn and
40 the feed server is displayed on stdout. Status messages are
41 interspersed when they are generated with warnings and errors going to
42 stderr. The following can be expected:
44 The only data we send to the feed are the username and password. These
45 will be highlighted in green on stdout.
47 All data received from the feed will be echoed in the default color to
50 Informational messages will be highlighted in cyan and sent to stdout.
52 Warnings will be highlighted in yellow and sent to stderr.
54 Errors will be highlighted in red and sent to stderr.
58 Logging is done either to syslog or a file. The destination and
59 verbosity are controlled by the \fI\-\-log\-file\fR,
60 \fI\-\-log\-level\fR, and \fI\-\-syslog\fR parameters which may be
61 specified either on the command line or in the configuration file.
65 .IP \fB\-\-daemonize\fR,\ \fB\-d\fR
66 Run as a daemon, in the background. When running as a daemon the
67 \fI\-\-pidfile\fR, \fI\-\-run\-as\-group\fR, and
68 \fI\-\-run\-as\-user\fR flags become relevant.
72 .IP \fB\-\-log-file\fR
73 If you specify a file here, logs will be written to it (possibly in
74 addition to syslog). Can be either a relative or absolute path. It
75 will not be auto-rotated; use something log logrotate for that.
79 .IP \fB\-\-log-level\fR
80 How verbose should the logs be? We log notifications at three levels:
81 INFO, WARN, and ERROR. Specify the \(dqmost boring\(dq level of
82 notifications you would like to receive (in all-caps); more
83 interesting notifications will be logged as well.
87 .IP \fB\-\-output\-directory\fR,\ \fB\-o\fR
88 To which directory should we write the XML files?
92 .IP \fB\-\-password\fR
93 The password associated with your TSN username. A password is
94 required, so you must supply one either on the command line or in a
100 (Daemon mode only) Create a PID file in the given location. This is
101 used by the init system on Unix to keep track of the running daemon.
103 Default: /run/htsn.pid
105 .IP \fB\-\-run\-as\-group\fR
106 (Daemon mode only) Run as the given system group. The PID file is
107 written before privileges are dropped, so the only privileges needed
108 by htsn are those necessary to write the XML files and (optionally)
111 Default: the current group
113 .IP \fB\-\-run\-as\-user\fR
114 (Daemon mode only) Run as the given system user. The PID file is
115 written before privileges are dropped, so the only privileges needed
116 by htsn are those necessary to write the XML files and (optionally)
119 Default: the current user
121 .IP \fB\-\-syslog\fR,\ \fB\-s\fR
122 Enable logging to syslog. On Windows this will attempt to communicate
123 (over UDP) with a syslog daemon on localhost, which will most likely
128 .IP \fB\-\-username\fR,\ \fB\-u\fR
129 Your TSN username. A username is required, so you must supply one
130 either on the command line or in a configuration file.
136 It is possible to pass a list of feed hostnames on the command-line
137 (see [HOSTNAMES] in the synopsis). By default \fBhtsn\fR will attempt
138 to connect to every known TSN XML feed host in a round-robin fashion,
139 so there is rarely a need to do this.
141 .SH CONFIGURATION FILE
143 Any of the command-line options mentioned above can be specified in a
144 configuration file instead. We look for a file named \(dq.htsnrc\(dq
145 in the user's home directory; its syntax is given by examples in the
146 htsnrc.example file (included with \fBhtsn\fR).
148 If you are using the \fI\-\-run\-as\-user\fR option, that means that
149 the configuration file will need to go in that user's home directory
150 (and not, for example, root's).
152 Options specified on the command-line override those in the
158 Send bugs to michael@orlitzky.com.