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