README.md 3.16 KB
Newer Older
Tim Stewart committed
1 2 3
tcprpc
======

4 5 6 7
A bare-bones RPC mechanism for communicating with a running Erlang
node.  Despite the name, this application defaults to setting up a
UNIX Domain Socket at `/tmp/tcprpc`.

8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

Experimental
------------

This application uses experimental support for opening UNIX Domain
Sockets and passing them to gen_tcp.  This support was reintroduced in
Erlang/OTP 19.0 as an experimental feature:

```
  OTP-13572    Application(s): erts, kernel
               Related Id(s): PR-612

               Experimental support for Unix Domain Sockets has been
               implemented. Read the sources if you want to try it
               out. Example: gen_udp:open(0,
               [{ifaddr,{local,"/tmp/socket"}}]). Documentation will
               be written after user feedback on the experimental API.
```

Also see https://github.com/erlang/otp/pull/612 for related
discussion.


Quick Start
-----------

34
You may start up a test instance quickly using rebar3:
Tim Stewart committed
35 36 37

    $ rebar3 shell

38 39
Once started, use `socat` to submit an RPC call in
Module:Function(Arg1, Arg2, ...) format:
Tim Stewart committed
40

41 42
    $ echo "erlang:system_info(cpu_topology)." \
          | socat - UNIX-CONNECT:/tmp/tcprpc
Tim Stewart committed
43 44 45 46 47
    [{processor,[{thread,{logical,0}},
                 {thread,{logical,1}},
                 {thread,{logical,2}},
                 {thread,{logical,3}}]}]

48 49 50 51 52 53 54
tcprpc will close the connection immediately after the answer has been
sent.

It would be wise to place the socket inside of a directory accessible
only to the UNIX user that should have RPC capabilities.  It is not
currently possible to control the permissions or the file mode of the
created socket.
Tim Stewart committed
55 56 57 58 59 60 61 62


Build
-----

    $ rebar3 compile


63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
Configuration
-------------

The following configuration parameters are available for the tcprpc
application:

| Parameter       | Type                  |                Default | Description                           |
|-----------------+-----------------------+------------------------+---------------------------------------|
| acceptors       | integer               |                    100 | Number of ranch acceptors to start    |
| max_connections | integer               |                   1024 | Upper limit on concurrent connections |
| ifaddr          | inet:socket_address() | {local, "/tmp/tcprpc"} | Socket interface address              |
| port            | inet:port_number()    |                      0 | Listening port                        |

The default will listen on a UNIX domain socket named `/tmp/tcprpc`:

    [
        {tcprpc, [
            {ifaddr, {local, "/tmp/tcprpc"}},
            {port, 0},
            ...
        ]}
    ].

You may also configure it for an actual TCP socket:

    [
        {tcprpc, [
            {ifaddr, {127,0,0,1}},
            {port, 5555},
            ...
        ]}
    ].

`127.0.0.1` is recommended if using TCP so that you're not exposing
the RPC mechanism to a wide audience.  However, the UNIX Domain Socket
is strongly preferred since it may be controlled via filesystem
permissions.


Tim Stewart committed
102 103 104 105 106 107
Acknowledgements
----------------

The `parse_mfa` and `args_to_terms` functions in tcprpc_protocol.erl
were taken largely from Manning's _Erlang and OTP in Action_ by Logan,
Merritt, and Carlsson.  Thanks!