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 - CoAP Server based on libcoap 18 19SYNOPSIS 20-------- 21*coap-server* [*-d* max] [*-e*] [*-g* group] [*-G* group_if] [*-l* loss] 22 [*-p* port] [*-v* num] [*-A* address] [*-L* value] [*-N*] 23 [*-P* scheme://addr[:port],name1[,name2..]] 24 [[*-h* hint] [*-i* match_identity_file] [*-k* key] 25 [*-s* match_psk_sni_file] [*-u* user]] 26 [[*-c* certfile] [*-j* keyfile] [*-n*] [*-C* cafile] 27 [*-J* pkcs11_pin] [*-M* rpk_file] [*-R* trust_casfile] 28 [*-S* match_pki_sni_file]] 29 30For *coap-server* versions that use libcoap compiled for different 31(D)TLS libraries, *coap-server-notls*, *coap-server-gnutls*, 32*coap-server-openssl*, *coap-server-mbedtls* or *coap-server-tinydtls* may be 33available. Otherwise, *coap-server* uses the default libcoap (D)TLS support. 34 35DESCRIPTION 36----------- 37*coap-server* is an example server for the 'Constrained Application Protocol` 38(RFC 7252). 39 40OPTIONS - General 41----------------- 42*-d* max:: 43 Enable support for creation of dynamic resources when doing a PUT up to a 44 limit of 'max'. If 'max' is reached, a 4.06 code is returned until one of 45 the dynamic resources has been deleted. 46 47*-e* :: 48 Echo back the data sent with a PUT. 49 50*-g* group:: 51 Join specified multicast 'group' on start up. 52 *Note:* DTLS over multicast is not currently supported. 53 54*-G* group_if:: 55 Use this interface for listening for the multicast group. This can be 56 different from the implied interface if the *-A* option is used. 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*-v* num:: 73 The verbosity level to use (default 3, maximum is 9). Above 7, there is 74 increased verbosity in GnuTLS and OpenSSL logging. 75 76*-A* address:: 77 The local address of the interface which the server has to listen on. 78 79*-L* value:: 80 Sum of one or more COAP_BLOCK_* flag values for different block handling 81 methods. Default is 1 (COAP_BLOCK_USE_LIBCOAP). 82 83 COAP_BLOCK_USE_LIBCOAP 1 84 COAP_BLOCK_SINGLE_BODY 2 85 86*-N* :: 87 Send NON-confirmable message for "observe" responses. If option *-N* is 88 not specified, a confirmable response will be sent. Even if set, every 89 fifth response will still be sent as a confirmable response 90 (RFC 7641 requirement). 91 92*-P* scheme://address[:port],name1[,name2[,name3..]] :: 93 Scheme, address, optional port of how to connect to the next proxy server 94 and one or more names (comma separated) that this proxy server is known by. 95 If the hostname of the incoming proxy request matches one of these names, 96 then this server is considered to be the final endpoint. If 97 scheme://address[:port] is not defined before the leading , (comma) of the 98 first name, then the ongoing connection will be a direct connection. 99 Scheme is one of coap, coaps, coap+tcp and coaps+tcp. 100 101 102OPTIONS - PSK 103------------- 104(If supported by underlying (D)TLS library) 105 106*-h* hint:: 107 Identity Hint to send. Default is *CoAP*. Zero length is no hint. 108 109*-i* match_identiity_file:: 110 This is a file that contains one or more lines of Identity Hints and (user) 111 Identities to match for a different new Pre-Shared Key (PSK) (comma 112 separated) to be used. E.g., per line + 113 hint_to_match,identity_to_match,use_key + 114 A line that starts with # is treated as a comment. + 115 Note: *-k* still needs to be defined for the default case. + 116 Note: A match using the *-s* option may mean that the current Identity Hint 117 is different to that defined by *-h*. 118 119*-k* key:: 120 Pre-shared key to use for inbound connections. This cannot be empty if 121 defined. + 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 Name 127 Identifier (SNI) to match to use a different Identity Hint and associated 128 Pre-Shared Key (PSK) (comma separated) instead of the *-h hint* and 129 *-k key* options. E.g., per line + 130 sni_to_match,use_hint,with_key + 131 Note: *-k key* still needs to be defined for the default case if there is 132 not a match. + 133 Note: The associated Pre-Shared Key will get updated if there is also a *-i* 134 match. The update checking order is *-s* followed by *-i*. 135 136*-u* user :: 137 User identity for pre-shared key mode (only used if option *-P* is set). 138 139OPTIONS - PKI 140------------- 141(If supported by underlying (D)TLS library) 142 143*Note:* If any one of *certfile*, *keyfile* or *cafile* is in PKCS11 URI 144naming format (pkcs11: prefix), then any remaining non PKCS11 URI file 145definitions have to be in DER, not PEM, format. Otherwise all of 146*certfile*, *keyfile* or *cafile* are in PEM format. 147 148*-c* certfile:: 149 PEM file or PKCS11 URI for the certificate. The private key can also be in 150 the PEM file, or has the same PKCS11 URI. If not, the private key is defined 151 by *-j keyfile*. + 152 Note: if *-k key* is defined, you need to define *-c certfile* as well to 153 have the server support both PSK and PKI. 154 155*-j* keyfile:: 156 PEM file or PKCS11 URI for the private key for the certificate in *-c 157 certfile* if the parameter is different from certfile in *-c certfile*. 158 159*-n* :: 160 Disable remote peer certificate checking. This gives clients the ability to 161 use PKI, but without any defined certificates. 162 163*-C* cafile:: 164 PEM file or PKCS11 URI that contains a list of one or more CAs that are to 165 be passed to the client for the client to determine what client certificate 166 to use. Normally, this list of CAs would be the root CA and and any 167 intermediate CAs. Ideally the server certificate should be signed by the 168 same CA so that mutual authentication can take place. The contents of 169 *cafile* are added to the trusted store of root CAs. Using the *-C* or *-R* 170 options will will trigger the validation of the client certificate unless 171 overridden by the *-n* option. 172 173*-J* pkcs11_pin:: 174 The user pin to unlock access to the PKCS11 token. 175 176*-M*:: 177 Raw Public Key (RPK) PEM file or PKCS11 URI that contains both PUBLIC KEY 178 and PRIVATE KEY or just EC PRIVATE KEY. (GnuTLS and TinyDTLS(PEM) support 179 only). *-C cafile* or *-R trust_casfile* are not required. 180 181*-R* trust_casfile:: 182 PEM file containing the set of trusted root CAs that are to be used to 183 validate the client certificate. Alternatively, this can point to a 184 directory containing a set of CA PEM files. The *-C cafile* CA does not have 185 to be in this list and is trusted for the validation. Using 186 *-R trust_casfile* disables common CA mutual authentication which can only 187 be done by using *-C cafile*. Using the *-C* or *-R* options will will 188 trigger the validation of the server certificate unless overridden by the 189 *-n* option. 190 191*-S* match_pki_sni_file:: 192 This option denotes a file that contains one or more lines of Subject Name 193 Identifier (SNI) to match for new certificate File and new CA File (comma 194 separated) to be used. E.g., entry per line + 195 sni_to_match,new_cert_file,new_ca_file + 196 A line that starts with # is treated as a comment. + 197 Note: *-c certfile* and *-C cafile* still needs to be defined for the 198 default case 199 200EXAMPLES 201-------- 202* Example 203---- 204coap-server -A ::1 205---- 206Let the server listen on localhost (port '5683') for UDP/TCP. 207 208* Example 209---- 210coap-server -A ::1 -k mysecretKey -h myhint 211---- 212Let the server listen on localhost (port '5683' for UDP/TCP and port '5684' for 213DTLS/TLS) with the server set up for PSK authentication if the client uses 214coaps:// or coaps+tcp://. 215 216* Example 217---- 218coap-server -A ::1 -k mysecretKey -h myhint -p 13011 219---- 220The same, except the UDP/TCP listening port is '13011' and the DTLS/TLS 221listening port is '13012' (and not the default ports '5683' and '5684'). 222 223* Example 224---- 225coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5 226---- 227The listening address is set to '2001:db8:81a8:0:6ef0:dead:feed:beef' and the 228verbosity level is set to '5'. 229 230* Example 231---- 232coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02::FD 233---- 234Set listening address to '2001:db8:81a8:0:6ef0:dead:feed:beef' and join the 235All CoAP Nodes multicast group 'FF02::FD'. 236 237FILES 238------ 239There are no configuration files. 240 241EXIT STATUS 242----------- 243*0*:: 244 Success 245 246*1*:: 247 Failure (syntax or usage error; configuration error; document 248 processing failure; unexpected error) 249 250BUGS 251----- 252Please report bugs on the mailing list for libcoap: 253libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 254https://github.com/obgm/libcoap/issues 255 256AUTHORS 257------- 258The libcoap project <libcoap-developers@lists.sourceforge.net> 259