What is tsld? ============= tsld is a daemon to log the output from a temperature sensor made to James Cameron's design, described on James' site here: http://quozl.netrek.org/ts/ tsld's home page is at: http://kirriwa.net/john/software/tsld/ Source and binary packages are available. I run Redhat Linux, so I provide rpm source and binary packages, as well as source in .tar.gz. The rpm spec file is included in the tarball. Licence ======= tsld is licenced under the GPL. Bug reports, requests for new features and patches (unified diffs please) to fix bugs or add new features are welcome. You can contact me at johnc+tsld@kirriwa.net. Installation ============ See INSTALL for instructions on how to build the program. For the impatient, try "./configure && make all install". You can build an rpm with "rpmbuild -ta tsld-$VERSION.tar.gz", or by installing the source rpm and rebuilding from the spec file (these two methods produce identical results). tsld supports these options to its configure script: --enable-debug (default is disabled) Build with debug information. If this option is enabled, the tsld binary will be built with debug information (i.e. the '-g' switch will be added to CFLAGS). --with-rrdtool (default is enabled) Build with rrdtool support, if the RRD header and library can be found. If these files are not in the standard include and library paths used by your compiler, there are two configuration options which allow you to specify their locations: --with-rrdtool-includes=DIR Use rrdtool includes in DIR. DIR will be added to the compiler's include path when compiling tsld. --with-rrdtool-lib=DIR Use rrdtool library in DIR. DIR will be added to the compiler's library path when linking tsld. If either rrd.h or librrd.so/librrd.a cannot be found, rrd support will be disabled. Running tsld ============ tsld will refuse to run as root. If not given a user and group, it will use both user and group "nobody" if they exist, otherwise it will exit. I suggest creating a user "tsld" and adding it to whichever group has permission to access your serial devices. On Redhat systems since at least 7.0 (and maybe earlier), that group is "uucp". The log directory should be owned by "tsld". It's safe to allow all users to read the logs (only output from the sensor is saved in the logs), so the directory can be mode 0755. I prefer to run tsld in the default averaging mode, which logs the average temperature over the sample period rather than taking an instantaneous reading. The distribution includes a sample SysVInit startup script and sample configuration file suitable for Redhat and some other systems. I develop and run tsld on a Redhat 7.3 machine and I use this init script. My /etc/sysconfig/tsld contains: TSLD_ARGS="-r /var/run/tsld.pid -p 60 -u tsld -g uucp -s /dev/ttyS1 -l /var/spool/tsld -R /var/spool/tsld/temperature.rrd" which adds "-p 60", "-s /dev/ttyS1" and "-R /var/spool/tsld/temperature.rrd" to the defaults in tsld.sysconfig. The rpm will, in addition to the binary and man page, install tsld.init in /etc/init.d, tsld.sysconfig in /etc/sysconfig, create user and group tsld, add user tsld to the uucp group, create a directory called /var/spool/tsld owned by tsld:tsld and mode 755, and run chkconfig to add links from /etc/rc*.d to /etc/init.d/tsld. The service will be off by default -- run "chkconfig tsld on" to enable it and "/etc/init.d/tsld start" or "service tsld start" to start it. Signals ======= When logging to a file or to a directory, tsld will close and reopen its log file when sent a SIGHUP. tsld will reset the sensor (by lowering DTR for one second) when sent a SIGUSR1. Logging ======= tsld has three modes of logging data: to a directory, to a file and to an RRD database. Logging to an RRD database may be used with one of the other two methods, but these other two may not be used together. Logging to a directory ---------------------- In this mode, tsld creates one file per day, stored in one directory per month, which is in turn stored in one directory per year. In other words, tsld creates a file named YYYY/MM/DD under the specified log directory, with a new file being created each day. The log directory must exist and be writable when tsld starts, but the subdirectories will be created by tsld as required. The default sample period of 60 seconds will create a 64800 byte log file for each day. Logging to a file ----------------- In this mode, the file should be rotated regularly to limit its size and tsld sent a SIGHUP to cause it to reopen the file. This is easy to do with logrotate: /var/log/tsld { missingok postrotate /bin/kill -HUP `cat /var/run/tsld.pid 2>/dev/null` 2> /dev/null || true endscript } The default sample period of 60 seconds will add 64800 bytes to this log file per day. Logging to an RRD database -------------------------- If tsld is built with RRD support, it can add readings to an RRD database. The RRD database should be created with a minumum update period less than or equal to tsld's sample period, and with one variable for each temperature sensor. Quick guide to creating an RRD database ======================================= To create a temperature database for use with tsld, run: rrdtool create temperature.rrd \ --start 1097583060 --step 60 \ DS:office:GAUGE:300:-20:100 \ DS:lounge:GAUGE:300:-20:100 \ DS:outside:GAUGE:300:-20:100 \ DS:cellar:GAUGE:300:-20:100 \ RRA:AVERAGE:0.5:1:1440 \ RRA:AVERAGE:0.5:5:2304 \ RRA:AVERAGE:0.5:30:1728 \ RRA:AVERAGE:0.5:120:2616 \ RRA:AVERAGE:0.5:720:1900 \ RRA:AVERAGE:0.5:1440:2780 This will create a database called temperature.rrd expecting new samples every 60 seconds, with four readings called "office", "lounge", "outside" and "cellar". Each temperature sample will be between -20 and 100 degrees, and will be considered unknown if more than five minutes has elapsed since the last sample was stored. The database will contain one day of one minute samples, one week of five minute samples, four weeks of 30 minute samples, 13 weeks of two hourly samples, one year of six hourly samples and five years of daily samples. The database will be 412212 bytes in size. The start time of 1097583060 is Tue Oct 12 12:11:00 2004 UTC, and is one minute prior to the first sample I took with tsld. The RRD tutorial at: http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/tutorial/rrdtutorial.html provides a simple guide to creating a database and how to calculate the number of samples required at each resolution.