freeswan/doc/manpage.d/ipsec.conf.5.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC.CONF</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC.CONF</H1>
   6 Section: File Formats (5)<BR>Updated: 14 June 2001<BR><A HREF="#index">Index</A>
   7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
   8
   9
  10 <A NAME="lbAB">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec.conf - IPsec configuration and connections
  14 <A NAME="lbAC">&nbsp;</A>
  15 <H2>DESCRIPTION</H2>
  16
  17 The
  18 <I>ipsec.conf</I>
  19
  20 file
  21 specifies most configuration and control information for the
  22 FreeS/WAN IPsec subsystem.
  23 (The major exception is secrets for authentication;
  24 see
  25 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5).)
  26
  27 Its contents are not security-sensitive
  28 <I>unless</I>
  29
  30 manual keying is being done for more than just testing,
  31 in which case the encryption/authentication keys in the
  32 descriptions for the manually-keyed connections are very sensitive
  33 (and those connection descriptions
  34 are probably best kept in a separate file,
  35 via the include facility described below).
  36 <P>
  37
  38 The file is a text file, consisting of one or more
  39 <I>sections</I>.
  40
  41 White space followed by
  42 <B>#</B>
  43
  44 followed by anything to the end of the line
  45 is a comment and is ignored,
  46 as are empty lines which are not within a section.
  47 <P>
  48
  49 A line which contains
  50 <B>include</B>
  51
  52 and a file name, separated by white space,
  53 is replaced by the contents of that file,
  54 preceded and followed by empty lines.
  55 If the file name is not a full pathname,
  56 it is considered to be relative to the directory containing the
  57 including file.
  58 Such inclusions can be nested.
  59 Only a single filename may be supplied, and it may not contain white space,
  60 but it may include shell wildcards (see
  61 <I><A HREF="sh.1.html">sh</A></I>(1));
  62
  63 for example:
  64 <P>
  65
  66 <B>include</B>
  67
  68 <B>ipsec.*.conf</B>
  69
  70 <P>
  71
  72 The intention of the include facility is mostly to permit keeping
  73 information on connections, or sets of connections,
  74 separate from the main configuration file.
  75 This permits such connection descriptions to be changed,
  76 copied to the other security gateways involved, etc.,
  77 without having to constantly extract them from the configuration
  78 file and then insert them back into it.
  79 Note also the
  80 <B>also</B>
  81
  82 parameter (described below) which permits splitting a single logical section
  83 (e.g. a connection description) into several actual sections.
  84 <P>
  85
  86 A section
  87 begins with a line of the form:
  88 <P>
  89
  90 <I>type</I>
  91
  92 <I>name</I>
  93
  94 <P>
  95
  96 where
  97 <I>type</I>
  98
  99 indicates what type of section follows, and
 100 <I>name</I>
 101
 102 is an arbitrary name which distinguishes the section from others
 103 of the same type.
 104 (Names must start with a letter and may contain only
 105 letters, digits, periods, underscores, and hyphens.)
 106 All subsequent lines which begin with white space are part of the section;
 107 comments within a section must begin with white space too.
 108 There may be only one section of a given type with a given name.
 109 <P>
 110
 111 Lines within the section are generally of the form
 112 <P>
 113
 114 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<I>parameter</I><B>=</B><I>value</I>
 115 <P>
 116
 117 (note the mandatory preceding white space).
 118 There can be white space on either side of the
 119 <B>=</B>.
 120
 121 Parameter names follow the same syntax as section names,
 122 and are specific to a section type.
 123 Unless otherwise explicitly specified,
 124 no parameter name may appear more than once in a section.
 125 <P>
 126
 127 An empty
 128 <I>value</I>
 129
 130 stands for the system default value (if any) of the parameter,
 131 i.e. it is roughly equivalent to omitting the parameter line entirely.
 132 A
 133 <I>value</I>
 134
 135 may contain white space only if the entire
 136 <I>value</I>
 137
 138 is enclosed in double quotes (<B>&quot;</B>);
 139 a
 140 <I>value</I>
 141
 142 cannot itself contain a double quote,
 143 nor may it be continued across more than one line.
 144 <P>
 145
 146 Numeric values are specified to be either an ``integer''
 147 (a sequence of digits) or a ``decimal number''
 148 (sequence of digits optionally followed by `.' and another sequence of digits).
 149 <P>
 150
 151 There is currently one parameter which is available in any type of
 152 section:
 153 <DL COMPACT>
 154 <DT><B>also</B>
 155
 156 <DD>
 157 the value is a section name;
 158 the parameters of that section are appended to this section,
 159 as if they had been written as part of it.
 160 The specified section must exist, must follow the current one,
 161 and must have the same section type.
 162 (Nesting is permitted,
 163 and there may be more than one
 164 <B>also</B>
 165
 166 in a single section,
 167 although it is forbidden to append the same section more than once.)
 168 This allows, for example, keeping the encryption keys
 169 for a connection in a separate file
 170 from the rest of the description, by using both an
 171 <B>also</B>
 172
 173 parameter and an
 174 <B>include</B>
 175
 176 line.
 177 (Caution, see BUGS below for some restrictions.)
 178 </DL>
 179 <P>
 180
 181 Parameter names beginning with
 182 <B>x-</B>
 183
 184 (or
 185 <B>X-</B>,
 186
 187 or
 188 <B>x_</B>,
 189
 190 or
 191 <B>X_</B>)
 192
 193 are reserved for user extensions and will never be assigned meanings
 194 by IPsec.
 195 Parameters with such names must still observe the syntax rules
 196 (limits on characters used in the name;
 197 no white space in a non-quoted value;
 198 no newlines or double quotes within the value).
 199 All other as-yet-unused parameter names are reserved for future IPsec
 200 improvements.
 201 <P>
 202
 203 A section with name
 204 <B>%default</B>
 205
 206 specifies defaults for sections of the same type.
 207 For each parameter in it,
 208 any section of that type which does not have a parameter of the same name
 209 gets a copy of the one from the
 210 <B>%default</B>
 211
 212 section.
 213 There may be multiple
 214 <B>%default</B>
 215
 216 sections of a given type,
 217 but only one default may be supplied for any specific parameter name,
 218 and all
 219 <B>%default</B>
 220
 221 sections of a given type must precede all non-<B>%default</B>
 222
 223 sections of that type.
 224 <B>%default</B>
 225
 226 sections may not contain
 227 <B>also</B>
 228
 229 parameters.
 230 <P>
 231
 232 Currently there are two types of section:
 233 a
 234 <B>config</B>
 235
 236 section specifies general configuration information for IPsec,
 237 while a
 238 <B>conn</B>
 239
 240 section specifies an IPsec connection.
 241 <A NAME="lbAD">&nbsp;</A>
 242 <H2>CONN SECTIONS</H2>
 243
 244 A
 245 <B>conn</B>
 246
 247 section contains a
 248 <I>connection specification</I>,
 249
 250 defining a network connection to be made using IPsec.
 251 The name given is arbitrary, and is used to identify the connection to
 252 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8)
 253
 254 and
 255 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8).
 256
 257 Here's a simple example:
 258 <P>
 259
 260
 261 <PRE>
 262 <B>
 263 conn snt
 264  left=10.11.11.1
 265  leftsubnet=10.0.1.0/24
 266  leftnexthop=172.16.55.66
 267  right=192.168.22.1
 268  rightsubnet=10.0.2.0/24
 269  rightnexthop=172.16.88.99
 270  keyingtries=0                # be very persistent
 271 </B></PRE>
 272
 273 <P>
 274
 275 To avoid trivial editing of the configuration file to suit it to each system
 276 involved in a connection,
 277 connection specifications are written in terms of
 278 <I>left</I>
 279
 280 and
 281 <I>right</I>
 282
 283 participants,
 284 rather than in terms of local and remote.
 285 Which participant is considered
 286 <I>left</I>
 287
 288 or
 289 <I>right</I>
 290
 291 is arbitrary;
 292 IPsec figures out which one it is being run on based on internal information.
 293 This permits using identical connection specifications on both ends.
 294 <P>
 295
 296 Many of the parameters relate to one participant or the other;
 297 only the ones for
 298 <I>left</I>
 299
 300 are listed here, but every parameter whose name begins with
 301 <B>left</B>
 302
 303 has a
 304 <B>right</B>
 305
 306 counterpart,
 307 whose description is the same but with
 308 <B>left</B>
 309
 310 and
 311 <B>right</B>
 312
 313 reversed.
 314 <P>
 315
 316 Parameters are optional unless marked ``(required)'';
 317 a parameter required for manual keying need not be included for
 318 a connection which will use only automatic keying, and vice versa.
 319 <A NAME="lbAE">&nbsp;</A>
 320 <H3>CONN PARAMETERS:  GENERAL</H3>
 321
 322 The following parameters are relevant to both automatic and manual keying.
 323 <DL COMPACT>
 324 <DT><B>type</B>
 325
 326 <DD>
 327 the type of the connection; currently the accepted values
 328 are
 329 <B>tunnel</B>
 330
 331 (the default)
 332 signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
 333 <B>transport</B>,
 334
 335 signifying host-to-host transport mode;
 336 and
 337 <B>passthrough</B>
 338
 339 (supported only for manual keying),
 340 signifying that no IPsec processing should be done at all
 341 <DT><B>compress</B>
 342
 343 <DD>
 344 whether IPComp compression of content is desired on the connection
 345 (link-level compression does not work on encrypted data,
 346 so to be effective, compression must be done <I>before</I> encryption);
 347 acceptable values are
 348 <B>yes</B>
 349
 350 and
 351 <B>no</B>
 352
 353 (the default).
 354 <DT><B>left</B>
 355
 356 <DD>
 357 (required)
 358 the IP address of the left participant's public-network interface,
 359 in any form accepted by
 360 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3).
 361
 362 If it is the magic value
 363 <B>%defaultroute</B>,
 364
 365 and
 366 <B>interfaces=%defaultroute</B>
 367
 368 is used in the
 369 <B>config</B>
 370
 371 <B>setup</B>
 372
 373 section,
 374 <B>left</B>
 375
 376 will be filled in automatically with the local address
 377 of the default-route interface (as determined at IPsec startup time);
 378 this also overrides any value supplied for
 379 <B>leftnexthop</B>.
 380
 381 (Either
 382 <B>left</B>
 383
 384 or
 385 <B>right</B>
 386
 387 may be
 388 <B>%defaultroute</B>,
 389
 390 but not both.)
 391 The magic value
 392 <B>%any</B>
 393
 394 signifies an address to be filled in (by automatic keying) during
 395 negotiation;
 396 the magic value
 397 <B>%opportunistic</B>
 398
 399 signifies that both
 400 <B>left</B>
 401
 402 and
 403 <B>leftnexthop</B>
 404
 405 are to be filled in (by automatic keying) from DNS data for
 406 <B>left</B>'s
 407
 408 client.
 409 <DT><B>leftsubnet</B>
 410
 411 <DD>
 412 private subnet behind the left participant, expressed as
 413 <I>network</I><B>/</B><I>netmask</I>
 414 (actually, any form acceptable to
 415 <I><A HREF="ipsec_ttosubnet.3.html">ipsec_ttosubnet</A></I>(3));
 416
 417 if omitted, essentially assumed to be <I>left</I><B>/32</B>,
 418 signifying that the left end of the connection goes to the left participant only
 419 <DT><B>leftnexthop</B>
 420
 421 <DD>
 422 next-hop gateway IP address for the left participant's connection
 423 to the public network;
 424 defaults to
 425 <B>%direct</B>
 426
 427 (meaning
 428 <I>right</I>).
 429
 430 If the value is to be overridden by the
 431 <B>left=%defaultroute</B>
 432
 433 method (see above),
 434 an explicit value must
 435 <I>not</I>
 436
 437 be given.
 438 If that method is not being used,
 439 but
 440 <B>leftnexthop</B>
 441
 442 is
 443 <B>%defaultroute</B>,
 444
 445 and
 446 <B>interfaces=%defaultroute</B>
 447
 448 is used in the
 449 <B>config</B>
 450
 451 <B>setup</B>
 452
 453 section,
 454 the next-hop gateway address of the default-route interface
 455 will be used.
 456 The magic value
 457 <B>%direct</B>
 458
 459 signifies a value to be filled in (by automatic keying)
 460 with the peer's address.
 461 <DT><B>leftupdown</B>
 462
 463 <DD>
 464 what ``updown'' script to run to adjust routing and/or firewalling
 465 when the status of the connection
 466 changes (default
 467 <B>ipsec _updown</B>).
 468
 469 May include positional parameters separated by white space
 470 (although this requires enclosing the whole string in quotes);
 471 including shell metacharacters is unwise.
 472 See
 473 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8)
 474
 475 for details.
 476 <DT><B>leftfirewall</B>
 477
 478 <DD>
 479 whether the left participant is doing forwarding-firewalling
 480 (including masquerading) for traffic from <I>leftsubnet</I>,
 481 which should be turned off (for traffic to the other subnet)
 482 once the connection is established;
 483 acceptable values are
 484 <B>yes</B>
 485
 486 and (the default)
 487 <B>no</B>.
 488
 489 May not be used in the same connection description with
 490 <B>leftupdown</B>.
 491
 492 Implemented as a parameter to the default
 493 <I>updown</I>
 494
 495 script.
 496 </DL>
 497 <P>
 498
 499 If one or both security gateways are doing forwarding firewalling
 500 (possibly including masquerading),
 501 and this is specified using the firewall parameters,
 502 tunnels established with IPsec are exempted from it
 503 so that packets can flow unchanged through the tunnels.
 504 (This means that all subnets connected in this manner must have
 505 distinct, non-overlapping subnet address blocks.)
 506 This is done by the default
 507 <I>updown</I>
 508
 509 script (see
 510 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8)).
 511
 512 <P>
 513
 514 The implementation of this makes certain assumptions about firewall setup,
 515 notably the use of the old
 516 <I>ipfwadm</I>
 517
 518 interface to the firewall.
 519 In situations calling for more control,
 520 it may be preferable for the user to supply his own
 521 <I>updown</I>
 522
 523 script,
 524 which makes the appropriate adjustments for his system.
 525 <A NAME="lbAF">&nbsp;</A>
 526 <H3>CONN PARAMETERS:  AUTOMATIC KEYING</H3>
 527
 528 The following parameters are relevant only to automatic keying,
 529 and are ignored in manual keying.
 530 <DL COMPACT>
 531 <DT><B>keyexchange</B>
 532
 533 <DD>
 534 method of key exchange;
 535 the default and currently the only accepted value is
 536 <B>ike</B>
 537
 538 <DT><B>auto</B>
 539
 540 <DD>
 541 what operation, if any, should be done automatically at IPsec startup;
 542 currently-accepted values are
 543 <B>add</B>
 544
 545 (signifying an
 546 <B>ipsec auto</B>
 547
 548 <B>--add</B>),
 549
 550 <B>route</B>
 551
 552 (signifying that plus an
 553 <B>ipsec auto</B>
 554
 555 <B>--route</B>),
 556
 557 <B>start</B>
 558
 559 (signifying that plus an
 560 <B>ipsec auto</B>
 561
 562 <B>--up</B>),
 563
 564 and
 565 <B>ignore</B>
 566
 567 (also the default) (signifying no automatic startup operation).
 568 This parameter is ignored unless the
 569 <B>plutoload</B>
 570
 571 or
 572 <B>plutostart</B>
 573
 574 configuration parameter is set suitably; see the
 575 <B>config</B>
 576
 577 <B>setup</B>
 578
 579 discussion below.
 580 <DT><B>auth</B>
 581
 582 <DD>
 583 whether authentication should be done as part of
 584 ESP encryption, or separately using the AH protocol;
 585 acceptable values are
 586 <B>esp</B>
 587
 588 (the default) and
 589 <B>ah</B>.
 590
 591 <DT><B>authby</B>
 592
 593 <DD>
 594 how the two security gateways should authenticate each other;
 595 acceptable values are
 596 <B>secret</B>
 597
 598 for shared secrets (the default) and
 599 <B>rsasig</B>
 600
 601 for RSA digital signatures
 602 <DT><B>leftid</B>
 603
 604 <DD>
 605 how
 606 the left participant
 607 should be identified for authentication;
 608 defaults to
 609 <B>left</B>.
 610
 611 Can be an IP address (in any
 612 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3)
 613
 614 syntax)
 615 or a fully-qualified domain name preceded by
 616 <B>@</B>
 617
 618 (which is used as a literal string and not resolved).
 619 <DT><B>leftrsasigkey</B>
 620
 621 <DD>
 622 the left participant's
 623 public key for RSA signature authentication,
 624 in RFC 2537 format using
 625 <I><A HREF="ipsec_ttodata.3.html">ipsec_ttodata</A></I>(3)
 626
 627 encoding;
 628 the magic value
 629 <B>%dns</B>
 630
 631 means to fetch it from DNS (at the time
 632 the connection description is read from
 633 <I>ipsec.conf</I>)
 634
 635 instead.
 636 The identity used for the left participant
 637 must be a specific host, not
 638 <B>%any</B>
 639
 640 or another magic value.
 641 <B>Caution:</B>
 642
 643 if two connection descriptions
 644 specify different public keys for the same
 645 <B>leftid</B>,
 646
 647 confusion and madness will ensue.
 648 <DT><B>pfs</B>
 649
 650 <DD>
 651 whether Perfect Forward Secrecy of keys is desired on the connection's
 652 keying channel
 653 (with PFS, penetration of the key-exchange protocol
 654 does not compromise keys negotiated earlier);
 655 acceptable values are
 656 <B>yes</B>
 657
 658 (the default)
 659 and
 660 <B>no</B>
 661
 662 <DT><B>keylife</B>
 663
 664 <DD>
 665 how long a particular instance of a connection
 666 (a set of encryption/authentication keys for user packets) should last,
 667 from successful negotiation to expiry;
 668 acceptable values are an integer optionally followed by
 669 <B>s</B>
 670
 671 (a time in seconds)
 672 or a decimal number followed by
 673 <B>m</B>,
 674
 675 <B>h</B>,
 676
 677 or
 678 <B>d</B>
 679
 680 (a time
 681 in minutes, hours, or days respectively)
 682 (default
 683 <B>8.0h</B>,
 684
 685 maximum
 686 <B>24h</B>).
 687
 688 Normally, the connection is renegotiated (via the keying channel)
 689 before it expires.
 690 <DT><B>rekeymargin</B>
 691
 692 <DD>
 693 how long before connection expiry should attempts to
 694 negotiate a replacement
 695 begin; acceptable values as for
 696 <B>keylife</B>
 697
 698 (default
 699 <B>9m</B>)
 700
 701 <DT><B>rekeyfuzz</B>
 702
 703 <DD>
 704 maximum percentage by which
 705 <B>rekeymargin</B>
 706
 707 should be randomly increased to randomize rekeying intervals
 708 (important for hosts with many connections);
 709 acceptable values are an integer,
 710 which may exceed 100,
 711 followed by a `%'
 712 (default set by
 713 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),
 714
 715 currently
 716 <B>100%</B>).
 717
 718 The value of
 719 <B>rekeymargin</B>,
 720
 721 after this random increase,
 722 must not exceed
 723 <B>keylife</B>.
 724
 725 The value
 726 <B>0%</B>
 727
 728 will suppress time randomization.
 729 <DT><B>keyingtries</B>
 730
 731 <DD>
 732 how many attempts (an integer) should be made to
 733 negotiate a connection, or a replacement for one, before giving up
 734 (default
 735 <B>3</B>);
 736
 737 the value
 738 <B>0</B>
 739
 740 means ``never give up''
 741 <DT><B>ikelifetime</B>
 742
 743 <DD>
 744 how long the keying channel of a connection (buzzphrase:  ``ISAKMP SA'')
 745 should last before being renegotiated;
 746 acceptable values as for
 747 <B>keylife</B>
 748
 749 (default set by
 750 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),
 751
 752 currently
 753 <B>1h</B>,
 754
 755 maximum
 756 <B>8h</B>).
 757
 758 </DL>
 759 <A NAME="lbAG">&nbsp;</A>
 760 <H3>CONN PARAMETERS:  MANUAL KEYING</H3>
 761
 762 The following parameters are relevant only to manual keying,
 763 and are ignored in automatic keying.
 764 A manually-keyed
 765 connection must specify at least one of AH or ESP.
 766 <DL COMPACT>
 767 <DT><B>spi</B>
 768
 769 <DD>
 770 (this or
 771 <B>spibase</B>
 772
 773 required for manual keying)
 774 the SPI number to be used for the connection (see
 775 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8));
 776
 777 must be of the form <B>0x</B><I>hex</I><B></B>,
 778 where
 779 <I>hex</I>
 780
 781 is one or more hexadecimal digits
 782 (note, it will generally be necessary to make
 783 <I>spi</I>
 784
 785 at least
 786 <B>0x100</B>
 787
 788 to be acceptable to KLIPS,
 789 and use of SPIs in the range
 790 <B>0x100</B>-<B>0xfff</B>
 791
 792 is recommended)
 793 <DT><B>spibase</B>
 794
 795 <DD>
 796 (this or
 797 <B>spi</B>
 798
 799 required for manual keying)
 800 the base number for the SPIs to be used for the connection (see
 801 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8));
 802
 803 must be of the form <B>0x</B><I>hex</I><B>0</B>,
 804 where
 805 <I>hex</I>
 806
 807 is one or more hexadecimal digits
 808 (note, it will generally be necessary to make
 809 <I>spibase</I>
 810
 811 at least
 812 <B>0x100</B>
 813
 814 for the resulting SPIs
 815 to be acceptable to KLIPS,
 816 and use of numbers in the range
 817 <B>0x100</B>-<B>0xff0</B>
 818
 819 is recommended)
 820 <DT><B>esp</B>
 821
 822 <DD>
 823 ESP encryption/authentication algorithm to be used
 824 for the connection, e.g.
 825 <B>3des-md5-96</B>
 826
 827 (must be suitable as a value of
 828 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
 829
 830 <B>--esp</B>
 831
 832 option);
 833 default is not to use ESP
 834 <DT><B>espenckey</B>
 835
 836 <DD>
 837 ESP encryption key
 838 (must be suitable as a value of
 839 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
 840
 841 <B>--enckey</B>
 842
 843 option)
 844 (may be specified separately for each direction using
 845 <B>leftespenckey</B>
 846
 847 (leftward SA)
 848 and
 849 <B>rightespenckey</B>
 850
 851 parameters)
 852 <DT><B>espauthkey</B>
 853
 854 <DD>
 855 ESP authentication key
 856 (must be suitable as a value of
 857 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
 858
 859 <B>--authkey</B>
 860
 861 option)
 862 (may be specified separately for each direction using
 863 <B>leftespauthkey</B>
 864
 865 (leftward SA)
 866 and
 867 <B>rightespauthkey</B>
 868
 869 parameters)
 870 <DT><B>espreplay_window</B>
 871
 872 <DD>
 873 ESP replay-window setting,
 874 an integer from
 875 <B>0</B>
 876
 877 (the
 878 <I>ipsec_manual</I>
 879
 880 default, which turns off replay protection) to
 881 <B>64</B>;
 882
 883 relevant only if ESP authentication is being used
 884 <DT><B>leftespspi</B>
 885
 886 <DD>
 887 SPI to be used for the leftward ESP SA, overriding
 888 automatic assignment using
 889 <B>spi</B>
 890
 891 or
 892 <B>spibase</B>;
 893
 894 typically a hexadecimal number beginning with
 895 <B>0x</B>
 896
 897 <DT><B>ah</B>
 898
 899 <DD>
 900 AH authentication algorithm to be used
 901 for the connection, e.g.
 902 <B>hmac-md5-96</B>
 903
 904 (must be suitable as a value of
 905 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
 906
 907 <B>--ah</B>
 908
 909 option);
 910 default is not to use AH
 911 <DT><B>ahkey</B>
 912
 913 <DD>
 914 (required if
 915 <B>ah</B>
 916
 917 is present) AH authentication key
 918 (must be suitable as a value of
 919 <I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s
 920
 921 <B>--authkey</B>
 922
 923 option)
 924 (may be specified separately for each direction using
 925 <B>leftahkey</B>
 926
 927 (leftward SA)
 928 and
 929 <B>rightahkey</B>
 930
 931 parameters)
 932 <DT><B>ahreplay_window</B>
 933
 934 <DD>
 935 AH replay-window setting,
 936 an integer from
 937 <B>0</B>
 938
 939 (the
 940 <I>ipsec_manual</I>
 941
 942 default, which turns off replay protection) to
 943 <B>64</B>
 944
 945 <DT><B>leftahspi</B>
 946
 947 <DD>
 948 SPI to be used for the leftward AH SA, overriding
 949 automatic assignment using
 950 <B>spi</B>
 951
 952 or
 953 <B>spibase</B>;
 954
 955 typically a hexadecimal number beginning with
 956 <B>0x</B>
 957
 958 </DL>
 959 <A NAME="lbAH">&nbsp;</A>
 960 <H2>CONFIG SECTIONS</H2>
 961
 962 At present, the only
 963 <B>config</B>
 964
 965 section known to the IPsec software is the one named
 966 <B>setup</B>,
 967
 968 which contains information used when the software is being started
 969 (see
 970 <I><A HREF="ipsec_setup.8.html">ipsec_setup</A></I>(8)).
 971
 972 Here's an example:
 973 <P>
 974
 975
 976 <PRE>
 977 <B>
 978 config setup
 979  interfaces=&quot;ipsec0=eth1 ipsec1=ppp0&quot;
 980  klipsdebug=none
 981  plutodebug=all
 982  manualstart=
 983  plutoload=&quot;snta sntb sntc sntd&quot;
 984  plutostart=
 985 </B></PRE>
 986
 987 <P>
 988
 989 Parameters are optional unless marked ``(required)''.
 990 The currently-accepted
 991 <I>parameter</I>
 992
 993 names in a
 994 <B>config</B>
 995
 996 <B>setup</B>
 997
 998 section are:
 999 <DL COMPACT>
1000 <DT><B>interfaces</B>
1001
1002 <DD>
1003 (required)
1004 virtual and physical interfaces for IPsec to use:
1005 a single
1006 <I>virtual</I><B>=</B><I>physical</I> pair, a (quoted!) list of pairs separated
1007 by white space,
1008 or
1009 <B>%defaultroute</B>,
1010
1011 which means to find the interface <I>d</I> that the default route points to,
1012 and then act as if the value was ``<B>ipsec0=</B><I>d</I>''.
1013 (Also, in the
1014 <B>%defaultroute</B>
1015
1016 case,
1017 information about the default route and its interface is noted for
1018 use by
1019 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8)
1020
1021 and
1022 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8).)
1023
1024 <DT><B>forwardcontrol</B>
1025
1026 <DD>
1027 whether
1028 <I>setup</I>
1029
1030 should turn IP forwarding on
1031 (if it's not already on) as IPsec is started,
1032 and turn it off again (if it was off) as IPsec is stopped;
1033 acceptable values are
1034 <B>yes</B>
1035
1036 and (the default)
1037 <B>no</B>.
1038
1039 For this to have full effect, forwarding must be
1040 disabled before the hardware interfaces are brought
1041 up (e.g.,
1042 <B>net.ipv4.ip_forward&nbsp;=&nbsp;0</B>
1043
1044 in Red Hat 6.x
1045 <I>/etc/sysctl.conf</I>),
1046
1047 because IPsec doesn't get control early enough to do that.
1048 <DT><B>syslog</B>
1049
1050 <DD>
1051 the
1052 <I><A HREF="syslog.2.html">syslog</A></I>(2)
1053
1054 ``facility'' name and priority to use for
1055 startup/shutdown log messages,
1056 default
1057 <B>daemon.error</B>.
1058
1059 <DT><B>klipsdebug</B>
1060
1061 <DD>
1062 how much KLIPS debugging output should be logged.
1063 An empty value,
1064 or the magic value
1065 <B>none</B>,
1066
1067 means no debugging output (the default).
1068 The magic value
1069 <B>all</B>
1070
1071 means full output.
1072 Otherwise only the specified types of output
1073 (a quoted list, names separated by white space) are enabled;
1074 for details on available debugging types, see
1075 <I><A HREF="ipsec_klipsdebug.8.html">ipsec_klipsdebug</A></I>(8).
1076
1077 <DT><B>plutodebug</B>
1078
1079 <DD>
1080 how much Pluto debugging output should be logged.
1081 An empty value,
1082 or the magic value
1083 <B>none</B>,
1084
1085 means no debugging output (the default).
1086 The magic value
1087 <B>all</B>
1088
1089 means full output.
1090 Otherwise only the specified types of output
1091 (a quoted list, names without the
1092 <B>--debug-</B>
1093
1094 prefix,
1095 separated by white space) are enabled;
1096 for details on available debugging types, see
1097 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8).
1098
1099 <DT><B>dumpdir</B>
1100
1101 <DD>
1102 in what directory should things started by
1103 <I>setup</I>
1104
1105 (notably the Pluto daemon) be allowed to
1106 dump core?
1107 The empty value (the default) means they are not
1108 allowed to.
1109 <DT><B>dump</B>
1110
1111 <DD>
1112 obsolete variant of
1113 <B>dumpdir</B>.
1114
1115 <B>dump=no</B>
1116
1117 is synonymous with
1118 <B>dumpdir=</B>
1119
1120 and
1121 <B>dump=yes</B>
1122
1123 is synonymous with
1124 <B>dump=/var/tmp</B>.
1125
1126 <DT><B>manualstart</B>
1127
1128 <DD>
1129 which manually-keyed connections to set up at startup
1130 (empty, a name, or a quoted list of names separated by white space);
1131 see
1132 <I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8).
1133
1134 Default is none.
1135 <DT><B>pluto</B>
1136
1137 <DD>
1138 whether to start Pluto or not;
1139 Values are
1140 <B>yes</B>
1141
1142 (the default)
1143 or
1144 <B>no</B>
1145
1146 (useful only in special circumstances).
1147 <DT><B>plutoload</B>
1148
1149 <DD>
1150 which connections (by name) to load
1151 into Pluto's internal database at startup
1152 (empty, a name, or a quoted list of names separated by white space);
1153 see
1154 <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8)
1155
1156 for details.
1157 Default is none.
1158 If the special value
1159 <B>%search</B>
1160
1161 is used, all connections with
1162 <B>auto=add</B>,
1163
1164 <B>auto=route</B>,
1165
1166 or
1167 <B>auto=start</B>
1168
1169 are loaded.
1170 <DT><B>plutostart</B>
1171
1172 <DD>
1173 which connections (by name) to attempt to negotiate
1174 at startup (empty, a name, or a quoted
1175 list of names separated by white space);
1176 any such names which do not appear in
1177 <B>plutoload</B>
1178
1179 are implicitly added to it.
1180 Default is none.
1181 If the special value
1182 <B>%search</B>
1183
1184 is used, all connections with
1185 <B>auto=route</B>
1186
1187 or
1188 <B>auto=start</B>
1189
1190 are routed,
1191 and all connections with
1192 <B>auto=start</B>
1193
1194 are started.
1195 <DT><B>plutowait</B>
1196
1197 <DD>
1198 should Pluto wait for each
1199 <B>plutostart</B>
1200
1201 negotiation attempt to
1202 finish before proceeding with the next?
1203 Values are
1204 <B>yes</B>
1205
1206 (the default)
1207 or
1208 <B>no</B>.
1209
1210 <DT><B>plutobackgroundload</B>
1211
1212 <DD>
1213 obsolete parameter, ignored, nominally specifying whether
1214 loading and starting of connections should be spun off as a background
1215 process to avoid startup delays.
1216 This is now always done.
1217 Values were
1218 <B>yes</B>
1219
1220 or
1221 <B>no</B>
1222
1223 (the default).
1224 <DT><B>prepluto</B>
1225
1226 <DD>
1227 shell command to run before starting Pluto
1228 (e.g., to decrypt an encrypted copy of the
1229 <I>ipsec.secrets</I>
1230
1231 file).
1232 It's run in a very simple way;
1233 complexities like I/O redirection are best hidden within a script.
1234 Any output is redirected for logging,
1235 so running interactive commands is difficult unless they use
1236 <I>/dev/tty</I>
1237
1238 or equivalent for their interaction.
1239 Default is none.
1240 <DT><B>postpluto</B>
1241
1242 <DD>
1243 shell command to run after starting Pluto
1244 (e.g., to remove a decrypted copy of the
1245 <I>ipsec.secrets</I>
1246
1247 file).
1248 It's run in a very simple way;
1249 complexities like I/O redirection are best hidden within a script.
1250 Any output is redirected for logging,
1251 so running interactive commands is difficult unless they use
1252 <I>/dev/tty</I>
1253
1254 or equivalent for their interaction.
1255 Default is none.
1256 <DT><B>fragicmp</B>
1257
1258 <DD>
1259 whether a tunnel's need to fragment a packet should be reported
1260 back with an ICMP message,
1261 in an attempt to make the sender lower his PMTU estimate;
1262 acceptable values are
1263 <B>yes</B>
1264
1265 and
1266 <B>no</B>
1267
1268 (the default).
1269 <DT><B>packetdefault</B>
1270
1271 <DD>
1272 what should be done with
1273 a packet which reaches KLIPS (via a route into a virtual interface)
1274 but does not match any eroute;
1275 acceptable values are
1276 <B>pass</B>
1277
1278 (<I>insecure unless you really know what you're doing!!!</I>),
1279 <B>drop</B>
1280
1281 (the default),
1282 and
1283 <B>reject</B>
1284
1285 (currently same as
1286 <B>drop</B>,
1287
1288 but eventually it will send an ICMP notification back
1289 to the sender).
1290 <DT><B>no_eroute_pass</B>
1291
1292 <DD>
1293 obsolete parameter similar to
1294 <B>packetdefault</B>
1295
1296 but with more limited functionality;
1297 ignored if
1298 <B>packetdefault</B>
1299
1300 is set;
1301 acceptable values are
1302 <B>yes</B>
1303
1304 (synonymous with
1305 <B>packetdefault=pass</B>)
1306
1307 and
1308 <B>no</B>
1309
1310 (synonymous with
1311 <B>packetdefault=drop</B>)
1312
1313 (the default).
1314 <DT><B>hidetos</B>
1315
1316 <DD>
1317 whether a tunnel packet's TOS field should be set to
1318 <B>0</B>
1319
1320 rather than copied from the user packet inside;
1321 acceptable values are
1322 <B>yes</B>
1323
1324 (the default)
1325 and
1326 <B>no</B>.
1327
1328 <DT><B>uniqueids</B>
1329
1330 <DD>
1331 whether a particular participant ID should be kept unique,
1332 with any new (automatically keyed)
1333 connection using an ID from a different IP address
1334 deemed to replace all old ones using that ID;
1335 acceptable values are
1336 <B>yes</B>
1337
1338 and
1339 <B>no</B>
1340
1341 (the default).
1342 <DT><B>overridemtu</B>
1343
1344 <DD>
1345 value that the MTU of the ipsec<I>n</I> interface(s) should be set to,
1346 overriding IPsec's (large) default.
1347 This parameter is needed only in special situations.
1348 </DL>
1349 <A NAME="lbAI">&nbsp;</A>
1350 <H2>FILES</H2>
1351
1352 /etc/ipsec.conf
1353 <A NAME="lbAJ">&nbsp;</A>
1354 <H2>SEE ALSO</H2>
1355
1356 <A HREF="ipsec.8.html">ipsec</A>(8), <A HREF="ipsec_ttoaddr.8.html">ipsec_ttoaddr</A>(8), <A HREF="ipsec_auto.8.html">ipsec_auto</A>(8), <A HREF="ipsec_manual.8.html">ipsec_manual</A>(8), <A HREF="ipsec_rsasigkey.8.html">ipsec_rsasigkey</A>(8)
1357 <A NAME="lbAK">&nbsp;</A>
1358 <H2>HISTORY</H2>
1359
1360 Designed for the FreeS/WAN project
1361 &lt;<A HREF="http://www.freeswan.org">http://www.freeswan.org</A>&gt;
1362 by Henry Spencer.
1363 <A NAME="lbAL">&nbsp;</A>
1364 <H2>BUGS</H2>
1365
1366 Including attributes of the keying channel
1367 (authentication methods,
1368 <B>ikelifetime</B>,
1369
1370 etc.)
1371 as an attribute of a connection,
1372 rather than of a participant pair, is dubious and incurs limitations.
1373 <P>
1374
1375 In general, the defaults often were chosen for backward compatibility
1376 and are less than ideal.
1377 Notably, the
1378 <B>keyingtries</B>
1379
1380 default should be
1381 <B>0</B>.
1382
1383 <P>
1384
1385 <I>Ipsec_manual</I>
1386
1387 is not nearly as generous about the syntax of subnets,
1388 addresses, etc. as the usual FreeS/WAN user interfaces.
1389 Four-component dotted-decimal must be used for all addresses.
1390 It
1391 <I>is</I>
1392
1393 smart enough to translate bit-count netmasks to dotted-decimal form.
1394 <P>
1395
1396 It would be good to have a line-continuation syntax,
1397 especially for the very long lines involved in
1398 RSA signature keys.
1399 <P>
1400
1401 The ability to specify different identities,
1402 <B>authby</B>,
1403
1404 and public keys for different automatic-keyed connections
1405 between the same participants is misleading;
1406 this doesn't work dependably because the identity of the participants
1407 is not known early enough.
1408 This is especially awkward for the ``Road Warrior'' case,
1409 where the remote IP address is specified as
1410 <B>0.0.0.0</B>,
1411
1412 and that is considered to be the ``participant'' for such connections.
1413 <P>
1414
1415 In principle it might be necessary to control MTU on an
1416 interface-by-interface basis,
1417 rather than with the single global override that
1418 <B>overridemtu</B>
1419
1420 provides.
1421 <P>
1422
1423 <HR>
1424 <A NAME="index">&nbsp;</A><H2>Index</H2>
1425 <DL>
1426 <DT><A HREF="#lbAB">NAME</A><DD>
1427 <DT><A HREF="#lbAC">DESCRIPTION</A><DD>
1428 <DT><A HREF="#lbAD">CONN SECTIONS</A><DD>
1429 <DL>
1430 <DT><A HREF="#lbAE">CONN PARAMETERS:  GENERAL</A><DD>
1431 <DT><A HREF="#lbAF">CONN PARAMETERS:  AUTOMATIC KEYING</A><DD>
1432 <DT><A HREF="#lbAG">CONN PARAMETERS:  MANUAL KEYING</A><DD>
1433 </DL>
1434 <DT><A HREF="#lbAH">CONFIG SECTIONS</A><DD>
1435 <DT><A HREF="#lbAI">FILES</A><DD>
1436 <DT><A HREF="#lbAJ">SEE ALSO</A><DD>
1437 <DT><A HREF="#lbAK">HISTORY</A><DD>
1438 <DT><A HREF="#lbAL">BUGS</A><DD>
1439 </DL>
1440 <HR>
1441 This document was created by
1442 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
1443 using the manual pages.<BR>
1444 Time: 05:09:30 GMT, June 19, 2001
1445 </BODY>
1446 </HTML>