COAP-SERVER(5)

📦
version 4.3.5 · 12 versions
, in ubuntu stonking

🌸 COAP-SERVER(5) 🌸

okay so welcome to the coap-server manual, bestie 💖 this is the CoAP Server based on libcoap and we are going to get into every single flag without losing a crumb. no cap, all the details are staying. 🫶

✨ NAME ✨

Meet the whole squad:

  • coap-server
  • coap-server-gnutls
  • coap-server-mbedtls
  • coap-server-openssl
  • coap-server-notls

they are all CoAP Server based on libcoap. periodt. 💅

🦋 SYNOPSIS 🦋

coap-server [-a priority] [-b max_block_size] [-d max] [-e] [-f
scheme://addr[:port] [-g group] [-l loss] [-p port] [-q
tls_engine_conf_file] [-r] [-t] [-v num] [-w [port][,secure_port]] [-A
address] [-E oscore_conf_file[,seq_file]] [-G group_if] [-L value] [-N]
[-P scheme://addr[:port],[name1[,name2..]]] [-T max_token_size] [-U
type] [-V num] [-X size] [[-h hint] [-i match_identity_file] [-k key]
[-s match_psk_sni_file] [-u user] [-2]] [[-c certfile] [-j keyfile] [-n]
[-C cafile] [-J pkcs11_pin] [-M rpk_file] [-R trust_casfile] [-S
match_pki_sni_file]]

for coap-server versions that use libcoap compiled for different (D)TLS libraries, you might also see coap-server-notls, coap-server-gnutls, coap-server-openssl, coap-server-mbedtls or coap-server-tinydtls available. otherwise, coap-server uses the default libcoap (D)TLS support. slay. ✨

💖 DESCRIPTION 💖

coap-server is the example server for the Constrained Application Protocol (RFC 7252). that’s the whole vibe check, bestie. 🦋

🌸 OPTIONS - GENERAL 🌸

  • -a priority — send logging output to syslog at priority level, and that level is 0-7. cute and numeric. 🎀
  • -b max_block_size — the maximum block size the server supports, in bytes. the valid glow-up values are 16, 32, 64, 128, 256, 512 or 1024. 💅
  • -d max — enable support for creating dynamic resources when someone does a PUT, up to a limit of max. if max is reached, a 4.06 code is returned until one of the dynamic resources has been deleted. so yes, there’s a whole little resource economy happening. 💀
  • -e — echo back the data sent with a PUT. it’s giving “say it back.” 🫶
  • -f scheme://address[:port] — act as a reverse proxy where scheme, address and the optional port define how to connect to the internal server. scheme is one of coap, coaps, coap+tcp, coaps+tcp, coap+ws, and coaps+ws. http(s) is not currently supported. this option can be repeated to provide multiple internal servers that are round-robin load balanced. obsessed with a balanced roster. 🌈
  • -g group — join the specified multicast group on start up. note: DTLS over multicast is not currently supported. sad but true. 😭
  • -l list — fail to send some datagrams specified by a comma separated list of numbers or number ranges. this is debugging only. iykyk. 🔥
  • -l loss% — randomly fail to send datagrams with the specified probability. 100% means all datagrams fail, 0% means no datagrams fail. this is also debugging only. dramatic but on purpose. 💀
  • -p port — the port on the given address will be listening for incoming connections. if (D)TLS is supported, then port + 1 will also be listened on for (D)TLS connections. the default port is 5683 if not given any other value. iconic default behavior. 👑
  • -q tls_engine_conf_file — tls_engine_conf_file contains TLS ENGINE configuration. only OpenSSL is currently supported. see coap-tls-engine-conf(5) for definitions. periodt. 🎀
  • -r — enable multicast per resource support. if enabled, only /, /async and /.well-known/core are enabled for multicast requests support; otherwise all resources are enabled. pick your multicast main characters wisely. 🌟
  • -t — track resource’s observe values so observe subscriptions can be maintained over a server restart. note: use kill SIGUSR2 <pid> for controlled shutdown. bestie, write that down. 🫶
  • -v num — the verbosity level to use for general CoAP logging. default is 4, maximum is 8. loud and proud. 🔥
  • -w [port][,secure_port] — enable WebSockets support on port (WS) and/or secure_port (WSS), comma separated. secure and non-secure can absolutely coexist. 💅
  • -A address — the local address of the interface which the server has to listen on. very “be where you say you’ll be” of it. 🦋
  • -E oscore_conf_file[,seq_file] — oscore_conf_file contains OSCORE configuration. see coap-oscore-conf(5) for definitions. the optional seq_file (which is created if needed) is used to save the current transmit sequence number, so on server restart sequence numbers continue to increase and are not reset, preventing anti-replay mechanisms from being triggered. no resetting the timeline, bestie. ⏳
  • -G group_if — use this interface for listening for the multicast group. this can be different from the implied interface if the -A option is used. interface multitasking. 🌈
  • -L value — sum of one or more COAP_BLOCK_* flag values for different block handling methods. default is 1 (COAP_BLOCK_USE_LIBCOAP). the flag lineup is:
    • COAP_BLOCK_USE_LIBCOAP — 1
    • COAP_BLOCK_SINGLE_BODY — 2
    • COAP_BLOCK_TRY_Q_BLOCK — 4
    • COAP_BLOCK_STLESS_BLOCK2 — 64
    • COAP_BLOCK_NOT_RANDOM_BLOCK1 — 128

yes, STLESS is exactly how it’s written. we respect the spelling. 💅

  • -N — send NON-confirmable message for "observe" responses. if option -N is not specified, a confirmable response will be sent. even if set, every fifth response will still be sent as a confirmable response (RFC 7641 requirement). the fifth one said “not me being confirmable.” 😭
  • -P scheme://address[:port],[name1[,name2[,name3..]]] — scheme, address and optional port for how to connect to the next proxy server, plus zero or more names (comma separated) that this proxy server is known by. the , (comma) is required. if there is no name1 or if the hostname of the incoming proxy request matches one of these names, then this server is considered to be the final endpoint. if scheme://address[:port] is not defined before the leading , (comma) of the first name, then the ongoing connection will be a direct connection. scheme is one of coap, coaps, coap+tcp, coaps+tcp, coap+ws, and coaps+ws. http and https are not currently supported. this option can be repeated to provide multiple upstream servers that are round-robin load balanced. very “tag ur proxy besties.” 🫶
  • -T max_token_size — set the maximum token length. valid range is 8-65804. big token energy. 🎀
  • -U type — treat the address defined by -A as a Unix socket address. type is coap (using datagram), coap+tcp (using stream), coaps (DTLS using datagram) or coaps+tcp (TLS using stream). choose your transport, bestie. 🌈
  • -V num — the verbosity level to use for (D)TLS library logging. default is 3, maximum is 7. secure but chatty. 🔥
  • -X size — maximum message size to use for TCP based connections. default is 8388864. maximum value is 2^32 -1. enormous. iconic. slay. 👑

🎀 OPTIONS - PSK 🎀

(If supported by underlying (D)TLS library) — okay so keep that in mind, bestie. 💖

  • -h hint — Identity Hint to send. default is CoAP. zero length is no hint. no hint, no problem. 🦋
  • -i match_identiity_file — this is a file that contains one or more lines of Identity Hints and (user) Identities to match for a different new Pre-Shared Key (PSK) (comma separated) to be used. e.g., per line:
hint_to_match,identity_to_match,use_key

a line that starts with # is treated as a comment. note: -k still needs to be defined for the default case. note: a match using the -s option may mean that the current Identity Hint is different to that defined by -h. matchmaking but for keys. 💅

  • -k key — Pre-shared key to use for inbound connections. this cannot be empty if defined. if the key begins with 0x, then the hex text (two [0-9a-f] per byte) is converted to binary data. note: if -c cafile is defined, you need to define -k key as well to have the server support both PSK and PKI. both, not either-or. 🫶
  • -s match_psk_sni_file — this is a file that contains one or more lines of received Subject Name Identifier (SNI) to match to use a different Identity Hint and associated Pre-Shared Key (PSK) (comma separated) instead of the -h hint and -k key options. e.g., per line:
sni_to_match,use_hint,with_key

note: -k key still needs to be defined for the default case if there is not a match. note: the associated Pre-Shared Key will get updated if there is also a -i match. the update checking order is -s followed by -i. order matters, bestie. ⭐

  • -u user — user identity for pre-shared key mode (only used if option -P is set). very situational, very valid. 💖
  • -2 — use EC-JPAKE negotiation (if supported). fancy negotiation behavior. 🎀

👑 OPTIONS - PKI 👑

(If supported by underlying (D)TLS library) — again, keep that in your notes. 💜

note: if any one of certfile, keyfile or cafile is in PKCS11 URI naming format (pkcs11: prefix), then any remaining non PKCS11 URI file definitions have to be in DER, not PEM, format. otherwise all of certfile, keyfile or cafile are in PEM format. no mixing and matching without consequences. 🫶

  • -c certfile — PEM file or PKCS11 URI for the certificate. the private key can also be in the PEM file, or has the same PKCS11 URI. if not, the private key is defined by -j keyfile. note: if -k key is defined, you need to define -c certfile as well to have the server support both PSK and PKI. 💅
  • -j keyfile — PEM file or PKCS11 URI for the private key for the certificate in -c certfile if the parameter is different from certfile in -c certfile. very “same but separate” of it. 🎀
  • -n — disable remote peer certificate checking. this gives clients the ability to use PKI, but without any defined certificates. lowkey chaotic, but that’s what it says. 😭
  • -C cafile — PEM file or PKCS11 URI that contains a list of one or more CAs that are to be passed to the client for the client to determine what client certificate to use. normally, this list of CAs would be the root CA and any intermediate CAs. ideally the server certificate should be signed by the same CA so that mutual authentication can take place. the contents of cafile are added to the trusted store of root CAs. using the -C or -R options will trigger the validation of the client certificate unless overridden by the -n option. trust chain drama, but make it secure. 🔥
  • -J pkcs11_pin — the user pin to unlock access to the PKCS11 token. unlock the token, bestie. 🔑✨
  • -M (shown as rpk_file in the synopsis) — Raw Public Key (RPK) PEM file or PKCS11 URI that contains both PUBLIC KEY and PRIVATE KEY or just EC PRIVATE KEY. (GnuTLS and TinyDTLS(PEM) support only). -C cafile or -R trust_casfile are not required. raw key energy. 💅
  • -R trust_casfile — PEM file containing the set of trusted root CAs that are to be used to validate the client certificate. alternatively, this can point to a directory containing a set of CA PEM files. the -C cafile CA does not have to be in this list and is trusted for the validation. using -R trust_casfile disables common CA mutual authentication, which can only be done by using -C cafile. using the -C or -R options will trigger the validation of the client certificate unless overridden by the -n option. very “choose your trust circle” behavior. 🌈
  • -S match_pki_sni_file — this option denotes a file that contains one or more lines of Subject Name Identifier (SNI) to match for new certificate File and new CA File (comma separated) to be used. e.g., entry per line:
sni_to_match,new_cert_file,new_ca_file

a line that starts with # is treated as a comment. note: -c certfile and -C cafile still needs to be defined for the default case. okay bestie, that’s the PKI section holding it down. 💖

✨ EXAMPLES ✨

okay bestie, real talk — these are the glow-up examples, the ones you're actually gonna type 💅

  • Example
coap-server -A ::1

Let the server listen on localhost (port 5683) for UDP/TCP. that's it. that's the whole vibe 🌸

  • Example
coap-server -A ::1 -k mysecretKey -h myhint

Let the server listen on localhost (port 5683 for UDP/TCP and port 5684 for DTLS/TLS) with the server set up for PSK authentication if the client uses coaps:// or coaps+tcp://. so like, secure mode unlocked 🔐✨

  • Example
coap-server -A ::1 -k mysecretKey -h myhint -p 13011

The same, except the UDP/TCP listening port is 13011 and the DTLS/TLS listening port is 13012 (and not the default ports 5683 and 5684). moving day, new ports, same energy 🎀

  • Example
coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5

The listening address is set to 2001:db8:81a8:0:6ef0:dead:feed:beef and the verbosity level is set to 5. the address is literally eating, no cap 👑

  • Example
coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02::FD

Set listening address to 2001:db8:81a8:0:6ef0:dead:feed:beef and join the All CoAP Nodes multicast group FF02::FD. it's giving "we're in the group chat now" 🫶

  • Example
coap-server -P, -A ::1

Let the server listen on localhost (port 5683) for UDP/TCP, as well as accept any CoAP proxy requests and directly respond to them. main character proxy energy fr fr 💫

  • Example
coap-server -P coap://upstream-proxy, -A ::1

Let the server listen on localhost (port 5683) for UDP/TCP, and then open an upstream coap session to upstream-proxy for proxying onwards the CoAP client's request. passing the message along like a loyal bestie 🦋

📁 FILES 📁

There are no configuration files.

so yes bestie — nothing to edit, nothing to lose, no config file to ghost you. iconic minimalism 💜

🚪 EXIT STATUS 🚪

  • 0 — Success. slay, it worked ✨
  • 1 — Failure (syntax or usage error; configuration error; document processing failure; unexpected error). 😭 the full sadness combo, don't take it personally

👀 SEE ALSO 👀

coap-client(5) and coap-oscore-conf(5) — go read the whole friend group, iykyk 💖

💀 BUGS 💀

Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs.

Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes.

like genuinely, if something's cursed, tell them — bug reports are self-care and PRs are a love language 🧚‍♀️

👑 AUTHORS 👑

The libcoap project <libcoap-developers@lists.sourceforge.net>

alright bestie, that's the whole page 🎀 this was coap-server 4.3.5, dated 08/24/2026, and it's literally COAP-SERVER(5) — go forth, run your server, and remember: verbosity level 5 is a personality trait 💅🔥

📦 where this page comes from