source: postlfs/security/stunnel.xml@ 2e0d6b9

10.0 10.1 11.0 11.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus perl-modules qt5new trunk upgradedb xry111/intltool xry111/test-20220226
Last change on this file since 2e0d6b9 was 2e0d6b9, checked in by Bruce Dubbs <bdubbs@…>, 4 years ago

Update sshfs instructions fo rmeson/ninja.
Tags and cleanup.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@19847 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 12.9 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY stunnel-download-http " ">
8 <!-- Following ftp also has older releases -->
9 <!ENTITY stunnel-download-ftp "ftp://ftp.stunnel.org/stunnel/archive/5.x/stunnel-&stunnel-version;.tar.gz">
10 <!-- Following ftp only has later release -->
11<!-- "ftp://ftp.stunnel.org/stunnel/stunnel-&stunnel-version;.tar.gz"> -->
12 <!ENTITY stunnel-md5sum "47697dee496c80c8e352b2b705c4a571">
13 <!ENTITY stunnel-size "684 KB">
14 <!ENTITY stunnel-buildsize "6.2 MB">
15 <!ENTITY stunnel-time "0.1 SBU">
16]>
17
18<sect1 id="stunnel" xreflabel="stunnel-&stunnel-version;">
19 <?dbhtml filename="stunnel.html"?>
20
21 <sect1info>
22 <othername>$LastChangedBy$</othername>
23 <date>$Date$</date>
24 </sect1info>
25
26 <title>stunnel-&stunnel-version;</title>
27
28 <indexterm zone="stunnel">
29 <primary sortas="a-stunnel">stunnel</primary>
30 </indexterm>
31
32 <sect2 role="package">
33 <title>Introduction to stunnel</title>
34
35 <para>The <application>stunnel</application> package contains a program
36 that allows you to encrypt arbitrary TCP connections inside SSL (Secure
37 Sockets Layer) so you can easily communicate with clients over secure
38 channels. <application>stunnel</application> can be used to add SSL
39 functionality to commonly used <application>Inetd</application> daemons
40 such as POP-2, POP-3, and IMAP servers, along with standalone daemons such
41 as NNTP, SMTP, and HTTP. <application>stunnel</application> can also be
42 used to tunnel PPP over network sockets without changes to the server
43 package source code.</para>
44
45 &lfs82_checked;
46
47 <bridgehead renderas="sect3">Package Information</bridgehead>
48 <itemizedlist spacing="compact">
49 <listitem>
50 <para>Download (HTTP): <ulink url="&stunnel-download-http;"/></para>
51 </listitem>
52 <listitem>
53 <para>Download (FTP): <ulink url="&stunnel-download-ftp;"/></para>
54 </listitem>
55 <listitem>
56 <para>Download MD5 sum: &stunnel-md5sum;</para>
57 </listitem>
58 <listitem>
59 <para>Download size: &stunnel-size;</para>
60 </listitem>
61 <listitem>
62 <para>Estimated disk space required: &stunnel-buildsize;</para>
63 </listitem>
64 <listitem>
65 <para>Estimated build time: &stunnel-time;</para>
66 </listitem>
67 </itemizedlist>
68
69 <bridgehead renderas="sect3">stunnel Dependencies</bridgehead>
70<!--
71 <bridgehead renderas="sect4">Required</bridgehead>
72 <para role="required">
73 <xref linkend="openssl"/>
74 </para>
75-->
76 <bridgehead renderas="sect4">Optional</bridgehead>
77 <para role="optional">
78 <ulink url="http://netcat.sourceforge.net/">netcat</ulink>,
79 <ulink url="ftp://ftp.porcupine.org/pub/security/">tcpwrappers</ulink> and
80 <ulink url="https://dist.torproject.org/">TOR</ulink>
81 </para>
82
83 <para condition="html" role="usernotes">User Notes:
84 <ulink url="&blfs-wiki;/stunnel"/></para>
85
86 </sect2>
87
88 <sect2 role="installation">
89 <title>Installation of stunnel</title>
90
91 <para>The <command>stunnel</command> daemon will be run in a
92 <command>chroot</command> jail by an unprivileged user. Create the
93 new user and group using the following commands as the
94 <systemitem class="username">root</systemitem> user:</para>
95
96<screen role="root"><userinput>groupadd -g 51 stunnel &amp;&amp;
97useradd -c "stunnel Daemon" -d /var/lib/stunnel \
98 -g stunnel -s /bin/false -u 51 stunnel</userinput></screen>
99
100 <note>
101 <para>A signed SSL Certificate and a Private Key is necessary to run the
102 <command>stunnel</command> daemon. After the package is installed, there
103 are instructions to generate them. However, if you own or have already
104 created a signed SSL Certificate you wish to use, copy it to
105 <filename>/etc/stunnel/stunnel.pem</filename> before starting the build
106 (ensure only <systemitem class="username">root</systemitem> has read and
107 write access). The <filename class="extension">.pem</filename> file must
108 be formatted as shown below:</para>
109
110<screen><literal>-----BEGIN PRIVATE KEY-----
111<replaceable>&lt;many encrypted lines of private key&gt;</replaceable>
112-----END PRIVATE KEY-----
113-----BEGIN CERTIFICATE-----
114<replaceable>&lt;many encrypted lines of certificate&gt;</replaceable>
115-----END CERTIFICATE-----
116-----BEGIN DH PARAMETERS-----
117<replaceable>&lt;encrypted lines of dh parms&gt;</replaceable>
118-----END DH PARAMETERS-----</literal></screen>
119 </note>
120
121 <para>Install <application>stunnel</application> by running the following
122 commands:</para>
123
124 <note>
125 <para>For some systems with <application>binutils</application>
126 versions prior to 2.25, <command>configure</command> may fail. If
127 necessary, fix it either with:</para>
128
129<screen><userinput>sed -i '/LDFLAGS.*static_flag/ s/^/#/' configure</userinput></screen>
130
131 <para>or, if <xref linkend="llvm"/> with Clang is installed, you can
132 replace <command>./configure ...</command> with <command>CC=clang
133 ./configure ...</command> in the first command below.</para>
134 </note>
135
136<screen revision="sysv"><userinput>./configure --prefix=/usr \
137 --sysconfdir=/etc \
138 --localstatedir=/var \
139 --disable-systemd &amp;&amp;
140make</userinput></screen>
141
142<screen revision="systemd"><userinput>./configure --prefix=/usr \
143 --sysconfdir=/etc \
144 --localstatedir=/var &amp;&amp;
145make</userinput></screen>
146
147 <para>If you have installed the optional netcat application, the
148 regression tests can be run with <command>make check</command>.</para>
149
150 <para>Now, as the <systemitem class="username">root</systemitem> user:</para>
151
152<screen role="root"><userinput>make docdir=/usr/share/doc/stunnel-&stunnel-version; install</userinput></screen>
153
154 <para revision="systemd">
155 Install the included systemd unit by running the following command as the
156 <systemitem class="username">root</systemitem> user:
157 </para>
158
159<screen role="root" revision="systemd"><userinput>install -v -m644 tools/stunnel.service /lib/systemd/system</userinput></screen>
160
161 <para>If you do not already have a signed SSL Certificate and Private Key,
162 create the <filename>stunnel.pem</filename> file in the
163 <filename class="directory">/etc/stunnel</filename> directory using the
164 command below. You will be prompted to enter the necessary
165 information. Ensure you reply to the</para>
166
167<screen><prompt>Common Name (FQDN of your server) [localhost]:</prompt></screen>
168
169 <para>prompt with the name or IP address you will be using
170 to access the service(s).</para>
171
172 <para>To generate a certificate, as the
173 <systemitem class="username">root</systemitem> user, issue:</para>
174
175<screen role="root"><userinput>make cert</userinput></screen>
176
177 </sect2>
178
179 <sect2 role="commands">
180 <title>Command Explanations</title>
181
182 <para revision="sysv"><parameter>--disable-systemd</parameter>: This switch
183 disables systemd socket activation support which is not available in
184 BLFS.</para>
185
186 <para><command>make docdir=... install</command>: This command installs the
187 package and changes the documentation installation directory to standard
188 naming conventions.</para>
189
190 </sect2>
191
192 <sect2 role="configuration">
193 <title>Configuring stunnel</title>
194
195 <sect3 id="stunnel-config">
196 <title>Config Files</title>
197
198 <para><filename>/etc/stunnel/stunnel.conf</filename></para>
199
200 <indexterm zone="stunnel stunnel-config">
201 <primary sortas="e-etc-stunnel-stunnel.conf">/etc/stunnel/stunnel.conf</primary>
202 </indexterm>
203
204 </sect3>
205
206 <sect3>
207 <title>Configuration Information</title>
208
209 <para>As the <systemitem class="username">root</systemitem> user,
210 create the directory used for the
211 <filename class="extension">.pid</filename> file created
212 when the <application>stunnel</application> daemon starts:</para>
213
214<screen role="root"><userinput>install -v -m750 -o stunnel -g stunnel -d /var/lib/stunnel/run &amp;&amp;
215chown stunnel:stunnel /var/lib/stunnel</userinput></screen>
216
217 <para>Next, create a basic <filename>/etc/stunnel/stunnel.conf</filename>
218 configuration file using the following commands as the
219 <systemitem class="username">root</systemitem> user:</para>
220
221<screen role="root"><userinput>cat &gt;/etc/stunnel/stunnel.conf &lt;&lt; "EOF"
222<literal>; File: /etc/stunnel/stunnel.conf
223
224; Note: The pid and output locations are relative to the chroot location.
225
226pid = /run/stunnel.pid
227chroot = /var/lib/stunnel
228client = no
229setuid = stunnel
230setgid = stunnel
231cert = /etc/stunnel/stunnel.pem
232
233;debug = 7
234;output = stunnel.log
235
236;[https]
237;accept = 443
238;connect = 80
239;; "TIMEOUTclose = 0" is a workaround for a design flaw in Microsoft SSL
240;; Microsoft implementations do not use SSL close-notify alert and thus
241;; they are vulnerable to truncation attacks
242;TIMEOUTclose = 0</literal>
243
244EOF</userinput></screen>
245
246 <para>Finally, add the service(s) you wish to encrypt to the
247 configuration file. The format is as follows:</para>
248
249<screen><literal>[<replaceable>&lt;service&gt;</replaceable>]
250accept = <replaceable>&lt;hostname:portnumber&gt;</replaceable>
251connect = <replaceable>&lt;hostname:portnumber&gt;</replaceable></literal></screen>
252
253 <para>If you use <application>stunnel</application> to encrypt a daemon
254 started from <command>[x]inetd</command>, you may need to disable that
255 daemon in the <filename>/etc/[x]inetd.conf</filename> file and enable a
256 corresponding <replaceable>&lt;service&gt;</replaceable>_stunnel service. You
257 may have to add an appropriate entry in <filename>/etc/services</filename>
258 as well.</para>
259
260 <para>For a full explanation of the commands and syntax used in the
261 configuration file, issue <command>man stunnel</command>.</para>
262
263 </sect3>
264
265 <sect3 id="stunnel-init">
266 <title><phrase revision="sysv">Boot Script</phrase>
267 <phrase revision="systemd">Systemd Unit</phrase></title>
268
269 <para revision="sysv">To automatically start the
270 <command>stunnel</command> daemon when the system is booted, install the
271 <filename>/etc/rc.d/init.d/stunnel</filename> bootscript from the
272 <xref linkend="bootscripts"/> package.</para>
273
274 <para revision="systemd">To start the <command>stunnel</command>
275 daemon at boot, enable the previously installed
276 <application>systemd</application> unit by running the following command
277 as the <systemitem class="username">root</systemitem> user:</para>
278
279 <indexterm zone="stunnel stunnel-init">
280 <primary sortas="f-stunnel">stunnel</primary>
281 </indexterm>
282
283<screen role="root" revision="sysv"><userinput>make install-stunnel</userinput></screen>
284
285<screen role="root" revision="systemd"><userinput>systemctl enable stunnel</userinput></screen>
286
287 </sect3>
288
289 </sect2>
290
291 <sect2 role="content">
292 <title>Contents</title>
293
294 <segmentedlist>
295 <segtitle>Installed Programs</segtitle>
296 <segtitle>Installed Library</segtitle>
297 <segtitle>Installed Directories</segtitle>
298
299 <seglistitem>
300 <seg>
301 stunnel and stunnel3
302 </seg>
303 <seg>
304 libstunnel.so
305 </seg>
306 <seg>
307 /{etc,usr/lib,var/lib}/stunnel and
308 /usr/share/doc/stunnel-&stunnel-version;
309 </seg>
310 </seglistitem>
311 </segmentedlist>
312
313 <variablelist>
314 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
315 <?dbfo list-presentation="list"?>
316 <?dbhtml list-presentation="table"?>
317
318 <varlistentry id="stunnel-prog">
319 <term><command>stunnel</command></term>
320 <listitem>
321 <para> is a program designed to work as an SSL
322 encryption wrapper between remote clients and local
323 (<command>{x}inetd</command>-startable) or remote servers.</para>
324 <indexterm zone="stunnel stunnel-prog">
325 <primary sortas="b-stunnel">stunnel</primary>
326 </indexterm>
327 </listitem>
328 </varlistentry>
329
330 <varlistentry id="stunnel3">
331 <term><command>stunnel3</command></term>
332 <listitem>
333 <para>is a <application>Perl</application> wrapper script to use
334 <command>stunnel</command> 3.x syntax with <command>stunnel</command>
335 >=4.05.</para>
336 <indexterm zone="stunnel stunnel3">
337 <primary sortas="b-stunnel3">stunnel3</primary>
338 </indexterm>
339 </listitem>
340 </varlistentry>
341
342 <varlistentry id="libstunnel">
343 <term><filename class='libraryfile'>libstunnel.so</filename></term>
344 <listitem>
345 <para> contains the API functions required by
346 <application>stunnel</application>.</para>
347 <indexterm zone="stunnel libstunnel">
348 <primary sortas="c-libstunnel">libstunnel.so</primary>
349 </indexterm>
350 </listitem>
351 </varlistentry>
352
353 </variablelist>
354
355 </sect2>
356
357</sect1>
Note: See TracBrowser for help on using the repository browser.