summaryrefslogtreecommitdiff
path: root/doc/localservice.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/localservice.html')
-rw-r--r--doc/localservice.html151
1 files changed, 0 insertions, 151 deletions
diff --git a/doc/localservice.html b/doc/localservice.html
deleted file mode 100644
index af7aafb..0000000
--- a/doc/localservice.html
+++ /dev/null
@@ -1,151 +0,0 @@
-<html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta http-equiv="Content-Language" content="en" />
- <title>s6-networking: what is a local service</title>
- <meta name="Description" content="s6-networking: what is a local service" />
- <meta name="Keywords" content="s6-networking local service s6-ipcserver" />
- <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
- </head>
-<body>
-
-<p>
-<a href="index.html">s6-networking</a><br />
-<a href="http://skarnet.org/software/">Software</a><br />
-<a href="http://skarnet.org/">skarnet.org</a>
-</p>
-
-<h1> Local services </h1>
-
-<p>
- A <em>local service</em> is a daemon that listens to incoming connections
-on a Unix domain socket. Clients of the service are programs connecting to
-this socket: the daemon performs operations on their behalf.
-</p>
-
-<p>
- The service is called <em>local</em> because it is not accessible to
-clients from the network.
-</p>
-
-<p>
- A widely known example of a local service is the <tt>syslogd</tt> daemon.
-On most implementations, it listens to the <tt>/dev/log</tt> socket.
-Its clients connect to it and send their logs via the socket. The
-<tt>openlog()</tt> function is just a wrapper arround the <tt>connect()</tt>
-system call, the <tt>syslog()</tt> function a wrapper around <tt>write()</tt>,
-and so on.
-</p>
-
-<h2> Benefits </h2>
-
-<h3> Privileges </h3>
-
-<p>
- The most important benefit of a local service is that it permits
-<strong>controlled privilege gains without using setuid programs</strong>.
-The daemon is run as user S; a client running as user C and connecting to
-the daemon asks it to perform operations: those will be done as user S.
-</p>
-
-<p>
- Standard Unix permissions on the listening socket can be used to implement
-some basic access control: to restrict access to clients belonging to group
-G, change the socket to user S and group G, and give it 0420 permissions.
-This is functionally equivalent to the basic access control for setuid
-programs: a program having user S, group G and permissions 4750 will be
-executable by group G and run with S rights.
-</p>
-
-<p>
- But modern systems implement the
-<a href="http://www.superscript.com/ucspi-ipc/getpeereid.html">getpeereid()</a>
-system call or library function. This function allows the server to know the
-client's credentials: so fine-grained access control is possible. On those
-systems, <strong>local services can do as much authentication as setuid programs,
-in a much more controlled environment</strong>.
-</p>
-
-<h3> fd-passing </h3>
-
-<p>
- The most obvious difference between a local service and a network service
-is that a local service does not serve network clients. But local services
-have another nice perk: while network services usually only provide you
-with a single channel (a TCP or UDP socket) of communication between the
-client and the server, forcing you to multiplex your data into that
-channel, local services allow you to have as many
-communication channels as you want.
-</p>
-
-<p>
-(The SCTP transport layer provides a way for network services to use
-several communication channels. Unfortunately, it is not widely deployed
-yet, and a lot of network services still depend on TCP.)
-</p>
-
-<p>
- The <em>fd-passing</em> mechanism is Unix domain socket black magic
-that allows one peer of the socket to send open file descriptors to
-the other peer. So, if the server opens a pipe and sends one end of
-this pipe to a client via this mechanism, there is effectively a
-socket <em>and</em> a pipe between the client and the server.
-</p>
-
-<h2> UCSPI </h2>
-
-<p>
- The <a href="http://cr.yp.to/proto/ucspi.txt">UCSPI</a> protocol
-is an easy way of abstracting clients and servers from the network.
-A server written as a UCSPI server, just as it can be run
-under inetd or s6-tcpserver, can be run under
-<a href="s6-ipcserver.html">s6-ipcserver</a>: choose a socket
-location and you have a local service.
-</p>
-
-<p>
- Fine-grained access control can be added by inserting
-<a href="s6-ipcserver-access.html">s6-ipcserver-access</a> in
-your server command line after s6-ipcserver.
-</p>
-
-<p>
- A client written as an UCSPI client, i.e. assuming it has descriptor
-6 (resp. 7) open and reading from (resp. writing to) the server socket,
-can be run under <a href="s6-ipcclient.html">s6-ipcclient</a>.
-</p>
-
-<h2> Use in skarnet.org software </h2>
-
-<p>
- skarnet.org libraries often use a separate process to handle
-asynchronicity and background work in a way that's invisible to
-the user. Among them are:
-</p>
-
-<ul>
- <li> <a href="http://skarnet.org/software/s6/s6-ftrigrd.html">s6-ftrigrd</a>,
-managing the reception of notifications and only waking up the client process
-when the notification pattern matches a regular expression. </li>
- <li> <a href="http://skarnet.org/software/s6/libs6lock/s6lockd.html">s6lockd</a>,
-handling time-constrained lock acquisition on client behalf. </li>
- <li> <a href="http://skarnet.org/software/s6-dns/skadns/skadnsd.html">skadnsd</a>,
-performing asynchronous DNS queries and only waking up the client process
-when an answer arrives. </li>
-</ul>
-
-<p>
- Those processes are usually spawned from a client, via the corresponding
-<tt>*_startf*()</tt> library call. But they can also be spawned from a
-s6-ipcserver program in a local service configuration. In both cases, they
-need an additional control channel to be passed from the server to
-the client: the main socket is used for synchronous commands from the client
-to the server and their answers, whereas the additional channel, which is
-now implemented as a socket as well (but created by the server on-demand
-and not bound to a local path), is used for asynchronous
-notifications from the server to the client. The fd-passing mechanism
-is used to transfer the additional channel from the server to the client.
-</p>
-
-</body>
-</html>