== osmo-pcap-server

The osmo-pcap-server program can run anywhere in your network, as long
as it can be reached by the remote osmo-pcap-client instances.

=== Running osmo-pcap-server

==== SYNOPSIS

*osmo-pcap-server* [-D] [-c CFG_FILE] | -h | -V

==== OPTIONS

*-h, --help*::
  Print a short help message about the supported options.
*-V, --version*::
  Print the compile-time version number of the program.
*-D, --daemonize*::
  Fork the process as a daemon into background.
*-c, --config-file 'CONFIGFILE'*::
  Specify the file and path name of the configuration file to be
  used. If none is specified, use `osmo-pcap-client.cfg` in the current
  working directory.

As osmo-pcap-server doesn't capture any packets itself and only receives streams of
captured packets from [remote] osmo-pcap-clients, there is no need to run it as root
or with elevated privileges.

=== Configuring osmo-pcap-server

The osmo-pcap-server configuration consists mainly of the following parts:

* the global server configuration, optionally including TLS related settings
* the per-client (per-connection) configuration

.osmo-pcap-server example global configuration
----
server
 base-path /var/lib/osmo-pcap-server <1>
 server ip 192.168.11.20 <2>
 server port 54321 <3>
 max-snaplen 100000 <4>
----
<1> directory to which the pcap files are stored
<2> IP address to which to bind/listen
<3> TCP port number to which to bind/listen
<4> maximum pcap snapshot length (per packet, in bytes; default: 9000)

The received packets are stored to a pcap file below the `base-path` using a filename
encoding both the client name and the date/time at time of file creation.

.osmo-pcap-server example global configuration
----
server
 client foo 192.168.100.1 <1>
 client bar 192.168.200.2 tls <2>
----
<1> Client `foo` connects from 192.168.100.1 and uses no TLS
<2> Client `bar` connects from 192.168.2.00.2 and uses TLS

=== Configuring TLS

By default, the captured packets are received in plain-text without any additional
layer of encryption or authentication.  This means that there is no confidentiality,
nor any integrity protection, unless the original captured packet already featured
such properties.

If desired, `osmo-pcap-server` can be configured to use TLS (transport layer security)
on the protocol between client and server.

TLS is configured separately for each remote server, whether primary or additional.

NOTE:: osmo-pcap-server uses the gnutls library for TLS support.  See its documentation in terms of supported file formats for CRL, certificates, keys, etc.

.osmo-pcap-server configuration with TLS
----
server
 tls allow-auth x509 <1>
 tls capath /etc/osmocom/osmo-pcap-ca <2>
 tls crlfile /etc/osmocom/osmo-pcap-ca.crl <3>
 tls server-cert /etc/osmocom/osmo-pcap-server.crt <4>
 tls server-key /etc/osmocom/osmo-pcap-server.key <5>
----
<1> require clients to authenticate using a X.509 client certificate
<2> path of all CA certificates we consider valid for signing the client cert
<3> file containing the certificate revocation list
<4> file containing the server certificate
<5> file containing the private key for the server certificate

=== PCAP file rotation

`osmo-pcap-server` can be configured to rotate the pcap file it writes to based
on multiple thresholds. Once such a threshold occurs, usually at the time where
a packet to be recorded into the pcap file is received.
`osmo-pcap-server` will decide whether to keep using the previous file or create
a new file and start writing to it instead.

Current rotation thresholds are based on:

* `max-file-size`: Rotate writing to a new file once the configured maximum file size is reached.
* `rotate-localtime`: Rotate writing a new file based on local time wall-clock
configuration

.Example: configuring pcap file rotation
----
server
 ...
 max-file-size 100000000 <1>
 rotate-localtime hour <2>
----
<1> Rotate to a new file once file reaches 100 MBytes.
<2> Rotate to a new file once the local time wall clock elapses to next hour (00:XY, 01:XY, 02:XY, ..., 23:XY)

The `rotate-localtime` VTY option also allows triggering the pcap file rotation
every N units of time, using the `rotate-localtime TIME_UNIT mod N` variant. For
instance, `rotate-localtime minute mod 21` will trigger rotation of pcap file at
minutes XY:00, XY:21, XY:42 every hour.

NOTE:: osmo-pcap-server rotates the pcap file when new traffic to be recorded is
received. That means, for instance following the example above, that if if no
traffic is received during XY:21 and XY:42, only 2 pcap wills be generated
instead of 3 during that hour.

WARNING:: If wall clock goes backward (eg. due to drift correction or Daylight
Saving procedure), osmo-pcap-server may end up recreating (and truncating) a
previous pcap file if it is generated with the same localtime timestamp, for
instance because connection from osmo-pcap-client was re-established.

=== Completed pcap directory

`osmo-pcap-server` creates and writes data to opened pcap files in the
`base-path` directory configured through VTY. Furthermore, if user supplies a
`completed-path` directory through the VTY, `osmo-pcap-server` will move the
file from `base-path` to `completed-path` directory once it closes the current
file due to rotation or because `osmo-pcap-client` became disconnected. The file
name is kept when moving from one directory to the other.

This feature is useful for users willing to have an external tool to monitor a
directory for new closed pcap files and then acting on them, eg. to gather
statistics of packets.

.Example: Move files from /tmp/recording to /tmp/done
----
server
 ...
 base-path /tmp/recording <1>
 completed-path /tmp/done <2>
----
<1> Files are opened and recorded under /tmp/recording
<2> Once closed files are moved under /tmp/done

NOTE:: `osmo-pcap-server` uses a rename() call to move the file atomically.
However, this has the drawback that both `base-path` and `completed-path` must
be placed in the same filesystem mounting point. Using directories in different
filesystem mount points will fail.
