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 February 9, 2008
  28 .Os
  29 .Dt FIFOLOG 1
  30 .Sh NAME
  31 .Nm fifolog_create , fifolog_write , fifolog_read
  32 .Nd "initialize, write, seek and extract data from a fifolog"
  33 .Sh SYNOPSIS
  34 .Nm fifolog_create
  35 .Op Fl l Ar record-size
  36 .Op Fl r Ar record-count
  37 .Op Fl s Ar size
  38 .Ar file
  39 .Nm fifolog_reader
  40 .Op Fl t
  41 .Op Fl b Ar tstart
  42 .Op Fl B Ar Tstart
  43 .Op Fl e Ar tend
  44 .Op Fl E Ar Tend
  45 .Op Fl o Ar ofile
  46 .Op Fl R Ar regexp
  47 .Op Fl T Ar timefmt
  48 .Ar file
  49 .Nm fifolog_writer
  50 .Op Fl w Ar write-rate
  51 .Op Fl s Ar sync-rate
  52 .Op Fl z Ar compression
  53 .Ar file
  54 .Sh DESCRIPTION
  55 Fifologs provide a compact round-robin circular storage for
  56 recording text and binary information to permanent storage in a bounded
  57 and predictable fashion, time and space wise.
  58 .Pp
  59 A fifolog can be stored either directly on a disk partition or in a
  60 regular file.
  61 .Pp
  62 The input data stream is encoded, compressed and marked up with
  63 timestamps before it is written to storage, such that it is possible
  64 to seek out a particular time interval in the stored data, without
  65 having to decompress the entire logfile.
  66 .Pp
  67 The
  68 .Nm fifolog_create
  69 utility
  70 is used to initialize the first sector of a disk device
  71 or file system file to make it a fifolog and should be called only
  72 once.
  73 .Pp
  74 Running
  75 .Nm fifolog_create
  76 on an existing fifolog will reset it so that
  77 .Nm fifolog_reader
  78 and
  79 .Nm fifolog_writer
  80 will not see the previous contents.
  81 (The previous contents are not physically erased, and with a bit
  82 of hand-work all but the first record can be easily recovered.)
  83 .Pp
  84 If the
  85 .Ar file
  86 does not already exist,
  87 .Nm
  88 will attempt to create and
  89 .Xr ftruncate 2
  90 it to the specified size, defaulting to 86400 records of 512 bytes
  91 if the
  92 .Fl r , l
  93 or
  94 .Fl s
  95 options do not specify otherwise.
  96 .Pp
  97 The
  98 .Nm fifolog_writer
  99 utility
 100 will read standard input and write it to the end of the fifolog
 101 according to the parameters given.
 102 .Pp
 103 Writes happen whenever the output buffer is filled with compressed
 104 data or when either of two timers expire, forcing a partially filled
 105 buffer to be written.
 106 .Pp
 107 The first and faster timer,
 108 .Fl w Ar write-rate ,
 109 forces available data to be written
 110 but does not flush and reset the compression dictionary.
 111 This timer is intended to minimize the amount of logdata lost in RAM
 112 in case of a crash and by default it fires 10 seconds after
 113 the previous write.
 114 .Pp
 115 The second and slower timer,
 116 .Fl s Ar sync-rate ,
 117 forces a full flush and reset of the compression
 118 engine and causes the next record written to be a synchronization
 119 point with an uncompressed timestamp, making it possible to start
 120 reading the logfile from that record.
 121 By default this timer fires a minute after the previous sync.
 122 .Pp
 123 The
 124 .Fl z Ar compression
 125 option controls the
 126 .Xr zlib 3
 127 compression level; legal values are zero to nine which is the default.
 128 .Pp
 129 The
 130 .Nm fifolog_reader
 131 utility
 132 will retrieve records from the fifolog according to the specified
 133 parameters and write them either to standard output or the file specified
 134 with
 135 .Fl o .
 136 .Pp
 137 It is possible to specify a start and end time to limit the amount
 138 of data
 139 .Nm fifolog_reader
 140 will report.
 141 The lower-case variants
 142 .Fl b
 143 and
 144 .Fl e
 145 take a
 146 .Vt time_t
 147 value, whereas the upper-case variants
 148 .Fl B
 149 and
 150 .Fl E
 151 take human-readable specifications such as
 152 .Dq Li "1 hour ago" .
 153 .Pp
 154 The
 155 .Fl t
 156 option forces timestamps to be formatted as
 157 .Dq Li "YYYYMMDDhhmmss"
 158 instead of as
 159 .Vt time_t ,
 160 and
 161 .Fl T
 162 allows the specification of an
 163 .Xr strftime 3
 164 formatting string.
 165 .Pp
 166 Finally, records can be filtered such that only records matching the
 167 .Pq Dv REG_BASIC
 168 regular expression specified with
 169 .Fl R
 170 are output.
 171 .Sh IMPLEMENTATION NOTES
 172 The data stored in the fifolog consists of three layers, an outer
 173 layer that allows searches to synchronization points based on timestamps
 174 without having to decompress and decode the actual contents, a
 175 compression layer implemented with
 176 .Xr zlib 3 ,
 177 and an inner serialization and timestamping layer.
 178 .Pp
 179 The exact encoding is described in the
 180 .Pa fifolog.h
 181 file.
 182 .Pp
 183 Fifolog is particularly well suited for use on Flash based media, where
 184 it results in much lower write-wear, than a file system with regular
 185 log files rotated with
 186 .Xr newsyslog 8
 187 etc.
 188 .Sh EXAMPLES
 189 Create a fifolog with 1024*1024 records of 512 bytes:
 190 .Pp
 191 .Dl "fifolog_create -r 10m /tmp/fifolog"
 192 .Pp
 193 Write a single record to this file:
 194 .Pp
 195 .Dl "date | fifolog_writer /tmp/fifolog"
 196 .Pp
 197 Read it back with human readable timestamps:
 198 .Pp
 199 .Dl "fifolog_reader -t /tmp/fifolog"
 200 .Pp
 201 One particular useful use of
 202 .Nm fifolog_writer
 203 is with
 204 .Xr syslogd 8
 205 using a line such as this in
 206 .Xr /etc/syslog.conf 5 :
 207 .Pp
 208 .Dl "*.* |fifolog_writer /var/log/syslog_fifolog"
 209 .Sh HISTORY
 210 The fifolog tools have been liberated from an open source
 211 .Tn SCADA
 212 applications called
 213 .Dq measured ,
 214 which monitors and controls remote radio navigation
 215 transmitters for the Danish Air Traffic Control system.
 216 .Sh AUTHORS
 217 The fifolog tools were written by
 218 .An Poul-Henning Kamp .