source: postlfs/security/stunnel.xml@ 9659858

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 9659858 was 9659858, checked in by Fernando de Oliveira <fernando@…>, 7 years ago
  • stunnel-5.24: forgot to remove one brace level.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@16545 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 <!-- 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<!-- <!ENTITY stunnel-download-ftp "ftp://ftp.stunnel.org/stunnel/stunnel-&stunnel-version;.tar.gz"> -->
12 <!ENTITY stunnel-md5sum "24ad1f10525181edcf82433aac8bad0b">
13 <!ENTITY stunnel-size "620 KB">
14 <!ENTITY stunnel-buildsize "7.9 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 &lfs78_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="ftp://ftp.porcupine.org/pub/security/">tcpwrappers</ulink> and
79 <ulink url="https://dist.torproject.org/">TOR</ulink>
80 </para>
81
82 <para condition="html" role="usernotes">User Notes:
83 <ulink url="&blfs-wiki;/stunnel"/></para>
84
85 </sect2>
86
87 <sect2 role="installation">
88 <title>Installation of stunnel</title>
89
90 <para>The <command>stunnel</command> daemon will be run in a
91 <command>chroot</command> jail by an unprivileged user. Create the
92 new user and group using the following commands as the
93 <systemitem class="username">root</systemitem> user:</para>
94
95<screen role="root"><userinput>groupadd -g 51 stunnel &amp;&amp;
96useradd -c "stunnel Daemon" -d /var/lib/stunnel \
97 -g stunnel -s /bin/false -u 51 stunnel</userinput></screen>
98
99 <note>
100 <para>A signed SSL Certificate and a Private Key is necessary to run the
101 <command>stunnel</command> daemon. After the package is installed, there
102 are instructions to generate them. However, if you own or have already
103 created a signed SSL Certificate you wish to use, copy it to
104 <filename>/etc/stunnel/stunnel.pem</filename> before starting the build
105 (ensure only <systemitem class="username">root</systemitem> has read and
106 write access). The <filename class="extension">.pem</filename> file must
107 be formatted as shown below:</para>
108
109<screen><literal>-----BEGIN PRIVATE KEY-----
110<replaceable>&lt;many encrypted lines of private key&gt;</replaceable>
111-----END PRIVATE KEY-----
112-----BEGIN CERTIFICATE-----
113<replaceable>&lt;many encrypted lines of certificate&gt;</replaceable>
114-----END CERTIFICATE-----
115-----BEGIN DH PARAMETERS-----
116<replaceable>&lt;encrypted lines of dh parms&gt;</replaceable>
117-----END DH PARAMETERS-----</literal></screen>
118 </note>
119
120 <para>Install <application>stunnel</application> by running the following
121 commands:</para>
122
123 <note>
124 <para>For some systems with <application>binutils</application>
125 versions prior to 2.25, <command>configure</command> may fail. If
126 necessary, fix it either with:</para>
127
128<screen><userinput>sed -i '/LDFLAGS.*static_flag/ s/^/#/' configure</userinput></screen>
129
130 <para>or, if <xref linkend="llvm"/> with Clang is installed, you can
131 replace <command>./configure ...</command> with <command>CC=clang
132 ./configure ...</command> in the first command below.</para>
133 </note>
134
135<screen><userinput>./configure --prefix=/usr \
136 --sysconfdir=/etc \
137 --localstatedir=/var \
138 --disable-systemd &amp;&amp;
139make</userinput></screen>
140
141 <para>This package does not come with a test suite.</para>
142
143 <para>Now, as the <systemitem class="username">root</systemitem> user:</para>
144
145<screen role="root"><userinput>make docdir=/usr/share/doc/stunnel-&stunnel-version; install</userinput></screen>
146
147 <para>If you do not already have a signed SSL Certificate and Private Key,
148 create the <filename>stunnel.pem</filename> file in the
149 <filename class="directory">/etc/stunnel</filename> directory using the
150 command below. You will be prompted to enter the necessary
151 information. Ensure you reply to the</para>
152
153<screen><prompt>Common Name (FQDN of your server) [localhost]:</prompt></screen>
154
155 <para>prompt with the name or IP address you will be using
156 to access the service(s).</para>
157
158 <para>To generate a certificate, as the
159 <systemitem class="username">root</systemitem> user, issue:</para>
160
161<screen role="root"><userinput>make cert</userinput></screen>
162
163 </sect2>
164
165 <sect2 role="commands">
166 <title>Command Explanations</title>
167
168 <para><parameter>--disable-systemd</parameter>: This switch disables
169 systemd socket activation support which is not available in BLFS.</para>
170
171 <para><command>make docdir=... install</command>: This command installs the
172 package and changes the documentation installation directory to standard
173 naming conventions.</para>
174
175 </sect2>
176
177 <sect2 role="configuration">
178 <title>Configuring stunnel</title>
179
180 <sect3 id="stunnel-config">
181 <title>Config Files</title>
182
183 <para><filename>/etc/stunnel/stunnel.conf</filename></para>
184
185 <indexterm zone="stunnel stunnel-config">
186 <primary sortas="e-etc-stunnel-stunnel.conf">/etc/stunnel/stunnel.conf</primary>
187 </indexterm>
188
189 </sect3>
190
191 <sect3>
192 <title>Configuration Information</title>
193
194 <para>As the <systemitem class="username">root</systemitem> user,
195 create the directory used for the
196 <filename class="extension">.pid</filename> file created
197 when the <application>stunnel</application> daemon starts:</para>
198
199<screen role="root"><userinput>install -v -m750 -o stunnel -g stunnel -d /var/lib/stunnel/run &amp;&amp;
200chown stunnel:stunnel /var/lib/stunnel</userinput></screen>
201
202 <para>Next, create a basic <filename>/etc/stunnel/stunnel.conf</filename>
203 configuration file using the following commands as the
204 <systemitem class="username">root</systemitem> user:</para>
205
206<screen role="root"><userinput>cat &gt;/etc/stunnel/stunnel.conf &lt;&lt; "EOF" &amp;&amp;
207<literal>; File: /etc/stunnel/stunnel.conf
208
209; Note: The pid and output locations are relative to the chroot location.
210
211pid = /run/stunnel.pid
212chroot = /var/lib/stunnel
213client = no
214setuid = stunnel
215setgid = stunnel
216cert = /etc/stunnel/stunnel.pem
217
218;debug = 7
219;output = stunnel.log
220
221;[https]
222;accept = 443
223;connect = 80
224;; "TIMEOUTclose = 0" is a workaround for a design flaw in Microsoft SSL
225;; Microsoft implementations do not use SSL close-notify alert and thus
226;; they are vulnerable to truncation attacks
227;TIMEOUTclose = 0</literal>
228
229EOF
230chmod -v 644 /etc/stunnel/stunnel.conf</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.