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] [-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
18       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

DESCRIPTION

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
30       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
35       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

OPTIONS - GENERAL

40       -a addr
41           The local address of the interface that has to be used.
42
43           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
47       -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
56       -e text
57           Include text as payload (use percent-encoding for non-ASCII
58           characters).
59
60       -f file
61           File to send with PUT/POST (use - for STDIN).
62
63       -l list
64           Fail to send some datagrams specified by a comma separated list of
65           numbers or number ranges (debugging only).
66
67       -l loss%
68           Randomly failed to send datagrams with the specified probability -
69           100% all datagrams, 0% no datagrams (debugging only).
70
71       -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
76       -o file
77           A filename to store data retrieved with GET.
78
79       -p port
80           The port to listen on.
81
82       -r
83           Use reliable protocol (TCP or TLS).
84
85       -s duration
86           Subscribe to / observe the resource specified by URI for the given
87           duration in seconds.
88
89       -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
96               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
104       -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
108       -w
109           Append a newline to received data.
110
111       -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
116       -B seconds
117           Break operation after waiting given seconds (default is 90).
118
119       -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
123       -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
127       -K interval
128           Send a ping after interval seconds of inactivity. If not specified
129           (or 0), keep-alive is disabled (default).
130
131       -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
135               COAP_BLOCK_USE_LIBCOAP  1
136               COAP_BLOCK_SINGLE_BODY  2
137
138       -N
139           Send NON-confirmable message. If option -N is not specified, a
140           confirmable message will be sent.
141
142       -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
147       -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
153       -T token
154           Define the initial starting token for the request.
155
156       -U
157           Never include Uri-Host or Uri-Port options.
158
159       -X size
160           Maximum message size to use for TCP based connections (default is
161           8388864). Maximum value of 2^32 -1.
162

OPTIONS - PSK

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

OPTIONS - PKI

188       (If supported by underlying (D)TLS library)
189
190       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
195       -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
200       -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
205       -n
206           Disable remote peer certificate checking.
207
208       -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
216       -J pkcs11_pin
217           The user pin to unlock access to the PKCS11 token.
218
219       -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
225       -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

EXAMPLES

236       •   Example
237
238           coap-client coap://coap.me
239
240       Query the resource / from server coap.me (using the GET method).
241
242       •   Example
243
244           coap-client -m get coap://[::1]/
245
246       Query the resource / on localhost using the GET method to get back the
247       summary defined attributes.
248
249       •   Example
250
251           coap-client -m get coap://[::1]/.well-known/core
252
253       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
256       •   Example
257
258           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
261       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
266       •   Example
267
268           coap-client -m put coap://[fec0::3]/ck -T 3a -t binary -f to_upload
269
270       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

FILES

275       There are no configuration files.
276

EXIT STATUS

278       0
279           Success
280
281       1
282           Failure (syntax or usage error; configuration error; document
283           processing failure; unexpected error)
284

BUGS

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

AUTHORS

291       The libcoap project <libcoap-developers@lists.sourceforge.net>
292
293
294
295coap-client 4.3.1                 01/19/2023                    COAP-CLIENT(5)
Impressum