diff options
| -rw-r--r-- | doc/index.html | 5 | ||||
| -rw-r--r-- | doc/s6-fdholder-transferdumpc.html | 9 | ||||
| -rw-r--r-- | doc/socket-activation.html | 113 |
3 files changed, 121 insertions, 6 deletions
diff --git a/doc/index.html b/doc/index.html index 7fcf79a..b830cb9 100644 --- a/doc/index.html +++ b/doc/index.html @@ -67,6 +67,8 @@ supervision that might help you understand the basics. <a href="libs6/ftrigr.html">ftrigr library</a> do exactly?</li> <li> How to run a s6-svscan-based supervision tree <a href="s6-svscan-not-1.html">without replacing init</a> </li> <li> How to <a href="s6-svscan-1.html">replace init</a> </li> +<li> How to perform <a href="socket-activation.html">socket activation +with s6</a> </li> </ul> <hr /> @@ -332,8 +334,7 @@ traditional init system for Linux. </li> <li> <a href="http://upstart.ubuntu.com/">Upstart</a> is a well-known init system for Linux, with complete service management, that comes with the Ubuntu distribution. It includes a coffee machine and the kitchen sink.</li> - <li> Because Upstart wasn't complex enough, someone came up with -<a href="systemd.html">systemd</a>, which is a problem in its own category. </li> + <li> <a href="systemd.html">systemd</a> is a problem in its own category. </li> <li> The various BSD flavors have their own style of <a href="http://www.freebsd.org/doc/handbook/boot-init.html">init</a>. </li> <li> MacOS X has its own init spaghetti monster called diff --git a/doc/s6-fdholder-transferdumpc.html b/doc/s6-fdholder-transferdumpc.html index 7bd6aa0..aea7181 100644 --- a/doc/s6-fdholder-transferdumpc.html +++ b/doc/s6-fdholder-transferdumpc.html @@ -71,11 +71,12 @@ takes care of all the plumbing. </li> requires special authorizations. Make sure the s6-fdholderd instances are <a href="s6-fdholderd.html#configuration">configured</a> to accept dump-getting and dump-setting requests from your client. </li> - <li> The point of the + <li> A typical use case of <a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a> and -s6-fdholder-transferdumpc programs is to move a set of fds from one -daemon to another, for instance in the event that the first one has to -to shut down for an upgrade. </li> +s6-fdholder-transferdumpc is when the main fd-holding daemon needs to +upgrade, or restart for some reason. Transferring the file descriptors +into another, temporary fd-holding daemon instance allows it to +restart without losing the descriptors. </li> </ul> </body> diff --git a/doc/socket-activation.html b/doc/socket-activation.html new file mode 100644 index 0000000..b2e726a --- /dev/null +++ b/doc/socket-activation.html @@ -0,0 +1,113 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: socket activation</title> + <meta name="Description" content="s6: socket activation" /> + <meta name="Keywords" content="s6 socket activation fd-holding client server socket fd passing" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> How do I perform socket activation with s6 ? </h1> + +<p> + First, it's important to realize that you don't <em>need</em> +socket activation. It's a marketing word used by systemd +advocates that mixes a couple useful architecture concepts and several +horrible ideas, for a very minor speed benefit. Read +<a href="http://skarnet.org/cgi-bin/archive.cgi?2:mss:423:oanakciaccabjicoagef">this mail</a> +and +<a href="http://forums.gentoo.org/viewtopic-t-994548-postdays-0-postorder-asc-start-25.html#7581522">this +post</a> for details. +</p> + +<ul> + <li> s6 <em>will not</em> help you implement super-servers in process 1, +because doing so is bad engineering. +However, it <em>will</em> help you set up super-servers. The +<a href="s6-ipcserver.html">s6-ipcserver</a> +program, for Unix domain sockets, as well as the +<a href="http://skarnet.org/software/s6-networking/s6-tcpserver4.html">s6-tcpserver4</a> and +<a href="http://skarnet.org/software/s6-networking/s6-tcpserver6.html">s6-tcpserver6</a> +programs, for TCP INET domain sockets (available in the +<a href="http://skarnet.org/software/s6-networking/">s6-networking</a> +package) are super-servers you can use to +your heart's content. They are even wrappers around simpler programs, +and you can use their components in the way you choose: bind sockets, +drop privileges, accept connections from clients, it's all about what you +write in your command line. Super-servers are a good thing; using process 1 +to act as a super-server is not. s6 provides you with the tools to get +the good without the bad. </li> + <li> s6 <em>will not</em> help you run all your services before their +dependencies are met, because doing so is <em>very</em> bad engineering. +However, it <em>will</em> provide you with: + <ul> + <li> a reliable logging infrastructure, that makes sure your services +never lose logs: +<a href="s6-log.html">s6-log</a>, in conjunction with +<a href="s6-supervise.html">s6-supervise</a> and +<a href="s6-svscan.html">s6-svscan</a>. </li> + <li> ways to open your sockets and bind them as early as you want in +your boot process, and make them accept client connections later: +<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>, +<a href="http://skarnet.org/software/s6-networking/s6-tcpserver4-socketbinder.html">s6-tcpserver4-socketbinder</a> and +<a href="http://skarnet.org/software/s6-networking/s6-tcpserver6-socketbinder.html">s6-tcpserver4-socketbinder</a>. + </li> + <li> A supervision infrastructure that can start as many services in parallel +as you want: +<a href="s6-supervise.html">s6-supervise</a> and +<a href="s6-svscan.html">s6-svscan</a>. </li> + </ul> </li> + <li> s6 <em>will not</em> help you centralize all your socket information +in process 1, because doing so is contrary to modularity and independence +of services. However, s6 +<em>will</em> provide you with a way to store your open sockets and +retrieve them when you want, which it calls "fd holding": +<a href="s6-fdholder-daemon.html">s6-fdholder-daemon</a>. </li> +</ul> + +<h2> So, how do I open all my sockets first, store them, and dispatch them +to daemons later ? </h2> + +<p> + Again, it's not necessary to do that: you'll be fine, and quite speedy, +just starting your +daemons in their good time. You <em>will not</em> reap any noticeable +benefit from performing "socket activation". But if you really want to: +</p> + +<ol> + <li> Make sure you have an early supervision infrastructure running. +Ideally, you would <a href="s6-svscan-1.html">make s6-svscan your +process 1</a>. </li> + <li> Start an early <a href="s6-fdholder-daemon.html">fd-holding +service</a>. Let's say the fd-holding daemon is listening on socket +<tt>/service/fdholder/s</tt>. </li> + <li> For every Unix domain socket <em>/my/socket</em> you need to open, run +<tt>s6-ipcserver-socketbinder /my/socket s6-fdholder-store /service/fdholder/s +unix:/my/socket</tt>. You can do the same with INET domain sockets. </li> + <li> Proceed to your initialization. </li> + <li> When you want to run a daemon <em>myserverd</em> that accepts clients +connecting to <em>/my/socket</em>, run <tt>s6-fdholder-retrieve +/service/fdholder/s unix:/my/socket myserverd</tt>. <em>myserverd</em> +will be executed with <em>/my/socket</em> as its standard input. </li> + <li> The descriptors remain safely stored in the fd-holding daemon and you +can retrieve them again whenever you want, for instance when your service +crashes and is restarted. </li> +</ol> + +<p> + That is all there is to it. You don't have to use specific libraries +or write complex unit files, you just need to understand how a command +line works. This is Unix. +</p> + +</body> +</html> |