doc/policygroups.html

   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="quickstart.html">Previous</A>
  22 <A HREF="faq.html">Next</A>
  23 <HR>
  24 <H1><A NAME="4">How to Configure Linux FreeS/WAN with Policy Groups</A></H1>
  25 <A NAME="policygroups"></A>
  26 <H2><A NAME="4_1">What are Policy Groups?</A></H2>
  27 <P><STRONG>Policy Groups</STRONG> are an elegant general mechanism to
  28  configure FreeS/WAN. They are useful for many FreeS/WAN users.</P>
  29 <P>In previous FreeS/WAN versions, you needed to configure each IPsec
  30  connection explicitly, on both local and remote hosts. This could
  31  become complex.</P>
  32 <P>By contrast, Policy Groups allow you to set local IPsec policy for
  33  lists of remote hosts and networks, simply by listing the hosts and
  34  networks which you wish to have special treatment in one of several
  35  Policy Group files. FreeS/WAN then internally creates the connections
  36  needed to implement each policy.</P>
  37 <P>In the next section we describe our five Base Policy Groups, which
  38  you can use to configure IPsec in many useful ways. Later, we will show
  39  you how to create an IPsec VPN using one line of configuration for each
  40  remote host or network.</P>
  41 <A NAME="builtin_policygroups"></A>
  42 <H3><A NAME="4_1_1">Built-In Security Options</A></H3>
  43 <P>FreeS/WAN offers these Base Policy Groups:</P>
  44 <DL>
  45 <DT>private</DT>
  46 <DD> FreeS/WAN only communicates privately with the listed<A HREF="glossary.html#CIDR">
  47  CIDR</A> blocks. If needed, FreeS/WAN attempts to create a connection
  48  opportunistically. If this fails, FreeS/WAN blocks communication.
  49  Inbound blocking is assumed to be done by the firewall. FreeS/WAN
  50  offers firewall hooks but no modern firewall rules to help with inbound
  51  blocking.</DD>
  52 <DT>private-or-clear</DT>
  53 <DD> FreeS/WAN prefers private communication with the listed CIDR
  54  blocks. If needed, FreeS/WAN attempts to create a connection
  55  opportunistically. If this fails, FreeS/WAN allows traffic in the
  56  clear.</DD>
  57 <DT>clear-or-private</DT>
  58 <DD> FreeS/WAN communicates cleartext with the listed CIDR blocks, but
  59  also accepts inbound OE connection requests from them. Also known as<A HREF="glossary.html#passive.OE">
  60  passive OE (pOE)</A>, this policy may be used to create an<A HREF="glossary.html#responder">
  61  opportunistic responder</A>.</DD>
  62 <DT>clear</DT>
  63 <DD> FreeS/WAN only communicates cleartext with the listed CIDR blocks.</DD>
  64 <DT>block</DT>
  65 <DD>FreeS/WAN blocks traffic to and from and the listed CIDR blocks.
  66  Inbound blocking is assumed to be done by the firewall. FreeS/WAN
  67  offers firewall hooks but no modern firewall rules to help with inbound
  68  blocking.
  69 <!-- also called "blockdrop".-->
  70 </DD>
  71 </DL>
  72 <A NAME="policy.group.notes"></A>
  73 <P>Notes:</P>
  74 <UL>
  75 <LI>Base Policy Groups apply to communication with this host only.</LI>
  76 <LI>The most specific rule (whether policy or pre-configured connection)
  77  applies. This has several practical applications:
  78 <UL>
  79 <LI>If CIDR blocks overlap, FreeS/WAN chooses the most specific
  80  applicable block.</LI>
  81 <LI>This decision also takes into account any pre-configured connections
  82  you may have.</LI>
  83 <LI>If the most specific connection is a pre-configured connection, the
  84  following procedure applies. If that connection is up, it will be used.
  85  If it is routed, it will be brought up. If it is added, no action will
  86  be taken.</LI>
  87 </UL>
  88 </LI>
  89 <LI>Base Policy Groups are created using built-in connections. Details
  90  in<A HREF="manpage.d/ipsec.conf.5.html"> man ipsec.conf</A>.</LI>
  91 <LI>All Policy Groups are bidirectional.<A HREF="src/policy-groups-table.html">
  92  This chart</A> shows some technical details. FreeS/WAN does not support
  93  one-way encryption, since it can give users a false sense of security.</LI>
  94 </UL>
  95 <H2><A NAME="4_2">Using Policy Groups</A></H2>
  96 <P>The Base Policy Groups which build IPsec connections rely on
  97  Opportunistic Encryption. To use the following examples, you must first
  98  become OE-capable, as described in our<A HREF="quickstart.html#quickstart">
  99  quickstart guide</A>.<A NAME="example1"></A></P>
 100 <H3><A NAME="4_2_1">Example 1: Using a Base Policy Group</A></H3>
 101 <P>Simply place CIDR blocks (<A HREF="#dnswarning">names</A>, IPs or IP
 102  ranges) in /etc/ipsec.d/policies/<VAR>[groupname]</VAR>, and reread the
 103  policy group files.</P>
 104 <P>For example, the<VAR> private-or-clear</VAR> policy tells FreeS/WAN
 105  to prefer encrypted communication to the listed CIDR blocks. Failing
 106  that, it allows talk in the clear.</P>
 107 <P>To make this your default policy, place<A HREF="glossary.html#fullnet">
 108  fullnet</A> in the<VAR> private-or-clear</VAR> policy group file:</P>
 109 <PRE>    [root@xy root]# cat /etc/ipsec.d/policies/private-or-clear
 110     # This file defines the set of CIDRs (network/mask-length) to which
 111     # communication should be private, if possible, but in the clear otherwise.
 112     ....
 113     0.0.0.0/0</PRE>
 114 <P>and reload your policies with</P>
 115 <PRE>    ipsec auto --rereadgroups</PRE>
 116 <P>Use<A HREF="quickstart.html#opp.test"> this test</A> to verify
 117  opportunistic connections.</P>
 118 <A NAME="example2"></A>
 119 <H3><A NAME="4_2_2">Example 2: Defining IPsec Security Policy with
 120  Groups</A></H3>
 121 <P>Defining IPsec security policy with Base Policy Groups is like
 122  creating a shopping list: just put CIDR blocks in the appropriate group
 123  files. For example:</P>
 124 <PRE>    [root@xy root]# cd /etc/ipsec.d/policies
 125     [root@xy policies]# cat private
 126         192.0.2.96/27              # The finance department
 127         192.0.2.192/29             # HR
 128         192.0.2.12                 # HR gateway
 129         irc.private.example.com    # Private IRC server
 130
 131     [root@xy policies]# cat private-or-clear
 132         0.0.0.0/0                  # My default policy: try to encrypt.
 133
 134     [root@xy policies]# cat clear
 135         192.0.2.18/32              # My POP3 server
 136         192.0.2.19/32              # My Web proxy
 137
 138     [root@xy policies]# cat block
 139         spamsource.example.com</PRE>
 140 <P>To make these settings take effect, type:</P>
 141 <PRE>    ipsec auto --rereadgroups</PRE>
 142 <P>Notes:</P>
 143 <UL>
 144 <LI>For opportunistic connection attempts to succeed, all participating
 145  FreeS/WAN hosts and gateways must be configured for OE.</LI>
 146 <LI>Examples 3 through 5 show how to implement a detailed<VAR> private</VAR>
 147  policy.</LI>
 148 <LI><A NAME="dnswarning"></A><FONT COLOR="RED"> Warning:</FONT> Using
 149  DNS names in policy files and ipsec.conf can be tricky. If the name
 150  does not resolve, the policy will not be implemented for that name. It
 151  is therefore safer either to use IPs, or to put any critical names in
 152  /etc/hosts. We plan to implement periodic DNS retry to help with this.
 153 <BR> Names are resolved at FreeS/WAN startup, or when the policies are
 154  reloaded. Unfortunately, name lookup can hold up the startup process.
 155  If you have fast DNS servers, the problem may be less severe.</LI>
 156 </UL>
 157 <A HREF="example3"></A>
 158 <H3><A NAME="4_2_3">Example 3: Creating a Simple IPsec VPN with the<VAR>
 159  private</VAR> Group</A></H3>
 160 <P>You can create an IPsec VPN between several hosts, with only one line
 161  of configuration per host, using the<VAR> private</VAR> policy group.</P>
 162 <P>First, use our<A HREF="quickstart.html"> quickstart guide</A> to set
 163  up each participating host with a FreeS/WAN install and OE.</P>
 164 <P>In one host's<VAR> /etc/ipsec.d/policies/private</VAR>, list the
 165  peers to which you wish to protect traffic. For example:</P>
 166 <PRE>    [root@xy root]# cd /etc/ipsec.d/policies
 167     [root@xy policies]# cat private
 168         192.0.2.9              # several hosts at example.com
 169         192.0.2.11
 170         192.0.2.12
 171         irc.private.example.com
 172 </PRE>
 173 <P>Copy the<VAR> private</VAR> file to each host. Remove the local host,
 174  and add the initial host.</P>
 175 <PRE>    scp2 /etc/ipsec.d/policies/private root@192.0.2.12:/etc/ipsec.d/policies/private</PRE>
 176 <P>On each host, reread the policy groups with</P>
 177 <PRE>    ipsec auto --rereadgroups</PRE>
 178 <P>That's it! You're configured.</P>
 179 <P>Test by pinging between two hosts. After a second or two, traffic
 180  should flow, and</P>
 181 <PRE>    ipsec eroute</PRE>
 182 <P>should yield something like</P>
 183 <PRE>    192.0.2.11/32   -&gt; 192.0.2.8/32  =&gt; tun0x149f@192.0.2.8</PRE>
 184 <P>where your host IPs are substituted for 192.0.2.11 and 192.0.2.8.</P>
 185 <P>If traffic does not flow, there may be an error in your OE setup.
 186  Revisit our<A HREF="quickstart.html"> quickstart guide</A>.</P>
 187 <P>Our next two examples show you how to add subnets to this IPsec VPN.</P>
 188 <A NAME="example4"></A>
 189 <H3><A NAME="4_2_4">Example 4: New Policy Groups to Protect a Subnet</A></H3>
 190 <P>To protect traffic to a subnet behind your FreeS/WAN gateway, you'll
 191  need additional DNS records, and new policy groups. To set up the DNS,
 192  see our<A HREF="quickstart.html#opp.gate"> quickstart guide</A>. To
 193  create five new policy groups for your subnet, copy these connections
 194  to<VAR> /etc/ipsec.conf</VAR>. Substitute your subnet's IPs for
 195  192.0.2.128/29.</P>
 196 <PRE>
 197 conn private-net
 198     also=private  # inherits settings (eg. auto=start) from built in conn
 199     leftsubnet=192.0.2.128/29  # your subnet's IPs here
 200
 201 conn private-or-clear-net
 202     also=private-or-clear
 203     leftsubnet=192.0.2.128/29
 204
 205 conn clear-or-private-net
 206     also=clear-or-private
 207     leftsubnet=192.0.2.128/29
 208
 209 conn clear-net
 210     also=clear
 211     leftsubnet=192.0.2.128/29
 212
 213 conn block-net
 214     also=block
 215     leftsubnet=192.0.2.128/29
 216 </PRE>
 217 <P>Copy the gateway's files to serve as the initial policy group files
 218  for the new groups:</P>
 219 <PRE>
 220     cp -p /etc/ipsec.d/policies/private /etc/ipsec.d/policies/private-net
 221     cp -p /etc/ipsec.d/policies/private-or-clear /etc/ipsec.d/policies/private-or-clear-net
 222     cp -p /etc/ipsec.d/policies/clear-or-private /etc/ipsec.d/policies/clear-or-private-net
 223     cp -p /etc/ipsec.d/policies/clear /etc/ipsec.d/policies/clear-net
 224     cp -p /etc/ipsec.d/policies/block /etc/ipsec.d/policies/block
 225 </PRE>
 226 <P><STRONG>Tip: Since a missing policy group file is equivalent to a
 227  file with no entries, you need only create files for the connections
 228  you'll use.</STRONG></P>
 229 <P>To test one of your new groups, place the fullnet 0.0.0.0/0 in<VAR>
 230  private-or-clear-net</VAR>. Perform the subnet test in<A HREF="quickstart.html#opp.test">
 231  our quickstart guide</A>. You should see a connection, and</P>
 232 <PRE>    ipsec eroute</PRE>
 233 <P>should include an entry which mentions the subnet node's IP and the
 234  OE test site IP, like this:</P>
 235 <PRE>    192.0.2.131/32   -&gt; 192.139.46.77/32  =&gt; tun0x149f@192.0.2.11</PRE>
 236 <A HREF="example5"></A>
 237 <H3><A NAME="4_2_5">Example 5: Adding a Subnet to the VPN</A></H3>
 238 <P>Suppose you wish to secure traffic to a subnet 192.0.2.192/29 behind
 239  a FreeS/WAN box 192.0.2.12.</P>
 240 <P>First, add DNS entries to configure 192.0.2.12 as an opportunistic
 241  gateway for that subnet. Instructions are in our<A HREF="quickstart.html#opp.gate">
 242  quickstart guide</A>. Next, create a<VAR> private-net</VAR> group on
 243  192.0.2.12 as described in<A HREF="#example4"> Example 4</A>.</P>
 244 <P>On each other host, add the subnet 192.0.2.192/29 to<VAR> private</VAR>
 245 , yielding for example</P>
 246 <PRE>    [root@xy root]# cd /etc/ipsec.d/policies
 247     [root@xy policies]# cat private
 248         192.0.2.9              # several hosts at example.com
 249         192.0.2.11
 250         192.0.2.12             # HR department gateway
 251         192.0.2.192/29         # HR subnet
 252         irc.private.example.com
 253 </PRE>
 254 <P>and reread policy groups with</P>
 255 <PRE>    ipsec auto --rereadgroups</PRE>
 256 <P>That's all the configuration you need.</P>
 257 <P>Test your VPN by pinging from a machine on 192.0.2.192/29 to any
 258  other host:</P>
 259 <PRE>    [root@192.0.2.194]# ping 192.0.2.11</PRE>
 260 <P>After a second or two, traffic should flow, and</P>
 261 <PRE>    ipsec eroute</PRE>
 262 <P>should yield something like</P>
 263 <PRE>    192.0.2.11/32   -&gt; 192.0.2.194/32  =&gt; tun0x149f@192.0.2.12
 264 </PRE>
 265 <P>Key:</P>
 266 <TABLE>
 267 <TR><TD>1.</TD><TD>192.0.2.11/32</TD><TD>Local start point of the
 268  protected traffic.</TD></TR>
 269 <TR><TD>2.</TD><TD>192.0.2.194/32</TD><TD>Remote end point of the
 270  protected traffic.</TD></TR>
 271 <TR><TD>3.</TD><TD>192.0.2.12</TD><TD>Remote FreeS/WAN node (gateway or
 272  host). May be the same as (2).</TD></TR>
 273 <TR><TD>4.</TD><TD>[not shown]</TD><TD>Local FreeS/WAN node (gateway or
 274  host), where you've produced the output. May be the same as (1).</TD></TR>
 275 </TABLE>
 276 <P>For additional assurance, you can verify with a packet sniffer that
 277  the traffic is being encrypted.</P>
 278 <P>Note</P>
 279 <UL>
 280 <LI>Because strangers may also connect via OE, this type of VPN may
 281  require a stricter firewalling policy than a conventional VPN.</LI>
 282 </UL>
 283 <H2><A NAME="4_3">Appendix</A></H2>
 284 <A NAME="hiddenconn"></A>
 285 <H3><A NAME="4_3_1">Our Hidden Connections</A></H3>
 286 <P>Our Base Policy Groups are created using hidden connections. These
 287  are spelled out in<A HREF="manpage.d/ipsec.conf.5.html"> man ipsec.conf</A>
 288  and defined in<VAR> /usr/local/lib/ipsec/_confread</VAR>.</P>
 289 <A NAME="custom_policygroups"></A>
 290 <H3><A NAME="4_3_2">Custom Policy Groups</A></H3>
 291 <P>A policy group is built using a special connection description in<VAR>
 292  ipsec.conf</VAR>, which:</P>
 293 <UL>
 294 <LI>is<STRONG> generic</STRONG>. It uses<VAR>
 295  right=[%group|%opportunisticgroup]</VAR> rather than specific IPs. The
 296  connection is cloned for every name or IP range listed in its Policy
 297  Group file.</LI>
 298 <LI>often has a<STRONG> failure rule</STRONG>. This rule, written<VAR>
 299  failureshunt=[passthrough|drop|reject|none]</VAR>, tells FreeS/WAN what
 300  to do with packets for these CIDRs if it fails to establish the
 301  connection. Default is<VAR> none</VAR>.</LI>
 302 </UL>
 303 <P>To create a new group:</P>
 304 <OL>
 305 <LI>Create its connection definition in<VAR> ipsec.conf</VAR>.</LI>
 306 <LI>Create a Policy Group file in<VAR> /etc/ipsec.d/policies</VAR> with
 307  the same name as your connection.</LI>
 308 <LI>Put a CIDR block in that file.</LI>
 309 <LI>Reread groups with<VAR> ipsec auto --rereadgroups</VAR>.</LI>
 310 <LI>Test:<VAR> ping</VAR> to activate any OE connection, and view
 311  results with<VAR> ipsec eroute</VAR>.</LI>
 312 </OL>
 313 <A NAME="disable_oe"></A><A NAME="disable_policygroups"></A>
 314 <H3><A NAME="4_3_3">Disabling Opportunistic Encryption</A></H3>
 315 <P>To disable OE (eg. policy groups and packetdefault), cut and paste
 316  the following lines to<VAR> /etc/ipsec.conf</VAR>:</P>
 317 <PRE>conn block
 318     auto=ignore
 319
 320 conn private
 321     auto=ignore
 322
 323 conn private-or-clear
 324     auto=ignore
 325
 326 conn clear-or-private
 327     auto=ignore
 328
 329 conn clear
 330     auto=ignore
 331
 332 conn packetdefault
 333     auto=ignore</PRE>
 334 <P>Restart FreeS/WAN so that the changes take effect:</P>
 335 <PRE>    ipsec setup restart</PRE>
 336 <HR>
 337 <A HREF="toc.html">Contents</A>
 338 <A HREF="quickstart.html">Previous</A>
 339 <A HREF="faq.html">Next</A>
 340 </BODY>
 341 </HTML>