1COAP-SERVER(5) coap-server Manual COAP-SERVER(5)
2
6 coap-server, coap-server-gnutls, coap-server-mbedtls, coap-server-
7 openssl, coap-server-notls - CoAP Server based on libcoap
8
10 coap-server [-d max] [-e] [-g group] [-l loss] [-p port] [-r] [-t] [-v
11 num] [-w [port][,secure_port]] [-A address] [-E
12 oscore_conf_file[,seq_file]] [-G group_if] [-L value] [-N] [-P
13 scheme://addr[:port],[name1[,name2..]]] [-T max_token_size] [-U type]
14 [-V num] [-X size] [[-h hint] [-i match_identity_file] [-k key] [-s
15 match_psk_sni_file] [-u user]] [[-c certfile] [-j keyfile] [-n] [-C
16 cafile] [-J pkcs11_pin] [-M rpk_file] [-R trust_casfile] [-S
17 match_pki_sni_file]]
18 For coap-server versions that use libcoap compiled for different (D)TLS
20 libraries, coap-server-notls, coap-server-gnutls, coap-server-openssl,
21 coap-server-mbedtls or coap-server-tinydtls may be available.
22 Otherwise, coap-server uses the default libcoap (D)TLS support.
23
25 coap-server is an example server for the 'Constrained Application
26 Protocol` (RFC 7252).
27
29 -d max
30 Enable support for creation of dynamic resources when doing a PUT
31 up to a limit of max. If max is reached, a 4.06 code is returned
32 until one of the dynamic resources has been deleted.
33 -e
35 Echo back the data sent with a PUT.
36 -g group
38 Join specified multicast group on start up. Note: DTLS over
39 multicast is not currently supported.
40 -l list
42 Fail to send some datagrams specified by a comma separated list of
43 numbers or number ranges (debugging only).
44 -l loss%
46 Randomly failed to send datagrams with the specified probability -
47 100% all datagrams, 0% no datagrams (debugging only).
48 -p port
50 The port on the given address will be listening for incoming
51 connections. If (D)TLS is supported, then port + 1 will also be
52 listened on for (D)TLS connections. The default port is 5683 if not
53 given any other value.
54 -r
56 Enable multicast per resource support. If enabled, only /, /async
57 and /.well-known/core are enabled for multicast requests support,
58 otherwise all resources are enabled.
59 -t
61 Track resource’s observe values so observe subscriptions can be
62 maintained over a server restart. Note: Use kill SIGUSR2 <pid> for
63 controlled shutdown.
64 -v num
66 The verbosity level to use (default 4, maximum is 8) for general
67 CoAP logging.
68 -w [port][,secure_port]
70 Enable WebSockets support support on port (WS) and/or secure_port
71 (WSS), comma separated.
72 -A address
74 The local address of the interface which the server has to listen
75 on.
76 -E oscore_conf_file[,seq_file]
78 oscore_conf_file contains OSCORE configuration. See
79 coap-oscore-conf(5) for definitions. Optional seq_file (which is
80 created if needed) is used to save the current transmit sequence
81 number, so on server restart sequence numbers continue to increase
82 and are not reset to prevent anti-replay mechanisms being
83 triggered.
84 -G group_if
86 Use this interface for listening for the multicast group. This can
87 be different from the implied interface if the -A option is used.
88 -L value
90 Sum of one or more COAP_BLOCK_* flag values for different block
91 handling methods. Default is 1 (COAP_BLOCK_USE_LIBCOAP).
92 COAP_BLOCK_USE_LIBCOAP 1
94 COAP_BLOCK_SINGLE_BODY 2
95 COAP_BLOCK_TRY_Q_BLOCK 4
96 -N
98 Send NON-confirmable message for "observe" responses. If option -N
99 is not specified, a confirmable response will be sent. Even if set,
100 every fifth response will still be sent as a confirmable response
101 (RFC 7641 requirement).
102 -P scheme://address[:port],[name1[,name2[,name3..]]]
104 Scheme, address, optional port of how to connect to the next proxy
105 server and zero or more names (comma separated) that this proxy
106 server is known by. The , (comma) is required. If there is no name1
107 or if the hostname of the incoming proxy request matches one of
108 these names, then this server is considered to be the final
109 endpoint. If scheme://address[:port] is not defined before the
110 leading , (comma) of the first name, then the ongoing connection
111 will be a direct connection. Scheme is one of coap, coaps, coap+tcp
112 and coaps+tcp.
113 -T max_token_size
115 Set the maximum token length (8-65804).
116 -U type
118 Treat address defined by -A as a Unix socket address. Type is coap
119 (using datagram), coap+tcp (using stream), coaps (DTLS using
120 datagram) or coaps+tcp (TLS using stream).
121 -V num
123 The verbosity level to use (default 3, maximum is 7) for (D)TLS
124 library logging.
125 -X size
127 Maximum message size to use for TCP based connections (default is
128 8388864). Maximum value of 2^32 -1.
129
131 (If supported by underlying (D)TLS library)
132 -h hint
134 Identity Hint to send. Default is CoAP. Zero length is no hint.
135 -i match_identiity_file
137 This is a file that contains one or more lines of Identity Hints
138 and (user) Identities to match for a different new Pre-Shared Key
139 (PSK) (comma separated) to be used. E.g., per line
140 hint_to_match,identity_to_match,use_key
142 A line that starts with # is treated as a comment.
144 Note: -k still needs to be defined for the default case.
146 Note: A match using the -s option may mean that the current
148 Identity Hint is different to that defined by -h.
149 -k key
151 Pre-shared key to use for inbound connections. This cannot be empty
152 if defined.
153 Note: if -c cafile is defined, you need to define -k key as well to
155 have the server support both PSK and PKI.
156 -s match_psk_sni_file
158 This is a file that contains one or more lines of received Subject
159 Name Identifier (SNI) to match to use a different Identity Hint and
160 associated Pre-Shared Key (PSK) (comma separated) instead of the -h
161 hint and -k key options. E.g., per line
162 sni_to_match,use_hint,with_key
164 Note: -k key still needs to be defined for the default case if
166 there is not a match.
167 Note: The associated Pre-Shared Key will get updated if there is
169 also a -i match. The update checking order is -s followed by -i.
170 -u user
172 User identity for pre-shared key mode (only used if option -P is
173 set).
174
176 (If supported by underlying (D)TLS library)
177 Note: If any one of certfile, keyfile or cafile is in PKCS11 URI naming
179 format (pkcs11: prefix), then any remaining non PKCS11 URI file
180 definitions have to be in DER, not PEM, format. Otherwise all of
181 certfile, keyfile or cafile are in PEM format.
182 -c certfile
184 PEM file or PKCS11 URI for the certificate. The private key can
185 also be in the PEM file, or has the same PKCS11 URI. If not, the
186 private key is defined by -j keyfile.
187 Note: if -k key is defined, you need to define -c certfile as well
189 to have the server support both PSK and PKI.
190 -j keyfile
192 PEM file or PKCS11 URI for the private key for the certificate in
193 -c certfile if the parameter is different from certfile in -c
194 certfile.
195 -n
197 Disable remote peer certificate checking. This gives clients the
198 ability to use PKI, but without any defined certificates.
199 -C cafile
201 PEM file or PKCS11 URI that contains a list of one or more CAs that
202 are to be passed to the client for the client to determine what
203 client certificate to use. Normally, this list of CAs would be the
204 root CA and and any intermediate CAs. Ideally the server
205 certificate should be signed by the same CA so that mutual
206 authentication can take place. The contents of cafile are added to
207 the trusted store of root CAs. Using the -C or -R options will will
208 trigger the validation of the client certificate unless overridden
209 by the -n option.
210 -J pkcs11_pin
212 The user pin to unlock access to the PKCS11 token.
213 -M
215 Raw Public Key (RPK) PEM file or PKCS11 URI that contains both
216 PUBLIC KEY and PRIVATE KEY or just EC PRIVATE KEY. (GnuTLS and
217 TinyDTLS(PEM) support only). -C cafile or -R trust_casfile are not
218 required.
219 -R trust_casfile
221 PEM file containing the set of trusted root CAs that are to be used
222 to validate the client certificate. Alternatively, this can point
223 to a directory containing a set of CA PEM files. The -C cafile CA
224 does not have to be in this list and is trusted for the validation.
225 Using -R trust_casfile disables common CA mutual authentication
226 which can only be done by using -C cafile. Using the -C or -R
227 options will will trigger the validation of the server certificate
228 unless overridden by the -n option.
229 -S match_pki_sni_file
231 This option denotes a file that contains one or more lines of
232 Subject Name Identifier (SNI) to match for new certificate File and
233 new CA File (comma separated) to be used. E.g., entry per line
234 sni_to_match,new_cert_file,new_ca_file
236 A line that starts with # is treated as a comment.
238 Note: -c certfile and -C cafile still needs to be defined for the
240 default case
241
243 • Example
244 coap-server -A ::1
246 Let the server listen on localhost (port 5683) for UDP/TCP.
248 • Example
250 coap-server -A ::1 -k mysecretKey -h myhint
252 Let the server listen on localhost (port 5683 for UDP/TCP and port 5684
254 for DTLS/TLS) with the server set up for PSK authentication if the
255 client uses coaps:// or coaps+tcp://.
256 • Example
258 coap-server -A ::1 -k mysecretKey -h myhint -p 13011
260 The same, except the UDP/TCP listening port is 13011 and the DTLS/TLS
262 listening port is 13012 (and not the default ports 5683 and 5684).
263 • Example
265 coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5
267 The listening address is set to 2001:db8:81a8:0:6ef0:dead:feed:beef and
269 the verbosity level is set to 5.
270 • Example
272 coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02::FD
274 Set listening address to 2001:db8:81a8:0:6ef0:dead:feed:beef and join
276 the All CoAP Nodes multicast group FF02::FD.
277
279 There are no configuration files.
280
282 0
283 Success
284 1
286 Failure (syntax or usage error; configuration error; document
287 processing failure; unexpected error)
288
290 coap-client(5) and coap-oscore-conf(5)
291
293 Please report bugs on the mailing list for libcoap:
294 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
295 https://github.com/obgm/libcoap/issues
296
298 The libcoap project <libcoap-developers@lists.sourceforge.net>
299coap-server 4.3.4 10/09/2023 COAP-SERVER(5)