


Maintenance Commands                            ssadm-logdump(1M)



NAME
     ssadm-logdump - filter a SunScreen log, or print a SunScreen
     log in human-readable form

AVAILABILITY
     SUNWicgSA (This command  may  be  executed  directly  on  an
     administration station.)

SYNOPSIS
     ssadm logdump [ -aDlvVNCq ]
          [ -c maxcount ] [ -i ifilename ] [ -o ofilename ]
          [ -n filename ] [ -t [ r | a | d ] ]
          [ -p first [  , last ] ] [ -x offset [ , length ] ]
          [ expression ]

DESCRIPTION
     logdump interprets Sunscreen logs retrieved using ssadm  log
     and  displays  their contents.  logdump can display a log or
     save part of it to a file for later inspection.

     logdump can display logged events in a  single-line  summary
     form  or in verbose multi-line forms.  In summary form, only
     the  data  pertaining  to  the  highest  level  protocol  is
     displayed.   For  example,  an NFS packet will have only NFS
     information displayed.  The underlying  RPC,  UDP,  IP,  and
     Ethernet   frame   information  is  suppressed  but  can  be
     displayed if either of the verbose options are chosen.

     logdump can also display session information  saved  in  the
     log  files.    Session information contains local and remote
     addresses and ports for the session, the  time  duration  of
     the  session,  and the amount of data transferred during the
     session.

     Finally, logdump can  display  extended  log  events;  these
     arise  from  non-packet, non-session occurences in SunScreen
     such as authentication,  configuration  changes,  and  proxy
     operations.

     The filtering abilities and syntax of logdump form the basis
     for all log event processing in SunScreen.

OPTIONS
     Unless otherwise indicated, the  remaining  discussion  uses
     the  term event to refer to all packet, session, or extended
     event types.  The filtering mechanisms of logdump attempt to
     operate all of these event sub-types to the greatest (intui-
     tive) extent possible.

     -a             Listen to packets on /dev/audio (warning: can
                    be noisy).




                    Last change: 7 March 2000                   1






Maintenance Commands                            ssadm-logdump(1M)



     -i ifilename   Display events in the captured SunScreen  log
                    ifilename.     This    field   is   required.
                    ifilename may be  in which case the  standard
                    input  supplies  the stream of logged events.
                    If a ifilename.names file is present,  it  is
                    automatically   loaded   into   logdump's  IP
                    address-to-name mapping table  (See  -N  flag
                    below).

     -o ofilename   Save captured events in ofilename.  ofilename
                    may be  in which case the resulting stream of
                    logged events is delivered  to  the  standard
                    output.   During event filtering (and without
                    the -q option), a  count  of  the  number  of
                    events  being saved in the file is displayed.
                    If you wish just to count events without sav-
                    ing to a file, name the file /dev/null.

     -n filename    Use filename as an IP address-to-name mapping
                    table.   This  file must have the same format
                    as the /etc/hosts file (IP  address  followed
                    by the hostname).

     -l             Display length of the entire  Ethernet  frame
                    in  bytes  on  the  summary  line  of  packet
                    events.

     -D             Indicate when log  entries  were  dropped  or
                    when  the  system  was rebooted.  This option
                    only works on the original log  file  fetched
                    from  the SunScreen.  If a log file is subse-
                    quently saved using the -o option, the infor-
                    mation  on  dropped  packets  and  reboots is
                    missing from the new file.

     -t  [ r | a | d ]
                    Time-stamp  presentation.   Time-stamps   are
                    accurate   to  within  4  microseconds.   The
                    default is for times to  be  presented  in  d
                    (delta)  format (the time since receiving the
                    previous event).
                    Option a (absolute) gives wall-clock time.
                    Option r (relative) gives  time  relative  to
                    the  first event displayed.  This can be used
                    with the -p option to display  time  relative
                    to any selected event.

     -v             Verbose mode.  Print packet headers and other
                    event  information  in  lots of detail.  This
                    display consumes many  lines  per  event  and
                    should be used only on selected events.




                    Last change: 7 March 2000                   2






Maintenance Commands                            ssadm-logdump(1M)



     -V             Verbose  summary  mode.   This   is   halfway
                    between  summary  mode  and  verbose  mode in
                    degree  of  verbosity.  For  packet   events,
                    instead  of  displaying just the summary line
                    for the highest level protocol in  a  packet,
                    it  displays a summary line for each protocol
                    layer in the packet.  For  instance,  for  an
                    NFS  packet  it  will display a line each for
                    the ETHER, IP, UDP, RPC and NFS layers.  Ver-
                    bose  summary mode output may be easily piped
                    through grep(1) to extract event of interest.
                    For example to view only RPC summary lines:
                    example# ssadm logdump -i rpc.cap -V  |  grep
                    RPC

     -p first [ , last ]
                    Select one or more  events  to  be  displayed
                    from  a  capture  file.   The first (histori-
                    cally, packet) event in the file is event #1.

     -x offset [ , length ]
                    Display packet data in hexadecimal and  ASCII
                    format.   The offset and length values select
                    a portion of the packet to be displayed.   To
                    display the whole packet, use an offset of 0.
                    If a length value is not provided,  the  rest
                    of the packet is displayed.

     -N             Create an IP address-to-name file from a cap-
                    ture  file.   This  must be set together with
                    the -i option that names a capture file.  The
                    address-to-name file has the same name as the
                    capture file with .names appended. This  file
                    records the IP address to hostname mapping at
                    the capture site and increases the  portabil-
                    ity  of  the capture file.  Generate a .names
                    file if the capture file is  to  be  analyzed
                    elsewhere.   Events  are  not  displayed when
                    this flag is used.

     -C             List  the  code  generated  from  the  filter
                    expression for logdump's filter.

     -q             Perform  silently.   In  specific,   suppress
                    counting behavior during capture using the -o
                    option.

     expression     Only events for which the expression is  true
                    will  be  selected.  If no expression is pro-
                    vided it is assumed to be true.
                    Given a filter expression, logdump  generates
                    code  for  its  own internal filter.  (The -C



                    Last change: 7 March 2000                   3






Maintenance Commands                            ssadm-logdump(1M)



                    flag can be used to view generated  code  for
                    logdump's filter expression.)
                    A filter expression consists of a  series  of
                    one  or  more  Boolean primitives that may be
                    combined with Boolean operators ( AND , OR  ,
                    and   NOT  ).  Normal  precedence  rules  for
                    Boolean operators apply.  Order of evaluation
                    of  these  operators  may  be controlled with
                    parentheses.   Since  parentheses  and  other
                    filter expression characters are known to the
                    shell, it is often necessary to  enclose  the
                    the  filter expression in quotes.  The primi-
                    tives are:

                    loglvl lvl
                         True  if  the  event  corresponds  to  a
                         packet  (loglvl  pkt),  session  (loglvl
                         sess).  authentication (loglvl auth)  or
                         application (loglvl app) event.

                    logsev sev
                         True if  the  event  is  of  a  severity
                         greater  than  or equal to sev.  sev may
                         be one of emerg, alert, crit,  info,  or
                         dbg.

                    logapp appname
                         True if the event was logged by the Sun-
                         Screen  application  appname.   For Sun-
                         Screen 3.1, valid appname's are:   auth,
                         edit, ftpp,

                    logiface ifprefix
                         True if the packet logged arrived on  an
                         interface  whose  name  has  the  prefix
                         ifprefix.

                    logwhy why#
                         True if the packet  was  logged  due  to
                         SunScreen reason (why) code why#.

                    host hostname
                         True  if  the  source   or   destination
                         address  is  that of hostname.  The key-
                         word host may be  omitted  if  the  name
                         does  not  conflict  with  the  name  of
                         another   expression   primitive    e.g.
                         "pinky" selects events transmitted to or
                         received from  the  host  pinky  whereas
                         "pinky and dinky" selects events between
                         hosts pinky AND dinky.  Normally the  IP
                         address   is   used.    With  the  ether



                    Last change: 7 March 2000                   4






Maintenance Commands                            ssadm-logdump(1M)



                         qualifier the Ethernet address is  used,
                         for instance, "ether pinky".

                    ipaddr or etheraddr
                         Literal addresses, both  IP  dotted  and
                         Ethernet colon are recognized. For exam-
                         ple, "129.144.40.13" matches all  events
                         with that IP address as source or desti-
                         nation, and similarly,  "8:0:20:f:b1:51"
                         matches  all  packets  with the Ethernet
                         address as source or  destination  (non-
                         packet  events  do  not contain Ethernet
                         addresses).  An Ethernet address  begin-
                         ning  with  a letter is interpreted as a
                         hostname. To avoid this, prepend a  zero
                         when  specifying  the address. For exam-
                         ple,  if   the   Ethernet   address   is
                         "aa:0:45:23:52:44",  then  specify it by
                         add  a   leading   zero   to   make   it
                         "0aa:0:45:23:52:44".

                         Ranges of literal IP addresses are  also
                         supported.   A  pair  of  dotted literal
                         addresses is separated by a pair of dots
                         (..),  signifying a request to match any
                         address within the inclusive range.  For
                         example,    matches all events using any
                         IP address within that range  as  source
                         or destination.


                    from or src
                         A qualifier that modifies the  following
                         host,  net,  ipaddr,  etheraddr, port or
                         rpc primitive to match just  the  source
                         address, port, or RPC reply.

                    to or dst
                         A qualifier that modifies the  following
                         host,  net,  ipaddr,  etheraddr, port or
                         rpc primitive to match just the destina-
                         tion address, port, or RPC call.

                    ether
                         A qualifier that modifies the  following
                         host  primitive  to resolve a name to an
                         Ethernet address. Normally,  IP  address
                         matching is performed.

                    ethertype number
                         True if  the  Ethernet  type  field  has
                         value number.



                    Last change: 7 March 2000                   5






Maintenance Commands                            ssadm-logdump(1M)



                         Equivalent to "ether[12:2] = number".

                    ip, arp, rarp
                         True if the packet is of the appropriate
                         ethertype.

                    broadcast
                         True  if  the  packet  is  a   broadcast
                         packet.
                         Equivalent to "ether[2:4] = 0xffffffff".

                    multicast
                         True  if  the  packet  is  a   multicast
                         packet.
                         Equivalent to "ether[0] & 1 = 1".

                    apple
                         True if the packet is an Apple Ethertalk
                         packet.
                         Equivalent to "ethertype 0x809b or  eth-
                         ertype 0x803f".

                    decnet
                         True if the packet is a DECNET packet.

                    greater length
                         True  if  the  packet  is  longer   than
                         length.

                    less length
                         True  if  the  packet  is  shorter  than
                         length.

                    udp, tcp, icmp
                         True  if  the  IP  protocol  is  of  the
                         appropriate type.

                    net net
                         True if either the IP source or destina-
                         tion  address  has  a  network number of
                         net.  The from or to  qualifier  may  be
                         used  to select event for which the net-
                         work number occurs only in the source or
                         destination address.

                    port port
                         True if either the source or destination
                         port  is port.  The port may be either a
                         port number or name from  /etc/services.
                         The tcp or udp primitives may be used to
                         select TCP or UDP ports only.  The  from
                         or  to  qualifier  may be used to select



                    Last change: 7 March 2000                   6






Maintenance Commands                            ssadm-logdump(1M)



                         packets for which the port  occurs  only
                         as the source or destination.

                         Ranges of numeric ports  are  also  sup-
                         ported.    A   pair  of  dotted  literal
                         integers is separated by a pair of  dots
                         (..),  signifying a request to match any
                         port within the  inclusive  range.   For
                         example,    matches all events using any
                         IP port within that range as  source  or
                         destination.

                    rpc prog [ , vers [ , proc ] ]
                         True if the packet is  an  RPC  call  or
                         reply packet for the protocol identified
                         by prog. The prog may be either the name
                         of  an  RPC  protocol from /etc/rpc or a
                         program number.  The vers and  proc  may
                         be  used  to further qualify the program
                         version and procedure number, for  exam-
                         ple, "rpc nfs,2,0" selects all calls and
                         replies for the NFS null procedure.  The
                         to  or  from  qualifier  may  be used to
                         select  either  call  or  reply  packets
                         only.

                    gateway host
                         True if the packet used host as a  gate-
                         way,  that  is,  the  Ethernet source or
                         destination address was for host but not
                         the IP address.
                         Equivalent to "ether host host  and  not
                         host host".

                    nofrag
                         True if the packet is unfragmented or is
                         the first in a series of IP fragments.
                         Equivalent to "ip[6:2] & 0x1fff = 0".

















                    Last change: 7 March 2000                   7






Maintenance Commands                            ssadm-logdump(1M)



                    expr  relop  expr
                         True if the relation holds, where  relop
                         is  one of >, <, >=, <=, =, !=, and expr
                         is an arithmetic expression composed  of
                         numbers,  packet  field  selectors,  the
                         length primitive, and arithmetic  opera-
                         tors  +,  -,  *,  &,  |,  ^, and %.  The
                         arithmetic  operators  within  expr  are
                         evaluated before the relational operator
                         and  normal   precedence   rules   apply
                         between  the  arithmetic operators, such
                         as   multiplication   before   addition.
                         Parentheses  may  be used to control the
                         order of evaluation.  To use  the  value
                         of a field in the packet use the follow-
                         ing syntax:
                              base[expr [: size ] ]
                         where expr evaluates  the  value  of  an
                         offset  into  the  packet  from  a  base
                         offset which may be ether, ip, udp, tcp,
                         or  icmp.   The size value specifies the
                         size of the field.  If not given,  1  is
                         assumed.   Other  legal values are 2 and
                         4.

                    Examples:

                         "ether[0] & 1 = 1" is equivalent to mul-
                         ticast.

                          "ether[2:4] = 0xffffffff" is equivalent
                         to broadcast.

                         "ip[ip[0] & 0xf * 4  :  2]  =  2049"  is
                         equivalent to "udp[0:2] = 2049".

                         "ip[0] & 0xf >  5"  selects  IP  packets
                         with options.

                         "ip[6:2] & 0x1fff  =  0"  eliminates  IP
                         fragments.

                         "udp and ip[6:2]&0x1fff = 0 and udp[6:2]
                         !=  0" finds all packets with UDP check-
                         sums.

                         The length  primitive  may  be  used  to
                         obtain  the  length  of the packet.  For
                         instance "length > 60" is equivalent  to
                         "greater  60",  and  "ether[length - 1]"
                         obtains the value of the last byte in  a
                         packet.



                    Last change: 7 March 2000                   8






Maintenance Commands                            ssadm-logdump(1M)



                    and  Perform a logical AND operation  between
                         two Boolean values. The AND operation is
                         implied  by  the  juxtaposition  of  two
                         Boolean  expressions, for example "dinky
                         pinky" is the same as "dinky AND pinky".

                    or or ,
                         Perform a logical OR  operation  between
                         two Boolean values.  A comma may be used
                         instead, for example,  "dinky,pinky"  is
                         the same as "dinky OR pinky".

                    not or !
                         Perform a logical NOT operation  on  the
                         following  Boolean value.  This operator
                         is evaluated before AND or OR .

EXAMPLES
     Display a SunScreen log:
     example# ssadm logdump -i log
     Display log entries with host funky as either the source  or
     destination:
     example# ssadm logdump -i log funky
     Display events between  funky  and  pinky  and  inspect  the
     events using times relative to the first logged event:
     example$ ssadm logdump -i cap  -t r funky pinky | more
     Look at selected events in another log file:
     example$ ssadm logdump -i pkts -p99,108 loglvl pkt

           99   0.0027   boutique -> sunroof     NFS C GETATTR FH=8E6C
          100   0.0046   sunroof -> boutique     NFS R GETATTR OK
          101   0.0080   boutique -> sunroof     NFS C RENAME FH=8E6C MTra00192 to .nfs08
          102   0.0102   marmot -> viper          NFS C LOOKUP FH=561E screen.r.13.i386
          103   0.0072   viper -> marmot          NFS R LOOKUP No such file or directory
          104   0.0085   bugbomb -> sunroof    RLOGIN C PORT=1023 h
          105   0.0005   kandinsky -> sparky    RSTAT C Get Statistics
          106   0.0004   beeblebrox -> sunroof  NFS C GETATTR FH=0307
          107   0.0021   sparky -> kandinsky    RSTAT R
          108   0.0073   office -> jeremiah        NFS C READ FH=2584 at 40960 for 8192

     Packet 101 Looks interesting. Take a look in more detail:
     example$ ssadm logdump -i pkts  -v -p101

          ETHER:  ----- Ether Header -----
          ETHER:
          ETHER:  Packet 101 arrived at 16:09:53.59
          ETHER:  Packet size = 210 bytes
          ETHER:  Destination = 8:0:20:1:3d:94, Sun
          ETHER:  Source      = 8:0:69:1:5f:e,  Silicon Graphics
          ETHER:  Ethertype = 0800 (IP)
          ETHER:
          IP:   ----- IP Header -----



                    Last change: 7 March 2000                   9






Maintenance Commands                            ssadm-logdump(1M)



          IP:
          IP:   Version = 4, header length = 20 bytes
          IP:   Type of service = 00
          IP:         ..0. .... = routine
          IP:         ...0 .... = normal delay
          IP:         .... 0... = normal throughput
          IP:         .... .0.. = normal reliability
          IP:   Total length = 196 bytes
          IP:   Identification 19846
          IP:   Flags = 0X
          IP:   .0.. .... = may fragment
          IP:   ..0. .... = more fragments
          IP:   Fragment offset = 0 bytes
          IP:   Time to live = 255 seconds/hops
          IP:   Protocol = 17 (UDP)
          IP:   Header checksum = 18DC
          IP:   Source address = 129.144.40.222, boutique
          IP:   Destination address = 129.144.40.200, sunroof
          IP:
          UDP:  ----- UDP Header -----
          UDP:
          UDP:  Source port = 1023
          UDP:  Destination port = 2049 (Sun RPC)
          UDP:  Length = 176
          UDP:  Checksum = 0
          UDP:
          RPC:  ----- SUN RPC Header -----
          RPC:
          RPC:  Transaction id = 665905
          RPC:  Type = 0 (Call)
          RPC:  RPC version = 2
          RPC:  Program = 100003 (NFS), version = 2, procedure = 1
          RPC:  Credentials: Flavor = 1 (Unix), len = 32 bytes
          RPC:     Time = 06-Mar-90 07:26:58
          RPC:     Hostname = boutique
          RPC:     Uid = 0, Gid = 1
          RPC:     Groups = 1
          RPC:  Verifier   : Flavor = 0 (None), len = 0 bytes
          RPC:
          NFS:  ----- SUN NFS -----
          NFS:
          NFS:  Proc = 11 (Rename)
          NFS:  File handle = 000016430000000100080000305A1C47
          NFS:                597A0000000800002046314AFC450000
          NFS:  File name = MTra00192
          NFS:  File handle = 000016430000000100080000305A1C47
          NFS:                597A0000000800002046314AFC450000
          NFS:  File name = .nfs08
          NFS:






                    Last change: 7 March 2000                  10






Maintenance Commands                            ssadm-logdump(1M)



     View just the NFS packets between sunroof and boutique:
     example$ ssadm logdump -i pkts  loglvl pkt rpc nfs and  sun-
     roof and boutique
       1   0.0000   boutique -> sunroof    NFS C GETATTR FH=8E6C
       2   0.0046    sunroof -> boutique   NFS R GETATTR OK
       3   0.0080   boutique -> sunroof    NFS C RENAME FH=8E6C MTra00192 to .nfs08


     Save these packets to a new capture file:
     $ ssadm logdump -i pkts -o pkts.nfs loglvl pkt rpc nfs  sun-
     roof boutique

WARNINGS
     logdump does not reassemble IP fragments. Interpretation  of
     higher level protocol halts at the end of the first IP frag-
     ment.

     The log records created for  routing  (EFS)  interfaces  are
     different  from  those  on stealth (SPF) interfaces.  Packet
     events recorded in stealth mode include the MAC header,  but
     the routing mode log events do not.

     logdump requires information from an RPC  request  to  fully
     interpret  an  RPC reply.  If an RPC reply in a capture file
     or packet range does not have a request preceding  it,  then
     only the RPC reply header will be displayed.

SEE ALSO
     bufmod(7),  dlpi(7),   netstat(1M),   pfmod(7),   snoop(1M),
     ssadm(1M), ssadm-log(1M), ssadm-logstats(1M)

NOTES
     logdump requires an interactive interface.






















                    Last change: 7 March 2000                  11



