Change in osmo-pcap[master]: Add user manual for osmo-pcap

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

laforge gerrit-no-reply at lists.osmocom.org
Sun Apr 18 13:26:20 UTC 2021 

laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/osmo-pcap/+/23783 )


Change subject: Add user manual for osmo-pcap
......................................................................

Add user manual for osmo-pcap

This adds one common user manual for both osmo-pcap-client
and osmo-pcap-server.

The manual is still basic in nature, but already contains useful
information regarding the setup of both clients and servers.

Change-Id: I66182fc55f1ee323eba45e7a7fc59db55bff520e
---
M doc/manuals/Makefile.am
A doc/manuals/chapters/client.adoc
A doc/manuals/chapters/overview.adoc
A doc/manuals/chapters/server.adoc
A doc/manuals/osmopcap-usermanual-docinfo.xml
A doc/manuals/osmopcap-usermanual.adoc
6 files changed, 352 insertions(+), 1 deletion(-)



  git pull ssh://gerrit.osmocom.org:29418/osmo-pcap refs/changes/83/23783/1

diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
index 2e24c6c..f2ffa29 100644
--- a/doc/manuals/Makefile.am
+++ b/doc/manuals/Makefile.am
@@ -1,6 +1,13 @@
-EXTRA_DIST = vty
+EXTRA_DIST = osmopcap-usermanual.adoc \
+    osmopcap-usermanual-docinfo.xml \
+    chapters \
+    vty
 
 if BUILD_MANUALS
+  ASCIIDOC = osmopcap-usermanual.adoc
+  ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+
   # This is a significantly modified, multi-target adopted copy of
   # $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
   VARIANTS = client server
diff --git a/doc/manuals/chapters/client.adoc b/doc/manuals/chapters/client.adoc
new file mode 100644
index 0000000..f6ceac5
--- /dev/null
+++ b/doc/manuals/chapters/client.adoc
@@ -0,0 +1,132 @@
+== osmo-pcap-client
+
+The osmo-pcap-client program runs at a location of your network
+where you would like to record some packets.  It captures those
+packets (with or without filter) and forwards them to one or multiple
+remote servers.
+
+=== Running osmo-pcap-client
+
+==== SYNOPSIS
+
+*osmo-pcap-client* [-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.
+
+Capturing network packets requires you to be superuser or have the CAP_NET_RAW capability.
+
+There are several options to achieve this:
+
+- start the program as root user (strongly discouraged)
+- globally enable the CAP_NET_RAW capability for the program using e.g. the tool `setcap`
+- asking `systemd` to start the program with the required capability
+
+NOTE:: This potentially opens a privilege escalation, as `osmo-pcap-client` can be configured
+via the VTY interface (telnet) which is by default accessible by any user on the local machine (access to the loopback device).  Please make sure to protect access to the VTY interface accordingly.
+
+
+=== Configuring the packet capture
+
+The VTY configuration node of osmo-pcap-client contains a `client` node,
+in which the packet capturing is configured
+
+.osmo-pcap-client VTY configuration for packet capture
+----
+client
+ pcap device eth0 <1>
+ pcap filter udp port 23000 <2>
+ pcap detect-loop 1 <3>
+----
+<1> the network device from which to obtain a capture
+<2> the libpcap filter string (`udp port 23000` in this example)
+<3> instruct osmo-pcap-client to automatically add a filter that prevents capturing
+    the traffic between osmo-pcap-client and osmo-pcap-server, which would create a loop.
+
+
+=== Configuring the primary server
+
+.osmo-pcap-client configuration for the primary remote server
+----
+client
+ server ip 192.168.11.20 <1>
+ server port 54321 <2>
+ source ip 192.168.11.1 <3>
+----
+<1> IP address of the server to which to send the traces
+<2> port number of the server to which to send the traces
+<3> local IP address to use when sending traffic to the server
+
+By default, a custom osmo-pcap specific protocol is used to transport
+the captured packets from client to server.  However, the `protocol`
+VTY configuration command can be used to switch to to using a simple `ipip`
+encapsulation.  `ipip` can be transparently decoded by protocol analysis
+tools like wireshark.
+
+
+=== Configuring additional servers
+
+In some use cases, you may want to send the captured packets to multiple
+remote destinations.
+
+The primary and each of the remote destinations each receive a copy
+of each captured packet.
+
+.osmo-pcap-client configuration for an additional remote server
+----
+client
+ pcap-store-connection my_server <1>
+  server ip 192.168.11.10 <2>
+  server port 54321 <3>
+  source ip 192.168.11.1 <4>
+  connect <5>
+----
+<1> a human-readable identifier for this specific connection (`my_server`)
+<2> IP address of the server to which to send the traces
+<3> port number of the server to which to send the traces
+<4> local IP address to use when sending traffic to the server
+<5> request connection to the remote server specified in this section
+
+
+=== Configuring TLS
+
+By default, the captured packets are sent 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-client` 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.
+
+.osmo-pcap-client configuration with TLS
+----
+client
+ server ip 192.168.11.20
+ server port 54321
+ source ip 192.168.11.1
+ enable tls <1>
+ tls hostname pcapserver.example.test<2>
+ tls verify-cert <3>
+ tls capath /etc/osmo-pcap/ca-certificates <4>
+ tls client-cert /etc/osmo-pcap/client.crt <5>
+ tls client-key /etc/osmo-pcap/client.key <6>
+----
+<1> enable TLS for this server
+<2> set the hostname we expect the server to have a certificate for
+<3> enable certificate verification
+<4> path of all CA certificates we consider valid for signing the server cert
+<5> file containing the client certificate
+<6> file containing the private key for the client certificate
+
diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc
new file mode 100644
index 0000000..96bbe4b
--- /dev/null
+++ b/doc/manuals/chapters/overview.adoc
@@ -0,0 +1,43 @@
+[[overview]]
+== OsmoPCAP Overview
+
+=== Package Capturing in distributed telecoms networks
+
+Obtaining raw, binary protocol traces [for later analysis] is an
+essential capability in order to investigate any kind of problem
+in any computer networking system.
+
+The very distributed, heterogenuous nature of cellular networks
+(compared to end-to-end IP networks) results in a lot of relevant
+information being present only at some specific interfaces / points
+in the network.  This in turn means that packet captures have to
+be performed at a variety of different network elements in order
+to get the full picture of what is happening.
+
+Recording protocol traces at various different points in the network
+inevitably raises the question of how to aggregate these.
+
+[[about]]
+=== About OsmoPCAP
+
+OsmoPCAP is a software suite consisting of two programs, a client and a
+server component.
+
+- osmo-pcap-client obtains protocol traces by using AF_PACKET sockets,
+  optionally with a capture filter.  It then forwards the captures to
+  a remote server.
+- osmo-pcap-server accepts incoming connections from clients. It
+  receives captured packets from those clients and stores them.
+
+The server and client communicate using a custom, TCP based protocol
+for passing captured packets from client to server.  Based on your
+configuration, it can optionally be secured by TLS transport-level
+encryption and authentication.
+
+NOTE:: The osmo-pcap programs runs as normal, single-threaded userspace
+programs, without any specific emphasis on efficiency.  It doesn't use
+any of the advanced zero-copy mechanisms available on many modern OSs.
+The goal is to capture telecom signaling (control plane) traffic, whose
+bandwidth is (unlike that of the user plane) typically relatively low
+compared to the available CPU / IO speeds.  Don't expect osmo-pcap to
+handle wire-rate multi-gigabit throughput.
diff --git a/doc/manuals/chapters/server.adoc b/doc/manuals/chapters/server.adoc
new file mode 100644
index 0000000..4f60880
--- /dev/null
+++ b/doc/manuals/chapters/server.adoc
@@ -0,0 +1,90 @@
+== 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-file-size 100000000 <4>
+ max-snaplen 100000 <5>
+----
+<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 size for pcap files; create a new file once max-file-size is reached
+<5> 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
diff --git a/doc/manuals/osmopcap-usermanual-docinfo.xml b/doc/manuals/osmopcap-usermanual-docinfo.xml
new file mode 100644
index 0000000..528635c
--- /dev/null
+++ b/doc/manuals/osmopcap-usermanual-docinfo.xml
@@ -0,0 +1,47 @@
+<revhistory>
+  <revision>
+    <revnumber>1</revnumber>
+    <date>January 4th, 2021</date>
+    <authorinitials>HW</authorinitials>
+    <revremark>
+      Initial version
+    </revremark>
+  </revision>
+</revhistory>
+
+<authorgroup>
+  <author>
+    <firstname>Harald</firstname>
+    <surname>Welte</surname>
+    <email>hwelte at sysmocom.de</email>
+    <authorinitials>HW</authorinitials>
+    <affiliation>
+      <shortaffil>sysmocom</shortaffil>
+      <orgname>sysmocom - s.f.m.c. GmbH</orgname>
+      <jobtitle>Managing Director</jobtitle>
+    </affiliation>
+  </author>
+</authorgroup>
+
+<copyright>
+  <year>2021</year>
+  <holder>sysmocom - s.f.m.c. GmbH</holder>
+</copyright>
+
+<legalnotice>
+  <para>
+	Permission is granted to copy, distribute and/or modify this
+	document under the terms of the GNU Free Documentation License,
+	Version 1.3 or any later version published by the Free Software
+	Foundation; with the Invariant Sections being just 'Foreword',
+	'Acknowledgements' and 'Preface', with no Front-Cover Texts,
+	and no Back-Cover Texts.  A copy of the license is included in
+	the section entitled "GNU Free Documentation License".
+  </para>
+  <para>
+	The Asciidoc source code of this manual can be found at
+	<ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
+		http://git.osmocom.org/osmo-gsm-manuals/
+	</ulink>
+  </para>
+</legalnotice>
diff --git a/doc/manuals/osmopcap-usermanual.adoc b/doc/manuals/osmopcap-usermanual.adoc
new file mode 100644
index 0000000..63daf6c
--- /dev/null
+++ b/doc/manuals/osmopcap-usermanual.adoc
@@ -0,0 +1,32 @@
+:gfdl-enabled:
+:program-name: OsmoPCAP
+
+OsmoPCAP User Manual
+====================
+Harald Welte <hwelte at sysmocom.de>
+
+
+include::./common/chapters/preface.adoc[]
+
+include::{srcdir}/chapters/overview.adoc[]
+
+include::{srcdir}/chapters/client.adoc[]
+
+include::{srcdir}/chapters/server.adoc[]
+
+
+include::./common/chapters/counters-overview.adoc[]
+
+
+
+include::./common/chapters/vty.adoc[]
+
+include::./common/chapters/logging.adoc[]
+
+include::./common/chapters/port_numbers.adoc[]
+
+include::./common/chapters/bibliography.adoc[]
+
+include::./common/chapters/glossary.adoc[]
+
+include::./common/chapters/gfdl.adoc[]

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-pcap/+/23783
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-pcap
Gerrit-Branch: master
Gerrit-Change-Id: I66182fc55f1ee323eba45e7a7fc59db55bff520e
Gerrit-Change-Number: 23783
Gerrit-PatchSet: 1
Gerrit-Owner: laforge <laforge at osmocom.org>
Gerrit-MessageType: newchange
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20210418/566a5a75/attachment.htm>

More information about the gerrit-log mailing list