usr.sbin/fifolog/fifolog_create/fifolog.1

   1 .\" Copyright (c) 2008 Poul-Henning Kamp
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd Feb 9, 2008
  28 .Os
  29 .Dt FIFOLOG 1
  30 .Sh NAME
  31 .Nm fifolog_create
  32 .Nd Initialize storage for fifolog
  33 .br
  34 .Nm fifolog_write
  35 .Nd Write data to fifolog
  36 .br
  37 .Nm fifolog_read
  38 .Nd Seek and extract data from fifolog
  39 .Sh SYNOPSIS
  40 .Nm fifolog_create
  41 .Op Fl l Ar record-size
  42 .Op Fl r Ar record-count
  43 .Op Fl s Ar size
  44 .Ar file
  45 .Nm fifolog_reader
  46 .Op Fl t
  47 .Op Fl b Ar tstart
  48 .Op Fl B Ar Tstart
  49 .Op Fl e Ar tend
  50 .Op Fl E Ar Tend
  51 .Op Fl o Ar ofile
  52 .Op Fl R Ar regexp
  53 .Op Fl T Ar timefmt
  54 .Ar file
  55 .Nm fifolog_writer
  56 .Op Fl w Ar write-rate
  57 .Op Fl s Ar sync-rate
  58 .Op Fl z Ar compression
  59 .Ar file
  60 .Sh DESCRIPTION
  61 Fifologs provide a compact round-robin circular storage for
  62 recording text and binary information to permanent storage in a bounded
  63 and predictable fashion, time and space wise.
  64 .Pp
  65 A fifolog can be stored either directly on a disk partition or in a
  66 regular file.
  67 .Pp
  68 The input data stream is encoded, compressed and marked up with
  69 timestamps before it is written to storage, such that it is possible
  70 to seek out a particular time interval in the stored data, without
  71 having to decompress the entire logfile.
  72 .Pp
  73 .Nm Fifolog_create
  74 is used to initialize the first sector of a disk device
  75 or filesystem file to make it a fifolog and should be called only
  76 once.
  77 .Pp
  78 Running
  79 .Nm
  80 on an existing fifolog will reset it so that
  81 .Nm fifolog_reader
  82 and
  83 .Nm fifolog_writer
  84 will not see the previous contents.
  85 (The previos contents is not physically erased, and with a bit
  86 of hand-work, all but the first record can be easily recovered).
  87 .Pp
  88 If the file does not already exist
  89 .Nm
  90 will attempt to create and
  91 .Xr ftruncate 3
  92 it to the specified size, defaulting to 86400 records of 512 bytes
  93 if the
  94 .Fl r ,
  95 .Fl l
  96 or
  97 .Fl s
  98 arguments do not specify otherwise.
  99 .Pp
 100 .Nm Fifolog_writer
 101 will read standard input and write it to the end of the fifolog
 102 according to the parameters given.
 103 .Pp
 104 Writes happen whenever the output buffer is filled with compressed
 105 data or when either of two timers expire, forcing a partially filled
 106 buffer to be written.
 107 .Pp
 108 The first and faster timer,
 109 .Fl w write-rate ,
 110 forces available data to be written
 111 but does not flush and reset the compression dictionary.
 112 This timer is intended to minimize the amount of logdata lost in RAM
 113 in case of a crash and by default it fires 10 seconds after
 114 the previous write.
 115 .Pp
 116 The second and slower timer,
 117 .Fl s sync-rate ,
 118 forces a full flush and reset of the compression
 119 engine and causes the next record written to be a synchronization
 120 point with an uncompressed timestamp, making it possible to start
 121 reading the logfile from that record.
 122 By default this timer fires a minute after the previous sync.
 123 .Pp
 124 The
 125 .Fl z compression
 126 argument controls the
 127 .Xr zlib 3
 128 compression level, legal values are zero to nine which is the default.
 129 .Pp
 130 .Nm Fifolog_reader
 131 will retrieve records from the fifolog according to the specified
 132 parameters and write them either to stdout or the file specified
 133 with
 134 .Fl o .
 135 .Pp
 136 It is possible to specify a start and end time to limit the amount
 137 of data
 138 .Nm fifolog_reader
 139 will report.
 140 The lower-case variants
 141 .Fl b
 142 and
 143 .Fl e
 144 take a
 145 .Xr time_t
 146 value, whereas the upper-case variants
 147 .Fl B
 148 and
 149 .Fl E
 150 take human redable specifications such as "1 hour ago".
 151 .Pp
 152 The
 153 .Fl t
 154 argument forces timestamps to be formatted as "YYYYMMDDhhmmss" instead
 155 of as time_t, and
 156 .Fl T
 157 allows the specification of a
 158 .Xr strftime 3
 159 formatting string.
 160 .Pp
 161 Finally, records can be filtered such that only records matching the
 162 (REG_BASIC) regular expression specified with
 163 .Fl R
 164 is output.
 165 .Sh IMPLEMENTATION NOTES
 166 The data stored in the fifolog consists of three layers, an outher
 167 layer that allows searches to synchronization points based on timestamps
 168 without having to decompress and decode the actual contents, a
 169 compression layer implemented with
 170 .Xr zlib 3
 171 and an inner serialization and timestamping layer.
 172 .Pp
 173 The exact encoding is described in the fifolog.h file.
 174 .Pp
 175 Fifolog is particularly well suited for use on Flash based media, where
 176 it results in much lower write-wear, than a filesystem with regular
 177 logfiles rotated with
 178 .Xr newsyslog 8
 179 etc.
 180 .Sh EXAMPLES
 181 Create a fifolog with 1024*1024 records of 512 bytes:
 182 .Bd -literal
 183 fifolog_create -r 10m /tmp/fifolog
 184 .Ed
 185 .Pp
 186 Write a single record to this file:
 187 .Bd -literal
 188 date | fifolog_writer /tmp/fifolog
 189 .Ed
 190 .Pp
 191 Read it back with human readable timestamps:
 192 .Bd -literal
 193 fifolog_reader -t /tmp/fifolog
 194 .Ed
 195 .Pp
 196 One particular useful use of
 197 .Nm fifolog_writer
 198 is with
 199 .Xr syslogd 8
 200 using a line such as this in
 201 .Xr /etc/syslog.conf 5 :
 202 .Bd -literal
 203 *.* |fifolog_writer /var/log/syslog_fifolog
 204 .Ed
 205 .Sh HISTORY
 206 The fifolog tools have been liberated from an open source SCADA applications
 207 called "measured", which monitors and controls remote radio navigation
 208 transmitters for the Danish Air Traffic Control system.
 209 .Sh AUTHORS
 210 The fifolog tools were written by Poul-Henning Kamp