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