1COAP-CLIENT(5)                coap-client Manual                COAP-CLIENT(5)
2
3
4

NAME

6       coap-client, coap-client-gnutls, coap-client-mbedtls, coap-client-
7       openssl, coap-client-notls - CoAP Client based on libcoap
8

SYNOPSIS

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
17       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

DESCRIPTION

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
29       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
34       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

OPTIONS - GENERAL

39       -a addr
40           The local address of the interface that has to be used.
41
42           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
46       -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
55       -e text
56           Include text as payload (use percent-encoding for non-ASCII
57           characters).
58
59       -f file
60           File to send with PUT/POST (use - for STDIN).
61
62       -l list
63           Fail to send some datagrams specified by a comma separated list of
64           numbers or number ranges (debugging only).
65
66       -l loss%
67           Randomly failed to send datagrams with the specified probability -
68           100% all datagrams, 0% no datagrams (debugging only).
69
70       -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
75       -o file
76           A filename to store data retrieved with GET.
77
78       -p port
79           The port to listen on.
80
81       -r
82           Use reliable protocol (TCP or TLS).
83
84       -s duration
85           Subscribe to / observe the resource specified by URI for the given
86           duration in seconds.
87
88       -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
95               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
103       -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
107       -w
108           Append a newline to received data.
109
110       -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
115       -B seconds
116           Break operation after waiting given seconds (default is 90).
117
118       -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
122       -K interval
123           Send a ping after interval seconds of inactivity. If not specified
124           (or 0), keep-alive is disabled (default).
125
126       -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
130               COAP_BLOCK_USE_LIBCOAP  1
131               COAP_BLOCK_SINGLE_BODY  2
132
133       -N
134           Send NON-confirmable message. If option -N is not specified, a
135           confirmable message will be sent.
136
137       -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
142       -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
148       -T token
149           Define the initial starting token for the request.
150
151       -U
152           Never include Uri-Host or Uri-Port options.
153

OPTIONS - PSK

155       (If supported by underlying (D)TLS library)
156
157       -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
163           hint_to_match,use_user,with_key
164
165           A line that starts with # is treated as a comment.
166
167           Note: -k key and -u user still need to be defined for the default
168           case in case there is no match.
169
170       -k key
171           Pre-shared key for the specified user identity (-u option also
172           required).
173
174       -u user
175           User identity to send for pre-shared key mode (-k option also
176           required).
177

OPTIONS - PKI

179       (If supported by underlying (D)TLS library)
180
181       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
186       -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
191       -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
196       -n
197           Disable remote peer certificate checking.
198
199       -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
207       -J pkcs11_pin
208           The user pin to unlock access to the PKCS11 token.
209
210       -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
216       -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

EXAMPLES

227       •   Example
228
229           coap-client coap://coap.me
230
231       Query the resource / from server coap.me (using the GET method).
232
233       •   Example
234
235           coap-client -m get coap://[::1]/
236
237       Query the resource / on localhost using the GET method to get back the
238       summary defined attributes.
239
240       •   Example
241
242           coap-client -m get coap://[::1]/.well-known/core
243
244       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
247       •   Example
248
249           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
252       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
257       •   Example
258
259           coap-client -m put coap://[fec0::3]/ck -T 3a -t binary -f to_upload
260
261       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

FILES

266       There are no configuration files.
267

EXIT STATUS

269       0
270           Success
271
272       1
273           Failure (syntax or usage error; configuration error; document
274           processing failure; unexpected error)
275

BUGS

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

AUTHORS

282       The libcoap project <libcoap-developers@lists.sourceforge.net>
283
284
285
286coap-client 4.3.0                 01/20/2022                    COAP-CLIENT(5)
Impressum