From 5fe188abc31eae9a516c71dee61fa51633378c5c Mon Sep 17 00:00:00 2001 From: juhlig Date: Tue, 21 May 2019 09:21:34 +0200 Subject: Add docs for local sockets --- doc/src/guide/listeners.asciidoc | 17 +++++++++++++++++ doc/src/manual/ranch.asciidoc | 2 +- doc/src/manual/ranch.get_addr.asciidoc | 21 ++++++++++++++++++--- doc/src/manual/ranch.get_port.asciidoc | 6 +++++- doc/src/manual/ranch_tcp.asciidoc | 7 +++++-- doc/src/manual/ranch_transport.asciidoc | 9 ++++++++- 6 files changed, 54 insertions(+), 8 deletions(-) diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc index 24fb455..94552ba 100644 --- a/doc/src/guide/listeners.asciidoc +++ b/doc/src/guide/listeners.asciidoc @@ -160,6 +160,23 @@ We recommend the use of port rewriting for systems with a single server, and load balancing for systems with multiple servers. Documenting these solutions is however out of the scope of this guide. +=== Listening on a UNIX Domain socket + +On UNIX systems, it is also possible to use Ranch to listen on a UNIX +domain socket by specifying `{local, SocketFile}` for the `ip` socket +option. In this case, the port must be set to 0 or omitted. The given +file must not exist: Ranch must be able to create it. + +.Starting a listener for TCP connections on a UNIX Domain socket + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, #{socket_opts => [ + {ip, {local, "/tmp/ranch_echo.sock"}}, + {port, 0} + ]}, echo_protocol, [] +). + === Accepting connections on an existing socket If you want to accept connections on an existing socket, you can write diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc index aa4a63f..549bb78 100644 --- a/doc/src/manual/ranch.asciidoc +++ b/doc/src/manual/ranch.asciidoc @@ -40,7 +40,7 @@ Options: Introspection: -* link:man:ranch:get_addr(3)[ranch:get_addr(3)] - Get the listening port and IP +* link:man:ranch:get_addr(3)[ranch:get_addr(3)] - Get the listening address * link:man:ranch:get_port(3)[ranch:get_port(3)] - Get the listening port * link:man:ranch:info(3)[ranch:info(3)] - Overview of Ranch listeners * link:man:ranch:procs(3)[ranch:procs(3)] - Retrieve pids from a listener diff --git a/doc/src/manual/ranch.get_addr.asciidoc b/doc/src/manual/ranch.get_addr.asciidoc index 3938347..7c48b3c 100644 --- a/doc/src/manual/ranch.get_addr.asciidoc +++ b/doc/src/manual/ranch.get_addr.asciidoc @@ -2,7 +2,7 @@ == Name -ranch:get_addr - Get the listening port and IP +ranch:get_addr - Get the listening address == Description @@ -11,9 +11,11 @@ ranch:get_addr - Get the listening port and IP get_addr(Ref :: ranch:ref()) -> {IP :: inet:ip_address(), Port :: inet:port_number()} + | {local, SocketFile :: binary()} + | {undefined, undefined} ---- -Get the listening port and IP. +Get the listening address. == Arguments @@ -23,11 +25,18 @@ The listener name. == Return value -The address of the listener is returned as a tuple. +The address of the listener is returned as a tuple of the form +`{IP, Port}` when listening on a network interface, or +`{local, SocketFile}` when listening on a UNIX Domain socket. +When the listener is suspended, `{undefined, undefined}` will +be returned. The IP address is the IP of the network interface the socket is bound to. +The socket file is the path of a file on your system the +socket is bound to. + == Examples .Get the listening port and IP @@ -36,6 +45,12 @@ socket is bound to. {IP, Port} = ranch:get_addr(example). ---- +.Get the listening UNIX Domain socket file +[source,erlang] +---- +{local, SocketFile} = ranch:get_addr(example). +---- + == See also link:man:ranch:start_listener(3)[ranch:start_listener(3)], diff --git a/doc/src/manual/ranch.get_port.asciidoc b/doc/src/manual/ranch.get_port.asciidoc index 0de4a3a..5c5563e 100644 --- a/doc/src/manual/ranch.get_port.asciidoc +++ b/doc/src/manual/ranch.get_port.asciidoc @@ -9,7 +9,7 @@ ranch:get_port - Get the listening port [source,erlang] ---- get_port(Ref :: ranch:ref()) - -> Port :: inet:port_number() + -> Port :: inet:port_number() | undefined ---- Get the listening port. @@ -28,6 +28,10 @@ The listener name. The listening port is returned. +When the listener is suspended or using a UNIX Domain +socket instead of a network interface, `undefined` +will be returned. + == Examples .Get the listening port diff --git a/doc/src/manual/ranch_tcp.asciidoc b/doc/src/manual/ranch_tcp.asciidoc index d01b262..bee73a7 100644 --- a/doc/src/manual/ranch_tcp.asciidoc +++ b/doc/src/manual/ranch_tcp.asciidoc @@ -32,7 +32,7 @@ opt() = {backlog, non_neg_integer()} | {high_watermark, non_neg_integer()} | inet | inet6 - | {ip, inet:ip_address()} + | {ip, inet:ip_address() | inet:local_address()} | {ipv6_v6only, boolean()} | {keepalive, boolean()} | {linger, {boolean(), non_neg_integer()}} @@ -108,7 +108,10 @@ Set up the socket for IPv6. ip:: -Interface to listen on. Listen on all interfaces by default. +Interface to listen on. Listen on all network interfaces by default. + +On UNIX systems, it is also possible to use a UNIX Domain +socket file by specifying `{local, SocketFile}`. ipv6_v6only (false):: diff --git a/doc/src/manual/ranch_transport.asciidoc b/doc/src/manual/ranch_transport.asciidoc index b7ec6d2..2d59e82 100644 --- a/doc/src/manual/ranch_transport.asciidoc +++ b/doc/src/manual/ranch_transport.asciidoc @@ -138,12 +138,16 @@ Return the name of the transport. ---- peername(Socket :: socket()) -> {ok, {inet:ip_address(), inet:port_number()}} - | {error, atom()}. + | {local, binary()} | {error, atom()}. ---- Return the address and port number for the other end of the connection. +For UNIX Domain sockets the return value will be +`{local, PeerSocket}`, with `PeerSocket` typically +an empty binary. + === recv [source,erlang] @@ -250,6 +254,9 @@ sockname(Socket :: socket()) Return the address and port number for the local end of the connection. +For UNIX Domain sockets the return value will be +`{local, SocketFile}`. + == Exports The following function can be used when implementing -- cgit v1.2.3