core-lightning/doc/lightning-connect.7

.TH "LIGHTNING-CONNECT" "7" "" "" "lightning-connect"
.SH NAME
lightning-connect - Command for connecting to another lightning node
.SH SYNOPSIS

\fBconnect\fR \fIid\fR [\fIhost\fR \fIport\fR]

.SH DESCRIPTION

The \fBconnect\fR RPC command establishes a new connection with another
node in the Lightning Network\.


\fIid\fR represents the target node’s public key\. As a convenience, \fIid\fR may
be of the form \fIid@host\fR or \fIid@host:port\fR\. In this case, the \fIhost\fR and
\fIport\fR parameters must be omitted\.


\fIhost\fR is the peer’s hostname or IP address\.


If not specified, the \fIport\fR defaults to 9735\.


If \fIhost\fR is not specified (or doesn't work), the connection will be attempted to an IP
belonging to \fIid\fR obtained through gossip with other already connected
peers\.
This can fail if your C-lightning node is a fresh install that has not
connected to any peers yet (your node has no gossip yet),
or if the target \fIid\fR is a fresh install that has no channels yet
(nobody will gossip about a node until it has one published channel)\.


If \fIhost\fR begins with a \fI/\fR it is interpreted as a local path, and the
connection will be made to that local socket (see \fBbind-addr\fR in
\fBlightningd-config\fR(5))\.


Connecting to a node is just the first step in opening a channel with
another node\. Once the peer is connected a channel can be opened with
\fBlightning-fundchannel\fR(7)\.

.SH RETURN VALUE

On success, an object is returned, containing:

.RS
.IP \[bu]
\fBid\fR (pubkey): the peer we connected to
.IP \[bu]
\fBfeatures\fR (hex): BOLT 9 features bitmap offered by peer
.IP \[bu]
\fBdirection\fR (string): Whether they initiated connection or we did (one of "in", "out")
.IP \[bu]

\fBaddress\fR (object): Address information (mainly useful if \fBdirection\fR is \fIout\fR):

.RS
.IP \[bu]
\fBtype\fR (string): Type of connection (\fItorv2\fR/\fItorv3\fR only if \fBdirection\fR is \fIout\fR) (one of "local socket", "ipv4", "ipv6", "torv2", "torv3")

.RE

If \fBtype\fR is "local socket":

.RS
.IP \[bu]
\fBsocket\fR (string): socket filename

.RE

If \fBtype\fR is "ipv4", "ipv6", "torv2" or "torv3":

.RS
.IP \[bu]
\fBaddress\fR (string): address in expected format for \fBtype\fR
.IP \[bu]
\fBport\fR (u16): port number

.RE


.RE
.SH ERRORS

On failure, one of the following errors will be returned:

.nf
.RS
{ "code" : 400, "message" : "Unable to connect, no address known for peer" }


.RE

.fi

If some addresses are known but connecting to all of them failed, the message
will contain details about the failures:

.nf
.RS
{ "code" : 401, "message" : "..." }


.RE

.fi

If the given parameters are wrong:

.nf
.RS
{ "code" : -32602, "message" : "..." }


.RE

.fi
.SH AUTHOR

Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
Felix \fI<fixone@gmail.com\fR> is the original author of this manpage\.

.SH SEE ALSO

\fBlightning-fundchannel\fR(7), \fBlightning-listpeers\fR(7),
\fBlightning-listchannels\fR(7), \fBlightning-disconnect\fR(7)

.SH RESOURCES

Main web site: \fIhttps://github.com/ElementsProject/lightning\fR

\" SHA256STAMP:47e5ec1e2d3cca8a40bd9b93faff9fd226b4fd481ab4c3c81d67f15dc6f8b839