1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc tw=0 3 4coap-client(5) 5============== 6:doctype: manpage 7:man source: coap-client 8:man version: @PACKAGE_VERSION@ 9:man manual: coap-client Manual 10 11NAME 12----- 13coap-client, 14coap-client-gnutls, 15coap-client-mbedtls, 16coap-client-openssl, 17coap-client-notls 18- CoAP Client based on libcoap 19 20SYNOPSIS 21-------- 22*coap-client* [*-a* addr] [*-b* [num,]size] [*-e* text] [*-f* file] [*-l* loss] 23 [*-m* method] [*-o* file] [*-p* port] [*-r*] [*-s duration*] 24 [*-t* type] [*-v* num] [*-w*] [*-A* type] [*-B* seconds] 25 [*-E* oscore_conf_file[,seq_file]] [*-G* count] [*-H* hoplimit] 26 [*-K* interval] [*-L* value] [*-N*] [*-O* num,text] 27 [*-P* scheme://addr[:port]] [*-T* token] [*-U*] [*-V* num] 28 [*-X* size] 29 [[*-h* match_hint_file] [*-k* key] [*-u* user]] 30 [[*-c* certfile] [*-j* keyfile] [*-n*] [*-C* cafile] 31 [*-J* pkcs11_pin] [*-M* rpk_file] [*-R* trust_casfile]] URI 32 33For *coap-client* versions that use libcoap compiled for different 34(D)TLS libraries, *coap-client-notls*, *coap-client-gnutls*, 35*coap-client-openssl*, *coap-client-mbedtls* or *coap-client-tinydtls* may be 36available. Otherwise, *coap-client* uses the default libcoap (D)TLS support. 37 38DESCRIPTION 39----------- 40*coap-client* is a CoAP client to communicate with 6LoWPAN devices via 41the protocol CoAP (RFC 7252) using the URI given as argument on the 42command line. The URI must have the scheme 'coap', 'coap+tcp', 'coaps' or 43'coaps+tcp'. 44 45'coaps' and 'coaps+tcp' are only supported when 46coap-client is built with support for secure (D)TLS communication. 47 48If 'coaps' or 'coaps+tcp' is being used, provided the CoAP server supports PKI 49and is configured with a certificate and private key, the coap-client does not 50need to have a Pre-Shared Key (-k) or certificate (-c) configured. 51 52The URI's host part may be a DNS name, a literal IP address or a Unix domain 53name. For Unix domain names, %2F is used as the / separator to differentiate 54between the host and patch definitions. For IPv6 address references, angle 55brackets are required (c.f. EXAMPLES) to delimit the host portion of the URI. 56 57OPTIONS - General 58----------------- 59*-a* addr:: 60 The local address of the interface that has to be used. + 61 Note: Do not use this option if the interface is likely to be transient - 62 i.e. it is a tunnel interface that may come and go, as this is likely to 63 cause "No such device" errors on transmission. 64 65*-b* [num,]size:: 66 The block size to be used in GET/PUT/POST requests (value must be a 67 multiple of 16 not larger than 1024 as libcoap uses a fixed maximum 68 PDU size of 1400 bytes). If 'num' is present, the request 69 chain will start at block 'num'. When the server includes a Block2 70 option in its response to a GET request, coap-client will automatically 71 retrieve the subsequent block from the server until there are no more 72 outstanding blocks for the requested content. 73 74*-e* text:: 75 Include text as payload (use percent-encoding for non-ASCII characters). 76 77*-f* file:: 78 File to send with PUT/POST (use '-' for STDIN). 79 80*-l* list:: 81 Fail to send some datagrams specified by a comma separated list of 82 numbers or number ranges (debugging only). 83 84*-l* loss%:: 85 Randomly failed to send datagrams with the specified probability - 100% 86 all datagrams, 0% no datagrams (debugging only). 87 88*-m* method:: 89 The request method for action (get|put|post|delete), default is 'get'. 90 (Note that the string passed to *-m* is compared case-insensitive.) 91 92*-o* file:: 93 A filename to store data retrieved with GET. 94 95*-p* port:: 96 The port to send from. 97 98*-r*:: 99 Use reliable protocol (TCP or TLS). 100 101*-s* duration:: 102 Subscribe to / observe the resource specified by URI for the given 103 'duration' in seconds. 104 105*-t* type:: 106 Content format for given resource for PUT/POST. 'type' must be either 107 a numeric value reflecting a valid CoAP content format or a string 108 describing a registered format. The following registered content format 109 descriptors are supported, with alternative shortcuts given in 110 parentheses: 111 112 text/plain (plain) 113 application/link-format (link, link-format) 114 application/xml (xml) 115 application/octet-stream (binary, octet-stream) 116 application/exi (exi) 117 application/json (json) 118 application/cbor (cbor) 119 120*-v* num:: 121 The verbosity level to use (default 4, maximum is 8) for general 122 CoAP logging. 123 124*-w*:: 125 Append a newline to received data. 126 127*-A* type:: 128 Accepted media type. 'type' must be either a numeric value reflecting a 129 valid CoAP content format or a string that specifies a registered format as 130 described for option *-t*. 131 132*-B* seconds:: 133 Break operation after waiting given seconds (default is 90). 134 135*-E* oscore_conf_file[,seq_file]:: 136 'oscore_conf_file' contains OSCORE configuration. See *coap-oscore-conf*(5) 137 for definitions. Optional 'seq_file' (which is created if needed) is used to 138 save the current transmit sequence number, so on client restart sequence 139 numbers continue to increase and are not reset to prevent anti-replay 140 mechanisms being triggered. 141 142*-G* count :: 143 Repeat the Request 'count' times with a second delay between each one. 144 Must have a value between 1 and 255 inclusive. Default is '1'. 145 146*-H* hoplimit:: 147 Set the Hop Limit count to hoplimit for proxies. Must have a value between 148 1 and 255 inclusive. Default is '16'. 149 150*-K* interval:: 151 Send a ping after interval seconds of inactivity. 152 If not specified (or 0), keep-alive is disabled (default). 153 154*-L* value:: 155 Sum of one or more COAP_BLOCK_* flag values for different block handling 156 methods. Default is 1 (COAP_BLOCK_USE_LIBCOAP). 157 158 COAP_BLOCK_USE_LIBCOAP 1 159 COAP_BLOCK_SINGLE_BODY 2 160 COAP_BLOCK_TRY_Q_BLOCK 4 161 COAP_BLOCK_USE_M_Q_BLOCK 8 162 COAP_BLOCK_NO_PREEMPTIVE_RTAG 16 163 164*-N* :: 165 Send NON-confirmable message. If option *-N* is not specified, a 166 confirmable message will be sent. 167 168*-O* num,text:: 169 Add option 'num' with contents of 'text' to the request. If the text begins 170 with 0x, then the hex text (two [0-9a-f] per byte) is converted to binary 171 data. 172 173*-P* scheme://addr[:port]:: 174 Scheme, address and optional port to define how to connect to a CoAP proxy 175 (automatically adds Proxy-Uri option to request) to forward the request to. 176 Scheme is one of coap, coaps, coap+tcp and coaps+tcp. 177 178*-T* token:: 179 Define the initial starting 'token' for the request (up to 24 characters). 180 181*-U* :: 182 Never include Uri-Host or Uri-Port options. 183 184*-V* num:: 185 The verbosity level to use (default 3, maximum is 7) for (D)TLS 186 library logging. 187 188*-X* size:: 189 Maximum message size to use for TCP based connections (default is 8388864). 190 Maximum value of 2^32 -1. 191 192OPTIONS - PSK 193------------- 194(If supported by underlying (D)TLS library) 195 196*-h* match_hint_file:: 197 This is a file that contains one or more lines of received Identity Hints 198 to match to use different user identity and associated pre-shared key (PSK) 199 (comma separated) instead of the *-k key* and *-u user* options. E.g., per 200 line + 201 hint_to_match,use_user,with_key + 202 A line that starts with # is treated as a comment. + 203 Note: *-k key* and *-u user* still need to be defined for the default case in 204 case there is no match. 205 206*-k* key:: 207 Pre-shared key for the specified user identity (*-u* option also required). 208 209*-u* user:: 210 User identity to send for pre-shared key mode (*-k* option also required). 211 212OPTIONS - PKI 213------------- 214(If supported by underlying (D)TLS library) 215 216*Note:* If any one of *certfile*, *keyfile* or *cafile* is in PKCS11 URI 217naming format (pkcs11: prefix), then any remaining non PKCS11 URI file 218definitions have to be in DER, not PEM, format. Otherwise all of 219*certfile*, *keyfile* or *cafile* are in PEM format. 220 221*-c* certfile:: 222 PEM file or PKCS11 URI for the certificate. The private key can also be in 223 the PEM file, or has the same PKCS11 URI. If not, the private key is defined 224 by *-j keyfile*. 225 226*-j* keyfile:: 227 PEM file or PKCS11 URI for the private key for the certificate in *-c 228 certfile* if the parameter is different from certfile in *-c certfile*. 229 230*-n* :: 231 Disable remote peer certificate checking. 232 233*-C* cafile:: 234PEM file or PKCS11 URI for the CA certificate that was used to sign the server 235 certfile. Ideally the client certificate should be signed by the same CA so 236 that mutual authentication can take place. The contents of cafile are added 237 to the trusted store of root CAs. Using the *-C* or *-R* options will trigger 238 the validation of the server certificate unless overridden by the *-n* option. 239 240*-J* pkcs11_pin:: 241 The user pin to unlock access to the PKCS11 token. 242 243*-M* rpk_file:: 244 Raw Public Key (RPK) PEM file or PKCS11 URI that contains both PUBLIC KEY 245 and PRIVATE KEY or just EC PRIVATE KEY. (GnuTLS and TinyDTLS(PEM) support 246 only). *-C cafile* or *-R trust_casfile* are not required. 247 248*-R* trust_casfile:: 249 PEM file containing the set of trusted root CAs that are to be used to 250 validate the server certificate. Alternatively, this can point to a 251 directory containing a set of CA PEM files. The *-C cafile* CA does not have 252 to be in this list and is trusted for the validation. Using 253 *-R trust_casfile* disables common CA mutual authentication which can only 254 be done by using *-C cafile*. Using the *-C* or *-R* options will will 255 trigger the validation of the server certificate unless overridden by the 256 *-n* option. 257 258EXAMPLES 259-------- 260* Example 261---- 262coap-client coap://libcoap.net 263---- 264Query the resource '/' from server 'libcoap.net' (using the GET method). 265 266* Example 267---- 268coap-client -m get coap://[::1]/ 269---- 270Query the resource '/' on localhost using the 'GET' method to get back the 271summary information. 272 273* Example 274---- 275coap-client -m get coap://%2Fsome%2Funix%2Fdomain%2Fpath/time 276---- 277Query the resource '/time' on server listening on datagram Unix domain 278'/some/unix/domain/path' using the 'GET' method to get back the 279current time. The %2F is the hex encoding for / and indicates 280which is the 'host' definition separator and the simple / is for the path 281definition separator. 282 283* Example 284---- 285coap-client -m get coap://[::1]/.well-known/core 286---- 287Query on the resource '.well-known/core' on localhost to get back a list of 288the known resources along with their attribute definitions. 289 290* Example 291---- 292echo -n "mode=on" | coap-client -m put \ 293coap://[2001:db8:c001:f00d:221:2eff:ff00:2704]:5683/actuators/leds?color=r -f- 294---- 295Send text 'mode=on' to resource 'actuators/leds?color=r' on the endpoint with 296address '2001:db8:c001:f00d:221:2eff:ff00:2704' and port '5683'. Note that the 297port '5683' is the default port and isn't actually required in this instance. 298 299* Example 300---- 301coap-client -m put coap://[fec0::3]/ck -T 3a -t binary -f to_upload 302---- 303Put the contents of file 'to_upload' with content type 'binary' (i.e. 304application/octet-stream) into resource 'ck' on 'fec0::3' using a token of 305'3a' via the 'PUT' method. 306 307FILES 308------ 309There are no configuration files. 310 311EXIT STATUS 312----------- 313*0*:: 314 Success 315 316*1*:: 317 Failure (syntax or usage error; configuration error; document 318 processing failure; unexpected error) 319 320SEE ALSO 321-------- 322 323*coap-server*(5) and *coap-oscore-conf*(5) 324 325BUGS 326----- 327Please report bugs on the mailing list for libcoap: 328libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 329https://github.com/obgm/libcoap/issues 330 331AUTHORS 332------- 333The libcoap project <libcoap-developers@lists.sourceforge.net> 334