1COAP-SERVER(5)                coap-server Manual                COAP-SERVER(5)
2
3
4

NAME

6       coap-server, coap-server-gnutls, coap-server-mbedtls, coap-server-
7       openssl, coap-server-notls - CoAP Server based on libcoap
8

SYNOPSIS

10       coap-server [-d max] [-e] [-g group] [-G group_if] [-l loss] [-p port]
11       [-r] [-v num] [-A address] [-L value] [-N] [-P
12       scheme://addr[:port],[name1[,name2..]]] [-X size] [[-h hint] [-i
13       match_identity_file] [-k key] [-s match_psk_sni_file] [-u user]] [[-c
14       certfile] [-j keyfile] [-n] [-C cafile] [-J pkcs11_pin] [-M rpk_file]
15       [-R trust_casfile] [-S match_pki_sni_file]]
16
17       For coap-server versions that use libcoap compiled for different (D)TLS
18       libraries, coap-server-notls, coap-server-gnutls, coap-server-openssl,
19       coap-server-mbedtls or coap-server-tinydtls may be available.
20       Otherwise, coap-server uses the default libcoap (D)TLS support.
21

DESCRIPTION

23       coap-server is an example server for the 'Constrained Application
24       Protocol` (RFC 7252).
25

OPTIONS - GENERAL

27       -d max
28           Enable support for creation of dynamic resources when doing a PUT
29           up to a limit of max. If max is reached, a 4.06 code is returned
30           until one of the dynamic resources has been deleted.
31
32       -e
33           Echo back the data sent with a PUT.
34
35       -g group
36           Join specified multicast group on start up.  Note: DTLS over
37           multicast is not currently supported.
38
39       -G group_if
40           Use this interface for listening for the multicast group. This can
41           be different from the implied interface if the -A option is used.
42
43       -l list
44           Fail to send some datagrams specified by a comma separated list of
45           numbers or number ranges (debugging only).
46
47       -l loss%
48           Randomly failed to send datagrams with the specified probability -
49           100% all datagrams, 0% no datagrams (debugging only).
50
51       -p port
52           The port on the given address will be listening for incoming
53           connections. If (D)TLS is supported, then port + 1 will also be
54           listened on for (D)TLS connections. The default port is 5683 if not
55           given any other value.
56
57       -r
58           Enable multicast per resource support. If enabled, only /, /async
59           and /.well-known/core are enabled for multicast requests support,
60           otherwise all resources are enabled.
61
62       -v num
63           The verbosity level to use (default 3, maximum is 9). Above 7,
64           there is increased verbosity in GnuTLS and OpenSSL logging.
65
66       -A address
67           The local address of the interface which the server has to listen
68           on.
69
70       -L value
71           Sum of one or more COAP_BLOCK_* flag values for different block
72           handling methods. Default is 1 (COAP_BLOCK_USE_LIBCOAP).
73
74               COAP_BLOCK_USE_LIBCOAP  1
75               COAP_BLOCK_SINGLE_BODY  2
76
77       -N
78           Send NON-confirmable message for "observe" responses. If option -N
79           is not specified, a confirmable response will be sent. Even if set,
80           every fifth response will still be sent as a confirmable response
81           (RFC 7641 requirement).
82
83       -P scheme://address[:port],[name1[,name2[,name3..]]]
84           Scheme, address, optional port of how to connect to the next proxy
85           server and zero or more names (comma separated) that this proxy
86           server is known by. The , (comma) is required. If there is no name1
87           or if the hostname of the incoming proxy request matches one of
88           these names, then this server is considered to be the final
89           endpoint. If scheme://address[:port] is not defined before the
90           leading , (comma) of the first name, then the ongoing connection
91           will be a direct connection. Scheme is one of coap, coaps, coap+tcp
92           and coaps+tcp.
93
94       -X size
95           Maximum message size to use for TCP based connections (default is
96           8388864). Maximum value of 2^32 -1.
97

OPTIONS - PSK

99       (If supported by underlying (D)TLS library)
100
101       -h hint
102           Identity Hint to send. Default is CoAP. Zero length is no hint.
103
104       -i match_identiity_file
105           This is a file that contains one or more lines of Identity Hints
106           and (user) Identities to match for a different new Pre-Shared Key
107           (PSK) (comma separated) to be used. E.g., per line
108
109           hint_to_match,identity_to_match,use_key
110
111           A line that starts with # is treated as a comment.
112
113           Note: -k still needs to be defined for the default case.
114
115           Note: A match using the -s option may mean that the current
116           Identity Hint is different to that defined by -h.
117
118       -k key
119           Pre-shared key to use for inbound connections. This cannot be empty
120           if defined.
121
122           Note: if -c cafile is defined, you need to define -k key as well to
123           have the server support both PSK and PKI.
124
125       -s match_psk_sni_file
126           This is a file that contains one or more lines of received Subject
127           Name Identifier (SNI) to match to use a different Identity Hint and
128           associated Pre-Shared Key (PSK) (comma separated) instead of the -h
129           hint and -k key options. E.g., per line
130
131           sni_to_match,use_hint,with_key
132
133           Note: -k key still needs to be defined for the default case if
134           there is not a match.
135
136           Note: The associated Pre-Shared Key will get updated if there is
137           also a -i match. The update checking order is -s followed by -i.
138
139       -u user
140           User identity for pre-shared key mode (only used if option -P is
141           set).
142

OPTIONS - PKI

144       (If supported by underlying (D)TLS library)
145
146       Note: If any one of certfile, keyfile or cafile is in PKCS11 URI naming
147       format (pkcs11: prefix), then any remaining non PKCS11 URI file
148       definitions have to be in DER, not PEM, format. Otherwise all of
149       certfile, keyfile or cafile are in PEM format.
150
151       -c certfile
152           PEM file or PKCS11 URI for the certificate. The private key can
153           also be in the PEM file, or has the same PKCS11 URI. If not, the
154           private key is defined by -j keyfile.
155
156           Note: if -k key is defined, you need to define -c certfile as well
157           to have the server support both PSK and PKI.
158
159       -j keyfile
160           PEM file or PKCS11 URI for the private key for the certificate in
161           -c certfile if the parameter is different from certfile in -c
162           certfile.
163
164       -n
165           Disable remote peer certificate checking. This gives clients the
166           ability to use PKI, but without any defined certificates.
167
168       -C cafile
169           PEM file or PKCS11 URI that contains a list of one or more CAs that
170           are to be passed to the client for the client to determine what
171           client certificate to use. Normally, this list of CAs would be the
172           root CA and and any intermediate CAs. Ideally the server
173           certificate should be signed by the same CA so that mutual
174           authentication can take place. The contents of cafile are added to
175           the trusted store of root CAs. Using the -C or -R options will will
176           trigger the validation of the client certificate unless overridden
177           by the -n option.
178
179       -J pkcs11_pin
180           The user pin to unlock access to the PKCS11 token.
181
182       -M
183           Raw Public Key (RPK) PEM file or PKCS11 URI that contains both
184           PUBLIC KEY and PRIVATE KEY or just EC PRIVATE KEY. (GnuTLS and
185           TinyDTLS(PEM) support only).  -C cafile or -R trust_casfile are not
186           required.
187
188       -R trust_casfile
189           PEM file containing the set of trusted root CAs that are to be used
190           to validate the client certificate. Alternatively, this can point
191           to a directory containing a set of CA PEM files. The -C cafile CA
192           does not have to be in this list and is trusted for the validation.
193           Using -R trust_casfile disables common CA mutual authentication
194           which can only be done by using -C cafile. Using the -C or -R
195           options will will trigger the validation of the server certificate
196           unless overridden by the -n option.
197
198       -S match_pki_sni_file
199           This option denotes a file that contains one or more lines of
200           Subject Name Identifier (SNI) to match for new certificate File and
201           new CA File (comma separated) to be used. E.g., entry per line
202
203           sni_to_match,new_cert_file,new_ca_file
204
205           A line that starts with # is treated as a comment.
206
207           Note: -c certfile and -C cafile still needs to be defined for the
208           default case
209

EXAMPLES

211       •   Example
212
213           coap-server -A ::1
214
215       Let the server listen on localhost (port 5683) for UDP/TCP.
216
217       •   Example
218
219           coap-server -A ::1 -k mysecretKey -h myhint
220
221       Let the server listen on localhost (port 5683 for UDP/TCP and port 5684
222       for DTLS/TLS) with the server set up for PSK authentication if the
223       client uses coaps:// or coaps+tcp://.
224
225       •   Example
226
227           coap-server -A ::1 -k mysecretKey -h myhint -p 13011
228
229       The same, except the UDP/TCP listening port is 13011 and the DTLS/TLS
230       listening port is 13012 (and not the default ports 5683 and 5684).
231
232       •   Example
233
234           coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5
235
236       The listening address is set to 2001:db8:81a8:0:6ef0:dead:feed:beef and
237       the verbosity level is set to 5.
238
239       •   Example
240
241           coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02::FD
242
243       Set listening address to 2001:db8:81a8:0:6ef0:dead:feed:beef and join
244       the All CoAP Nodes multicast group FF02::FD.
245

FILES

247       There are no configuration files.
248

EXIT STATUS

250       0
251           Success
252
253       1
254           Failure (syntax or usage error; configuration error; document
255           processing failure; unexpected error)
256

BUGS

258       Please report bugs on the mailing list for libcoap:
259       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
260       https://github.com/obgm/libcoap/issues
261

AUTHORS

263       The libcoap project <libcoap-developers@lists.sourceforge.net>
264
265
266
267coap-server 4.3.1                 01/19/2023                    COAP-SERVER(5)
Impressum