s3:rpc_server: Add samba-dcerpcd

Central dispatcher for incoming RPC requests, supported by helpers
that implement RPC services.

Upon startup, it asks all helpers which interfaces and endpoints to
listen on so it doesn't interfere with the samba binary when we're
configured as an Active Directory Domain Controller, then samba-dcerpcd
opens the relevant sockets. Once clients connect, start required helpers
and tell them to shut down once idle for a while.

Can be started as a full standalone daemon without smbd involved or as
a helper daemon started on demand by smbd or winbind or other local
processes trying to connect to a named pipe based RPC service.

NB. To start as a standalone daemon the smb.conf [global] option
"rpc start on demand helpers = false" must be set.
By default "rpc start on demand helpers = true"
in order to allow upgrades without needing an smb.conf change.

Signed-off-by: Volker Lendecke <vl@samba.org>
Reviewed-by: Samuel Cabrero <scabrero@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>
Reviewed-by: Stefan Metzmacher <metze@samba.org>

1 files changed, 210 insertions, 0 deletions

diff --git a/docs-xml/manpages/samba-dcerpcd.8.xml b/docs-xml/manpages/samba-dcerpcd.8.xml
new file mode 100644
index 00000000000..da8b77c9517
--- /dev/null
+++ b/docs-xml/manpages/samba-dcerpcd.8.xml
@@ -0,0 +1,210 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="samba-dcerpcd.8">
+
+<refmeta>
+	<refentrytitle>samba-dcerpcd</refentrytitle>
+	<manvolnum>8</manvolnum>
+	<refmiscinfo class="source">Samba</refmiscinfo>
+	<refmiscinfo class="manual">System Administration tools</refmiscinfo>
+	<refmiscinfo class="version">&doc.version;</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+	<refname>samba-dcerpcd</refname>
+	<refpurpose>This is one of Samba's DCERPC server processes
+	that can listen on sockets where RPC services are offered and
+	is the parent process of the DCERPC services it
+	invokes. Unless separately invoked it is started on demand
+	from <command>smbd</command> or <command>winbind</command> and
+	serves DCERPC only over named pipes (np) as a helper
+	process. This will be the standard setup for most
+	installations (standalone/member server/AD server) unless they
+	modify their startup scripts. Note in when Samba is configured
+	as an Active Directory Domain controller the
+	<command>samba</command> process that invokes
+	<command>smbd</command> will still provide its normal DCERPC
+	services, not <command>samba-dcerpcd</command>. When
+	separately invoked by system startup scripts or a a daemon,
+	the global smb.conf option <smbconfoption name="rpc start on
+	demand helpers">false</smbconfoption> MUST be set to allow
+	<command>samba-dcerpcd</command> to start standalone.
+	</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+	<cmdsynopsis>
+		<command>samba-dcerpcd</command>
+		<arg choice="opt">-D|--daemon</arg>
+		<arg choice="opt">-i|--interactive</arg>
+		<arg choice="opt">-F|--foreground</arg>
+		<arg choice="opt">--no-process-group</arg>
+		<arg choice="opt">-d &lt;debug level&gt;</arg>
+		<arg choice="opt">--debug-stdout</arg>
+		<arg choice="opt">--configfile=&lt;configuration file&gt;</arg>
+		<arg choice="opt">--option=&lt;name&gt;=&lt;value&gt;</arg>
+		<arg choice="opt">--leak-report</arg>
+		<arg choice="opt">--leak-report-full</arg>
+		<arg choice="opt">-V|--version</arg>
+		<arg choice="opt">--libexec-rpcds</arg>
+		<arg choice="opt">--np-helper</arg>
+		<arg choice="opt">--ready-signal-fd=&lt;fd&gt;</arg>
+		<arg choice="opt">&lt;SERVICE_1&gt;</arg>
+		<arg choice="opt">&lt;SERVICE_2&gt;</arg>
+		<arg choice="opt">&lt;...&gt;</arg>
+	</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+	<title>DESCRIPTION</title>
+
+	<para>This tool is part of the
+	<citerefentry><refentrytitle>samba</refentrytitle>
+	<manvolnum>7</manvolnum></citerefentry> suite.</para>
+
+	<para>
+	  samba-dcerpcd can be used in two ways. In the normal case
+	  without startup script modification and the global smb.conf
+	  option <smbconfoption name="rpc start on demand
+	  helpers">true</smbconfoption> is set (the default setting),
+	  it is invoked on demand from <command>smbd</command> or
+	  <command>winbind</command> with a command line
+	  containing--np-helper to serve DCERPC over named pipes
+	  (np). It can also be used in a standalone mode where it is
+	  started separately from <command>smbd</command> or
+	  <command>winbind</command> via system startup scripts. If
+	  invoked as a standalone daemon or started from system
+	  startup scripts the global smb.conf option <smbconfoption
+	  name="rpc start on demand helpers">false</smbconfoption>
+	  MUST be set to false. If the global smb.conf option
+	  <smbconfoption name="rpc start on demand
+	  helpers">true</smbconfoption> is set to true or left as
+	  default, <command>samba-dcerpcd</command> will fail to start
+	  and log an error message.
+	</para>
+	<para>
+	  Note that when Samba is run in the Active Directory Domain
+	  Controller mode the <command>samba</command> AD code will
+	  still provide its normal DCERPC services whilst allowing
+	  samba-dcerpcd to provide services like SRVSVC in the same
+	  way that <command>smbd</command> used to in this
+	  configuration.
+	</para>
+	<para>
+	  The standalone mode can also be useful for use outside of
+	  the Samba framework, for example, use with the Linux kernel
+	  SMB2 server ksmbd or possibly other SMB2 server
+	  implementations. In this mode it behaves like inetd and
+	  listens on sockets on behalf of RPC server implementations.
+	</para>
+	<para>
+	  When a client connects, <command>samba-dcerpcd</command>
+	  will start the relevant RPC service binary on demand and
+	  hand over the connection to that service. When an RPC
+	  service has been idle for a while,
+	  <command>samba-dcerpcd</command> will ask it to shut down
+	  again.
+	</para>
+
+</refsect1>
+
+<refsect1>
+	<title>OPTIONS</title>
+
+	<variablelist>
+		<varlistentry>
+		<term>-D|--daemon</term>
+		<listitem><para>If specified, this parameter causes
+		the server to operate as a daemon. That is, it
+		detaches itself and runs in the background, fielding
+		requests on the appropriate port. Operating the server
+		as a daemon is useful for running
+		<command>samba-dcerpcd</command> outside of the Samba
+		framework. However, it can also be used in this way
+		within Samba for member servers if configured to start
+		up via system startup scripts.  This switch is assumed
+		if <command>samba-dcerpcd</command> is executed on the
+		command line of a shell.  </para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-i|--interactive</term>
+		<listitem><para>If this parameter is specified it
+		causes the server to run "interactively", not as a
+		daemon, even if the server is executed on the command
+		line of a shell. Setting this parameter negates the
+		implicit daemon mode when run from the command
+		line. <command>samba-dcerpcd</command> will only
+		accept one connection and terminate. It will also log
+		to standard output, as if the <command>-S</command>
+		parameter had been given.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-F|--foreground</term>
+		<listitem><para>If specified, this parameter causes
+		the main <command>samba-dcerpcd</command> process to
+		not daemonize, i.e. double-fork and disassociate with
+		the terminal.  Child processes are still spawned as
+		normal to service each connection request, but the
+		main process does not exit. This operation mode is
+		suitable for running <command>samba-dcerpcd</command>
+		under process supervisors such as
+		<command>supervise</command> and
+		<command>svscan</command> from Daniel J. Bernstein's
+		<command>daemontools</command> package, or the AIX
+		process monitor.  </para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--no-process-group</term>
+		<listitem><para>Do not create a new process group for
+		samba-dcerpcd.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--libexec-rpcds</term>
+		<listitem><para>Offer RPC services for all daemons in
+		Samba's LIBEXECDIR, all programs starting with
+		&quot;rpcd_&quot; are assumed to offer RPC
+		services. If you don't use the
+		<command>--libexec-rpcds</command> option, you can
+		explicitly list all RPC service helpers explicitly on
+		the command line.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--np-helper</term>
+		<listitem><para>Run <command>samba-dcerpcd</command>
+		on demand opening named pipe sockets as helpers for
+		<command>smbd</command> or <command>winbind</command>.
+		In order to run in this mode, the global smb.conf
+		option <smbconfoption name="rpc start on demand
+		helpers">true</smbconfoption> must be set to true
+		(this is the default setting).  </para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>--ready-signal-fd=&lt;fd&gt;</term>
+		<listitem><para>Report service readiness via this fd
+		to <command>smbd</command>. Only for internal use.
+		</para></listitem>
+		</varlistentry>
+	</variablelist>
+</refsect1>
+
+<refsect1>
+	<title>AUTHOR</title>
+
+	<para>
+	  The original Samba software and related utilities were
+	  created by Andrew Tridgell. Samba is now developed by the
+	  Samba Team as an Open Source project similar to the way the
+	  Linux kernel is developed.
+	</para>
+</refsect1>
+
+</refentry>