glfs/postlfs/security/stunnel.xml
Bruce Dubbs 1334c9aa32 Update to xterm-361.
Update to LibRaw-0.20.2. 
Update to stunnel-5.57. 
Update to libpwquality-1.4.4. 



git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@23816 af4574ff-66df-0310-9fd7-8a98e5e911e0
2020-10-16 19:08:07 +00:00

415 lines
13 KiB
XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % general-entities SYSTEM "../../general.ent">
%general-entities;
<!ENTITY stunnel-download-http " ">
<!-- Following ftp also has older releases -->
<!ENTITY stunnel-download-ftp "ftp://ftp.stunnel.org/stunnel/archive/5.x/stunnel-&stunnel-version;.tar.gz">
<!-- Following ftp only has later release -->
<!-- "ftp://ftp.stunnel.org/stunnel/stunnel-&stunnel-version;.tar.gz"> -->
<!ENTITY stunnel-md5sum "6bbe921f8d2ab4967dc7ff42f6e5d45a">
<!ENTITY stunnel-size "964 KB">
<!ENTITY stunnel-buildsize "7.3 MB">
<!ENTITY stunnel-time "less than 0.1 SBU">
]>
<sect1 id="stunnel" xreflabel="stunnel-&stunnel-version;">
<?dbhtml filename="stunnel.html"?>
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<title>stunnel-&stunnel-version;</title>
<indexterm zone="stunnel">
<primary sortas="a-stunnel">stunnel</primary>
</indexterm>
<sect2 role="package">
<title>Introduction to stunnel</title>
<para>
The <application>stunnel</application> package contains a program
that allows you to encrypt arbitrary TCP connections inside SSL (Secure
Sockets Layer) so you can easily communicate with clients over secure
channels. <application>stunnel</application> can be used to add SSL
functionality to commonly used <application>Inetd</application> daemons
such as POP-2, POP-3, and IMAP servers, along with standalone daemons
such as NNTP, SMTP, and HTTP. <application>stunnel</application> can
also be used to tunnel PPP over network sockets without changes to the
server package source code.
</para>
&lfs10_checked;
<bridgehead renderas="sect3">Package Information</bridgehead>
<itemizedlist spacing="compact">
<listitem>
<para>
Download (HTTP): <ulink url="&stunnel-download-http;"/>
</para>
</listitem>
<listitem>
<para>
Download (FTP): <ulink url="&stunnel-download-ftp;"/>
</para>
</listitem>
<listitem>
<para>
Download MD5 sum: &stunnel-md5sum;
</para>
</listitem>
<listitem>
<para>
Download size: &stunnel-size;
</para>
</listitem>
<listitem>
<para>
Estimated disk space required: &stunnel-buildsize;
</para>
</listitem>
<listitem>
<para>
Estimated build time: &stunnel-time;
</para>
</listitem>
</itemizedlist>
<bridgehead renderas="sect3">stunnel Dependencies</bridgehead>
<bridgehead renderas="sect4">Optional</bridgehead>
<para role="optional">
<ulink url="http://netcat.sourceforge.net/">netcat</ulink>
(required for tests),
<ulink url="ftp://ftp.porcupine.org/pub/security/">tcpwrappers</ulink>,
and
<ulink url="https://dist.torproject.org/">TOR</ulink>
</para>
<para condition="html" role="usernotes">User Notes:
<ulink url="&blfs-wiki;/stunnel"/></para>
</sect2>
<sect2 role="installation">
<title>Installation of stunnel</title>
<para>
The <command>stunnel</command> daemon will be run in a
<command>chroot</command> jail by an unprivileged user. Create the
new user and group using the following commands as the
<systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>groupadd -g 51 stunnel &amp;&amp;
useradd -c "stunnel Daemon" -d /var/lib/stunnel \
-g stunnel -s /bin/false -u 51 stunnel</userinput></screen>
<note>
<para>
A signed SSL Certificate and a Private Key is necessary to run the
<command>stunnel</command> daemon. After the package is installed,
there are instructions to generate them. However, if you own or have
already created a signed SSL Certificate you wish to use, copy it to
<filename>/etc/stunnel/stunnel.pem</filename> before starting the
build (ensure only <systemitem class="username">root</systemitem> has
read and write access). The <filename class="extension">.pem</filename>
file must be formatted as shown below:
</para>
<screen><literal>-----BEGIN PRIVATE KEY-----
<replaceable>&lt;many encrypted lines of private key&gt;</replaceable>
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
<replaceable>&lt;many encrypted lines of certificate&gt;</replaceable>
-----END CERTIFICATE-----
-----BEGIN DH PARAMETERS-----
<replaceable>&lt;encrypted lines of dh parms&gt;</replaceable>
-----END DH PARAMETERS-----</literal></screen>
</note>
<para>
Install <application>stunnel</application> by running the following
commands:
</para>
<note>
<para>
For some systems with <application>binutils</application>
versions prior to 2.25, <command>configure</command> may fail. If
necessary, fix it either with:
</para>
<screen><userinput>sed -i '/LDFLAGS.*static_flag/ s/^/#/' configure</userinput></screen>
<para>
or, if <xref linkend="llvm"/> with Clang is installed, you can
replace <command>./configure ...</command> with <command>CC=clang
./configure ...</command> in the first command below.
</para>
</note>
<screen revision="sysv"><userinput>./configure --prefix=/usr \
--sysconfdir=/etc \
--localstatedir=/var \
--disable-systemd &amp;&amp;
make</userinput></screen>
<screen revision="systemd"><userinput>./configure --prefix=/usr \
--sysconfdir=/etc \
--localstatedir=/var &amp;&amp;
make</userinput></screen>
<para>
If you have installed the optional netcat application, the
regression tests can be run with <command>make check</command>.
</para>
<para>
Now, as the <systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>make docdir=/usr/share/doc/stunnel-&stunnel-version; install</userinput></screen>
<para revision="systemd">
Install the included systemd unit by running the following command as the
<systemitem class="username">root</systemitem> user:
</para>
<screen role="root" revision="systemd"><userinput>install -v -m644 tools/stunnel.service /lib/systemd/system</userinput></screen>
<para>
If you do not already have a signed SSL Certificate and Private Key,
create the <filename>stunnel.pem</filename> file in the
<filename class="directory">/etc/stunnel</filename> directory using the
command below. You will be prompted to enter the necessary
information. Ensure you reply to the
</para>
<screen><prompt>Common Name (FQDN of your server) [localhost]:</prompt></screen>
<para>
prompt with the name or IP address you will be using
to access the service(s).
</para>
<para>
To generate a certificate, as the
<systemitem class="username">root</systemitem> user, issue:
</para>
<screen role="root"><userinput>make cert</userinput></screen>
</sect2>
<sect2 role="commands">
<title>Command Explanations</title>
<para revision="sysv">
<parameter>--disable-systemd</parameter>: This switch disables systemd
socket activation support which is not available in BLFS.
</para>
<para>
<command>make docdir=... install</command>: This command installs the
package and changes the documentation installation directory to standard
naming conventions.
</para>
</sect2>
<sect2 role="configuration">
<title>Configuring stunnel</title>
<sect3 id="stunnel-config">
<title>Config Files</title>
<para>
<filename>/etc/stunnel/stunnel.conf</filename>
</para>
<indexterm zone="stunnel stunnel-config">
<primary sortas="e-etc-stunnel-stunnel.conf">/etc/stunnel/stunnel.conf</primary>
</indexterm>
</sect3>
<sect3>
<title>Configuration Information</title>
<para>
As the <systemitem class="username">root</systemitem> user,
create the directory used for the
<filename class="extension">.pid</filename> file created
when the <application>stunnel</application> daemon starts:
</para>
<screen role="root"><userinput>install -v -m750 -o stunnel -g stunnel -d /var/lib/stunnel/run &amp;&amp;
chown stunnel:stunnel /var/lib/stunnel</userinput></screen>
<para>
Next, create a basic <filename>/etc/stunnel/stunnel.conf</filename>
configuration file using the following commands as the
<systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>cat &gt;/etc/stunnel/stunnel.conf &lt;&lt; "EOF"
<literal>; File: /etc/stunnel/stunnel.conf
; Note: The pid and output locations are relative to the chroot location.
pid = /run/stunnel.pid
chroot = /var/lib/stunnel
client = no
setuid = stunnel
setgid = stunnel
cert = /etc/stunnel/stunnel.pem
;debug = 7
;output = stunnel.log
;[https]
;accept = 443
;connect = 80
;; "TIMEOUTclose = 0" is a workaround for a design flaw in Microsoft SSL
;; Microsoft implementations do not use SSL close-notify alert and thus
;; they are vulnerable to truncation attacks
;TIMEOUTclose = 0</literal>
EOF</userinput></screen>
<para>
Finally, add the service(s) you wish to encrypt to the
configuration file. The format is as follows:
</para>
<screen><literal>[<replaceable>&lt;service&gt;</replaceable>]
accept = <replaceable>&lt;hostname:portnumber&gt;</replaceable>
connect = <replaceable>&lt;hostname:portnumber&gt;</replaceable></literal></screen>
<para>
If you use <application>stunnel</application> to encrypt a daemon
started from <command>[x]inetd</command>, you may need to disable that
daemon in the <filename>/etc/[x]inetd.conf</filename> file and enable a
corresponding <replaceable>&lt;service&gt;</replaceable>_stunnel
service. You may have to add an appropriate entry in
<filename>/etc/services</filename> as well.
</para>
<para>
For a full explanation of the commands and syntax used in the
configuration file, issue <command>man stunnel</command>.
</para>
</sect3>
<sect3 id="stunnel-init">
<title><phrase revision="sysv">Boot Script</phrase>
<phrase revision="systemd">Systemd Unit</phrase></title>
<para revision="sysv">
To automatically start the <command>stunnel</command> daemon when the
system is booted, install the
<filename>/etc/rc.d/init.d/stunnel</filename> bootscript from the
<xref linkend="bootscripts"/> package.
</para>
<para revision="systemd">
To start the <command>stunnel</command>
daemon at boot, enable the previously installed
<application>systemd</application> unit by running the following
command as the <systemitem class="username">root</systemitem> user:
</para>
<indexterm zone="stunnel stunnel-init">
<primary sortas="f-stunnel">stunnel</primary>
</indexterm>
<screen role="root" revision="sysv"><userinput>make install-stunnel</userinput></screen>
<screen role="root" revision="systemd"><userinput>systemctl enable stunnel</userinput></screen>
</sect3>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Library</segtitle>
<segtitle>Installed Directories</segtitle>
<seglistitem>
<seg>
stunnel and stunnel3
</seg>
<seg>
libstunnel.so
</seg>
<seg>
/{etc,usr/lib,var/lib}/stunnel and
/usr/share/doc/stunnel-&stunnel-version;
</seg>
</seglistitem>
</segmentedlist>
<variablelist>
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
<?dbfo list-presentation="list"?>
<?dbhtml list-presentation="table"?>
<varlistentry id="stunnel-prog">
<term><command>stunnel</command></term>
<listitem>
<para>
is a program designed to work as an SSL
encryption wrapper between remote clients and local
(<command>{x}inetd</command>-startable) or remote servers.
</para>
<indexterm zone="stunnel stunnel-prog">
<primary sortas="b-stunnel">stunnel</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="stunnel3">
<term><command>stunnel3</command></term>
<listitem>
<para>
is a <application>Perl</application> wrapper script to use
<command>stunnel</command> 3.x syntax with
<command>stunnel</command> 4.05 or later.
</para>
<indexterm zone="stunnel stunnel3">
<primary sortas="b-stunnel3">stunnel3</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="libstunnel">
<term><filename class='libraryfile'>libstunnel.so</filename></term>
<listitem>
<para>
contains the API functions required by
<application>stunnel</application>.
</para>
<indexterm zone="stunnel libstunnel">
<primary sortas="c-libstunnel">libstunnel.so</primary>
</indexterm>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>