doc/man1/htsn.1

   1 .TH htsn 1
   2
   3 .SH NAME
   4 htsn \- Parse XML files from The Sports Network feed.
   5
   6 .SH SYNOPSIS
   7
   8 \fBhtsn\fR [OPTIONS] [HOSTNAMES]
   9
  10 .SH DESCRIPTION
  11
  12 .P
  13 The Sports Network <http://www.sportsnetwork.com> offers an XML feed
  14 containing various sports news and statistics. The goal of \fBhtsn\fR
  15 is to watch the XML feed and parse the individual XML documents into
  16 files.
  17 .P
  18 Once started, we will choose an XML feed host to connect to. The
  19 choice is made from a list in a round-robin fashion, and by default,
  20 the list contains all known TSN feed hosts. Once we have a connection,
  21 your username and password are sent. If they are accepted, we begin to
  22 parse the feed saving all XML files to the configured output directory
  23 (see \fI\-\-output\-directory\fR).
  24 .P
  25 If we encounter an error (say, the connection is dropped), then we
  26 will attempt to connect to the next host in the list after waiting
  27 five seconds. This process continues indefinitely.
  28 .P
  29 The program can run either interactively (i.e. outputting to the
  30 console), or as a daemon with the \fI\-\-daemonize\fR flag.
  31
  32 .SH INPUT
  33
  34 .P
  35 The program takes no input; a username and password must be supplied
  36 on the command-line or in a configuration file.
  37
  38 .SH OUTPUT
  39
  40 .P
  41 Output is not generated when running as a daemon; otherwise, standard
  42 out and standard error are fairly noisy. All traffic between htsn and
  43 the feed server is displayed on stdout. Status messages are
  44 interspersed when they are generated with warnings and errors going to
  45 stderr. The following can be expected:
  46 .IP \[bu] 2
  47 The only data we send to the feed are the username and password. These
  48 will be highlighted in green on stdout.
  49 .IP \[bu]
  50 All data received from the feed will be echoed in the default color to
  51 stdout.
  52 .IP \[bu]
  53 Informational messages will be highlighted in cyan and sent to stdout.
  54 .IP \[bu]
  55 Warnings will be highlighted in yellow and sent to stderr.
  56 .IP \[bu]
  57 Errors will be highlighted in red and sent to stderr.
  58
  59 .SH LOGGING
  60
  61 Logging is done either to syslog or a file. The destination and
  62 verbosity are controlled by the \fI\-\-log_file\fR,
  63 \fI\-\-log_level\fR, and \fI\-\-syslog\fR parameters which may be
  64 specified either on the command line or in the configuration file.
  65
  66 .SH OPTIONS
  67
  68 .IP \fB\-\-daemonize\fR
  69 Run as a daemon, in the background. When running as a daemon the
  70 \fI\-\-pidfile\fR, \fI\-\-run\-as\-group\fR, and
  71 \fI\-\-run\-as\-user\fR flags become relevant.
  72
  73 Default: disabled
  74
  75 .IP \fB\-\-log-file\fR
  76 If you specify a file here, logs will be written to it (possibly in
  77 addition to syslog). Can be either a relative or absolute path. It
  78 will not be auto-rotated; use something log logrotate for that.
  79
  80 Default: none
  81
  82 .IP \fB\-\-log-level\fR
  83 How verbose should the logs be? We log notifications at three levels:
  84 INFO, WARN, and ERROR. Specify the \(dqmost boring\(dq level of
  85 notifications you would like to receive (in all-caps); more
  86 interesting notifications will be logged as well.
  87
  88 Default: INFO
  89
  90 .IP \fB\-\-output\-directory\fR,\ \fB\-o\fR
  91 To which directory should we write the XML files?
  92
  93 Default: .
  94
  95 .IP \fB\-\-password\fR
  96 The password associated with your TSN username. A password is
  97 required, so you must supply one either on the command line or in a
  98 configuration file.
  99
 100 Default: none
 101
 102 .IP \fB\-\-pidfile\fR
 103 (Daemon mode only) Create a PID file in the given location. This is
 104 used by the init system on Unix to keep track of the running daemon.
 105
 106 Default: /run/htsn.pid
 107
 108 .IP \fB\-\-run\-as\-group\fR
 109 (Daemon mode only) Run as the given system group. The PID file is
 110 written before privileges are dropped, so the only privileges needed
 111 by htsn are those necessary to write the XML files and (optionally)
 112 the log file.
 113
 114 Default: the current group
 115
 116 .IP \fB\-\-run\-as\-user\fR
 117 (Daemon mode only) Run as the given system user. The PID file is
 118 written before privileges are dropped, so the only privileges needed
 119 by htsn are those necessary to write the XML files and (optionally)
 120 the log file.
 121
 122 Default: the current user
 123
 124 .IP \fB\-\-syslog\fR,\ \fB\-s\fR
 125 Enable logging to syslog. On Windows this will attempt to communicate
 126 (over UDP) with a syslog daemon on localhost, which will most likely
 127 not work.
 128
 129 Default: disabled
 130
 131 .IP \fB\-\-username\fR,\ \fB\-u\fR
 132 Your TSN username. A username is required, so you must supply one
 133 either on the command line or in a configuration file.
 134
 135 Default: none
 136
 137 .SH FEED HOSTS
 138
 139 It is possible to pass a list of feed hostnames on the command-line
 140 (see [HOSTNAMES] in the synopsis). By default \fBhtsn\fR will attempt
 141 to connect to every known TSN XML feed host in a round-robin fashion,
 142 so there is rarely a need to do this.
 143
 144 .SH BUGS
 145
 146 .P
 147 Send bugs to michael@orlitzky.com.