New keyword available in Service section: Control.

* NEWS: Document changes.
* doc/pound.8: Likewise.
* doc/poundctl.8: Likewise.
* doc/pound.texi: Likewise.
* src/config.c: New keyword available in Service section: Control.
* src/http.c (control_response): A wrapper over control_response_basic
that runs request rewriting prior to calling it.
* src/pound.h (control_response): Rename to control_response_basic.
* src/svc.c: Likewise.
* src/poundctl.c: The -s option accepts a URL as its argument.
Implement plain HTTP, HTTPS and basic auth.
New options:
  -C CAFILE   load CA certificates from file or directory
  -K CERT     load client certificate for peer authentication.
  -k          disable peer verification.

NEWS

@@ -1,4 +1,4 @@
-Pound -- history of user-visible changes. 2024-09-30
+Pound -- history of user-visible changes. 2024-10-02
 See the end of file for copying conditions.
 
 Pound is a continuation of the software originally developed by
@@ -7,7 +7,7 @@ on 2022-09-19.  See the README file for details.
 
 Please send pound bug reports to <gray@gnu.org>
 
-Version 4.13.90 (git,resolver)
+Version 4.13.90 (git)
 
 * Dynamic backends
 
@@ -155,6 +155,37 @@ balancing algorightm applies when selecting an emergency backend.
 All statements valid within a "Backend" section are also valid within
 an emergency backend declaration.
 
+* Remote access to the management interface
+
+A new backend type "Control" is introduced to make it possible to
+access the management interface remotely.  The example below shows
+how to configure pound to expose the management interface on
+http://192.0.2.1:3434:
+
+  ListenHTTP
+      Address 192.0.2.1
+      Port 3434
+      Service
+          ACL "secure"
+	  Control
+      End
+  End
+
+* poundctl
+
+Changes in poundctl functionality reflect those in the management
+interface.  First of all, the -s option accepts URL as its argument:
+
+  -s https://user:password@hostname:8080/path
+
+Additionally, the following new options are implemented:
+
+  -C FILE      Load CA certificates from FILE.  If FILE is a
+               directory, all PEM files will be loaded from it.
+  -K FILE      Load client certificate and key from FILE.  During TLS
+               handshake, send them to the peer for authentication.
+  -k           Insecure mode: disable peer verification.	       
+
 * configure
 
 Removed historic "--with-owner" and "--with-group" options.

doc/pound.8

@@ -14,7 +14,7 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with pound.  If not, see <http://www.gnu.org/licenses/>.
-.TH POUND 8 "September 27, 2024" "pound" "System Manager's Manual"
+.TH POUND 8 "October 1, 2024" "pound" "System Manager's Manual"
 .SH NAME
 pound \- HTTP/HTTPS reverse-proxy and load-balancer
 .SH SYNOPSIS
@@ -769,16 +769,15 @@ effect until next
 statement or end of the configuration file, whichever occurs first.
 .SS Control socket
 .B Pound
-can be instructed to listen on a UNIX socket for management requests,
+can be instructed to listen for management requests,
 which will allow you to obtain information about the running
 instance, change state of configured listeners, services, and
 backends, etc.  These requests may be issued by using the
 .BR poundctl (8)
 utility.
 .PP
-The use of this
-.I control socket
-is configured via the
+Usually, a UNIX socket is used to communicate with the management interface.
+It is configured via the
 .B Control
 statement.  This statement has two forms.  In
 .I inline
@@ -822,6 +821,15 @@ global statements is used.  When set to
 .B true
 it will change the owner of the socket file to that specified by
 those two statements.
+.PP
+It is also possible to have
+.B pound
+listen for management requests on an INET or INET6 address.  See
+below, the section
+.BR "Backend definitions" ,
+description of the
+.B Control
+statement.
 .SH "HTTP Listener"
 An HTTP listener defines an address and port that
 .B pound
@@ -1595,6 +1603,41 @@ may define multiple backends per service, in which case
 .B pound
 will attempt to load-balance between them.
 .TP
+.B Control
+Enables a special \fBcontrol backend\fR -- a management interface that
+returns information about the running \fBpound\fR server, makes it
+possible to change state of configured listeners, services and
+backends, and provides other management facilities.  The management
+interface is discussed in detail in 
+section
+.BR "Control socket" ,
+above.  The \fBControl\fR backend provides remote access to this
+interface.  Be careful to properly protect the control interface
+by use of HTTPS, ACLs and/or basic authorization, e.g.:
+.IP
+.RS
+.EX
+ListenHTTPS
+    Address 192.0.2.1
+    Port 443
+    Cert "/etc/ssl/priv/example.pem"
+        
+    Service
+        Not BasicAuth "pound/htpasswd"
+        Rewrite response
+            SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\""
+        End
+        Error 401
+    End
+
+    Service
+        ACL "secure"
+        Control
+    End
+End
+.EE
+.RE
+.TP
 \fBRedirect\fR [\fIcode\fR] "\fIurl\fR"
 This is a special type of backend. Instead of sending the request to a backend
 .B pound

doc/pound.texi

@@ -972,7 +972,7 @@ authentication are declared after that service.  This way, any request
 that does not convey an @code{Authentication} header with credentials
 matching an entry from your password file will match this service, and
 will be replied to with a properly formatted 401 response, which will
-prompt the remote user to authenticate himself.  On the other hand,
+prompt the remote user to authenticate themselves.  On the other hand,
 authorized requests will not match this service and will eventually be
 handled by one of the services declared after it.
 
@@ -2587,15 +2587,15 @@ When logging, replace the last byte of client IP addresses with 0.
 Default: log the client address in full.
 @end deffn
 
-@node Control socket
-@section Control socket settings
-@cindex control socket
-@command{Pound} can be instructed to listen on a UNIX socket for management
-requests, which will allow you to obtain information about the running
-instance, change state of configured listeners, services, and backends,
-etc.  These requests are normally issued by the poundctl utility
-(@pxref{poundctl}).
+@node Management interface
+@section Management Interface
+@command{Pound} provides a management interface, which allows one to
+obtain information about the running instance, change state of
+configured listeners, services, and backends, etc.  These requests are
+normally issued by the poundctl utility (@pxref{poundctl}).
 
+@cindex control socket
+The management interface is usually made available via a UNIX socket.
 Properties of this @dfn{control socket} are configured via the
 @code{Control} statement.  It has two forms: @dfn{directive} and
 @dfn{section}.
@@ -2638,6 +2638,73 @@ End
 @end group
 @end example
 
+@node Service Control
+@subsection Remote Access to Management Interface
+@kwindex Control
+  To make the management interface available remotely, use the
+@code{Control} statement in a @code{Service} section:
+
+@example
+@group
+ListenHTTP
+    Address 192.0.2.1
+    Port 80
+    Service
+        Control
+    End
+End
+@end group
+@end example
+
+  This configuration makes management interface accessible via
+@indicateurl{http://192.0.2.1/}.  Due to obvious security
+implications, you'd be better off protecting the @code{Control}
+endpoint using HTTPS, ACLs and/or basic authorization.  The example
+below illustrates all these techniques:
+
+@example
+ListenHTTPS
+    Address 192.0.2.1
+    Port 443
+    Cert "/etc/ssl/priv/example.pem"
+    Disable TLSv1
+    
+    Service
+        Not BasicAuth "pound/htpasswd"
+        Rewrite response
+            SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\""
+        End
+        Error 401
+    End
+    
+    Service
+        ACL "secure"
+        Control
+    End
+End
+@end example
+
+@xref{Authentication}, for a discussion of @code{BasicAuth} statement,
+and see @ref{ACL} for a discussion of access control lists (this
+example assumes that the ACL @samp{secure} is defined elsewhere in the
+configuration file).
+
+If you wish to make management interface available under a special
+path, make sure the path prefix is stripped off, e.g.:
+
+@example
+@group
+Service
+    URL -re "^/control(/.+)"
+    SetURL "$1"
+    Control
+End
+@end group
+@end example
+
+@xref{Service Request and Response Modification}, for details about
+@code{SetURL} statement and request modification in general.
+
 @node Timeouts
 @section Timeouts
 
@@ -3511,6 +3578,7 @@ certificates after host-specific certificates).
 @code{Cert} directives must precede all other SSL-specific directives.
 @end deffn
 
+@anchor{ClientCert}
 @deffn {ListenHTTPS} ClientCert @var{mode} @var{depth}
 Specifies whether the listener must ask for the client's HTTPS
 certificate.  Allowed values for @var{mode} are:
@@ -4150,6 +4218,12 @@ then the request path is ignored.
 @xref{Redirects}, for a detailed discussion of this backend and its use.
 @end deffn
 
+@deffn {Service directive} Control
+Defines a special backend that serves @dfn{pound management
+interface}.  @xref{Service Control}, for a detailed discussion of this
+feature.
+@end deffn
+
 @anchor{Metrics}
 @deffn {Service directive} Metrics
 This directive defines a special backend that generates Openmetric
@@ -4362,18 +4436,23 @@ defines its own retry interval value.
 the running instance and allows you to change some of them.
 
   The program communicates with the running @command{pound} daemon via
-a UNIX socket.  For this to work, @command{pound} configuration file
-must contain a @code{Control} statement (@pxref{Control statement}).
-When started, @command{poundctl} opens the default @file{pound.cfg}
-file, looks up for this statement and then uses the pathname defined
-in it as the control socket file.
+a UNIX socket or remotely, via HTTP or HTTPS.  To use UNIX socket,
+@command{pound} configuration file must contain a @code{Control}
+statement (@pxref{Control statement}).  When started,
+@command{poundctl} opens the default @file{pound.cfg} file, looks up
+for this statement and then uses the pathname defined in it as the
+control socket file.
 
   This behavior can be altered in two ways.  First, if the
 configuration file is in a non-standard location, the pathname
 of this file can be given to the program using the @option{-f}
 command line option.  Secondly, the socket name can be supplied in the
 command line explicitly, using the @option{-s} option.
 
+  To access remote @command{pound} daemon via HTTP or HTTPS, supply
+its URL as argument to the @option{-s} option.  @xref{poundctl
+remote}, for a detailed discussion.
+
   The program invocation syntax is:
 
 @example
@@ -4479,11 +4558,46 @@ be specified.
 Add a session with the given @var{key}.
 @end deffn
 
+@node poundctl remote
+@section Using @command{poundctl} for remote access
+  Starting from version 4.14, @command{pound} is able to provide its
+management interface via HTTP (@pxref{Service Control}).  To use
+remote management interface, supply its URL with the @option{-s}
+command line option.  The URL syntax is:
+
+@example
+@var{scheme}://[@var{user}[:@var{password}]@@]@var{hostname}[:@var{port}][/@var{path}]
+@end example
+
+@noindent
+where @samp{[]} denote optional parts.  Valid @var{scheme} values are
+@samp{http} and @samp{https}.  Use @var{user} and @var{password} if
+the interface is protected by basic authentication (@pxref{Authentication}).
+
+When using @samp{https} protocol, you may need to supply the
+@dfn{certificate authority} file using the @option{-C @var{file}}
+option, where @var{file} is the name of the file in PEM format.  This
+option can also take a directory name as its argument.  In this case
+all PEM files from that directory will be loaded.
+
+To disable peer certificate verification, use the @option{-k} option.
+
+If @command{pound} configuration requires the client to send its
+certificate for authentication (@pxref{ClientCert}), use the
+@option{-K @var{file}} option to supply it.  Its argument, @var{file},
+is the name of the file with the certificate and key in PEM format.
+
 @node poundctl options
 @section @command{poundctl} options
   The following options are understood by @command{poundctl}:
 
 @table @option
+@kwindex -C, poundctl
+@item -C @var{file}
+@itemx -C @var{dir}
+Read certificate authority files from @var{file} or from files in
+@var{dir}.  @xref{poundctl remote}.
+
 @kwindex -f, poundctl
 @item -f @var{file}
 Read @command{pound} configuration from @var{file}, instead of the
@@ -4497,13 +4611,24 @@ Sets indentation level for JSON output to @var{n} columns.
 @item -j
 Use JSON output format.
 
+@kwindex -K, poundctl
+@item -K @var{file}
+Read client certificate and private key from @var{file}.
+@xref{poundctl remote}.
+
+@kwindex -k
+@item -k
+Disable peer certificate verification.  @xref{poundctl remote}.
+
 @kwindex -h, poundctl
 @item -h
 Shows a short help output and exits.
 
 @kwindex -s, poundctl
 @item -s @var{socket}
-Sets pathname of the control socket.
+@itemx -s @var{url}
+Sets pathname of the control socket, or its URL (for remote access,
+@pxref{poundctl remote}).
 
 @kwindex -T, poundctl
 @item -T @var{file}