source: postlfs/security/stunnel-systemd.xml@ 295ca00

systemd-13485
Last change on this file since 295ca00 was 295ca00, checked in by Douglas R. Reno <renodr@…>, 6 years ago

Update to Sudo-1.8.15 (merged from trunk r16594)
Update to stunnel-5.29 (merged from trunk r16797)
Update to ssh-askpass-4.1p2 (merged from trunk r16811)
Update to p11-kit-0.23.2 (merged from trunk r16716)
Update to OpenSSL-1.0.2e (merged from trunk r16708)
Update to OpenSSH-7.1p2 (merged from trunk r16811)
Update to NSS-3.21 (merged from trunk r16627)
Update to MIT Kerberos V5-1.14 (merged from trunk r16679)
Update to iptables-1.6.0 (merged from trunk r16742)
Update to GPGME-1.6.0 (merged from trunk r16360)
Update to GnuTLS-3.4.8 (merged from trunk r16797)

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/branches/systemd@16833 af4574ff-66df-0310-9fd7-8a98e5e911e0

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