'\" t
.\"     Title: coap-client
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/14/2022
.\"    Manual: coap-client Manual
.\"    Source: coap-client 4.2.1
.\"  Language: English
.\"
.TH "COAP\-CLIENT" "5" "05/14/2022" "coap\-client 4\&.2\&.1" "coap\-client Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap-client \- CoAP Client based on libcoap
.SH "SYNOPSIS"
.sp
\fBcoap\-client\fR [\fB\-a\fR addr] [\fB\-b\fR [num,]size] [\fB\-e\fR text] [\fB\-f\fR file] [\fB\-l\fR loss] [\fB\-m\fR method] [\fB\-o\fR file] [\fB\-p\fR port] [\fB\-r\fR] [\fB\-s duration\fR] [\fB\-t\fR type] [\fB\-v\fR num] [\fB\-A\fR type] [\fB\-B\fR seconds] [\fB\-K\fR interval] [\fB\-N\fR] [\fB\-O\fR num,text] [\fB\-P\fR addr[:port]] [\fB\-T\fR token] [\fB\-U\fR] [[\fB\-k\fR key] [\fB\-u\fR user]] [[\fB\-c\fR certfile] [\fB\-C\fR cafile] [\fB\-R\fR root_cafile]] URI
.SH "DESCRIPTION"
.sp
\fBcoap\-client\fR is a CoAP client to communicate with 6LoWPAN devices via the protocol CoAP (RFC 7252) using the URI given as argument on the command line\&. The URI must have the scheme \fIcoap\fR, \fIcoap+tcp\fR, \fIcoaps\fR or \fIcoaps+tcp\fR\&. \fIcoaps\fR and \fIcoaps+tcp\fR are only supported when coap\-client is built with support for secure (D)TLS communication\&.
.sp
If \fIcoaps\fR or \fIcoap+tcp\fR is being used, provided the CoAP server supports PKI and is configured with a Certificate and Private Key, the coap\-client does not need to have a Pre\-Shared Key (\-k) or Certificate (\-c) configured\&.
.sp
The URI\(cqs host part may be a DNS name or a literal IP address\&. Note that, for IPv6 address references, angle brackets are required (c\&.f\&. EXAMPLES)\&.
.SH "OPTIONS \- GENERAL"
.PP
\fB\-a\fR addr
.RS 4
The local address of the interface that has to be used\&.
.RE
.PP
\fB\-b\fR [num,]size
.RS 4
The block size to be used in GET/PUT/POST requests (value must be a multiple of 16 not larger than 1024 as libcoap uses a fixed maximum PDU size of 1400 bytes)\&. If
\fInum\fR
is present, the request chain will start at block
\fInum\fR\&. When the server includes a Block2 option in its response to a GET request, coap\-client will automatically retrieve the subsequent block from the server until there are no more outstanding blocks for the requested content\&.
.RE
.PP
\fB\-e\fR text
.RS 4
Include text as payload (use percent\-encoding for non\-ASCII characters)\&.
.RE
.PP
\fB\-f\fR file
.RS 4
File to send with PUT/POST (use
\fI\-\fR
for STDIN)\&.
.RE
.PP
\fB\-l\fR list
.RS 4
Fail to send some datagrams specified by a comma separated list of numbers or number ranges (debugging only)\&.
.RE
.PP
\fB\-l\fR loss%
.RS 4
Randomly failed to send datagams with the specified probability \- 100% all datagrams, 0% no datagrams (debugging only)\&.
.RE
.PP
\fB\-m\fR method
.RS 4
The request method for action (get|put|post|delete), default is
\fIget\fR\&. (Note that the string passed to
\fB\-m\fR
is compared case\-insensitive\&.)
.RE
.PP
\fB\-o\fR file
.RS 4
A filename to store data retrieved with GET\&.
.RE
.PP
\fB\-p\fR port
.RS 4
The port to listen on\&.
.RE
.PP
\fB\-r\fR
.RS 4
Use reliable protocol (TCP or TLS)\&.
.RE
.PP
\fB\-s\fR duration
.RS 4
Subscribe to / observe the resource specified by URI for the given
\fIduration\fR
in seconds\&.
.RE
.PP
\fB\-t\fR type
.RS 4
Content format for given resource for PUT/POST\&.
\fItype\fR
must be either a numeric value reflecting a valid CoAP content format or a string describing a registered format\&. The following registered content format descriptors are supported, with alternative shortcuts given in parentheses:
.sp
.if n \{\
.RS 4
.\}
.nf
text/plain (plain)
application/link\-format (link, link\-format)
application/xml (xml)
application/octet\-stream (binary, octet\-stream)
application/exi (exi)
application/json (json)
application/cbor (cbor)
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-v\fR num
.RS 4
The verbosity level to use (default 3, maximum is 9)\&. Above 7, there is increased verbosity in GnuTLS and OpenSSL logging\&.
.RE
.PP
\fB\-A\fR type
.RS 4
Accepted media type\&.
\fItype\fR
must be either a numeric value reflecting a valid CoAP content format or a string that specifies a registered format as described for option
\fB\-t\fR\&.
.RE
.PP
\fB\-B\fR seconds
.RS 4
Break operation after waiting given seconds (default is 90)\&.
.RE
.PP
\fB\-K\fR interval
.RS 4
Send a ping after interval seconds of inactivity\&. If not specified (or 0), keep\-alive is disabled (default)\&.
.RE
.PP
\fB\-N\fR
.RS 4
Send NON\-confirmable message\&. If option
\fB\-N\fR
is not specified, a confirmable message will be sent\&.
.RE
.PP
\fB\-O\fR num,text
.RS 4
Add option
\fInum\fR
with contents of
\fItext\fR
to the request\&. If the text begins with 0x, then the hex text is converted to binary data\&.
.RE
.PP
\fB\-P\fR addr[:port]
.RS 4
Address (and port) for proxy to use (automatically adds Proxy\-Uri option to request)\&.
.RE
.PP
\fB\-T\fR token
.RS 4
Include the
\fItoken\fR
to the request\&.
.RE
.PP
\fB\-U\fR
.RS 4
Never include Uri\-Host or Uri\-Port options\&.
.RE
.SH "OPTIONS \- PSK"
.sp
(If supported by underlying (D)TLS library)
.PP
\fB\-k\fR key
.RS 4
Pre\-shared key for the specified user (\fB\-u\fR
option also required)\&.
.RE
.PP
\fB\-u\fR user
.RS 4
User identity for pre\-shared key mode (\fB\-k\fR
option also required)\&.
.RE
.SH "OPTIONS \- PKI"
.sp
(If supported by underlying (D)TLS library)
.PP
\fB\-c\fR certfile
.RS 4
Use the specified PEM file which contains the CERTIFICATE and PRIVATE KEY information\&.
.RE
.PP
\fB\-C\fR cafile
.RS 4
PEM file containing the CA Certificate that was used to sign the certfile defined using
\fB\-c certfile\fR\&. This will trigger the validation of the server certificate\&. If certfile is self\-signed (as defined by
\fB\-c certfile\fR), then you need to have on the command line the same filename for both the certfile and cafile (as in
\fB\-c certfile \-C certfile\fR) to trigger validation\&.
.RE
.PP
\fB\-R\fR root_cafile
.RS 4
PEM file containing the set of trusted root CAs that are to be used to validate the server certificate\&. The
\fB\-C cafile\fR
does not have to be in this list and is "trusted" for the verification\&. Alternatively, this can point to a directory containing a set of CA PEM files\&.
.RE
.SH "EXAMPLES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Example
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
coap\-client coap://coap\&.me
.fi
.if n \{\
.RE
.\}
.sp
Query the resource \fI/\fR from server \fIcoap\&.me\fR (using the GET method)\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Example
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
coap\-client \-m get coap://[::1]/
.fi
.if n \{\
.RE
.\}
.sp
Query the resource \fI/\fR on localhost using the \fIGET\fR method to get back the summary defined attributes\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Example
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
coap\-client \-m get coap://[::1]/\&.well\-known/core
.fi
.if n \{\
.RE
.\}
.sp
Query on the resource \fI\&.well\-known/core\fR on localhost to get back a list of the known resources along with their attribute definitions\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Example
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
echo \-n "mode=on" | coap\-client \-m put \e
coap://[2001:db8:c001:f00d:221:2eff:ff00:2704]:5683/actuators/leds?color=r \-f\-
.fi
.if n \{\
.RE
.\}
.sp
Send text \fImode=on\fR to resource \fIactuators/leds?color=r\fR on the endpoint with address \fI2001:db8:c001:f00d:221:2eff:ff00:2704\fR and port \fI5683\fR\&. Note that the port \fI5683\fR is the default port and isn\(cqt actually required in this instance\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Example
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
coap\-client \-m put coap://[fec0::3]/ck \-T 3a \-t binary \-f to_upload
.fi
.if n \{\
.RE
.\}
.sp
Put the contents of file \fIto_upload\fR with content type \fIbinary\fR (i\&.e\&. application/octet\-stream) into resource \fIck\fR on \fIfec0::3\fR using a token of \fI3a\fR via the \fIPUT\fR method\&.
.SH "FILES"
.sp
There are no configuration files\&.
.SH "EXIT STATUS"
.PP
\fB0\fR
.RS 4
Success
.RE
.PP
\fB1\fR
.RS 4
Failure (syntax or usage error; configuration error; document processing failure; unexpected error)
.RE
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>