For many, many issues, logs and IP captures are the main source to see, what causes trouble.

Therefore you read

• If you have logs, please provide them
• If you have tcpdump captures (wireshark), please provide them.

when you create a new issue. This guide shows, how to do so.

Californium uses slf4j as logging API. If logs are wanted, a implementation of that API is required. The Californium's demo-apps are using logback for that.

If you use one of the demo-apps, enabling logs is done by configuring logback with a "logback.xml" file.

<configuration>

	<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
		<!-- encoders are assigned the type ch.qos.logback.classic.encoder.PatternLayoutEncoder 
			by default -->
		<encoder>
			<pattern>%d{HH:mm:ss.SSS} %level [%logger{0}]: %msg%n</pattern>
		</encoder>
	</appender>

	<root level="DEBUG" >
		<appender-ref ref="STDOUT" />
	</root>

</configuration>

This file is usually stored in "src/main/resources" in the supporting demo-apps. Depending on the variant to start the application, e.g. from IDE, or command line with java -cp or java -jar the file from that directory is used, or not. In the case, the file from that directory is not used, or a different "logback.xml" file should be used, this could be configured with.

java -Dlogback.configurationFile=<your-path>/logback.xml ...

(Note: not all demo-apps may support it, but adding the "logback.xml" enables it.)

If you want to create logs for your own application, you may use also logback. To do so, logback must be added to the maven dependencies of your project:

<dependencies>
        ...
	<!-- runtime dependencies -->
	<dependency>
		<groupId>ch.qos.logback</groupId>
		<artifactId>logback-classic</artifactId>
		<scope>runtime</scope>
	</dependency>
</dependencies>

Also add the configuration file "logback.xml" as describe above.

Many issues requires details of the communcation to be answered. This should give some hint to collect them.

Belong many tools, two are in my opinion specially useful:

• tcpdump
• wireshark

The first tcpdump is a simple command line tool, which allows to collect data on "headless" units. The second wireshark is a pwoerful UI Tool, which allows to collect and/or analyze that collected data.

Tcpdump comes with rich feature set. In order to analyze the capture later with wireshark, it may be started with

sudo tcpdump -s 0 -w <filename>.pcap -i any '(udp port 5683) or (udp port 5684) or (udp port 53)'

That starts to capture all coap (udp port 5683), dtls (udp port 5684), and dns (udp port 53) and stores the captured traffic in the provided file. If you want to stop the capture, press Ctrl-C, or use the "-c numberORecords" option of tcpdump. That results in a .pcap file, which then may be further analyzed using wireshark.

Wireshark

Wireshark - Ubuntu

❗❗❗ Provide NO SCREENSHOTS, the capture files are required ❗❗❗

Wireshark is very powerful tool. It offers a UI to analyze the data and see the details. It maybe used to collect the data itself or to load a capture from tcpdump. For append capture data to Californium issues, it's frequently required to select a subset and save only the intended packets. To do so, either fist stop the current capture, if wireshark is used for capturing, or load the capture file from tcpdump.

Here WireShark is used to capture the traffic. "dns or dtls" filter are applied to only see the related packets (if the issues is for dtls). That current capture need to be stopped before being able to export packages. Therefore press the red button at the left top. If the current capture is stopped or a tcpdump capture is loaded, then the menu "File -> Export Specified Packets ..." is active and could be selected.

When "Export Specified Packets ..." is selected, this dialog appears. Usually it pays off, to limit the range to the intended subset by using the number range. Please do a final check, if the exported capture contains only the packages intended for the issue. The current wireshark version offers you to "Compress with gzip" use that. Or, if you use an older version, please zip that capture and then append it by "drag&drop" to the issue.

If all handshake-messages, from the client's ClientHello up to the server's Finish are captured, wireshark is able to decrypt a the records, if you provide the secret key in the configuration. Therefore chose the menu, "Edit - > Preferences ...". Select in the dialog's tree on the left side "Protocols -> DTLS" and the settings for "Datagram Transport Layer Security".

Enter the value of the (secret) Pre-Shared Key there in hexadecimal, e.g. "73656372657450534b" for "secretPSK".

This works only for basic PSK cipher suites, for ECDHE based ones, as TLS_ECDHE_PSK_WITH_AES_128_CCM_SHA256, this doesn't work.

UDP traffic for port 5683 get automatically decoded as CoAP, and on port 5684 as DTLS. If you need to use other ports, e.g. 5784, you must configure wireshark to decode the packages. Either use the "Decode As ..." context menu (right mouse button) of the message, or via menu bar "Analyze -> Decode As ..-", or via hotkeys "Ctrl+Shift+U".

If the decoded DTLS message should be decoded as CoAP as well, that takes two entries, as shown in the screenshot for port 5784.

In some cases it may not be possible to provide the capture file by itself. Especially, if there are doubts about the contained information. If you feel, that you know the part of the information, which causes the issue, you may also provided a textual copy of the selected wireshark items. To do so, please unfold the item and all sub-items. Then select the context menu "Copy -> All Visible Selected Tree Items".

Paste the copied text into the github issue:

Handshake Protocol: Client Hello
    Handshake Type: Client Hello (1)
    Length: 82
    Message Sequence: 0
    Fragment Offset: 0
    Fragment Length: 82
    Version: DTLS 1.2 (0xfefd)
    Random: 00000000e7b7b9f600c6d84ff0858b08aa9f1f5d7a4fe8cc...
        GMT Unix Time: Jan  1, 1970 01:00:00.000000000 CET
        Random Bytes: e7b7b9f600c6d84ff0858b08aa9f1f5d7a4fe8cc79390093...
    Session ID Length: 0
    Cookie Length: 0
    Cipher Suites Length: 2
    Cipher Suites (1 suite)
        Cipher Suite: TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 (0xc0ae)
    Compression Methods Length: 1
    Compression Methods (1 method)
        Compression Method: null (0)
    Extensions Length: 38
    Extension: client_certificate_type (len=2)
        Type: client_certificate_type (19)
        Length: 2
        Certificate Type List Length: 1
        Certificate Type List (1)
            Certificate Type: Raw Public Key (0x02)
    Extension: server_certificate_type (len=2)
        Type: server_certificate_type (20)
        Length: 2
        Certificate Type List Length: 1
        Certificate Type List (1)
            Certificate Type: Raw Public Key (0x02)
    Extension: supported_groups (len=4)
        Type: supported_groups (10)
        Length: 4
        Supported Groups List Length: 2
        Supported Groups (1 group)
            Supported Group: secp256r1 (0x0017)
    Extension: ec_point_formats (len=2)
        Type: ec_point_formats (11)
        Length: 2
        EC point formats Length: 1
        Elliptic curves point formats (1)
            EC point format: uncompressed (0)
    Extension: signature_algorithms (len=4)
        Type: signature_algorithms (13)
        Length: 4
        Signature Hash Algorithms Length: 2
        Signature Hash Algorithms (1 algorithm)
            Signature Algorithm: ecdsa_secp256r1_sha256 (0x0403)
                Signature Hash Algorithm Hash: SHA256 (4)
                Signature Hash Algorithm Signature: ECDSA (3)
    Extension: extended_master_secret (len=0)
        Type: extended_master_secret (23)
        Length: 0

Don't forget to check, if all information contained is intended to be published! Remove or replace critical information by ??? or ....