<p>laforge has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/osmo-pcap/+/23783">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Add user manual for osmo-pcap<br><br>This adds one common user manual for both osmo-pcap-client<br>and osmo-pcap-server.<br><br>The manual is still basic in nature, but already contains useful<br>information regarding the setup of both clients and servers.<br><br>Change-Id: I66182fc55f1ee323eba45e7a7fc59db55bff520e<br>---<br>M doc/manuals/Makefile.am<br>A doc/manuals/chapters/client.adoc<br>A doc/manuals/chapters/overview.adoc<br>A doc/manuals/chapters/server.adoc<br>A doc/manuals/osmopcap-usermanual-docinfo.xml<br>A doc/manuals/osmopcap-usermanual.adoc<br>6 files changed, 352 insertions(+), 1 deletion(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/osmo-pcap refs/changes/83/23783/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am</span><br><span>index 2e24c6c..f2ffa29 100644</span><br><span>--- a/doc/manuals/Makefile.am</span><br><span>+++ b/doc/manuals/Makefile.am</span><br><span>@@ -1,6 +1,13 @@</span><br><span style="color: hsl(0, 100%, 40%);">-EXTRA_DIST = vty</span><br><span style="color: hsl(120, 100%, 40%);">+EXTRA_DIST = osmopcap-usermanual.adoc \</span><br><span style="color: hsl(120, 100%, 40%);">+    osmopcap-usermanual-docinfo.xml \</span><br><span style="color: hsl(120, 100%, 40%);">+    chapters \</span><br><span style="color: hsl(120, 100%, 40%);">+    vty</span><br><span> </span><br><span> if BUILD_MANUALS</span><br><span style="color: hsl(120, 100%, 40%);">+  ASCIIDOC = osmopcap-usermanual.adoc</span><br><span style="color: hsl(120, 100%, 40%);">+  ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc</span><br><span style="color: hsl(120, 100%, 40%);">+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span>   # This is a significantly modified, multi-target adopted copy of</span><br><span>   # $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc</span><br><span>   VARIANTS = client server</span><br><span>diff --git a/doc/manuals/chapters/client.adoc b/doc/manuals/chapters/client.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..f6ceac5</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/client.adoc</span><br><span>@@ -0,0 +1,132 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== osmo-pcap-client</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The osmo-pcap-client program runs at a location of your network</span><br><span style="color: hsl(120, 100%, 40%);">+where you would like to record some packets.  It captures those</span><br><span style="color: hsl(120, 100%, 40%);">+packets (with or without filter) and forwards them to one or multiple</span><br><span style="color: hsl(120, 100%, 40%);">+remote servers.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Running osmo-pcap-client</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== SYNOPSIS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*osmo-pcap-client* [-D] [-c CFG_FILE] | -h | -V</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== OPTIONS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*-h, --help*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Print a short help message about the supported options.</span><br><span style="color: hsl(120, 100%, 40%);">+*-V, --version*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Print the compile-time version number of the program.</span><br><span style="color: hsl(120, 100%, 40%);">+*-D, --daemonize*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Fork the process as a daemon into background.</span><br><span style="color: hsl(120, 100%, 40%);">+*-c, --config-file 'CONFIGFILE'*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Specify the file and path name of the configuration file to be</span><br><span style="color: hsl(120, 100%, 40%);">+  used. If none is specified, use `osmo-pcap-client.cfg` in the current</span><br><span style="color: hsl(120, 100%, 40%);">+  working directory.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Capturing network packets requires you to be superuser or have the CAP_NET_RAW capability.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There are several options to achieve this:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- start the program as root user (strongly discouraged)</span><br><span style="color: hsl(120, 100%, 40%);">+- globally enable the CAP_NET_RAW capability for the program using e.g. the tool `setcap`</span><br><span style="color: hsl(120, 100%, 40%);">+- asking `systemd` to start the program with the required capability</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE:: This potentially opens a privilege escalation, as `osmo-pcap-client` can be configured</span><br><span style="color: hsl(120, 100%, 40%);">+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.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring the packet capture</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The VTY configuration node of osmo-pcap-client contains a `client` node,</span><br><span style="color: hsl(120, 100%, 40%);">+in which the packet capturing is configured</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-client VTY configuration for packet capture</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+client</span><br><span style="color: hsl(120, 100%, 40%);">+ pcap device eth0 <1></span><br><span style="color: hsl(120, 100%, 40%);">+ pcap filter udp port 23000 <2></span><br><span style="color: hsl(120, 100%, 40%);">+ pcap detect-loop 1 <3></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> the network device from which to obtain a capture</span><br><span style="color: hsl(120, 100%, 40%);">+<2> the libpcap filter string (`udp port 23000` in this example)</span><br><span style="color: hsl(120, 100%, 40%);">+<3> instruct osmo-pcap-client to automatically add a filter that prevents capturing</span><br><span style="color: hsl(120, 100%, 40%);">+    the traffic between osmo-pcap-client and osmo-pcap-server, which would create a loop.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring the primary server</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-client configuration for the primary remote server</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+client</span><br><span style="color: hsl(120, 100%, 40%);">+ server ip 192.168.11.20 <1></span><br><span style="color: hsl(120, 100%, 40%);">+ server port 54321 <2></span><br><span style="color: hsl(120, 100%, 40%);">+ source ip 192.168.11.1 <3></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> IP address of the server to which to send the traces</span><br><span style="color: hsl(120, 100%, 40%);">+<2> port number of the server to which to send the traces</span><br><span style="color: hsl(120, 100%, 40%);">+<3> local IP address to use when sending traffic to the server</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By default, a custom osmo-pcap specific protocol is used to transport</span><br><span style="color: hsl(120, 100%, 40%);">+the captured packets from client to server.  However, the `protocol`</span><br><span style="color: hsl(120, 100%, 40%);">+VTY configuration command can be used to switch to to using a simple `ipip`</span><br><span style="color: hsl(120, 100%, 40%);">+encapsulation.  `ipip` can be transparently decoded by protocol analysis</span><br><span style="color: hsl(120, 100%, 40%);">+tools like wireshark.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring additional servers</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+In some use cases, you may want to send the captured packets to multiple</span><br><span style="color: hsl(120, 100%, 40%);">+remote destinations.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The primary and each of the remote destinations each receive a copy</span><br><span style="color: hsl(120, 100%, 40%);">+of each captured packet.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-client configuration for an additional remote server</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+client</span><br><span style="color: hsl(120, 100%, 40%);">+ pcap-store-connection my_server <1></span><br><span style="color: hsl(120, 100%, 40%);">+  server ip 192.168.11.10 <2></span><br><span style="color: hsl(120, 100%, 40%);">+  server port 54321 <3></span><br><span style="color: hsl(120, 100%, 40%);">+  source ip 192.168.11.1 <4></span><br><span style="color: hsl(120, 100%, 40%);">+  connect <5></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> a human-readable identifier for this specific connection (`my_server`)</span><br><span style="color: hsl(120, 100%, 40%);">+<2> IP address of the server to which to send the traces</span><br><span style="color: hsl(120, 100%, 40%);">+<3> port number of the server to which to send the traces</span><br><span style="color: hsl(120, 100%, 40%);">+<4> local IP address to use when sending traffic to the server</span><br><span style="color: hsl(120, 100%, 40%);">+<5> request connection to the remote server specified in this section</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring TLS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By default, the captured packets are sent in plain-text without any additional</span><br><span style="color: hsl(120, 100%, 40%);">+layer of encryption or authentication.  This means that there is no confidentiality,</span><br><span style="color: hsl(120, 100%, 40%);">+nor any integrity protection, unless the original captured packet already featured</span><br><span style="color: hsl(120, 100%, 40%);">+such properties.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If desired, `osmo-pcap-client` can be configured to use TLS (transport layer security)</span><br><span style="color: hsl(120, 100%, 40%);">+on the protocol between client and server.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+TLS is configured separately for each remote server, whether primary or additional.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-client configuration with TLS</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+client</span><br><span style="color: hsl(120, 100%, 40%);">+ server ip 192.168.11.20</span><br><span style="color: hsl(120, 100%, 40%);">+ server port 54321</span><br><span style="color: hsl(120, 100%, 40%);">+ source ip 192.168.11.1</span><br><span style="color: hsl(120, 100%, 40%);">+ enable tls <1></span><br><span style="color: hsl(120, 100%, 40%);">+ tls hostname pcapserver.example.test<2></span><br><span style="color: hsl(120, 100%, 40%);">+ tls verify-cert <3></span><br><span style="color: hsl(120, 100%, 40%);">+ tls capath /etc/osmo-pcap/ca-certificates <4></span><br><span style="color: hsl(120, 100%, 40%);">+ tls client-cert /etc/osmo-pcap/client.crt <5></span><br><span style="color: hsl(120, 100%, 40%);">+ tls client-key /etc/osmo-pcap/client.key <6></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> enable TLS for this server</span><br><span style="color: hsl(120, 100%, 40%);">+<2> set the hostname we expect the server to have a certificate for</span><br><span style="color: hsl(120, 100%, 40%);">+<3> enable certificate verification</span><br><span style="color: hsl(120, 100%, 40%);">+<4> path of all CA certificates we consider valid for signing the server cert</span><br><span style="color: hsl(120, 100%, 40%);">+<5> file containing the client certificate</span><br><span style="color: hsl(120, 100%, 40%);">+<6> file containing the private key for the client certificate</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span>diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..96bbe4b</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/overview.adoc</span><br><span>@@ -0,0 +1,43 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[overview]]</span><br><span style="color: hsl(120, 100%, 40%);">+== OsmoPCAP Overview</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Package Capturing in distributed telecoms networks</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Obtaining raw, binary protocol traces [for later analysis] is an</span><br><span style="color: hsl(120, 100%, 40%);">+essential capability in order to investigate any kind of problem</span><br><span style="color: hsl(120, 100%, 40%);">+in any computer networking system.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The very distributed, heterogenuous nature of cellular networks</span><br><span style="color: hsl(120, 100%, 40%);">+(compared to end-to-end IP networks) results in a lot of relevant</span><br><span style="color: hsl(120, 100%, 40%);">+information being present only at some specific interfaces / points</span><br><span style="color: hsl(120, 100%, 40%);">+in the network.  This in turn means that packet captures have to</span><br><span style="color: hsl(120, 100%, 40%);">+be performed at a variety of different network elements in order</span><br><span style="color: hsl(120, 100%, 40%);">+to get the full picture of what is happening.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Recording protocol traces at various different points in the network</span><br><span style="color: hsl(120, 100%, 40%);">+inevitably raises the question of how to aggregate these.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+[[about]]</span><br><span style="color: hsl(120, 100%, 40%);">+=== About OsmoPCAP</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoPCAP is a software suite consisting of two programs, a client and a</span><br><span style="color: hsl(120, 100%, 40%);">+server component.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+- osmo-pcap-client obtains protocol traces by using AF_PACKET sockets,</span><br><span style="color: hsl(120, 100%, 40%);">+  optionally with a capture filter.  It then forwards the captures to</span><br><span style="color: hsl(120, 100%, 40%);">+  a remote server.</span><br><span style="color: hsl(120, 100%, 40%);">+- osmo-pcap-server accepts incoming connections from clients. It</span><br><span style="color: hsl(120, 100%, 40%);">+  receives captured packets from those clients and stores them.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The server and client communicate using a custom, TCP based protocol</span><br><span style="color: hsl(120, 100%, 40%);">+for passing captured packets from client to server.  Based on your</span><br><span style="color: hsl(120, 100%, 40%);">+configuration, it can optionally be secured by TLS transport-level</span><br><span style="color: hsl(120, 100%, 40%);">+encryption and authentication.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+NOTE:: The osmo-pcap programs runs as normal, single-threaded userspace</span><br><span style="color: hsl(120, 100%, 40%);">+programs, without any specific emphasis on efficiency.  It doesn't use</span><br><span style="color: hsl(120, 100%, 40%);">+any of the advanced zero-copy mechanisms available on many modern OSs.</span><br><span style="color: hsl(120, 100%, 40%);">+The goal is to capture telecom signaling (control plane) traffic, whose</span><br><span style="color: hsl(120, 100%, 40%);">+bandwidth is (unlike that of the user plane) typically relatively low</span><br><span style="color: hsl(120, 100%, 40%);">+compared to the available CPU / IO speeds.  Don't expect osmo-pcap to</span><br><span style="color: hsl(120, 100%, 40%);">+handle wire-rate multi-gigabit throughput.</span><br><span>diff --git a/doc/manuals/chapters/server.adoc b/doc/manuals/chapters/server.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..4f60880</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/server.adoc</span><br><span>@@ -0,0 +1,90 @@</span><br><span style="color: hsl(120, 100%, 40%);">+== osmo-pcap-server</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The osmo-pcap-server program can run anywhere in your network, as long</span><br><span style="color: hsl(120, 100%, 40%);">+as it can be reached by the remote osmo-pcap-client instances.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Running osmo-pcap-server</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== SYNOPSIS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*osmo-pcap-server* [-D] [-c CFG_FILE] | -h | -V</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== OPTIONS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*-h, --help*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Print a short help message about the supported options.</span><br><span style="color: hsl(120, 100%, 40%);">+*-V, --version*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Print the compile-time version number of the program.</span><br><span style="color: hsl(120, 100%, 40%);">+*-D, --daemonize*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Fork the process as a daemon into background.</span><br><span style="color: hsl(120, 100%, 40%);">+*-c, --config-file 'CONFIGFILE'*::</span><br><span style="color: hsl(120, 100%, 40%);">+  Specify the file and path name of the configuration file to be</span><br><span style="color: hsl(120, 100%, 40%);">+  used. If none is specified, use `osmo-pcap-client.cfg` in the current</span><br><span style="color: hsl(120, 100%, 40%);">+  working directory.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+As osmo-pcap-server doesn't capture any packets itself and only receives streams of</span><br><span style="color: hsl(120, 100%, 40%);">+captured packets from [remote] osmo-pcap-clients, there is no need to run it as root</span><br><span style="color: hsl(120, 100%, 40%);">+or with elevated privileges.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring osmo-pcap-server</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The osmo-pcap-server configuration consists mainly of the following parts:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* the global server configuration, optionally including TLS related settings</span><br><span style="color: hsl(120, 100%, 40%);">+* the per-client (per-connection) configuration</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-server example global configuration</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+server</span><br><span style="color: hsl(120, 100%, 40%);">+ base-path /var/lib/osmo-pcap-server <1></span><br><span style="color: hsl(120, 100%, 40%);">+ server ip 192.168.11.20 <2></span><br><span style="color: hsl(120, 100%, 40%);">+ server port 54321 <3></span><br><span style="color: hsl(120, 100%, 40%);">+ max-file-size 100000000 <4></span><br><span style="color: hsl(120, 100%, 40%);">+ max-snaplen 100000 <5></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> directory to which the pcap files are stored</span><br><span style="color: hsl(120, 100%, 40%);">+<2> IP address to which to bind/listen</span><br><span style="color: hsl(120, 100%, 40%);">+<3> TCP port number to which to bind/listen</span><br><span style="color: hsl(120, 100%, 40%);">+<4> maximum size for pcap files; create a new file once max-file-size is reached</span><br><span style="color: hsl(120, 100%, 40%);">+<5> maximum pcap snapshot length (per packet, in bytes; default: 9000)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The received packets are stored to a pcap file below the `base-path` using a filename</span><br><span style="color: hsl(120, 100%, 40%);">+encoding both the client name and the date/time at time of file creation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-server example global configuration</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+server</span><br><span style="color: hsl(120, 100%, 40%);">+ client foo 192.168.100.1 <1></span><br><span style="color: hsl(120, 100%, 40%);">+ client bar 192.168.200.2 tls <2></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> Client `foo` connects from 192.168.100.1 and uses no TLS</span><br><span style="color: hsl(120, 100%, 40%);">+<2> Client `bar` connects from 192.168.2.00.2 and uses TLS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Configuring TLS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+By default, the captured packets are received in plain-text without any additional</span><br><span style="color: hsl(120, 100%, 40%);">+layer of encryption or authentication.  This means that there is no confidentiality,</span><br><span style="color: hsl(120, 100%, 40%);">+nor any integrity protection, unless the original captured packet already featured</span><br><span style="color: hsl(120, 100%, 40%);">+such properties.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If desired, `osmo-pcap-server` can be configured to use TLS (transport layer security)</span><br><span style="color: hsl(120, 100%, 40%);">+on the protocol between client and server.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+TLS is configured separately for each remote server, whether primary or additional.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+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.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-pcap-server configuration with TLS</span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+server</span><br><span style="color: hsl(120, 100%, 40%);">+ tls allow-auth x509 <1></span><br><span style="color: hsl(120, 100%, 40%);">+ tls capath /etc/osmocom/osmo-pcap-ca <2></span><br><span style="color: hsl(120, 100%, 40%);">+ tls crlfile /etc/osmocom/osmo-pcap-ca.crl <3></span><br><span style="color: hsl(120, 100%, 40%);">+ tls server-cert /etc/osmocom/osmo-pcap-server.crt <4></span><br><span style="color: hsl(120, 100%, 40%);">+ tls server-key /etc/osmocom/osmo-pcap-server.key <5></span><br><span style="color: hsl(120, 100%, 40%);">+----</span><br><span style="color: hsl(120, 100%, 40%);">+<1> require clients to authenticate using a X.509 client certificate</span><br><span style="color: hsl(120, 100%, 40%);">+<2> path of all CA certificates we consider valid for signing the client cert</span><br><span style="color: hsl(120, 100%, 40%);">+<3> file containing the certificate revocation list</span><br><span style="color: hsl(120, 100%, 40%);">+<4> file containing the server certificate</span><br><span style="color: hsl(120, 100%, 40%);">+<5> file containing the private key for the server certificate</span><br><span>diff --git a/doc/manuals/osmopcap-usermanual-docinfo.xml b/doc/manuals/osmopcap-usermanual-docinfo.xml</span><br><span>new file mode 100644</span><br><span>index 0000000..528635c</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/osmopcap-usermanual-docinfo.xml</span><br><span>@@ -0,0 +1,47 @@</span><br><span style="color: hsl(120, 100%, 40%);">+<revhistory></span><br><span style="color: hsl(120, 100%, 40%);">+  <revision></span><br><span style="color: hsl(120, 100%, 40%);">+    <revnumber>1</revnumber></span><br><span style="color: hsl(120, 100%, 40%);">+    <date>January 4th, 2021</date></span><br><span style="color: hsl(120, 100%, 40%);">+    <authorinitials>HW</authorinitials></span><br><span style="color: hsl(120, 100%, 40%);">+    <revremark></span><br><span style="color: hsl(120, 100%, 40%);">+      Initial version</span><br><span style="color: hsl(120, 100%, 40%);">+    </revremark></span><br><span style="color: hsl(120, 100%, 40%);">+  </revision></span><br><span style="color: hsl(120, 100%, 40%);">+</revhistory></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+<authorgroup></span><br><span style="color: hsl(120, 100%, 40%);">+  <author></span><br><span style="color: hsl(120, 100%, 40%);">+    <firstname>Harald</firstname></span><br><span style="color: hsl(120, 100%, 40%);">+    <surname>Welte</surname></span><br><span style="color: hsl(120, 100%, 40%);">+    <email>hwelte@sysmocom.de</email></span><br><span style="color: hsl(120, 100%, 40%);">+    <authorinitials>HW</authorinitials></span><br><span style="color: hsl(120, 100%, 40%);">+    <affiliation></span><br><span style="color: hsl(120, 100%, 40%);">+      <shortaffil>sysmocom</shortaffil></span><br><span style="color: hsl(120, 100%, 40%);">+      <orgname>sysmocom - s.f.m.c. GmbH</orgname></span><br><span style="color: hsl(120, 100%, 40%);">+      <jobtitle>Managing Director</jobtitle></span><br><span style="color: hsl(120, 100%, 40%);">+    </affiliation></span><br><span style="color: hsl(120, 100%, 40%);">+  </author></span><br><span style="color: hsl(120, 100%, 40%);">+</authorgroup></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+<copyright></span><br><span style="color: hsl(120, 100%, 40%);">+  <year>2021</year></span><br><span style="color: hsl(120, 100%, 40%);">+  <holder>sysmocom - s.f.m.c. GmbH</holder></span><br><span style="color: hsl(120, 100%, 40%);">+</copyright></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+<legalnotice></span><br><span style="color: hsl(120, 100%, 40%);">+  <para></span><br><span style="color: hsl(120, 100%, 40%);">+    Permission is granted to copy, distribute and/or modify this</span><br><span style="color: hsl(120, 100%, 40%);">+  document under the terms of the GNU Free Documentation License,</span><br><span style="color: hsl(120, 100%, 40%);">+       Version 1.3 or any later version published by the Free Software</span><br><span style="color: hsl(120, 100%, 40%);">+       Foundation; with the Invariant Sections being just 'Foreword',</span><br><span style="color: hsl(120, 100%, 40%);">+        'Acknowledgements' and 'Preface', with no Front-Cover Texts,</span><br><span style="color: hsl(120, 100%, 40%);">+  and no Back-Cover Texts.  A copy of the license is included in</span><br><span style="color: hsl(120, 100%, 40%);">+        the section entitled "GNU Free Documentation License".</span><br><span style="color: hsl(120, 100%, 40%);">+  </para></span><br><span style="color: hsl(120, 100%, 40%);">+  <para></span><br><span style="color: hsl(120, 100%, 40%);">+     The Asciidoc source code of this manual can be found at</span><br><span style="color: hsl(120, 100%, 40%);">+       <ulink url="http://git.osmocom.org/osmo-gsm-manuals/"></span><br><span style="color: hsl(120, 100%, 40%);">+                http://git.osmocom.org/osmo-gsm-manuals/</span><br><span style="color: hsl(120, 100%, 40%);">+      </ulink></span><br><span style="color: hsl(120, 100%, 40%);">+  </para></span><br><span style="color: hsl(120, 100%, 40%);">+</legalnotice></span><br><span>diff --git a/doc/manuals/osmopcap-usermanual.adoc b/doc/manuals/osmopcap-usermanual.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..63daf6c</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/osmopcap-usermanual.adoc</span><br><span>@@ -0,0 +1,32 @@</span><br><span style="color: hsl(120, 100%, 40%);">+:gfdl-enabled:</span><br><span style="color: hsl(120, 100%, 40%);">+:program-name: OsmoPCAP</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+OsmoPCAP User Manual</span><br><span style="color: hsl(120, 100%, 40%);">+====================</span><br><span style="color: hsl(120, 100%, 40%);">+Harald Welte <hwelte@sysmocom.de></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/preface.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/overview.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/client.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/server.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/counters-overview.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/vty.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/logging.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/port_numbers.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/bibliography.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/glossary.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+include::./common/chapters/gfdl.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-pcap/+/23783">change 23783</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-pcap/+/23783"/><meta itemprop="name" content="View Change"/></div></div>

<div style="display:none"> Gerrit-Project: osmo-pcap </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I66182fc55f1ee323eba45e7a7fc59db55bff520e </div>
<div style="display:none"> Gerrit-Change-Number: 23783 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>