Provided by: stenographer_1.0.1-2ubuntu2.1_amd64 bug

NAME

       stenographer - Stenographer packet capture daemon

SYNOPSIS

       stenographer [-config FILE] [-syslog] [-v INT]

DESCRIPTION

       Stenographer  is a full-packet-capture utility for buffering packets to disk for intrusion
       detection and incident response purposes. It provides a high-performance implementation of
       NIC-to-disk  packet  writing,  handles deleting those files as disk fills up, and provides
       methods for reading back specific sets of packets quickly and easily.

       This is the main executable for Stenographer. It is recommended to interact  with  it  via
       the provided init scripts.

OPTIONS

       -config FILE
              File location to read configuration from (default "/etc/stenographer/config")

       -syslog
              If true, log to syslog.  Otherwise, log to stderr (default true)

       -v int log many verbose logs (default -1)

USER AND GROUPS

       A  single  system  group  `stenographer`, and a system user `stenographer` are used to run
       Stenographer.

       The `stenographer` group is used to control access to locally stored  packet  data.  Users
       are added to this group to allow them to query stenographer (via the `stenoread` command).

       The `stenographer` user is used to run the `stenographer` and `stenotype` binaries. We use
       the `stenographer` user to protect the system from `stenographer` and `stenotype`...  this
       user  has  no  special privileges except the ability to read/write packet data and run the
       (setcap'd) stenotype binary. So if either is compromised, the system as a whole won't be.

CONFIGURATION FILE

       The `/etc/stenographer/config` file tells Stenographer what  packets  to  read,  where  to
       write  them,  how  to  serve  them,  etc. It also tells the clients where the Stenographer
       server is running and how to query it.

       Here's an example config (note: it's JSON):

           {
             "Threads": [
                 { "PacketsDirectory": "/disk1/stenopkt", "IndexDirectory": "/disk3/stenoidx/disk1"}
               , { "PacketsDirectory": "/disk2/stenopkt", "IndexDirectory": "/disk3/stenoidx/disk2", "DiskFreePercentage": 25}
             ]
             , "StenotypePath": "/usr/local/bin/stenotype"
             , "Interface": "em1"
             , "Port": 1234
             , "Flags": []
             , "CertPath": "/etc/stenographer/certs"
           }

       Let's look at each part of this in detail:

              * `StenotypePath`:
                     Where `stenographer` can find the `stenotype` binary, which  it  runs  as  a
                     subprocess

              * `Interface`:
                     Network interface to read packets from

              * `Port`:
                     Port `stenographer` will bind to in order to serve `stenoread` requests.

              * `CertPath`:
                     Where  `stenographer`  will  write certificates for client verification, and
                     where the clients will read certificates when issuing queries.

       The `Threads` section is one of the most  important.  It  tells  `stenotype`,  the  packet
       capturing  subprocess, a number of things: how many threads to read packets with, where to
       store those packets, and how to clean them up.

       For each packet reading thread you'd like to run (IE: for each core you'd  like  to  use),
       you must specify:

              * `PacketsDirectory`:
                     Where  to write packet files. We recommend mounting a separate disk for each
                     thread... we've found that at least for spinning disks, a  single  core  can
                     easily fill a disk's entire write throughput with room to spare.

              * `IndexDirectory`:
                     Where to write index files. We've had good luck with using a single separate
                     disk to write all index files, writing each thread's  index  to  a  separate
                     subdirectory. This directory gets FAR fewer writes, and they're FAR smaller.
                     We've found that even with up to 8 threads, the all 8 index directories take
                     up less than 20% of the space of a single thread's packets.

              * `DiskFreePercentage`:
                     The  amount  of  space to keep free in the packets directory. `stenographer`
                     will delete files in this thread's packets directory when  free  disk  space
                     decreases  below  this  percentage.  Note  that  we  don't  currently do any
                     automated cleanup of the index directory.  When a packet file is cleaned up,
                     its  index file is cleaned up, and because index files take so little space,
                     we  haven't  ever  needed   to   clean   them   up   directly.   Note   that
                     `DiskFreePercentage` is optional, it defaults to 10%.

              * `MaxDirectoryFiles`:
                     The  maximum number of packet/index files to create before cleaning old ones
                     up. Defaults to 30K  files,  to  avoid  issues  with  ext3's  32K  file-per-
                     directory  maximums. For ext4 you should be able to go higher without issue.
                     Note that since we create at least one file every minute, this defaults to a
                     maximum limit of 8 1/3 days before we drop old packets.

       The  `Flags`  section  allows you to specify flags to pass to the `stenotype` binary. Here
       are some flags which may prove particularly useful:

              * `-v`:
                     Add verbosity to logging. Logs by default are written  to  syslog,  and  are
                     relatively  quiet.  Adding  one  `-v`  will  have stenotype write per-thread
                     capture statistics every minute or 100MB of packets, whichever comes  first.
                     Adding more `-v` flags will provide you with reams of debugging information.

              * `--blocks=NUM`:
                     The  number  of  1MB  packet  blocks  used  by AF_PACKET to store packets in
                     memory, *per thread*. This flag basically allows you to control how much RAM
                     the  `stenotype`  binary  uses:  `blocks  * threads * 1MB`. More blocks will
                     allow a thread to handle traffic  spikes:  if  you  have  2048  blocks  (the
                     default),  then a thread can hold 2GB of traffic in memory while waiting for
                     it to hit disk. If you have slow links  and  you  want  to  decrease  memory
                     usage, you can probably decrease this a LOT. :)

              * `--fanout_type=NUM`:
                     This  sets  the  AF_PACKET fanout type to the passed-in value. See AF_PACKET
                     documentation for details on options here. The default  should  probably  be
                     fine.

              * `--filter=HEX`:
                     Allows  users to specify a BPF filter for packet capture, only packets which
                     match this filter will be written by  `stenotype`.  This  is  NOT  a  human-
                     readable  BPF  filter, it's a hex-encoded compiled filter.  Use the supplied
                     `compile_bpf.sh` script to generate  this  encoding  from  a  human-readable
                     filter.

              * `--seccomp=none|trace|kill`:
                     We  use  seccomp  to  sandbox  stenotype,  but  we've found that this can be
                     fragile as we switch between  different  machine  configurations.  Some  VMs
                     appear  to  freeze  while  trying  to  set  up  seccomp sandboxes: for those
                     environments, you can pass `--seccomp=none` in (note that this will turn off
                     some  sandboxing). If you're trying to debug a `stenotype` failure you think
                     is caused by overzealous sandboxing, you can pass in `--seccomp=trace`, then
                     run stenotype with `strace` to figure out why things are misbehaving.

              * `--preallocate_file_mb=NUM`:
                     Certain  file  systems  handle  writes  faster  if the file has already been
                     allocated to its eventual size.  If  you  set  this  flag  to  `4096`,  then
                     stenotype  will  preallocate each new packet file to this size while opening
                     it. The file will be truncated to its actual size when closed.  This  should
                     not  be necessary unless you're really trying to eak out some extra speed on
                     a file system that supports extents.

       If you are using xfs on 4.1+ kernel, setting "--preallocate_file_mb"  becomes  crucial  to
       performance.  This is in that when appending to the end of file (i.e. EOF updates), kernel
       will serialize all operations. Please refer to upstream commit  (b9d5984  xfs:  DIO  write
       completion size updates race).