source: postlfs/security/stunnel.xml@ cd602728

10.0 10.1 11.0 11.1 7.10 7.9 8.0 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus nosym perl-modules qt5new trunk upgradedb xry111/intltool xry111/test-20220226
Last change on this file since cd602728 was cd602728, checked in by Fernando de Oliveira <fernando@…>, 7 years ago
  • Update to stunnel-5.28.
  • Update to Update to libnl-3.2.27.
  • Update to stunnel-5.28.

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

  • Property mode set to 100644
File size: 11.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 "https://www.stunnel.org/downloads/stunnel-&stunnel-version;.tar.gz">-->
8 <!ENTITY stunnel-download-http " ">
9 <!-- Following ftp also has older releases -->
10 <!ENTITY stunnel-download-ftp "ftp://ftp.stunnel.org/stunnel/archive/5.x/stunnel-&stunnel-version;.tar.gz">
11 <!-- Following ftp only has later release -->
12<!-- <!ENTITY stunnel-download-ftp "ftp://ftp.stunnel.org/stunnel/stunnel-&stunnel-version;.tar.gz"> -->
13 <!ENTITY stunnel-md5sum "2c39ae0be771f91bf5b0205beafddca6">
14 <!ENTITY stunnel-size "624 KB">
15 <!ENTITY stunnel-buildsize "7.9 MB">
16 <!ENTITY stunnel-time "0.1 SBU">
17]>
18
19<sect1 id="stunnel" xreflabel="stunnel-&stunnel-version;">
20 <?dbhtml filename="stunnel.html"?>
21
22 <sect1info>
23 <othername>$LastChangedBy$</othername>
24 <date>$Date$</date>
25 </sect1info>
26
27 <title>stunnel-&stunnel-version;</title>
28
29 <indexterm zone="stunnel">
30 <primary sortas="a-stunnel">stunnel</primary>
31 </indexterm>
32
33 <sect2 role="package">
34 <title>Introduction to stunnel</title>
35
36 <para>The <application>stunnel</application> package contains a program
37 that allows you to encrypt arbitrary TCP connections inside SSL (Secure
38 Sockets Layer) so you can easily communicate with clients over secure
39 channels. <application>stunnel</application> can be used to add SSL
40 functionality to commonly used <application>Inetd</application> daemons
41 such as POP-2, POP-3, and IMAP servers, along with standalone daemons such
42 as NNTP, SMTP, and HTTP. <application>stunnel</application> can also be
43 used to tunnel PPP over network sockets without changes to the server
44 package source code.</para>
45
46 &lfs78_checked;
47
48 <bridgehead renderas="sect3">Package Information</bridgehead>
49 <itemizedlist spacing="compact">
50 <listitem>
51 <para>Download (HTTP): <ulink url="&stunnel-download-http;"/></para>
52 </listitem>
53 <listitem>
54 <para>Download (FTP): <ulink url="&stunnel-download-ftp;"/></para>
55 </listitem>
56 <listitem>
57 <para>Download MD5 sum: &stunnel-md5sum;</para>
58 </listitem>
59 <listitem>
60 <para>Download size: &stunnel-size;</para>
61 </listitem>
62 <listitem>
63 <para>Estimated disk space required: &stunnel-buildsize;</para>
64 </listitem>
65 <listitem>
66 <para>Estimated build time: &stunnel-time;</para>
67 </listitem>
68 </itemizedlist>
69
70 <bridgehead renderas="sect3">stunnel Dependencies</bridgehead>
71
72 <bridgehead renderas="sect4">Required</bridgehead>
73 <para role="required">
74 <xref linkend="openssl"/>
75 </para>
76
77 <bridgehead renderas="sect4">Optional</bridgehead>
78 <para role="optional">
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><userinput>./configure --prefix=/usr \
137 --sysconfdir=/etc \
138 --localstatedir=/var \
139 --disable-systemd &amp;&amp;
140make</userinput></screen>
141
142 <para>This package does not come with a test suite.</para>
143
144 <para>Now, as the <systemitem class="username">root</systemitem> user:</para>
145
146<screen role="root"><userinput>make docdir=/usr/share/doc/stunnel-&stunnel-version; install</userinput></screen>
147
148 <para>If you do not already have a signed SSL Certificate and Private Key,
149 create the <filename>stunnel.pem</filename> file in the
150 <filename class="directory">/etc/stunnel</filename> directory using the
151 command below. You will be prompted to enter the necessary
152 information. Ensure you reply to the</para>
153
154<screen><prompt>Common Name (FQDN of your server) [localhost]:</prompt></screen>
155
156 <para>prompt with the name or IP address you will be using
157 to access the service(s).</para>
158
159 <para>To generate a certificate, as the
160 <systemitem class="username">root</systemitem> user, issue:</para>
161
162<screen role="root"><userinput>make cert</userinput></screen>
163
164 </sect2>
165
166 <sect2 role="commands">
167 <title>Command Explanations</title>
168
169 <para><parameter>--disable-systemd</parameter>: This switch disables
170 systemd socket activation support which is not available in BLFS.</para>
171
172 <para><command>make docdir=... install</command>: This command installs the
173 package and changes the documentation installation directory to standard
174 naming conventions.</para>
175
176 </sect2>
177
178 <sect2 role="configuration">
179 <title>Configuring stunnel</title>
180
181 <sect3 id="stunnel-config">
182 <title>Config Files</title>
183
184 <para><filename>/etc/stunnel/stunnel.conf</filename></para>
185
186 <indexterm zone="stunnel stunnel-config">
187 <primary sortas="e-etc-stunnel-stunnel.conf">/etc/stunnel/stunnel.conf</primary>
188 </indexterm>
189
190 </sect3>
191
192 <sect3>
193 <title>Configuration Information</title>
194
195 <para>As the <systemitem class="username">root</systemitem> user,
196 create the directory used for the
197 <filename class="extension">.pid</filename> file created
198 when the <application>stunnel</application> daemon starts:</para>
199
200<screen role="root"><userinput>install -v -m750 -o stunnel -g stunnel -d /var/lib/stunnel/run &amp;&amp;
201chown stunnel:stunnel /var/lib/stunnel</userinput></screen>
202
203 <para>Next, create a basic <filename>/etc/stunnel/stunnel.conf</filename>
204 configuration file using the following commands as the
205 <systemitem class="username">root</systemitem> user:</para>
206
207<screen role="root"><userinput>cat &gt;/etc/stunnel/stunnel.conf &lt;&lt; "EOF" &amp;&amp;
208<literal>; File: /etc/stunnel/stunnel.conf
209
210; Note: The pid and output locations are relative to the chroot location.
211
212pid = /run/stunnel.pid
213chroot = /var/lib/stunnel
214client = no
215setuid = stunnel
216setgid = stunnel
217cert = /etc/stunnel/stunnel.pem
218
219;debug = 7
220;output = stunnel.log
221
222;[https]
223;accept = 443
224;connect = 80
225;; "TIMEOUTclose = 0" is a workaround for a design flaw in Microsoft SSL
226;; Microsoft implementations do not use SSL close-notify alert and thus
227;; they are vulnerable to truncation attacks
228;TIMEOUTclose = 0</literal>
229
230EOF</userinput></screen>
231
232 <para>Finally, add the service(s) you wish to encrypt to the
233 configuration file. The format is as follows:</para>
234
235<screen><literal>[<replaceable>&lt;service&gt;</replaceable>]
236accept = <replaceable>&lt;hostname:portnumber&gt;</replaceable>
237connect = <replaceable>&lt;hostname:portnumber&gt;</replaceable></literal></screen>
238
239 <para>If you use <application>stunnel</application> to encrypt a daemon
240 started from <command>[x]inetd</command>, you may need to disable that
241 daemon in the <filename>/etc/[x]inetd.conf</filename> file and enable a
242 corresponding <replaceable>&lt;service&gt;</replaceable>_stunnel service. You
243 may have to add an appropriate entry in <filename>/etc/services</filename>
244 as well.</para>
245
246 <para>For a full explanation of the commands and syntax used in the
247 configuration file, issue <command>man stunnel</command>.</para>
248
249 </sect3>
250
251 <sect3 id="stunnel-init">
252 <title>Boot Script</title>
253
254 <para>To automatically start the <command>stunnel</command> daemon
255 when the system is booted, install the
256 <filename>/etc/rc.d/init.d/stunnel</filename> bootscript from the
257 <xref linkend="bootscripts"/> package.</para>
258
259 <indexterm zone="stunnel stunnel-init">
260 <primary sortas="f-stunnel">stunnel</primary>
261 </indexterm>
262
263<screen role="root"><userinput>make install-stunnel</userinput></screen>
264
265 </sect3>
266
267 </sect2>
268
269 <sect2 role="content">
270 <title>Contents</title>
271
272 <segmentedlist>
273 <segtitle>Installed Programs</segtitle>
274 <segtitle>Installed Library</segtitle>
275 <segtitle>Installed Directories</segtitle>
276
277 <seglistitem>
278 <seg>
279 stunnel and stunnel3
280 </seg>
281 <seg>
282 libstunnel.so
283 </seg>
284 <seg>
285 /{etc,usr/lib,var/lib}/stunnel and
286 /usr/share/doc/stunnel-&stunnel-version;
287 </seg>
288 </seglistitem>
289 </segmentedlist>
290
291 <variablelist>
292 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
293 <?dbfo list-presentation="list"?>
294 <?dbhtml list-presentation="table"?>
295
296 <varlistentry id="stunnel-prog">
297 <term><command>stunnel</command></term>
298 <listitem>
299 <para> is a program designed to work as an SSL
300 encryption wrapper between remote clients and local
301 (<command>{x}inetd</command>-startable) or remote servers.</para>
302 <indexterm zone="stunnel stunnel-prog">
303 <primary sortas="b-stunnel">stunnel</primary>
304 </indexterm>
305 </listitem>
306 </varlistentry>
307
308 <varlistentry id="stunnel3">
309 <term><command>stunnel3</command></term>
310 <listitem>
311 <para>is a <application>Perl</application> wrapper script to use
312 <command>stunnel</command> 3.x syntax with <command>stunnel</command>
313 >=4.05.</para>
314 <indexterm zone="stunnel stunnel3">
315 <primary sortas="b-stunnel3">stunnel3</primary>
316 </indexterm>
317 </listitem>
318 </varlistentry>
319
320 <varlistentry id="libstunnel">
321 <term><filename class='libraryfile'>libstunnel.so</filename></term>
322 <listitem>
323 <para> contains the API functions required by
324 <application>stunnel</application>.</para>
325 <indexterm zone="stunnel libstunnel">
326 <primary sortas="c-libstunnel">libstunnel.so</primary>
327 </indexterm>
328 </listitem>
329 </varlistentry>
330
331 </variablelist>
332
333 </sect2>
334
335</sect1>
Note: See TracBrowser for help on using the repository browser.