Provided by: isdnlog_3.12.20071127-0ubuntu6_i386 bug

NAME

       isdnrep - report isdn activity

DESCRIPTION

       Isdnrep   reads   the   isdnlog  log  files,  generates  reports,  does
       statistics, and other things. It can also generate HTML output for  use
       with a web server.

OPTIONS

       -V     show version information and exit.

       -a   all
              Show  all  connections  registered. If this option is not given,
              show only the connections made today.

       -S   Summary
              Show a summary (no individual calls) for selected date range. If
              this  option  is  given  twice, the summaries per day are hidden
              too. Don’t use with -h

       -h   no header
              There will be no header for each day, nor will  the  summary  at
              the  end  of each day and at the end of the report be generated.
              This is useful if the output  is  to  be  processed  by  another
              program.

              This option doesn’t work if the -wX is also given.

       -n   numbers
              Display numbers instead of the aliases for those numbers.

       -fFILE The  file  from  which  to  generate the report. This is usually
              /var/lib/isdn/calls,    or    whatever    is    configured    in
              /etc/isdn/isdn.conf  as LOGFILE = .  The -f option will override
              the setting in /etc/isdn/isdn.conf.

       -t time span   time="time span"
              With this option a specific time span covered by  the  log  file
              can be displayed, e.g. all calls in November 1995, or on January
              3rd 1996 between 03:00 and 09:45.

              The format in which times are given  is  described  below.   The
              time span has the following syntax:

              time-time display from begin time up to end time
              time-     display from given time up to "now"
              -time     display from beginning of log file up to given time
              time      display the given month, day, hour, ...

       -d -time  delete="time"
              Delete  entries  from the log file up to (but not including) the
              specified time. The format is the same as  for  the  -t  option.
              The  minus  before the time must be given! It is not possible to
              define begin and end times; entries are always deleted from  the
              beginning up to the time given.

              Warning!  Entries are really deleted from the file. Careless use
              can result in all entries being deleted, e.g. with  "isdnrep  -d
              -".

       -E   print Errors
              Display  all  connections  and connection attempts. Without this
              option, only successful connections are displayed.

       -v   verbose
              Display warnings on startup.

       -c   ignore default options
              Do not append the "REPOPTIONS" setting from  /etc/isdn/isdn.conf
              to the commandline.

       -p [n][m]number[,[m]number...] phonenumber
              Display only selected phone numbers.

              "number"  is  specified  in  the same format as in configuration
              files (see isdn.conf(5)). E.g. wildcards can be used.

              If the flag ’m’ is given, the corresponding MSN is meant.  E.g.:
              "m2"  means  MSN#2.  If  "m0"  is  given,  all numbers are to be
              displayed.

              If the flag ’n’  is  given,  the  given  number  is  not  to  be
              displayed.

       -U [_][.]numberdefault source number
              Use ’number’ as source number for outgoing calls with an unknown
              source number ("?").  ’.’ is replaced by country and  area  code
              from isdn.conf.

              With  ’_’ the default source number is used internally (e.g. for
              fetching the right zone names from the ratefile) but it  is  not
              displayed.

       -i   incoming
              Only incoming connections are displayed.

       -o   outgoing
              Only outgoing connections are displayed.

       -xX  include/exclude calls
              Select  calls  by day and/or hour.  The following selections are
              possible and can specified in any combination and quantity using
              : as separator:
              ddaylist
                     only days matching daylist
              Ddaylist
                     all days not matching daylist
              htimelist
                     only hours matching timelist
              Htimelist
                     all hours not matching timelist

       daylist  and  timelist  have  the  same  syntax  as  described in rate-
       files(5).  If a day or an hour is included  and  excluded  it  will  be
       excluded.

       Example:

              -xd2-4:DH:h9-17:H12-15

       This  will display all calls on Tuesdays, Wednesdays, or Thursdays that
       are no holidays with a start time between 09:00 and 12:00 or 15:00  and
       17:00.

       -u   unknown caller
              At   the   end  of  the  report,  all  numbers  not  aliased  in
              callerid.conf or ~/.isdn  are  displayed.  This  option  is  not
              available when HTML output is requested.

       -LX  summary lists
              Select  the  summaries  in  the footer by any combination of the
              following letters:
              i,I    foreign numbers of incoming calls
              o,O    foreign numbers of outgoing calls
              c,C    foreign numbers of all calls
              z,Z    zones of outgoing calls
              p,P    providers of outgoing calls
              m,M    MSNs (own subscriber numbers) of outgoing calls

       Upper case letters deselect, lower case letters select a summary.  With
       at  least one lower case letter, only the selected summaries are shown,
       as long as they are not also deselected.  -LiI for example will show no
       summary at all.  Per default all summaries are displayed.

       -rPROV recompute
              Recompute  the connection fees with the current ratefile instead
              of showing the amounts stored in  the  logfile  as  usual.   The
              provider  PROV  for  recomputation  is  selected  in  one of the
              following ways:

              -         Use the logged provider.
              pNUM      Use provider with Pnum NUM (according  to  P:  tag  in
                        ratefile).    The   provider  variant  is  taken  from
                        rate.conf where the provider must be enabled.
              pNUM_VAR  Use provider with Pnum NUM and variant VAR  (according
                        to   P:NUM,VAR  in  ratefile).   No  requirements  for
                        rate.conf.
              vVBN
              vVBN_VAR  Similar to pNUM[_VAR] but the provider is selected via
                        VBN (B: tag in ratefile) instead of Pnum.
              b         Use   the  cheapest  of  all  booked  providers.   The
                        provider selection is done per call.  Booked providers
                        are those, which are enabled in rate.conf
              B         Like b but allow all providers, not only the booked.

       -m[*|/]number  modify call costs
              Multiply (*) or divide (/) the stored or recalculated call costs
              by number before displaying them.  If neither * nor / is  given,
              multiply.

       -wX  WWW
              isdnrep  can give its output in HTML format; this is switched on
              with this option. Two modes are possible:

              0      The HTML header is suppressed. Useful if the output is to
                     be included into an existing page.
              1      A complete HTML page is generated.

       -sX  format string
              The  output  generated  by isdnrep can be modified by specifying
              the format of the line generated for each connection. The syntax
              is  similar to that used by printf. The following parameters are
              possible (the x where given means that a width  for  the  field,
              also known as the precision, must be given):

              %X  time without date, e.g. 23:54:06
              %x  the date, e.g. 25/07/97
              %y  date without year, e.g. Sun May 04
              %Y  year, in four digits, e.g. 1997
              %D  duration of connection, e.g. 00:03:34
              %xH the  local  MSN;  if  an  alias  can  be found, that will be
                  displayed instead
              %xh the local  MSN,  only  as  a  number;  no  aliases  will  be
                  substituted
              %xF the  remote  number;  if an alias can be found, that will be
                  displayed instead
              %xf the remote number, only as a  number;  no  aliases  will  be
                  substituted
              %xL the  town  corresponding to the local MSN if known; an empty
                  string otherwise
              %xl the town corresponding to the remote  number  if  known;  an
                  empty string otherwise
              %T  an  arrow  indicating  the direction of the connection ("->"
                  outgoing  or  "<-"  incoming);  the  local  MSN  should   be
                  displayed on the left side of this.
              %t  an   arrow  indicating  the  direction  of  the  connection,
                  reversed ("<-" outgoing or "->"  incoming);  the  local  MSN
                  should be displayed on the right side of this.
              %xu the charge units, if known, e.g. 6 EH
              %U  the cost, if known, e.g. 2,28 DM
              %xj the name of the used provider
              %v  the  VBN  (carrier  selection  prefix) of the provider, e.g.
                  01012
              %V  the VBN and variant of the provider, e.g. 01012_3
              %I  amount of INPUT data
              %O  amount of OUTPUT data
              %P  INPUT throughput (bps)
              %p  OUTPUT throughput (bps)
              %S  Service Indicator
              %G  displays a HTTP link to the corresponding fax,  when  a  fax
                  was  received  by mgetty. This fax can be displayed by using
                  the link in a HTTP browser.

                  This option is only valid when used with -wx, see below  for
                  more information.
              %C  displays a HTTP link to the corresponding voice file, when a
                  call was recorded by vbox.  This option is only  valid  when
                  used with -wx, see below for more information.

       The default format string for (non-HTML output) is
              "  %X %D %15.15H %T %-15.15F %7u %U %I %O"

       With  the  following  string  all the important data is displayed while
       keeping the total length to 80:

              "%X%D %10.10H%T%-14.14F%U%I %O"

       The above string is put into isdn.conf at installation  as  REPFMTSHORT
       and can be used with -Fshort.

       Without  showing  the  transfered  bytes, this string also fits into 80
       chars:

              "  %X %D %16.16H %T %-25.25F %U"

       It is included as REPFMTNIO.

       -FX  format
              format strings can be specified in  isdn.conf;  this  option  is
              used  to  select  one  of  these.  Entries can be defined in the
              section [ISDNLOG] with names beginning with "REPFMT". The string
              after  the  -F  option  is  added  to REPFMT to find the correct
              entry. Case is not sensitive. E.g.:

              REPFMT1        = ... # -> isdnrep -F1
              REPFMTMYSTRING = ... # -> isdnrep -Fmystring or
                                        isdnrep -F MYSTRING

HTML USE

       isdnrep can generate a HTML page containing links to files generated by
       vbox and mgetty (faxes), so that the messages and faxes can be heard or
       seen from within a browser. However, a couple  of  things  need  to  be
       configured first.

       answering machine messages

       The  %C  can  be  used in the isdnrep output format to make a link to a
       voice recording file.  For this to work, the following entry is  needed
       in the [ISDNLOG] section in isdn.conf:

           VBOXPATH= /var/spool/vbox/fred/incoming # incoming directory pathname

       Now  isdnrep  can  find  the file correctly. Clicking on this link will
       cause the file to be sent. These files are in ZyXEL format; the browser
       cannot use these directly. The type is given by isdnrep as follows:

           Content-Type: application/x-zyxel4

       The  correct  application (helper) for this has to be configured in the
       browser. Alternatively,  a  conversion  program  can  be  specified  to
       isdnrep  which  will convert the ZyXEL format. The pathname of the file
       to convert is given as a parameter to the program.

       In the [ISDNLOG] section of isdn.conf an  entry  as  follows  specifies
       which conversion program to use:

           VBOXCMD1 = /usr/bin/program1

       for versions 0.x and 1.x of vbox, and

           VBOXCMD2 = /usr/bin/program2

       for versions 2.x of vbox. Both entries can be given, isdnrep recognizes
       which version created the recording.

       The program must first output a line with the content-type, followed by
       the  data  itself.  To  convert  the  ZyXEL format into a WAV file, the
       following script may be used:
              #! /bin/sh
              ##
              ## script to play voice messages from vbox-2.0
              ##
              ## WARNING! If the paths are not set correctly,
              ## netscape may simply crash!

              PATH=$PATH:"path to sox":"path to pvftools":"path to vbox"
              FILENAME1=/tmp/voxplay.$$.voc
              FILENAME2=/tmp/voxplay.$$.wav
              VOLUME=8

              vboxtoau <$1             | \
                        autopvf        | \
                        pvfamp $VOLUME | \
                        pvfcut 0.20    | \
                              pvftovoc > $FILENAME1

              sox $FILENAME1 $FILENAME2

              echo Content-Type: audio/x-wav
              echo
              cat $FILENAME2

              rm -f $FILENAME1 $FILENAME2

       The script above needs the packages sox  and  pvftools.   Additionally,
       the browser needs to be told how to handle "audio/x-wav".  This is done
       by adding the following lines to the files listed:

           ~/.mime.types
               type=audio/x-wav    \
               desc="auWAV Audio"  \
               exts="wav"

           ~/.mailcap
               audio/x-wav;/usr/bin/auplay %s

       The package NAS (Network Audio System) may be needed.

       Now, when the browser is started, it will recognize WAV files and start
       the  corresponding  program  to  handle  these. The WAV format has been
       chosen as this can also be played from a Windows pc.

       faxes received by mgetty

       When %G is used in the isdnrep output format,  any  faxes  received  by
       mgetty  will  be  accessible via a HTML link, in the same manner as the
       ansering machine messages.

       For the faxes the following entry in the [ISDNLOG] section in isdn.conf
       is needed:

           MGETTYPATH = /var/spool/fax/incoming

       WARNING:  if  isdnrep  doesn’t  have permission to read the files, they
       will not be displayed; there will be no error message.

       When isdnrep passes these files back to the browser, they have  the  G3
       format. The following header is used to notify the browser of this:

           Content-Type: application/x-faxg3

       As  the  browser probably doesn’t understand this format, the following
       changes to the files listed are needed:

           ~/.mime.types
               type=application/x-faxg3  \
               desc="G3-Fax Format"      \
               exts="fax,g3"

           ~/.mailcap
               pplication/x-faxg3;/usr/X11/bin/g3view %s

       The program g3view has to be installed for this to work.

       If now the link is clicked on, the browser will automatically start the
       external g3view to handle this data.

       If  you  prefer another format (instead of G3) such as JPEG, the format
       has to be converted. The following entry in the  [ISDNLOG]  section  of
       isdn.conf takes care of this:

       VBOXCMD = /usr/bin/g3tojpeg # example

       The script g3tojpeg can be something like this:

              #! /bin/sh
              ##
              ## command to display faxes in a browser
              ##
              ## WARNING! If the paths are not set correctly,
              ## netscape may simply crash!

              export PATH=$PATH:"path to g3topbm":"path to convert"

              echo Content-Type: image/jpeg
              echo

              g3topbm < $1 | convert pbm:- jpeg:-

       The  packages  ImageMagick  and  mgetty  are needed. Mgetty is probably
       already installed if you want to use this feature :-)

       The advantage of the JPEG format is that it can also be displayed by  a
       browser running on a Windows pc.

       summary

       A suitable value for REPFMTWWW is

           REPFMTWWW = "%X %D %17.17H %T %-17.17F %-20.20l SI: %S %9u %U %I %O %G %C"

       Netscape  3.0  Gold and Arena have been tested, and both work fine with
       isdnrep’s HTML output, although Arena’s display is not as colourful  as
       Netscape’s.

       A   known   problem  (which  is  impossible  to  solve  completely)  is
       determining the relationship between an isdn connection and  a  fax  or
       vbox  recording.   Unfortunately the times for isdnrep, mgetty and vbox
       differ. Isdnrep tries to make the best guess, but it’s always  possible
       that e.g. a fax is connected to the wrong isdn connection.

EXAMPLE OUTPUT

       With the default configuration the following output can be generated on
       stdout (whitespace slightly edited for clarity):

              $ isdnrep -v -t 6/1/96
              I S D N  Connection Report  -  Tue Aug 26 22:21:19 1997

              Sat Jan  6 1996
                00:54:19                 UNKNOWN -> UNKNOWN     No user responding      (4)
              [...]
                16:33:24  0:03:23        UNKNOWN -> UNKNOWN        7 EH      0,84 DM
                17:33:47                 UNKNOWN -> UNKNOWN     Unallocated (unassigned)(5)
                                                                number
                20:02:28  0:02:37     Phone/HDLC <- UNKNOWN                             (1)
                20:09:53  0:07:01     Modem/X.75 -> T-Online       3 EH      0,36 DM    (2)
                21:27:56                 UNKNOWN -> UNKNOWN     User busy               (3)
                22:09:41  0:29:36        UNKNOWN -> UNKNOWN       43 EH      9,89 DM*
              ======================================================================
                1 IN= 0:02:37,  13 OUT= 3:40:14,   3 failed      210 EH     25,20 DM
              (6)^^^^^^^^^^^^  (7)^^^^^^^^^^^^^  (8)^^^^^^^   (9)^^^^^^ (10)^^^^^^^^

              DIALOUT Summary for Sat Jan  6 1996                                      (11)
              -----------------------------------------------------------
              T-Online         1 call(s)  0:07:01     3 EH    0,36 DM
              UNKNOWN         11 call(s)  0:17:00    20 EH    2,40 DM

              DIALIN Summary for Sat Jan  6 1996                                       (12)
              -----------------------------------------------------------
              UNKNOWN          1 call(s)  0:02:37

              Zone 1 : City              2 call(s)  2:23:13     50 EH    6,00 DM       (13)
              Zone x : UNKNOWN          11 call(s)  0:17:00     20 EH    2,40 DM

       Notes
         (1) "xxx <- xxx" was an incoming call, so doesn’t cost anything
         (2) "xxx -> xxx" was an outgoing call lasting  203  seconds,  so  for
             City zone, off-peak time (Saturday), 3 charge units = DM 0,36
         (3) there was no connection, as the called party was busy
         (4) there  was  no connection, as the called party didn’t pick up the
             phone
         (5) "the number you have dialled is not connected. Hang up  and  dial
             again. ..."
         (6) total time for incoming calls
         (7) total time for outgoing calls
         (8) 3 calls failed; busy (3), no answer (4) and error in dialing (5)
         (9) total charge units incurred for one day
        (10) total costs incurred for one day
        (11) outgoing calls grouped per number
        (12) incoming calls grouped per number
        (13) outgoing and incoming calls grouped per tariff zone

       If  the  charge  units are marked with "*", the PTT switch did not give
       charge info; these are the number of units guestimated by isdnrep.

TIME FORMAT

       For the -d and -t options, the  time  is  specified  in  the  following
       formats:

       [DD/][M]M/[[YY]YY]
              specifies the month or day.

              Examples:

              7/        July of the current year
              8/1996    August 1996
              29/6/05   June 29th 2005
              6/6/      error,  is not June 6th of the current year; it’s June
                        1906

       [D]D   day of current month

       [D]D.[M]M.[[[CC]Y]Y]
              specifies a day.  If century or year and  century  are  missing,
              they will be taken from the current date.

              Examples:

              23.5.     May 23rd in the current year
              19.01.38  January 19th 2038
              16.10.1998
                        October 16th 1998

       [MM]DD[hhmm[[CC]YY][.ss]]
              specifies an exact time. Unspecified parts are defined as 0 when
              interpreted as a begin time, and 23 or 59 when interpreted as an
              end time.

              If a year is to be specified, the hours and minutes must also be
              specified.

              The format is copied from the date command.

              Examples:

              0107   January 1st in the current year
              0107173196.25
                     January 7th 1996 17:31:25
              010717311996
                     January 7th 1996 17:31:00 (or 17:31:59)
              12141995
                     error: not December 12th 1995, but December 12th  of  the
                     current year at 19:95, so it’s garbage.

              Examples of time spans and their meaning:
                     6/95-081214381996.25
                             all  entries  between  June 1st 1995 00:00:00 and
                             August 12th 14:38:25
                     0912030495.20-12/95
                             all entries between September 12th 1995  03:04:20
                             and December 31st 1995 23:59:59
                     09.06.2006-9/7/6
                             all  entries  between  June 6th 2006 00:00:00 and
                             July 7th 2006 00:00:00
                      7/95   all entries between July 1st  1995  00:00:00  and
                             July 31st 1995 23:59:59
                      0908   all  entries between September 8th in the current
                             year 00:00:00 and September 8th  in  the  current
                             year 23:59:59
                      3      third day of the current month

       [CC]YY-MM-DDThh:mm:ss
              specifies   a  year,  a  moment,  or  something  between.   Each
              seperator ´-’, ’T’, and ’:’ can be omitted or not.  If the first
              ’-’ is missing, the century must be given.

              This notation cannot be combined with the above notations.  Time
              spans are noted with ’--’ instead of ’-’.  If no ’--’ is  given,
              ´i’ must be noted after the -t option.

              Examples:

              i2002  the  entire  year  2002  from  January  1st  00:00:00  to
                     December 31st 23:59:59
              i200306
                     the entire month June 2003
              200308--200309
                     August and September 2003
              2003-10-03T17--
                     all entries after October 3rd 2003 16:59:59
              2003-08-27T11:51:25--20030827115128
                     4 seconds at August 27th 2003
              200306 error: neither ’i’ nor ’--’ given
              2003-1-4
                     error: leading zeros (at month and day) must not omitted

       "y"    yesterday,
       "yy"   the day before yesterday,
       "yyy"  three days ago and so on.  For time spans these can also be used
              in conjunction with the notations explained above.

FILES

       /var/lib/isdn/calls or /var/lib/isdn/calls
              isdnlog log file with information about all calls.

       /etc/isdn/isdn.conf
              general configuration

       /etc/isdn/callerid.conf
              aliases for telephone numbers

SEE ALSO

       isdnlog(5) isdnlog(8) isdn.conf(5)

AUTHOR

       This  manual  page  was  adapted  from  isdnlog/README by Paul Slootman
       <paul@isdn4linux.de>, for Debian GNU/Linux and isdn4linux.