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