Provided by: stenographer_1.0.1-2ubuntu2.1_amd64 
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).