diff options
Diffstat (limited to 'doc/manpage.d/ipsec.conf.5.html')
| -rw-r--r-- | doc/manpage.d/ipsec.conf.5.html | 1830 |
1 files changed, 0 insertions, 1830 deletions
diff --git a/doc/manpage.d/ipsec.conf.5.html b/doc/manpage.d/ipsec.conf.5.html deleted file mode 100644 index 36e0452ef..000000000 --- a/doc/manpage.d/ipsec.conf.5.html +++ /dev/null @@ -1,1830 +0,0 @@ -Content-type: text/html - -<HTML><HEAD><TITLE>Manpage of IPSEC.CONF</TITLE> -</HEAD><BODY> -<H1>IPSEC.CONF</H1> -Section: File Formats (5)<BR>Updated: 26 Nov 2001<BR><A HREF="#index">Index</A> -<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> - - -<A NAME="lbAB"> </A> -<H2>NAME</H2> - -ipsec.conf - IPsec configuration and connections -<A NAME="lbAC"> </A> -<H2>DESCRIPTION</H2> - -The optional -<I>ipsec.conf</I> - -file -specifies most configuration and control information for the -FreeS/WAN IPsec subsystem. -(The major exception is secrets for authentication; -see -<I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5).) - -Its contents are not security-sensitive -<I>unless</I> - -manual keying is being done for more than just testing, -in which case the encryption/authentication keys in the -descriptions for the manually-keyed connections are very sensitive -(and those connection descriptions -are probably best kept in a separate file, -via the include facility described below). -<P> - -The file is a text file, consisting of one or more -<I>sections</I>. - -White space followed by -<B>#</B> - -followed by anything to the end of the line -is a comment and is ignored, -as are empty lines which are not within a section. -<P> - -A line which contains -<B>include</B> - -and a file name, separated by white space, -is replaced by the contents of that file, -preceded and followed by empty lines. -If the file name is not a full pathname, -it is considered to be relative to the directory containing the -including file. -Such inclusions can be nested. -Only a single filename may be supplied, and it may not contain white space, -but it may include shell wildcards (see -<I><A HREF="sh.1.html">sh</A></I>(1)); - -for example: -<P> - -<B>include</B> - -<B>ipsec.*.conf</B> - -<P> - -The intention of the include facility is mostly to permit keeping -information on connections, or sets of connections, -separate from the main configuration file. -This permits such connection descriptions to be changed, -copied to the other security gateways involved, etc., -without having to constantly extract them from the configuration -file and then insert them back into it. -Note also the -<B>also</B> - -and -<B>alsoflip</B> - -parameters (described below) which permit splitting a single logical section -(e.g. a connection description) into several actual sections. -<P> - -The first significant line of the file must specify the version -of this specification that it conforms to: -<P> - -<B>version 2</B> -<P> - -A section -begins with a line of the form: -<P> - -<I>type</I> - -<I>name</I> - -<P> - -where -<I>type</I> - -indicates what type of section follows, and -<I>name</I> - -is an arbitrary name which distinguishes the section from others -of the same type. -(Names must start with a letter and may contain only -letters, digits, periods, underscores, and hyphens.) -All subsequent non-empty lines -which begin with white space are part of the section; -comments within a section must begin with white space too. -There may be only one section of a given type with a given name. -<P> - -Lines within the section are generally of the form -<P> - - <I>parameter</I><B>=</B><I>value</I> -<P> - -(note the mandatory preceding white space). -There can be white space on either side of the -<B>=</B>. - -Parameter names follow the same syntax as section names, -and are specific to a section type. -Unless otherwise explicitly specified, -no parameter name may appear more than once in a section. -<P> - -An empty -<I>value</I> - -stands for the system default value (if any) of the parameter, -i.e. it is roughly equivalent to omitting the parameter line entirely. -A -<I>value</I> - -may contain white space only if the entire -<I>value</I> - -is enclosed in double quotes (<B>"</B>); -a -<I>value</I> - -cannot itself contain a double quote, -nor may it be continued across more than one line. -<P> - -Numeric values are specified to be either an ``integer'' -(a sequence of digits) or a ``decimal number'' -(sequence of digits optionally followed by `.' and another sequence of digits). -<P> - -There is currently one parameter which is available in any type of -section: -<DL COMPACT> -<DT><B>also</B> - -<DD> -the value is a section name; -the parameters of that section are appended to this section, -as if they had been written as part of it. -The specified section must exist, must follow the current one, -and must have the same section type. -(Nesting is permitted, -and there may be more than one -<B>also</B> - -in a single section, -although it is forbidden to append the same section more than once.) -This allows, for example, keeping the encryption keys -for a connection in a separate file -from the rest of the description, by using both an -<B>also</B> - -parameter and an -<B>include</B> - -line. -(Caution, see BUGS below for some restrictions.) -<DT><B>alsoflip</B> - -<DD> -can be used in a -<B>conn</B> - -section. -It acts like an -<B>also</B> - -that flips the referenced section's entries left-for-right. -</DL> -<P> - -Parameter names beginning with -<B>x-</B> - -(or -<B>X-</B>, - -or -<B>x_</B>, - -or -<B>X_</B>) - -are reserved for user extensions and will never be assigned meanings -by IPsec. -Parameters with such names must still observe the syntax rules -(limits on characters used in the name; -no white space in a non-quoted value; -no newlines or double quotes within the value). -All other as-yet-unused parameter names are reserved for future IPsec -improvements. -<P> - -A section with name -<B>%default</B> - -specifies defaults for sections of the same type. -For each parameter in it, -any section of that type which does not have a parameter of the same name -gets a copy of the one from the -<B>%default</B> - -section. -There may be multiple -<B>%default</B> - -sections of a given type, -but only one default may be supplied for any specific parameter name, -and all -<B>%default</B> - -sections of a given type must precede all non-<B>%default</B> - -sections of that type. -<B>%default</B> - -sections may not contain -<B>also</B> - -or -<B>alsoflip</B> - -parameters. -<P> - -Currently there are two types of section: -a -<B>config</B> - -section specifies general configuration information for IPsec, -while a -<B>conn</B> - -section specifies an IPsec connection. -<A NAME="lbAD"> </A> -<H2>CONN SECTIONS</H2> - -A -<B>conn</B> - -section contains a -<I>connection specification</I>, - -defining a network connection to be made using IPsec. -The name given is arbitrary, and is used to identify the connection to -<I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) - -and -<I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8). - -Here's a simple example: -<P> - - -<PRE> -<B> -conn snt - left=10.11.11.1 - leftsubnet=10.0.1.0/24 - leftnexthop=172.16.55.66 - right=192.168.22.1 - rightsubnet=10.0.2.0/24 - rightnexthop=172.16.88.99 - keyingtries=%forever -</B></PRE> - -<P> - -A note on terminology... -In automatic keying, there are two kinds of communications going on: -transmission of user IP packets, and gateway-to-gateway negotiations for -keying, rekeying, and general control. -The data path (a set of ``IPsec SAs'') used for user packets is herein -referred to as the ``connection''; -the path used for negotiations (built with ``ISAKMP SAs'') is referred to as -the ``keying channel''. -<P> - -To avoid trivial editing of the configuration file to suit it to each system -involved in a connection, -connection specifications are written in terms of -<I>left</I> - -and -<I>right</I> - -participants, -rather than in terms of local and remote. -Which participant is considered -<I>left</I> - -or -<I>right</I> - -is arbitrary; -IPsec figures out which one it is being run on based on internal information. -This permits using identical connection specifications on both ends. -There are cases where there is no symmetry; a good convention is to -use -<I>left</I> - -for the local side and -<I>right</I> - -for the remote side (the first letters are a good mnemonic). -<P> - -Many of the parameters relate to one participant or the other; -only the ones for -<I>left</I> - -are listed here, but every parameter whose name begins with -<B>left</B> - -has a -<B>right</B> - -counterpart, -whose description is the same but with -<B>left</B> - -and -<B>right</B> - -reversed. -<P> - -Parameters are optional unless marked ``(required)''; -a parameter required for manual keying need not be included for -a connection which will use only automatic keying, and vice versa. -<A NAME="lbAE"> </A> -<H3>CONN PARAMETERS: GENERAL</H3> - -The following parameters are relevant to both automatic and manual keying. -Unless otherwise noted, -for a connection to work, -in general it is necessary for the two ends to agree exactly -on the values of these parameters. -<DL COMPACT> -<DT><B>type</B> - -<DD> -the type of the connection; currently the accepted values -are -<B>tunnel</B> - -(the default) -signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; -<B>transport</B>, - -signifying host-to-host transport mode; -<B>passthrough</B>, - -signifying that no IPsec processing should be done at all; -<B>drop</B>, - -signifying that packets should be discarded; and -<B>reject</B>, - -signifying that packets should be discarded and a diagnostic ICMP returned. -<DT><B>left</B> - -<DD> -(required) -the IP address of the left participant's public-network interface, -in any form accepted by -<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3) - -or one of several magic values. -If it is -<B>%defaultroute</B>, - -and -the -<B>config</B> - -<B>setup</B> - -section's, -<B>interfaces</B> - -specification contains -<B>%defaultroute,</B> - -<B>left</B> - -will be filled in automatically with the local address -of the default-route interface (as determined at IPsec startup time); -this also overrides any value supplied for -<B>leftnexthop</B>. - -(Either -<B>left</B> - -or -<B>right</B> - -may be -<B>%defaultroute</B>, - -but not both.) -The value -<B>%any</B> - -signifies an address to be filled in (by automatic keying) during -negotiation. -The value -<B>%opportunistic</B> - -signifies that both -<B>left</B> - -and -<B>leftnexthop</B> - -are to be filled in (by automatic keying) from DNS data for -<B>left</B>'s - -client. -The values -<B>%group</B> - -and -<B>%opportunisticgroup</B> - -makes this a policy group conn: one that will be instantiated -into a regular or opportunistic conn for each CIDR block listed in the -policy group file with the same name as the conn. -<DT><B>leftsubnet</B> - -<DD> -private subnet behind the left participant, expressed as -<I>network</I><B>/</B><I>netmask</I> -(actually, any form acceptable to -<I><A HREF="ipsec_ttosubnet.3.html">ipsec_ttosubnet</A></I>(3)); - -if omitted, essentially assumed to be <I>left</I><B>/32</B>, -signifying that the left end of the connection goes to the left participant only -<DT><B>leftnexthop</B> - -<DD> -next-hop gateway IP address for the left participant's connection -to the public network; -defaults to -<B>%direct</B> - -(meaning -<I>right</I>). - -If the value is to be overridden by the -<B>left=%defaultroute</B> - -method (see above), -an explicit value must -<I>not</I> - -be given. -If that method is not being used, -but -<B>leftnexthop</B> - -is -<B>%defaultroute</B>, - -and -<B>interfaces=%defaultroute</B> - -is used in the -<B>config</B> - -<B>setup</B> - -section, -the next-hop gateway address of the default-route interface -will be used. -The magic value -<B>%direct</B> - -signifies a value to be filled in (by automatic keying) -with the peer's address. -Relevant only locally, other end need not agree on it. -<DT><B>leftupdown</B> - -<DD> -what ``updown'' script to run to adjust routing and/or firewalling -when the status of the connection -changes (default -<B>ipsec _updown</B>). - -May include positional parameters separated by white space -(although this requires enclosing the whole string in quotes); -including shell metacharacters is unwise. -See -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8) - -for details. -Relevant only locally, other end need not agree on it. -<DT><B>leftfirewall</B> - -<DD> -whether the left participant is doing forwarding-firewalling -(including masquerading) for traffic from <I>leftsubnet</I>, -which should be turned off (for traffic to the other subnet) -once the connection is established; -acceptable values are -<B>yes</B> - -and (the default) -<B>no</B>. - -May not be used in the same connection description with -<B>leftupdown</B>. - -Implemented as a parameter to the default -<I>updown</I> - -script. -See notes below. -Relevant only locally, other end need not agree on it. -</DL> -<P> - -If one or both security gateways are doing forwarding firewalling -(possibly including masquerading), -and this is specified using the firewall parameters, -tunnels established with IPsec are exempted from it -so that packets can flow unchanged through the tunnels. -(This means that all subnets connected in this manner must have -distinct, non-overlapping subnet address blocks.) -This is done by the default -<I>updown</I> - -script (see -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8)). - -<P> - -The implementation of this makes certain assumptions about firewall setup, -notably the use of the old -<I>ipfwadm</I> - -interface to the firewall. -In situations calling for more control, -it may be preferable for the user to supply his own -<I>updown</I> - -script, -which makes the appropriate adjustments for his system. -<A NAME="lbAF"> </A> -<H3>CONN PARAMETERS: AUTOMATIC KEYING</H3> - -The following parameters are relevant only to automatic keying, -and are ignored in manual keying. -Unless otherwise noted, -for a connection to work, -in general it is necessary for the two ends to agree exactly -on the values of these parameters. -<DL COMPACT> -<DT><B>keyexchange</B> - -<DD> -method of key exchange; -the default and currently the only accepted value is -<B>ike</B> - -<DT><B>auto</B> - -<DD> -what operation, if any, should be done automatically at IPsec startup; -currently-accepted values are -<B>add</B> - -(signifying an -<B>ipsec auto</B> - -<B>--add</B>), - -<B>route</B> - -(signifying that plus an -<B>ipsec auto</B> - -<B>--route</B>), - -<B>start</B> - -(signifying that plus an -<B>ipsec auto</B> - -<B>--up</B>), - -<B>manual</B> - -(signifying an -<B>ipsec</B> - -<B>manual</B> - -<B>--up</B>), - -and -<B>ignore</B> - -(also the default) (signifying no automatic startup operation). -See the -<B>config</B> - -<B>setup</B> - -discussion below. -Relevant only locally, other end need not agree on it -(but in general, for an intended-to-be-permanent connection, -both ends should use -<B>auto=start</B> - -to ensure that any reboot causes immediate renegotiation). -<DT><B>auth</B> - -<DD> -whether authentication should be done as part of -ESP encryption, or separately using the AH protocol; -acceptable values are -<B>esp</B> - -(the default) and -<B>ah</B>. - -<DT><B>authby</B> - -<DD> -how the two security gateways should authenticate each other; -acceptable values are -<B>secret</B> - -for shared secrets, -<B>rsasig</B> - -for RSA digital signatures (the default), -<B>secret|rsasig</B> - -for either, and -<B>never</B> - -if negotiation is never to be attempted or accepted (useful for shunt-only conns). -Digital signatures are superior in every way to shared secrets. -<DT><B>leftid</B> - -<DD> -how -the left participant -should be identified for authentication; -defaults to -<B>left</B>. - -Can be an IP address (in any -<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3) - -syntax) -or a fully-qualified domain name preceded by -<B>@</B> - -(which is used as a literal string and not resolved). -The magic value -<B>%myid</B> - -stands for the current setting of <I>myid</I>. -This is set in <B>config setup</B> or by <I><A HREF="ipsec_whack.8.html">ipsec_whack</A></I>(8)), or, if not set, -it is the IP address in <B>%defaultroute</B> (if that is supported by a TXT record in its reverse domain), or otherwise -it is the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined. -<DT><B>leftrsasigkey</B> - -<DD> -the left participant's -public key for RSA signature authentication, -in RFC 2537 format using -<I><A HREF="ipsec_ttodata.3.html">ipsec_ttodata</A></I>(3) - -encoding. -The magic value -<B>%none</B> - -means the same as not specifying a value (useful to override a default). -The value -<B>%dnsondemand</B> - -(the default) -means the key is to be fetched from DNS at the time it is needed. -The value -<B>%dnsonload</B> - -means the key is to be fetched from DNS at the time -the connection description is read from -<I>ipsec.conf</I>; - -currently this will be treated as -<B>%none</B> - -if -<B>right=%any</B> - -or -<B>right=%opportunistic</B>. - -The value -<B>%dns</B> - -is currently treated as -<B>%dnsonload</B> - -but will change to -<B>%dnsondemand</B> - -in the future. -The identity used for the left participant -must be a specific host, not -<B>%any</B> - -or another magic value. -<B>Caution:</B> - -if two connection descriptions -specify different public keys for the same -<B>leftid</B>, - -confusion and madness will ensue. -<DT><B>leftrsasigkey2</B> - -<DD> -if present, a second public key. -Either key can authenticate the signature, allowing for key rollover. -<DT><B>pfs</B> - -<DD> -whether Perfect Forward Secrecy of keys is desired on the connection's -keying channel -(with PFS, penetration of the key-exchange protocol -does not compromise keys negotiated earlier); -acceptable values are -<B>yes</B> - -(the default) -and -<B>no</B>. - -<DT><B>keylife</B> - -<DD> -how long a particular instance of a connection -(a set of encryption/authentication keys for user packets) should last, -from successful negotiation to expiry; -acceptable values are an integer optionally followed by -<B>s</B> - -(a time in seconds) -or a decimal number followed by -<B>m</B>, - -<B>h</B>, - -or -<B>d</B> - -(a time -in minutes, hours, or days respectively) -(default -<B>8.0h</B>, - -maximum -<B>24h</B>). - -Normally, the connection is renegotiated (via the keying channel) -before it expires. -The two ends need not exactly agree on -<B>keylife</B>, - -although if they do not, -there will be some clutter of superseded connections on the end -which thinks the lifetime is longer. -<DT><B>rekey</B> - -<DD> -whether a connection should be renegotiated when it is about to expire; -acceptable values are -<B>yes</B> - -(the default) -and -<B>no</B>. - -The two ends need not agree, -but while a value of -<B>no</B> - -prevents Pluto from requesting renegotiation, -it does not prevent responding to renegotiation requested from the other end, -so -<B>no</B> - -will be largely ineffective unless both ends agree on it. -<DT><B>rekeymargin</B> - -<DD> -how long before connection expiry or keying-channel expiry -should attempts to -negotiate a replacement -begin; acceptable values as for -<B>keylife</B> - -(default -<B>9m</B>). - -Relevant only locally, other end need not agree on it. -<DT><B>rekeyfuzz</B> - -<DD> -maximum percentage by which -<B>rekeymargin</B> - -should be randomly increased to randomize rekeying intervals -(important for hosts with many connections); -acceptable values are an integer, -which may exceed 100, -followed by a `%' -(default set by -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8), - -currently -<B>100%</B>). - -The value of -<B>rekeymargin</B>, - -after this random increase, -must not exceed -<B>keylife</B>. - -The value -<B>0%</B> - -will suppress time randomization. -Relevant only locally, other end need not agree on it. -<DT><B>keyingtries</B> - -<DD> -how many attempts (a whole number or <B>%forever</B>) should be made to -negotiate a connection, or a replacement for one, before giving up -(default -<B>%forever</B>). - -The value <B>%forever</B> -means ``never give up'' (obsolete: this can be written <B>0</B>). -Relevant only locally, other end need not agree on it. -<DT><B>ikelifetime</B> - -<DD> -how long the keying channel of a connection (buzzphrase: ``ISAKMP SA'') -should last before being renegotiated; -acceptable values as for -<B>keylife</B> - -(default set by -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8), - -currently -<B>1h</B>, - -maximum -<B>8h</B>). - -The two-ends-disagree case is similar to that of -<B>keylife</B>. - -<DT><B>compress</B> - -<DD> -whether IPComp compression of content is proposed on the connection -(link-level compression does not work on encrypted data, -so to be effective, compression must be done <I>before</I> encryption); -acceptable values are -<B>yes</B> - -and -<B>no</B> - -(the default). -The two ends need not agree. -A value of -<B>yes</B> - -causes IPsec to propose both compressed and uncompressed, -and prefer compressed. -A value of -<B>no</B> - -prevents IPsec from proposing compression; -a proposal to compress will still be accepted. -<DT><B>disablearrivalcheck</B> - -<DD> -whether KLIPS's normal tunnel-exit check -(that a packet emerging from a tunnel has plausible addresses in its header) -should be disabled; -acceptable values are -<B>yes</B> - -and -<B>no</B> - -(the default). -Tunnel-exit checks improve security and do not break any normal configuration. -Relevant only locally, other end need not agree on it. -<DT><B>failureshunt</B> - -<DD> -what to do with packets when negotiation fails. -The default is -<B>none</B>: - -no shunt; -<B>passthrough</B>, - -<B>drop</B>, - -and -<B>reject</B> - -have the obvious meanings. -</DL> -<A NAME="lbAG"> </A> -<H3>CONN PARAMETERS: MANUAL KEYING</H3> - -The following parameters are relevant only to manual keying, -and are ignored in automatic keying. -Unless otherwise noted, -for a connection to work, -in general it is necessary for the two ends to agree exactly -on the values of these parameters. -A manually-keyed -connection must specify at least one of AH or ESP. -<DL COMPACT> -<DT><B>spi</B> - -<DD> -(this or -<B>spibase</B> - -required for manual keying) -the SPI number to be used for the connection (see -<I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8)); - -must be of the form <B>0x</B><I>hex</I><B></B>, -where -<I>hex</I> - -is one or more hexadecimal digits -(note, it will generally be necessary to make -<I>spi</I> - -at least -<B>0x100</B> - -to be acceptable to KLIPS, -and use of SPIs in the range -<B>0x100</B>-<B>0xfff</B> - -is recommended) -<DT><B>spibase</B> - -<DD> -(this or -<B>spi</B> - -required for manual keying) -the base number for the SPIs to be used for the connection (see -<I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8)); - -must be of the form <B>0x</B><I>hex</I><B>0</B>, -where -<I>hex</I> - -is one or more hexadecimal digits -(note, it will generally be necessary to make -<I>spibase</I> - -at least -<B>0x100</B> - -for the resulting SPIs -to be acceptable to KLIPS, -and use of numbers in the range -<B>0x100</B>-<B>0xff0</B> - -is recommended) -<DT><B>esp</B> - -<DD> -ESP encryption/authentication algorithm to be used -for the connection, e.g. -<B>3des-md5-96</B> - -(must be suitable as a value of -<I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s - -<B>--esp</B> - -option); -default is not to use ESP -<DT><B>espenckey</B> - -<DD> -ESP encryption key -(must be suitable as a value of -<I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s - -<B>--enckey</B> - -option) -(may be specified separately for each direction using -<B>leftespenckey</B> - -(leftward SA) -and -<B>rightespenckey</B> - -parameters) -<DT><B>espauthkey</B> - -<DD> -ESP authentication key -(must be suitable as a value of -<I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s - -<B>--authkey</B> - -option) -(may be specified separately for each direction using -<B>leftespauthkey</B> - -(leftward SA) -and -<B>rightespauthkey</B> - -parameters) -<DT><B>espreplay_window</B> - -<DD> -ESP replay-window setting, -an integer from -<B>0</B> - -(the -<I>ipsec_manual</I> - -default, which turns off replay protection) to -<B>64</B>; - -relevant only if ESP authentication is being used -<DT><B>leftespspi</B> - -<DD> -SPI to be used for the leftward ESP SA, overriding -automatic assignment using -<B>spi</B> - -or -<B>spibase</B>; - -typically a hexadecimal number beginning with -<B>0x</B> - -<DT><B>ah</B> - -<DD> -AH authentication algorithm to be used -for the connection, e.g. -<B>hmac-md5-96</B> - -(must be suitable as a value of -<I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s - -<B>--ah</B> - -option); -default is not to use AH -<DT><B>ahkey</B> - -<DD> -(required if -<B>ah</B> - -is present) AH authentication key -(must be suitable as a value of -<I><A HREF="ipsec_spi.8.html">ipsec_spi</A></I>(8)'s - -<B>--authkey</B> - -option) -(may be specified separately for each direction using -<B>leftahkey</B> - -(leftward SA) -and -<B>rightahkey</B> - -parameters) -<DT><B>ahreplay_window</B> - -<DD> -AH replay-window setting, -an integer from -<B>0</B> - -(the -<I>ipsec_manual</I> - -default, which turns off replay protection) to -<B>64</B> - -<DT><B>leftahspi</B> - -<DD> -SPI to be used for the leftward AH SA, overriding -automatic assignment using -<B>spi</B> - -or -<B>spibase</B>; - -typically a hexadecimal number beginning with -<B>0x</B> - -</DL> -<A NAME="lbAH"> </A> -<H2>CONFIG SECTIONS</H2> - -At present, the only -<B>config</B> - -section known to the IPsec software is the one named -<B>setup</B>, - -which contains information used when the software is being started -(see -<I><A HREF="ipsec_setup.8.html">ipsec_setup</A></I>(8)). - -Here's an example: -<P> - - -<PRE> -<B> -config setup - interfaces="ipsec0=eth1 ipsec1=ppp0" - klipsdebug=none - plutodebug=all - manualstart= -</B></PRE> - -<P> - -Parameters are optional unless marked ``(required)''. -The currently-accepted -<I>parameter</I> - -names in a -<B>config</B> - -<B>setup</B> - -section are: -<DL COMPACT> -<DT><B>myid</B> - -<DD> -the identity to be used for -<B>%myid</B>. - -<B>%myid</B> - -is used in the implicit policy group conns and can be used as -an identity in explicit conns. -If unspecified, -<B>%myid</B> - -is set to the IP address in <B>%defaultroute</B> (if that is supported by a TXT record in its reverse domain), or otherwise -the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined. -An explicit value generally starts with ``<B>@</B>''. -<DT><B>interfaces</B> - -<DD> -virtual and physical interfaces for IPsec to use: -a single -<I>virtual</I><B>=</B><I>physical</I> pair, a (quoted!) list of pairs separated -by white space, or -<B>%none</B>. - -One of the pairs may be written as -<B>%defaultroute</B>, - -which means: find the interface <I>d</I> that the default route points to, -and then act as if the value was ``<B>ipsec0=</B><I>d</I>''. -<B>%defaultroute</B> - -is the default; -<B>%none</B> - -must be used to denote no interfaces. -If -<B>%defaultroute</B> - -is used (implicitly or explicitly) -information about the default route and its interface is noted for -use by -<I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8) - -and -<I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8).) - -<DT><B>forwardcontrol</B> - -<DD> -whether -<I>setup</I> - -should turn IP forwarding on -(if it's not already on) as IPsec is started, -and turn it off again (if it was off) as IPsec is stopped; -acceptable values are -<B>yes</B> - -and (the default) -<B>no</B>. - -For this to have full effect, forwarding must be -disabled before the hardware interfaces are brought -up (e.g., -<B>net.ipv4.ip_forward = 0</B> - -in Red Hat 6.x -<I>/etc/sysctl.conf</I>), - -because IPsec doesn't get control early enough to do that. -<DT><B>rp_filter</B> - -<DD> -whether and how -<I>setup</I> - -should adjust the reverse path filtering mechanism for the -physical devices to be used. -Values are <B>%unchanged</B> (to leave it alone) -or <B>0</B>, <B>1</B>, <B>2</B> (values to set it to). -<I>/proc/sys/net/ipv4/conf/PHYS/rp_filter</I> -is badly documented; it must be <B>0</B> in many cases -for ipsec to function. -The default value for the parameter is <B>0</B>. -<DT><B>syslog</B> - -<DD> -the -<I><A HREF="syslog.2.html">syslog</A></I>(2) - -``facility'' name and priority to use for -startup/shutdown log messages, -default -<B>daemon.error</B>. - -<DT><B>klipsdebug</B> - -<DD> -how much KLIPS debugging output should be logged. -An empty value, -or the magic value -<B>none</B>, - -means no debugging output (the default). -The magic value -<B>all</B> - -means full output. -Otherwise only the specified types of output -(a quoted list, names separated by white space) are enabled; -for details on available debugging types, see -<I><A HREF="ipsec_klipsdebug.8.html">ipsec_klipsdebug</A></I>(8). - -<DT><B>plutodebug</B> - -<DD> -how much Pluto debugging output should be logged. -An empty value, -or the magic value -<B>none</B>, - -means no debugging output (the default). -The magic value -<B>all</B> - -means full output. -Otherwise only the specified types of output -(a quoted list, names without the -<B>--debug-</B> - -prefix, -separated by white space) are enabled; -for details on available debugging types, see -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8). - -<DT><B>plutoopts</B> - -<DD> -additional options to pass to pluto upon startup. See -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8). - -<DT><B>plutostderrlog</B> - -<DD> -do not use syslog, but rather log to stderr, and direct stderr to the -argument file. -<DT><B>dumpdir</B> - -<DD> -in what directory should things started by -<I>setup</I> - -(notably the Pluto daemon) be allowed to -dump core? -The empty value (the default) means they are not -allowed to. -<DT><B>manualstart</B> - -<DD> -which manually-keyed connections to set up at startup -(empty, a name, or a quoted list of names separated by white space); -see -<I><A HREF="ipsec_manual.8.html">ipsec_manual</A></I>(8). - -Default is none. -<DT><B>pluto</B> - -<DD> -whether to start Pluto or not; -Values are -<B>yes</B> - -(the default) -or -<B>no</B> - -(useful only in special circumstances). -<DT><B>plutowait</B> - -<DD> -should Pluto wait for each -negotiation attempt that is part of startup to -finish before proceeding with the next? -Values are -<B>yes</B> - -or -<B>no</B> - -(the default). -<DT><B>prepluto</B> - -<DD> -shell command to run before starting Pluto -(e.g., to decrypt an encrypted copy of the -<I>ipsec.secrets</I> - -file). -It's run in a very simple way; -complexities like I/O redirection are best hidden within a script. -Any output is redirected for logging, -so running interactive commands is difficult unless they use -<I>/dev/tty</I> - -or equivalent for their interaction. -Default is none. -<DT><B>postpluto</B> - -<DD> -shell command to run after starting Pluto -(e.g., to remove a decrypted copy of the -<I>ipsec.secrets</I> - -file). -It's run in a very simple way; -complexities like I/O redirection are best hidden within a script. -Any output is redirected for logging, -so running interactive commands is difficult unless they use -<I>/dev/tty</I> - -or equivalent for their interaction. -Default is none. -<DT><B>fragicmp</B> - -<DD> -whether a tunnel's need to fragment a packet should be reported -back with an ICMP message, -in an attempt to make the sender lower his PMTU estimate; -acceptable values are -<B>yes</B> - -(the default) -and -<B>no</B>. - -<DT><B>hidetos</B> - -<DD> -whether a tunnel packet's TOS field should be set to -<B>0</B> - -rather than copied from the user packet inside; -acceptable values are -<B>yes</B> - -(the default) -and -<B>no</B>. - -<DT><B>uniqueids</B> - -<DD> -whether a particular participant ID should be kept unique, -with any new (automatically keyed) -connection using an ID from a different IP address -deemed to replace all old ones using that ID; -acceptable values are -<B>yes</B> - -(the default) -and -<B>no</B>. - -Participant IDs normally <I>are</I> unique, -so a new (automatically-keyed) connection using the same ID is -almost invariably intended to replace an old one. -<DT><B>overridemtu</B> - -<DD> -value that the MTU of the ipsec<I>n</I> interface(s) should be set to, -overriding IPsec's (large) default. -This parameter is needed only in special situations. -</DL> -<A NAME="lbAI"> </A> -<H2>IMPLICIT CONNS</H2> - -<P> - -The system automatically defines several conns to implement -default policy groups. Each can be overridden by explicitly -defining a new conn with the same name. If the new conn has <B>auto=ignore</B>, -the definition is suppressed. -<P> - -Here are the automatically supplied definitions. -<P> - - -<PRE> -<B> -conn clear - type=passthrough - authby=never - left=%defaultroute - right=%group - auto=route - -conn clear-or-private - type=passthrough - left=%defaultroute - leftid=%myid - right=%opportunisticgroup - failureshunt=passthrough - keyingtries=3 - ikelifetime=1h - keylife=1h - rekey=no - auto=route - -conn private-or-clear - type=tunnel - left=%defaultroute - leftid=%myid - right=%opportunisticgroup - failureshunt=passthrough - keyingtries=3 - ikelifetime=1h - keylife=1h - rekey=no - auto=route - -conn private - type=tunnel - left=%defaultroute - leftid=%myid - right=%opportunisticgroup - failureshunt=drop - keyingtries=3 - ikelifetime=1h - keylife=1h - rekey=no - auto=route - -conn block - type=reject - authby=never - left=%defaultroute - right=%group - auto=route - -# default policy -conn packetdefault - type=tunnel - left=%defaultroute - leftid=%myid - left=0.0.0.0/0 - right=%opportunistic - failureshunt=passthrough - keyingtries=3 - ikelifetime=1h - keylife=1h - rekey=no - auto=route -</B></PRE> - -<P> - -These conns are <I>not</I> affected by anything in <B>conn %default</B>. -They will only work if <B>%defaultroute</B> works. -The <B>leftid</B> will be the interfaces IP address; this -requires that reverse DNS records be set up properly. -<P> - -The implicit conns are defined after all others. It is -appropriate and reasonable to use <B>also=private-or-clear</B> -(for example) in any other opportunistic conn. -<A NAME="lbAJ"> </A> -<H2>POLICY GROUP FILES</H2> - -<P> - -The optional files under -<I>/etc/ipsec.d/policy</I>, - -including -<PRE> - -/etc/ipsec.d/policies/clear -/etc/ipsec.d/policies/clear-or-private -/etc/ipsec.d/policies/private-or-clear -/etc/ipsec.d/policies/private -/etc/ipsec.d/policies/block - -</PRE> - -may contain policy group configuration information to -supplement -<I>ipsec.conf</I>. - -Their contents are not security-sensitive. -<P> - -These files are text files. -Each consists of a list of CIDR blocks, one per line. -White space followed by # followed by anything to the end of the line -is a comment and is ignored, as are empty lines. -<P> - -A connection in -<I>/etc/ipsec.conf</I> - -which has -<B>right=%group</B> - -or -<B>right=%opportunisticgroup</B> - -is a policy group connection. -When a policy group file of the same name is loaded, with -<P> - - <B>ipsec auto --rereadgroups</B> -<P> - -or at system start, the connection is instantiated such that each -CIDR block serves as an instance's -<B>right</B> - -value. The system treats the -resulting instances as normal connections. -<P> - -For example, given a suitable connection definition -<B>private</B>, - -and the file -<I>/etc/ipsec.d/policy/private </I> - -with an entry 192.0.2.3, -the system creates a connection instance -<B>private#192.0.2.3.</B> - -This connection inherits all details from -<B>private</B>, - -except that its right client is 192.0.2.3. -<A NAME="lbAK"> </A> -<H2>DEFAULT POLICY GROUPS</H2> - -<P> - -The standard FreeS/WAN install includes several policy groups -which provide a way of classifying possible peers into IPsec security classes: -<B>private</B> - -(talk encrypted only), -<B>private-or-clear</B> - -(prefer encryption), -<B>clear-or-private</B> - -(respond to requests for encryption), -<B>clear</B> - -and -<B>block</B>. - -Implicit policy groups apply to the local host only, -and are implemented by the -<B>IMPLICIT CONNECTIONS </B> - -described above. -<A NAME="lbAL"> </A> -<H2>CHOOSING A CONNECTION</H2> - -<P> - -When choosing a connection to apply to an outbound packet caught with a -<B>%trap,</B> - -the system prefers the one with the most specific eroute that -includes the packet's source and destination IP addresses. -Source subnets are examined before destination subnets. -For initiating, only routed connections are considered. For responding, -unrouted but added connections are considered. -<P> - -When choosing a connection to use to respond to a negotiation which -doesn't match an ordinary conn, an opportunistic connection -may be instantiated. Eventually, its instance will be /32 -> /32, but -for earlier stages of the negotiation, there will not be enough -information about the client subnets to complete the instantiation. -<A NAME="lbAM"> </A> -<H2>FILES</H2> - -<PRE> -/etc/ipsec.conf -/etc/ipsec.d/policies/clear -/etc/ipsec.d/policies/clear-or-private -/etc/ipsec.d/policies/private-or-clear -/etc/ipsec.d/policies/private -/etc/ipsec.d/policies/block -</PRE> - -<A NAME="lbAN"> </A> -<H2>SEE ALSO</H2> - -<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) -<A NAME="lbAO"> </A> -<H2>HISTORY</H2> - -Designed for the FreeS/WAN project -<<A HREF="http://www.freeswan.org">http://www.freeswan.org</A>> -by Henry Spencer. -<A NAME="lbAP"> </A> -<H2>BUGS</H2> - -<P> - -When -<B>type</B> - -or -<B>failureshunt</B> - -is set to -<B>drop</B> - -or -<B>reject,</B> - -FreeS/WAN blocks outbound packets using eroutes, but assumes inbound -blocking is handled by the firewall. FreeS/WAN offers firewall hooks -via an ``updown'' script. However, the default -<B>ipsec _updown</B> - -provides no help in controlling a modern firewall. -<P> - -Including attributes of the keying channel -(authentication methods, -<B>ikelifetime</B>, - -etc.) -as an attribute of a connection, -rather than of a participant pair, is dubious and incurs limitations. -<P> - -<I>Ipsec_manual</I> - -is not nearly as generous about the syntax of subnets, -addresses, etc. as the usual FreeS/WAN user interfaces. -Four-component dotted-decimal must be used for all addresses. -It -<I>is</I> - -smart enough to translate bit-count netmasks to dotted-decimal form. -<P> - -It would be good to have a line-continuation syntax, -especially for the very long lines involved in -RSA signature keys. -<P> - -The ability to specify different identities, -<B>authby</B>, - -and public keys for different automatic-keyed connections -between the same participants is misleading; -this doesn't work dependably because the identity of the participants -is not known early enough. -This is especially awkward for the ``Road Warrior'' case, -where the remote IP address is specified as -<B>0.0.0.0</B>, - -and that is considered to be the ``participant'' for such connections. -<P> - -In principle it might be necessary to control MTU on an -interface-by-interface basis, -rather than with the single global override that -<B>overridemtu</B> - -provides. -<P> - -A number of features which <I>could</I> be implemented in -both manual and automatic keying -actually are not yet implemented for manual keying. -This is unlikely to be fixed any time soon. -<P> - -If conns are to be added before DNS is available, -<B>left=</B><I>FQDN</I>, -<B>leftnextop=</B><I>FQDN</I>, -and -<B>leftrsasigkey=%dnsonload</B> - -will fail. -<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8) - -does not actually use the public key for our side of a conn but it -isn't generally known at a add-time which side is ours (Road Warrior -and Opportunistic conns are currently exceptions). -<P> - -The <B>myid</B> option does not affect explicit <B> ipsec auto --add</B> or <B>ipsec auto --replace</B> commands for implicit conns. -<P> - -<HR> -<A NAME="index"> </A><H2>Index</H2> -<DL> -<DT><A HREF="#lbAB">NAME</A><DD> -<DT><A HREF="#lbAC">DESCRIPTION</A><DD> -<DT><A HREF="#lbAD">CONN SECTIONS</A><DD> -<DL> -<DT><A HREF="#lbAE">CONN PARAMETERS: GENERAL</A><DD> -<DT><A HREF="#lbAF">CONN PARAMETERS: AUTOMATIC KEYING</A><DD> -<DT><A HREF="#lbAG">CONN PARAMETERS: MANUAL KEYING</A><DD> -</DL> -<DT><A HREF="#lbAH">CONFIG SECTIONS</A><DD> -<DT><A HREF="#lbAI">IMPLICIT CONNS</A><DD> -<DT><A HREF="#lbAJ">POLICY GROUP FILES</A><DD> -<DT><A HREF="#lbAK">DEFAULT POLICY GROUPS</A><DD> -<DT><A HREF="#lbAL">CHOOSING A CONNECTION</A><DD> -<DT><A HREF="#lbAM">FILES</A><DD> -<DT><A HREF="#lbAN">SEE ALSO</A><DD> -<DT><A HREF="#lbAO">HISTORY</A><DD> -<DT><A HREF="#lbAP">BUGS</A><DD> -</DL> -<HR> -This document was created by -<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, -using the manual pages.<BR> -Time: 21:40:17 GMT, November 11, 2003 -</BODY> -</HTML> |