source: postlfs/security/stunnel.xml@ ab70ce0

11.0 11.1 11.2 lazarus plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since ab70ce0 was ab70ce0, checked in by Bruce Dubbs <bdubbs@…>, 19 months ago

Fix stunnel md5sum.

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