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