[thirdparty/strongswan.git] / doc / upgrading.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>Introduction to FreeS/WAN</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
<STYLE TYPE="text/css"><!--
BODY { font-family: serif }
H1 { font-family: sans-serif }
H2 { font-family: sans-serif }
H3 { font-family: sans-serif }
H4 { font-family: sans-serif }
H5 { font-family: sans-serif }
H6 { font-family: sans-serif }
SUB { font-size: smaller }
SUP { font-size: smaller }
PRE { font-family: monospace }
--></STYLE>
</HEAD>
<BODY>
<A HREF="toc.html">Contents</A>
<A HREF="intro.html">Previous</A>
<A HREF="quickstart.html">Next</A>
<HR>
<A NAME="upgrading"></A>
<H1><A NAME="2">Upgrading to FreeS/WAN 2.x</A></H1>
<H2><A NAME="2_1">New! Built in Opportunistic connections</A></H2>
<P>Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP
 traffic. It will try to establish IPsec connections for:</P>
<UL>
<LI> IP traffic from the Linux box on which you have installed
 FreeS/WAN, and</LI>
<LI> outbound IP traffic routed through that Linux box (eg. from a
 protected subnet).</LI>
</UL>
<P>FreeS/WAN 2.x uses<STRONG> hidden, automatically enabled<VAR>
 ipsec.conf</VAR> connections</STRONG> to do this.</P>
<P>This behaviour is part of our campaign to get Opportunistic
 Encryption (OE) widespread in the Linux world, so that any two Linux
 boxes can encrypt to one another without prearrangement. There's one
 catch, however: you must<A HREF="quickstart.html#quickstart"> set up a
 few DNS records</A> to distribute RSA public keys and (if applicable)
 IPsec gateway information.</P>
<P>If you start FreeS/WAN before you have set up these DNS records, your
 connectivity will be slow, and messages relating to the built in
 connections will clutter your logs. If you are unable to set up DNS for
 OE, you will wish to<A HREF="policygroups.html#disable_policygroups">
 disable the hidden connections</A>.</P>
<A NAME="upgrading.flagday"></A>
<H3><A NAME="2_1_1">Upgrading Opportunistic Encryption to 2.01 (or
 later)</A></H3>
<P>As of FreeS/WAN 2.01, Opportunistic Encryption (OE) uses DNS TXT
 resource records (RRs) only (rather than TXT with KEY). This change
 causes a &quot;flag day&quot;. Users of FreeS/WAN 2.00 (or earlier) OE who are
 upgrading may need to post additional resource records.</P>
<P>If you are running<A HREF="glossary.html#initiate-only">
 initiate-only OE</A>, you<EM> must</EM> put up a TXT record in any
 forward domain as per our<A HREF="quickstart.html#opp.client">
 quickstart instructions</A>. This replaces your old forward KEY.</P>
<P> If you are running full OE, you require no updates. You already have
 the needed TXT record in the reverse domain. However, to facilitate
 future features, you may also wish to publish that TXT record in a
 forward domain as instructed<A HREF="quickstart.html#opp.incoming">
 here</A>.</P>
<P>If you are running OE on a gateway (and encrypting on behalf of
 subnetted boxes) you require no updates. You already have the required
 TXT record in your gateway's reverse map, and the TXT records for any
 subnetted boxes require no updating. However, to facilitate future
 features, you may wish to publish your gateway's TXT record in a
 forward domain as shown<A HREF="quickstart.html#opp.incoming"> here</A>
.</P>
<P> During the transition, you may wish to leave any old KEY records up
 for some time. They will provide limited backward compatibility.
<!--
For more
detail on that compatibility, see <A HREF="oe.known-issues">Known Issues with
OE</A>.
-->
</P>
<H2><A NAME="2_2">New! Policy Groups</A></H2>
<P>We want to make it easy for you to declare security policy as it
 applies to IPsec connections.</P>
<P>Policy Groups make it simple to say:</P>
<UL>
<LI>These are the folks I want to talk to in the clear.</LI>
<LI>These spammers' domains -- I don't want to talk to them at all.</LI>
<LI>To talk to the finance department, I must use IPsec.</LI>
<LI>For any other communication, try to encrypt, but it's okay if we
 can't.</LI>
</UL>
<P>FreeS/WAN then implements these policies, creating OE connections if
 and when needed. You can use Policy Groups along with connections you
 explicitly define in ipsec.conf.</P>
<P>For more information, see our<A HREF="policygroups.html"> Policy
 Group HOWTO</A>.</P>
<H2><A NAME="2_3">New! Packetdefault Connection</A></H2>
<P>Free/SWAN 2.x ships with the<STRONG> automatically enabled, hidden
 connection</STRONG><VAR> packetdefault</VAR>. This configures a
 FreeS/WAN box as an OE gateway for any hosts located behind it. As
 mentioned above, you must configure some<A HREF="quickstart.html"> DNS
 records</A> for OE to work.</P>
<P>As the name implies, this connection functions as a default. If you
 have more specific connections, such as policy groups which configure
 your FreeS/WAN box as an OE gateway for a local subnet, these will
 apply before<VAR> packetdefault</VAR>. You can view<VAR> packetdefault</VAR>
's specifics in<A HREF="manpage.d/ipsec.conf.5.html"> man ipsec.conf</A>
.</P>
<H2><A NAME="2_4">FreeS/WAN now disables Reverse Path Filtering</A></H2>
<P>FreeS/WAN often doesn't work with reverse path filtering. At start
 time, FreeS/WAN now turns rp_filter off, and logs a warning.</P>
<P>FreeS/WAN does not turn it back on again. You can do this yourself
 with a command like:</P>
<PRE>   echo 1 &gt; /proc/sys/net/ipv4/conf/eth0/rp_filter</PRE>
<P>For eth0, substitute the interface which FreeS/WAN was affecting.</P>
<A NAME="ipsec.conf_v2"></A>
<H2><A NAME="2_5">Revised<VAR> ipsec.conf</VAR></A></H2>
<H3><A NAME="2_5_1">No promise of compatibility</A></H3>
<P>The FreeS/WAN team promised config-file compatibility throughout the
 1.x series. That means a 1.5 config file can be directly imported into
 a fresh 1.99 install with no problems.</P>
<P>With FreeS/WAN 2.x, we've given ourselves permission to make the
 config file easier to use. The cost: some FreeS/WAN 1.x configurations
 will not work properly. Many of the new features are, however, backward
 compatible.</P>
<H3><A NAME="2_5_2">Most<VAR> ipsec.conf</VAR> files will work fine</A></H3>
<P>... so long as you paste this line,<STRONG> with no preceding
 whitespace</STRONG>, at the top of your config file:</P>
<PRE>    version 2</PRE>
<H3><A NAME="2_5_3">Backward compatibility patch</A></H3>
<P>If the new defaults bite you, use<A HREF="ipsec.conf.2_to_1"> this<VAR>
 ipsec.conf</VAR> fragment</A> to simulate the old default values.</P>
<H3><A NAME="2_5_4">Details</A></H3>
<P> We've obsoleted various directives which almost no one was using:</P>
<PRE>    dump
    plutobackgroundload
    no_eroute_pass
    lifetime
    rekeystart
    rekeytries</PRE>
<P>For most of these, there is some other way to elicit the desired
 behaviour. See<A HREF="http://lists.freeswan.org/pipermail/design/2002-August/003243.html">
 this post</A>.</P>
<P> We've made some settings, which almost everyone was using, defaults.
 For example:</P>
<PRE>    interfaces=%defaultroute
    plutoload=%search
    plutostart=%search
    uniqueids=yes</PRE>
<P>We've also changed some default values to help with OE and Policy
 Groups:</P>
<PRE>    authby=rsasig   ## not secret!!!
    leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed.
    rightrsasigkey=%dnsondemand</PRE>
<P> Of course, you can still override any defaults by explictly
 declaring something else in your connection.</P>
<P><A HREF="http://lists.freeswan.org/pipermail/design/2002-August/003243.html">
 A post with a list of many ipsec.conf changes.</A>
<BR><A HREF="manpage.d/ipsec.conf.5.html"> Current ipsec.conf manual.</A>
</P>
<A NAME="upgrading.rpms"></A>
<H3><A NAME="2_5_5">Upgrading from 1.x RPMs to 2.x RPMs</A></H3>
<P>Note: When upgrading from 1-series to 2-series RPMs,<VAR> rpm -U</VAR>
 will not work.</P>
<P>You must instead erase the 1.x RPMs, then install the 2.x set:</P>
<PRE>    rpm -e freeswan</PRE>
<PRE>    rpm -e freeswan-module</PRE>
<P>On erasing, your old<VAR> ipsec.conf</VAR> should be moved to<VAR>
 ipsec.conf.rpmsave</VAR>. Keep this. You will probably want to copy
 your existing connections to the end of your new 2.x file.</P>
<P>Install the RPMs suitable for your kernel version, such as:</P>
<PRE>    rpm -ivh freeswan-module-2.04_2.4.20_20.9-0.i386.rpm</PRE>
<PRE>    rpm -ivh freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm</PRE>
<P>Or, to splice the files:</P>
<PRE>    cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave &gt; /etc/ipsec.conf.tmp
    mv /etc/ipsec.conf.tmp /etc/ipsec.conf</PRE>
<P>Then, remove the redundant<VAR> conn %default</VAR> and<VAR> config
 setup</VAR> sections. Unless you have done any special configuring
 here, you'll likely want to remove the 1.x versions. Remove<VAR> conn
 OEself</VAR>, if present.</P>
<HR>
<A HREF="toc.html">Contents</A>
<A HREF="intro.html">Previous</A>
<A HREF="quickstart.html">Next</A>
</BODY>
</HTML>
Commit	Line	Data
997358a6 MW	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
	2	<HTML>
	3	<HEAD>
	4	<TITLE>Introduction to FreeS/WAN</TITLE>
	5	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso-8859-1">
	6	<STYLE TYPE="text/css"><!--
	7	BODY { font-family: serif }
	8	H1 { font-family: sans-serif }
	9	H2 { font-family: sans-serif }
	10	H3 { font-family: sans-serif }
	11	H4 { font-family: sans-serif }
	12	H5 { font-family: sans-serif }
	13	H6 { font-family: sans-serif }
	14	SUB { font-size: smaller }
	15	SUP { font-size: smaller }
	16	PRE { font-family: monospace }
	17	--></STYLE>
	18	</HEAD>
	19	<BODY>
	20	<A HREF="toc.html">Contents</A>
	21	<A HREF="intro.html">Previous</A>
	22	<A HREF="quickstart.html">Next</A>
	23	<HR>
	24	<A NAME="upgrading"></A>
	25	<H1><A NAME="2">Upgrading to FreeS/WAN 2.x</A></H1>
	26	<H2><A NAME="2_1">New! Built in Opportunistic connections</A></H2>
	27	<P>Out of the box, FreeS/WAN 2.x will attempt to encrypt all your IP
	28	traffic. It will try to establish IPsec connections for:</P>
	29	<UL>
	30	<LI> IP traffic from the Linux box on which you have installed
	31	FreeS/WAN, and</LI>
	32	<LI> outbound IP traffic routed through that Linux box (eg. from a
	33	protected subnet).</LI>
	34	</UL>
	35	<P>FreeS/WAN 2.x uses<STRONG> hidden, automatically enabled<VAR>
	36	ipsec.conf</VAR> connections</STRONG> to do this.</P>
	37	<P>This behaviour is part of our campaign to get Opportunistic
	38	Encryption (OE) widespread in the Linux world, so that any two Linux
	39	boxes can encrypt to one another without prearrangement. There's one
	40	catch, however: you must<A HREF="quickstart.html#quickstart"> set up a
	41	few DNS records</A> to distribute RSA public keys and (if applicable)
	42	IPsec gateway information.</P>
	43	<P>If you start FreeS/WAN before you have set up these DNS records, your
	44	connectivity will be slow, and messages relating to the built in
	45	connections will clutter your logs. If you are unable to set up DNS for
	46	OE, you will wish to<A HREF="policygroups.html#disable_policygroups">
	47	disable the hidden connections</A>.</P>
	48	<A NAME="upgrading.flagday"></A>
	49	<H3><A NAME="2_1_1">Upgrading Opportunistic Encryption to 2.01 (or
	50	later)</A></H3>
	51	<P>As of FreeS/WAN 2.01, Opportunistic Encryption (OE) uses DNS TXT
	52	resource records (RRs) only (rather than TXT with KEY). This change
	53	causes a "flag day". Users of FreeS/WAN 2.00 (or earlier) OE who are
	54	upgrading may need to post additional resource records.</P>
	55	<P>If you are running<A HREF="glossary.html#initiate-only">
	56	initiate-only OE</A>, you<EM> must</EM> put up a TXT record in any
	57	forward domain as per our<A HREF="quickstart.html#opp.client">
	58	quickstart instructions</A>. This replaces your old forward KEY.</P>
	59	<P> If you are running full OE, you require no updates. You already have
	60	the needed TXT record in the reverse domain. However, to facilitate
	61	future features, you may also wish to publish that TXT record in a
	62	forward domain as instructed<A HREF="quickstart.html#opp.incoming">
	63	here</A>.</P>
	64	<P>If you are running OE on a gateway (and encrypting on behalf of
65	subnetted boxes) you require no updates. You already have the required
66	TXT record in your gateway's reverse map, and the TXT records for any
67	subnetted boxes require no updating. However, to facilitate future
68	features, you may wish to publish your gateway's TXT record in a
69	forward domain as shown<A HREF="quickstart.html#opp.incoming"> here</A>
70	.</P>
71	<P> During the transition, you may wish to leave any old KEY records up
72	for some time. They will provide limited backward compatibility.
73	<!--
74	For more
75	detail on that compatibility, see <A HREF="oe.known-issues">Known Issues with
76	OE</A>.
77	-->
78	</P>
79	<H2><A NAME="2_2">New! Policy Groups</A></H2>
80	<P>We want to make it easy for you to declare security policy as it
81	applies to IPsec connections.</P>
82	<P>Policy Groups make it simple to say:</P>
83	<UL>
84	<LI>These are the folks I want to talk to in the clear.</LI>
85	<LI>These spammers' domains -- I don't want to talk to them at all.</LI>
86	<LI>To talk to the finance department, I must use IPsec.</LI>
87	<LI>For any other communication, try to encrypt, but it's okay if we
88	can't.</LI>
89	</UL>
90	<P>FreeS/WAN then implements these policies, creating OE connections if
91	and when needed. You can use Policy Groups along with connections you
92	explicitly define in ipsec.conf.</P>
93	<P>For more information, see our<A HREF="policygroups.html"> Policy
94	Group HOWTO</A>.</P>
95	<H2><A NAME="2_3">New! Packetdefault Connection</A></H2>
96	<P>Free/SWAN 2.x ships with the<STRONG> automatically enabled, hidden
97	connection</STRONG><VAR> packetdefault</VAR>. This configures a
98	FreeS/WAN box as an OE gateway for any hosts located behind it. As
99	mentioned above, you must configure some<A HREF="quickstart.html"> DNS
100	records</A> for OE to work.</P>
101	<P>As the name implies, this connection functions as a default. If you
102	have more specific connections, such as policy groups which configure
103	your FreeS/WAN box as an OE gateway for a local subnet, these will
104	apply before<VAR> packetdefault</VAR>. You can view<VAR> packetdefault</VAR>
105	's specifics in<A HREF="manpage.d/ipsec.conf.5.html"> man ipsec.conf</A>
106	.</P>
107	<H2><A NAME="2_4">FreeS/WAN now disables Reverse Path Filtering</A></H2>
108	<P>FreeS/WAN often doesn't work with reverse path filtering. At start
109	time, FreeS/WAN now turns rp_filter off, and logs a warning.</P>
110	<P>FreeS/WAN does not turn it back on again. You can do this yourself
111	with a command like:</P>
112	<PRE> echo 1 > /proc/sys/net/ipv4/conf/eth0/rp_filter</PRE>
113	<P>For eth0, substitute the interface which FreeS/WAN was affecting.</P>
114	<A NAME="ipsec.conf_v2"></A>
115	<H2><A NAME="2_5">Revised<VAR> ipsec.conf</VAR></A></H2>
116	<H3><A NAME="2_5_1">No promise of compatibility</A></H3>
117	<P>The FreeS/WAN team promised config-file compatibility throughout the
118	1.x series. That means a 1.5 config file can be directly imported into
119	a fresh 1.99 install with no problems.</P>
120	<P>With FreeS/WAN 2.x, we've given ourselves permission to make the
121	config file easier to use. The cost: some FreeS/WAN 1.x configurations
122	will not work properly. Many of the new features are, however, backward
123	compatible.</P>
124	<H3><A NAME="2_5_2">Most<VAR> ipsec.conf</VAR> files will work fine</A></H3>
125	<P>... so long as you paste this line,<STRONG> with no preceding
126	whitespace</STRONG>, at the top of your config file:</P>
127	<PRE> version 2</PRE>
128	<H3><A NAME="2_5_3">Backward compatibility patch</A></H3>
129	<P>If the new defaults bite you, use<A HREF="ipsec.conf.2_to_1"> this<VAR>
130	ipsec.conf</VAR> fragment</A> to simulate the old default values.</P>
131	<H3><A NAME="2_5_4">Details</A></H3>
132	<P> We've obsoleted various directives which almost no one was using:</P>
133	<PRE> dump
134	plutobackgroundload
135	no_eroute_pass
136	lifetime
137	rekeystart
138	rekeytries</PRE>
139	<P>For most of these, there is some other way to elicit the desired
140	behaviour. See<A HREF="http://lists.freeswan.org/pipermail/design/2002-August/003243.html">
141	this post</A>.</P>
142	<P> We've made some settings, which almost everyone was using, defaults.
143	For example:</P>
144	<PRE> interfaces=%defaultroute
145	plutoload=%search
146	plutostart=%search
147	uniqueids=yes</PRE>
148	<P>We've also changed some default values to help with OE and Policy
149	Groups:</P>
150	<PRE> authby=rsasig ## not secret!!!
151	leftrsasigkey=%dnsondemand ## looks up missing keys in DNS when needed.
152	rightrsasigkey=%dnsondemand</PRE>
153	<P> Of course, you can still override any defaults by explictly
154	declaring something else in your connection.</P>
155	<P><A HREF="http://lists.freeswan.org/pipermail/design/2002-August/003243.html">
156	A post with a list of many ipsec.conf changes.</A>
157	<BR><A HREF="manpage.d/ipsec.conf.5.html"> Current ipsec.conf manual.</A>
158	</P>
159	<A NAME="upgrading.rpms"></A>
160	<H3><A NAME="2_5_5">Upgrading from 1.x RPMs to 2.x RPMs</A></H3>
161	<P>Note: When upgrading from 1-series to 2-series RPMs,<VAR> rpm -U</VAR>
162	will not work.</P>
163	<P>You must instead erase the 1.x RPMs, then install the 2.x set:</P>
164	<PRE> rpm -e freeswan</PRE>
165	<PRE> rpm -e freeswan-module</PRE>
166	<P>On erasing, your old<VAR> ipsec.conf</VAR> should be moved to<VAR>
167	ipsec.conf.rpmsave</VAR>. Keep this. You will probably want to copy
168	your existing connections to the end of your new 2.x file.</P>
169	<P>Install the RPMs suitable for your kernel version, such as:</P>
170	<PRE> rpm -ivh freeswan-module-2.04_2.4.20_20.9-0.i386.rpm</PRE>
171	<PRE> rpm -ivh freeswan-userland-2.04_2.4.20_20.9-0.i386.rpm</PRE>
172	<P>Or, to splice the files:</P>
173	<PRE> cat /etc/ipsec.conf /etc/ipsec.conf.rpmsave > /etc/ipsec.conf.tmp
174	mv /etc/ipsec.conf.tmp /etc/ipsec.conf</PRE>
175	<P>Then, remove the redundant<VAR> conn %default</VAR> and<VAR> config
176	setup</VAR> sections. Unless you have done any special configuring
177	here, you'll likely want to remove the 1.x versions. Remove<VAR> conn
178	OEself</VAR>, if present.</P>
179	<HR>
180	<A HREF="toc.html">Contents</A>
181	<A HREF="intro.html">Previous</A>
182	<A HREF="quickstart.html">Next</A>
183	</BODY>
184	</HTML>