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