2020-07-13 - russng v7.0 release on bitbucket.org.

What is RUSS?

RUSS is a protocol and framework for building service-oriented servers using UNIX/Domain sockets.

RUSS is an alternative to HTTP/web technologies for services running on UNIX/Linux.

RUSS is built on some familiar ideas:

  • orthogonal operations: execute, help, list
  • service path: /-separated list of strings identifying a service and how to get there
  • ordered list of string arguments (aka positional arguments)
  • unordered collection of string attritubes as key=value pairs (like environment variables)
  • exit/return value
  • stream I/O over file descriptors (stdin, stdout, stderr)

The benefits of using UNIX/Domain sockets are:

  • performance
  • standard part of UNIX/Linux (no kernel modules needed)
  • credentials are mediated by the OS
  • connection between independent processes (even between different users)
  • passing of descriptors between independent processes (even between different users)

More Info

Get started with RUSS v7 - Quickstart Setup.

Further information for users and developers is available in the Documentation section:

Show Me Something

First things

  • + - the area that system servers register at; usually under /var/run/russ/services
  • ruls - command line tool to list servers/services (think ls)
  • ruhelp - command line tool to get help information (think man)
  • ruexec - command line tool to execute a service
  • pyruss - Python bindings for the C API
  • rubb - manage servers/services

Listing Servers/Services

What's available?

$ ruls +

What services does the debug server provide?

$ ruls +/debug

Getting Help - Built in Man Page

How do I use the debug services?

$ ruhelp +/debug
Provides services useful for debugging.

    Generate and send characters following the RFC 864 character
    generator protocol sequence.

    Report connection information.

    Report the date and time.

/discard[/...] [--perf]
    Discard all data received from stdin. If --perf is specified,
    performance feedback is reported to stderr.

    Simple echo service: read from stdin and write back to stdout.

    Report server side environ entries.

/exit <value>
    Return with given exit value (between 0 and 255).

    Report request information.

    Report session information.

    Report service path information.

Running a Service

Try the character generator:

$ ruexec +/debug/chargen

Show "request" information (as received and sent back by the server):

$ ruexec -a X=123 -a Y=abc +/debug/request hello there world
protocol string (0010)
spath (/request)
op (execute)
opnum (2)
attrv[0] (X=123)
attrv[1] (Y=abc)
argv[0] (hello)
argv[1] (there)
argv[2] (world)

Call the daytime service:

$ ruexec +/debug/daytime
Friday, February 16, 2018 11:45:50-GMT

Call the daytime service on another machine "buddy" (ssh must work without user interaction):

$ ruexec +/ssh/buddy/+/debug/daytime
Friday, February 16, 2018 11:46:55-GMT

Call the daytime service from Python:

$ PYTHONPATH=/usr/lib/russng python2
>>> import pyruss
>>> rv, ev, out, err = pyruss.execv_wait_inouterr_timeout(1000, "+/ssh/buddy/+/debug/daytime")
>>> print out
Friday, February 16, 2018 11:48:23-GMT

Echo a message, hopping through three machines "buddy", "bobby", and "bibby" (as before, ssh must work without user interaction):

$ echo "hop hop hop" | ruexec +/ssh/buddy/+/ssh/bobby/+/ssh/bibby/+/debug/echo
hop hop hop