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, 1830 insertions, 0 deletions
diff --git a/doc/manpage.d/ipsec.conf.5.html b/doc/manpage.d/ipsec.conf.5.html new file mode 100644 index 000000000..36e0452ef --- /dev/null +++ b/doc/manpage.d/ipsec.conf.5.html @@ -0,0 +1,1830 @@ +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> |