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] [-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 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
23 coap-server is an example server for the 'Constrained Application
24 Protocol` (RFC 7252).
25
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 -e
33 Echo back the data sent with a PUT.
34 -g group
36 Join specified multicast group on start up. Note: DTLS over
37 multicast is not currently supported.
38 -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 -l list
44 Fail to send some datagrams specified by a comma separated list of
45 numbers or number ranges (debugging only).
46 -l loss%
48 Randomly failed to send datagrams with the specified probability -
49 100% all datagrams, 0% no datagrams (debugging only).
50 -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 -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 -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 -A address
67 The local address of the interface which the server has to listen
68 on.
69 -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 COAP_BLOCK_USE_LIBCOAP 1
75 COAP_BLOCK_SINGLE_BODY 2
76 -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 -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 -X size
95 Maximum message size to use for TCP based connections (default is
96 8388864). Maximum value of 2^32 -1.
97
99 (If supported by underlying (D)TLS library)
100 -h hint
102 Identity Hint to send. Default is CoAP. Zero length is no hint.
103 -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 hint_to_match,identity_to_match,use_key
110 A line that starts with # is treated as a comment.
112 Note: -k still needs to be defined for the default case.
114 Note: A match using the -s option may mean that the current
116 Identity Hint is different to that defined by -h.
117 -k key
119 Pre-shared key to use for inbound connections. This cannot be empty
120 if defined.
121 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 -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 sni_to_match,use_hint,with_key
132 Note: -k key still needs to be defined for the default case if
134 there is not a match.
135 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 -u user
140 User identity for pre-shared key mode (only used if option -P is
141 set).
142
144 (If supported by underlying (D)TLS library)
145 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 -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 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 -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 -n
165 Disable remote peer certificate checking. This gives clients the
166 ability to use PKI, but without any defined certificates.
167 -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 -J pkcs11_pin
180 The user pin to unlock access to the PKCS11 token.
181 -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 -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 -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 sni_to_match,new_cert_file,new_ca_file
204 A line that starts with # is treated as a comment.
206 Note: -c certfile and -C cafile still needs to be defined for the
208 default case
209
211 • Example
212 coap-server -A ::1
214 Let the server listen on localhost (port 5683) for UDP/TCP.
216 • Example
218 coap-server -A ::1 -k mysecretKey -h myhint
220 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 • Example
226 coap-server -A ::1 -k mysecretKey -h myhint -p 13011
228 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 • Example
233 coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5
235 The listening address is set to 2001:db8:81a8:0:6ef0:dead:feed:beef and
237 the verbosity level is set to 5.
238 • Example
240 coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02::FD
242 Set listening address to 2001:db8:81a8:0:6ef0:dead:feed:beef and join
244 the All CoAP Nodes multicast group FF02::FD.
245
247 There are no configuration files.
248
250 0
251 Success
252 1
254 Failure (syntax or usage error; configuration error; document
255 processing failure; unexpected error)
256
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
263 The libcoap project <libcoap-developers@lists.sourceforge.net>
264coap-server 4.3.1 01/19/2023 COAP-SERVER(5)