Get started · Linux
Linux gateways
kcoap compiles to a native Linux executable for x86-64, with OpenSSL 3 linked in: the gateway needs neither a JVM nor a system OpenSSL. The same common code as everywhere else, with UDP, TCP and WebSockets.
- Target
linuxX64 - TransportsUDP, TCP, WebSocket client and server
- CryptographyOpenSSL 3, linked in
- ARM gatewaysNo
linuxArm64yet
Prerequisites
- An x86-64 Linux machine to build on, with a JDK 17 or newer for Gradle. The Kotlin/Native toolchain downloads itself.
- Kotlin 2.3 or newer; the samples use 2.4.21, the version kcoap is built with.
- An x86-64 gateway to run on. The executable needs no JVM and no system OpenSSL.
Install status
kcoap 0.1.0 is on Maven Central, its linuxX64 artifacts included. CI runs every common test as native Linux code, and the WebSocket loopback test natively; the UDP and TCP adapter tests run on the JVM only, from the same common code.
Set up
-
Create the build file
The bill of materials,
kcoap-bom, sets one version for every kcoap module, so the modules name none.Kotlin DSL
build.gradle.kts
plugins { kotlin("multiplatform") version "2.4.21" } repositories { mavenCentral() } kotlin { linuxX64 { binaries.executable() } sourceSets { commonMain.dependencies { val bom = "dev.kcoap:kcoap-bom:0.1.0" implementation(project.dependencies.platform(bom)) implementation("dev.kcoap:kcoap-coap") implementation("dev.kcoap:kcoap-transport-ktor") implementation("dev.kcoap:kcoap-crypto-default") implementation("dev.kcoap:kcoap-oscore") implementation("dev.kcoap:kcoap-edhoc-oscore") } } }Version catalog
gradle/libs.versions.toml
[versions] kotlin = "2.4.21" kcoap = "0.1.0" [libraries] kcoap-bom = { module = "dev.kcoap:kcoap-bom", version.ref = "kcoap" } kcoap-coap = { module = "dev.kcoap:kcoap-coap" } kcoap-transport-ktor = { module = "dev.kcoap:kcoap-transport-ktor" } kcoap-crypto-default = { module = "dev.kcoap:kcoap-crypto-default" } kcoap-oscore = { module = "dev.kcoap:kcoap-oscore" } kcoap-edhoc-oscore = { module = "dev.kcoap:kcoap-edhoc-oscore" } [bundles] kcoap = [ "kcoap-coap", "kcoap-transport-ktor", "kcoap-crypto-default", "kcoap-oscore", "kcoap-edhoc-oscore", ] [plugins] kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }build.gradle.kts
plugins { alias(libs.plugins.kotlin.multiplatform) } repositories { mavenCentral() } kotlin { linuxX64 { binaries.executable() } sourceSets { commonMain.dependencies { implementation(project.dependencies.platform(libs.kcoap.bom)) implementation(libs.bundles.kcoap) } } }A standard Kotlin Multiplatform build file; kcoap’s coordinates are checked. kcoap’s repository has no Linux application that builds this file.
First client and server
The same server and client as in the JVM guide, as a native program. On Kotlin/Native, Dispatchers.Default runs the coroutines.
src/linuxX64Main/kotlin/Main.kt
import dev.kcoap.coap.CoapResponse
import dev.kcoap.coap.ContentFormat
import dev.kcoap.coap.client.CoapClient
import dev.kcoap.coap.server.CoapServer
import dev.kcoap.transport.ktor.KtorUdpTransport
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
try {
var stored = "nothing yet"
val transport = KtorUdpTransport.bind("127.0.0.1", 5683)
val server = CoapServer(transport, scope) {
resource("hello") { get { CoapResponse.content("Hello, $peer") } }
resource("store") {
get { CoapResponse.content(stored) }
put {
stored = payloadAsText()
CoapResponse.changed()
}
}
}
val client = CoapClient(KtorUdpTransport.bind("127.0.0.1"), scope)
val uri = "coap://127.0.0.1:5683"
println(client.get("$uri/hello").payloadAsText())
val body = "on".encodeToByteArray()
client.put("$uri/store", body, ContentFormat.TEXT_PLAIN)
println(client.get("$uri/store").payloadAsText())
client.close()
server.close()
} finally {
scope.cancel()
}
}The kcoap lines are the guide’s, which CI compiles and runs on the JVM; the same common code runs natively in CI’s Linux tests. This program as a whole is not compiled in CI.
Build the executable and run it:
Terminal
./gradlew linkReleaseExecutableLinuxX64
# the .kexe file to copy to the gateway
ls build/bin/linuxX64/releaseExecutable/A gateway that serves browsers adds the WebSocket listener: kcoap-transport-ktor-websocket-server with io.ktor:ktor-server-cio:3.6.1, whose CIO engine runs natively on Linux. The TCP and WebSocket example is the same code.
Keys and state on a gateway
- Pre-shared OSCORE keys need a durable
SequenceNumberStore. The Linux recipe uses POSIX calls withfsyncon the file and its directory. It is not compiled or tested on Linux yet. - EDHOC derives new keys for each session and needs no durable store. Bound the security contexts on a long-running gateway:
InMemoryContextRepositorynever evicts. - No post-quantum EDHOC on Linux native yet: ML-KEM and ML-DSA come only from
kcoap-crypto-bc, which is for the JVM and Android.
Platform notes
OpenSSL
DefaultCryptoBackend() uses cryptography-kotlin’s prebuilt OpenSSL 3 provider, linked into the executable. Updates of that OpenSSL come with kcoap’s cryptography-kotlin version.
ARM gateways
There is no linuxArm64 target yet; it is planned. On an ARM gateway with a Java 17 runtime, the JVM artifacts are today’s route. No ARM machine runs in CI.
TLS
There is no TLS on Linux native: ktor has none there, so neither a coaps+tcp client nor coaps+ws runs on the gateway. Terminate TLS in a proxy in front of it, such as stunnel or nginx’s stream module, as ADR 0010 recommends for native gateways. DTLS for coaps:// comes last.
Troubleshooting
- Could not find
dev.kcoap:…-linuxx64 - Check that
mavenCentral()is in your repositories, and that the target islinuxX64: kcoap publishes no other Linux target. Dispatchers.IOdoes not resolve- On Kotlin/Native it needs
import kotlinx.coroutines.IO.Dispatchers.Defaultworks without it. Cannot resolve '…': configure an EndpointResolver- The default resolver knows no DNS for
coap://. Use an IP address, or set a resolver inCoapClientConfig. - The program will not start on an ARM board
- The executable is x86-64 only. Use the JVM artifacts on a Java 17 runtime there.
Next steps
- The client and server guide: Observe, endpoint tuning and Q-Block for large bodies over lossy links.
- Serving browsers through the gateway: the browser guide.
- Features: what kcoap implements and how it is checked.