ipsec.conf.5

来自「This a good VPN source」· 5 代码 · 共 1,422 行 · 第 1/3 页

.TH IPSEC.CONF 5 "26 Nov 2001"
.\" RCSID $Id: ipsec.conf.5,v 1.108 2004/11/01 22:40:05 ken Exp $
.SH NAME
ipsec.conf \- IPsec configuration and connections
.SH DESCRIPTION
The optional
.I ipsec.conf
file
specifies most configuration and control information for the
Openswan IPsec subsystem.
(The major exception is secrets for authentication;
see
.IR ipsec.secrets (5).)
Its contents are not security-sensitive
.I unless
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).
.PP
The file is a text file, consisting of one or more
.IR sections .
White space followed by
.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.
.PP
A line which contains
.B include
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
.IR sh (1));
for example:
.PP
.B include
.B "ipsec.*.conf"
.PP
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
and
.B alsoflip
parameters (described below) which permit splitting a single logical section
(e.g. a connection description) into several actual sections.
.PP
The first significant line of the file must specify the version
of this specification that it conforms to:
.PP
\fBversion 2\fP
.PP
A section
begins with a line of the form:
.PP
.I type
.I name
.PP
where
.I type
indicates what type of section follows, and
.I name
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.
.PP
Lines within the section are generally of the form
.PP
\ \ \ \ \ \fIparameter\fB=\fIvalue\fR
.PP
(note the mandatory preceding white space).
There can be white space on either side of the
.BR = .
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.
.PP
An empty
.I value
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
may contain white space only if the entire
.I value
is enclosed in double quotes (\fB"\fR);
a
.I value
cannot itself contain a double quote,
nor may it be continued across more than one line.
.PP
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).
.PP
There is currently one parameter which is available in any type of
section:
.TP
.B also
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
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
parameter and an
.B include
line.
(Caution, see BUGS below for some restrictions.)
.TP
.B alsoflip
can be used in a
.B conn
section.
It acts like an
.B also
that flips the referenced section's entries left-for-right.
.PP
Parameter names beginning with
.B x-
(or
.BR X- ,
or
.BR x_ ,
or
.BR X_ )
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.
.PP
A section with name
.B %default
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
section.
There may be multiple
.B %default
sections of a given type,
but only one default may be supplied for any specific parameter name,
and all
.B %default
sections of a given type must precede all non-\c
.B %default
sections of that type.
.B %default
sections may not contain
.B also
or
.B alsoflip
parameters.
.PP
Currently there are two types of section:
a
.B config
section specifies general configuration information for IPsec,
while a
.B conn
section specifies an IPsec connection.
.SH "CONN SECTIONS"
A
.B conn
section contains a
.IR "connection specification" ,
defining a network connection to be made using IPsec.
The name given is arbitrary, and is used to identify the connection to
.IR ipsec_auto (8)
and
.IR ipsec_manual (8).
Here's a simple example:
.PP
.ne 10
.nf
.ft B
.ta 1c
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
.ft
.fi
.PP
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''.
.PP
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
and
.I right
participants,
rather than in terms of local and remote.
Which participant is considered
.I left
or
.I right
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
for the local side and
.I right
for the remote side (the first letters are a good mnemonic).
.PP
Many of the parameters relate to one participant or the other;
only the ones for
.I left
are listed here, but every parameter whose name begins with
.B left
has a
.B right
counterpart,
whose description is the same but with
.B left
and
.B right
reversed.
.PP
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.
.SS "CONN PARAMETERS:  GENERAL"
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.
.TP 14
.B type
the type of the connection; currently the accepted values
are
.B tunnel
(the default)
signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
.BR transport ,
signifying host-to-host transport mode;
.BR passthrough ,
signifying that no IPsec processing should be done at all;
.BR drop ,
signifying that packets should be discarded; and
.BR reject ,
signifying that packets should be discarded and a diagnostic ICMP returned.
.TP
.B left
(required)
the IP address of the left participant's public-network interface,
in any form accepted by
.IR ipsec_ttoaddr (3)
or one of several magic values.
If it is
.BR %defaultroute ,
and
the
.B config
.B setup
section's,
.B interfaces
specification contains
.BR %defaultroute,
.B left
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
.BR leftnexthop .
(Either
.B left
or
.B right
may be
.BR %defaultroute ,
but not both.)
The value
.B %any
signifies an address to be filled in (by automatic keying) during
negotiation.
The value
.B %opportunistic
signifies that both
.B left
and
.B leftnexthop
are to be filled in (by automatic keying) from DNS data for
.BR left 's
client.
The values
.B %group
and
.B %opportunisticgroup
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.
.TP
.B leftsubnet
private subnet behind the left participant, expressed as
\fInetwork\fB/\fInetmask\fR
(actually, any form acceptable to
.IR ipsec_ttosubnet (3));
if omitted, essentially assumed to be \fIleft\fB/32\fR,
signifying that the left end of the connection goes to the left participant only
.TP
.B leftnexthop
next-hop gateway IP address for the left participant's connection
to the public network;
defaults to
.B %direct
(meaning
.IR right ).
If the value is to be overridden by the
.B left=%defaultroute
method (see above),
an explicit value must
.I not
be given.
If that method is not being used,
but
.B leftnexthop
is
.BR %defaultroute ,
and
.B interfaces=%defaultroute
is used in the
.B config
.B setup
section,
the next-hop gateway address of the default-route interface
will be used.
The magic value
.B %direct
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.
.TP
.B leftupdown
what ``updown'' script to run to adjust routing and/or firewalling
when the status of the connection
changes (default
.BR "ipsec _updown" ).
May include positional parameters separated by white space
(although this requires enclosing the whole string in quotes);
including shell metacharacters is unwise.
See
.IR ipsec_pluto (8)
for details.
Relevant only locally, other end need not agree on it.
.TP
.PP
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
script (see
.IR ipsec_pluto (8)).
.PP
.SS "CONN PARAMETERS:  AUTOMATIC KEYING"
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.
.TP 14
.B keyexchange
method of key exchange;
the default and currently the only accepted value is
.B ike
.TP
.B auto
what operation, if any, should be done automatically at IPsec startup;
currently-accepted values are
.B add
(signifying an
.B ipsec auto
.BR \-\-add ),
.B route
(signifying that plus an
.B ipsec auto
.BR \-\-route ),
.B start
(signifying that plus an
.B ipsec auto
.BR \-\-up ),
.B manual
(signifying an
.B ipsec
.B manual
.BR \-\-up ),
and
.B ignore
(also the default) (signifying no automatic startup operation).
See the
.B config
.B setup
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
to ensure that any reboot causes immediate renegotiation).
.TP
.B auth
whether authentication should be done as part of
ESP encryption, or separately using the AH protocol;
acceptable values are
.B esp
(the default) and
.BR ah .
.TP
.B authby
how the two security gateways should authenticate each other;
acceptable values are
.B secret
for shared secrets,
.B rsasig
for RSA digital signatures (the default),
.B secret|rsasig
for either, and
.B never
if negotiation is never to be attempted or accepted (useful for shunt-only conns).
Digital signatures are superior in every way to shared secrets.
.TP
.B leftid