[people/ms/strongswan.git] / doc / manpage.d / ipsec_manual.8.html

Content-type: text/html

<HTML><HEAD><TITLE>Manpage of IPSEC_MANUAL</TITLE>
</HEAD><BODY>
<H1>IPSEC_MANUAL</H1>
Section: Maintenance Commands (8)<BR>Updated: 17 July 2001<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>


<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

ipsec manual - take manually-keyed IPsec connections up and down
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>ipsec</B>

<B>manual</B>

[
<B>--show</B>

] [
<B>--showonly</B>

] [
<B>--other</B>

]
<BR>

&nbsp;&nbsp;&nbsp;[
<B>--iam</B>

address<B>@</B>interface

] [
<B>--config</B>

configfile
]
<BR>

&nbsp;&nbsp;&nbsp;operation connection
<P>
<B>ipsec</B>

<B>manual</B>

[
<I>options</I>

]
<B>--union</B>

operation part ...
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<I>Manual</I>

manipulates manually-keyed FreeS/WAN IPsec connections,
setting them up and shutting them down,
based on the information in the IPsec configuration file.
In the normal usage,
<I>connection</I>

is the name of a connection specification in the configuration file;
<I>operation</I>

is
<B>--up</B>,

<B>--down</B>,

<B>--route</B>,

or
<B>--unroute</B>.

<I>Manual</I>

generates setup (<B>--route</B>

or
<B>--up</B>)

or
teardown (<B>--down</B>

or
<B>--unroute</B>)

commands for the connection and feeds them to a shell for execution.
<P>

The
<B>--up</B>

operation brings the specified connection up, including establishing a
suitable route for it if necessary.
<P>

The
<B>--route</B>

operation just establishes the route for a connection.
Unless and until an
<B>--up</B>

operation is done, packets routed by that route will simply be discarded.
<P>

The
<B>--down</B>

operation tears the specified connection down,
<I>except</I>

that it leaves the route in place.
Unless and until an
<B>--unroute</B>

operation is done, packets routed by that route will simply be discarded.
This permits establishing another connection to the same destination
without any ``window'' in which packets can pass without encryption.
<P>

The
<B>--unroute</B>

operation (and only the
<B>--unroute</B>

operation) deletes any route established for a connection.
<P>

In the
<B>--union</B>

usage, each
<I>part</I>

is the name of a partial connection specification in the configuration file,
and the union of all the partial specifications is the
connection specification used.
The effect is as if the contents of the partial specifications were
concatenated together;
restrictions on duplicate parameters, etc., do apply to the result.
(The same effect can now be had, more gracefully, using the
<B>also</B>

parameter in connection descriptions;
see
<I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)

for details.)
<P>

The
<B>--show</B>

option turns on the
<B>-x</B>

option of the shell used to execute the commands,
so each command is shown as it is executed.
<P>

The
<B>--showonly</B>

option causes
<I>manual</I>

to show the commands it would run, on standard output,
and not run them.
<P>

The
<B>--other</B>

option causes
<I>manual</I>

to pretend it is the other end of the connection.
This is probably not useful except in combination with
<B>--showonly</B>.

<P>

The
<B>--iam</B>

option causes
<I>manual</I>

to believe it is running on the host with the specified IP
<I>address</I>,

and that it should use the specified
<I>interface</I>

(normally it determines all this automatically,
based on what IPsec interfaces are up and how they are configured).
<P>

The
<B>--config</B>

option specifies a non-standard location for the FreeS/WAN IPsec
configuration file (default
<I>/etc/ipsec.conf</I>).

<P>

See
<I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)

for details of the configuration file.
Apart from the basic parameters which specify the endpoints and routing
of a connection (<B>left</B>
and
<B>right</B>,

plus possibly
<B>leftsubnet</B>,

<B>leftnexthop</B>,

<B>leftfirewall</B>,

their
<B>right</B>

equivalents,
and perhaps
<B>type</B>),

a non-<B>passthrough</B>
<I>manual</I>

connection needs an
<B>spi</B>

or
<B>spibase</B>

parameter and some parameters specifying encryption, authentication, or
both, most simply
<B>esp</B>,

<B>espenckey</B>,

and
<B>espauthkey</B>.

Moderately-secure keys can be obtained from
<I><A HREF="ipsec_ranbits.8.html">ipsec_ranbits</A></I>(8).

For production use of manually-keyed connections,
it is strongly recommended that the keys be kept in a separate file
(with permissions
<B>rw-------</B>)

using the
<B>include</B>

and
<B>also</B>

facilities of the configuration file (see
<I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)).

<P>

If an
<B>spi</B>

parameter is given,
<I>manual</I>

uses that value as the SPI number for all the SAs
(which are in separate number spaces anyway).
If an
<B>spibase</B>

parameter is given instead,
<I>manual</I>

assigns SPI values by altering the bottom digit
of that value;
SAs going from left to right get even digits starting at 0,
SAs going from right to left get odd digits starting at 1.
Either way, it is suggested that manually-keyed connections use
three-digit SPIs with the first digit non-zero,
i.e. in the range
<B>0x100</B>

through
<B>0xfff</B>;

FreeS/WAN reserves those for manual keying and will not
attempt to use them for automatic keying (unless requested to,
presumably by a non-FreeS/WAN other end).
<A NAME="lbAE">&nbsp;</A>
<H2>FILES</H2>


/etc/ipsec.conf<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT>default IPsec configuration file<BR>
<BR>

/var/run/ipsec.info<TT>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TT><B>%defaultroute</B> information<BR>
<A NAME="lbAF">&nbsp;</A>
<H2>SEE ALSO</H2>

<A HREF="ipsec.8.html">ipsec</A>(8), <A HREF="ipsec.conf.5.html">ipsec.conf</A>(5), <A HREF="ipsec_spi.8.html">ipsec_spi</A>(8), <A HREF="ipsec_eroute.8.html">ipsec_eroute</A>(8), <A HREF="ipsec_spigrp.8.html">ipsec_spigrp</A>(8),
<A HREF="route.8.html">route</A>(8)
<A NAME="lbAG">&nbsp;</A>
<H2>HISTORY</H2>

Written for the FreeS/WAN project
&lt;<A HREF="http://www.freeswan.org/">http://www.freeswan.org/</A>&gt;
by Henry Spencer.
<A NAME="lbAH">&nbsp;</A>
<H2>BUGS</H2>

It's 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>

If the connection specification for a connection is changed between an
<B>--up</B>

and the ensuing
<B>--down</B>,

chaos may ensue.
<P>

The
<B>--up</B>

operation is not smart enough to notice whether the connection is already up.
<P>

<I>Manual</I>

is not smart enough to reject insecure combinations of algorithms,
e.g. encryption with no authentication at all.
<P>

Any non-IPsec route to the other end which is replaced by the
<B>--up</B>

or
<B>--route</B>

operation will not be re-established by
<B>--unroute</B>.

Whether this is a feature or a bug depends on your viewpoint.
<P>

The optional parameters which
override the automatic
<B>spibase</B>-based

SPI assignment are a messy area of the code and bugs are likely.
<P>

``Road warrior'' handling,
and other special forms of setup which
require negotiation between the two security gateways,
inherently cannot be done with
<I>manual</I>.

<P>

<I>Manual</I>

generally lags behind
<I>auto</I>

in support of various features,
even when implementation <I>would</I> be possible.
For example, currently it does not do IPComp content compression.
<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">FILES</A><DD>
<DT><A HREF="#lbAF">SEE ALSO</A><DD>
<DT><A HREF="#lbAG">HISTORY</A><DD>
<DT><A HREF="#lbAH">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:18 GMT, November 11, 2003
</BODY>
</HTML>
Commit	Line	Data
997358a6 MW	1	Content-type: text/html
	2
	3	<HTML><HEAD><TITLE>Manpage of IPSEC_MANUAL</TITLE>
	4	</HEAD><BODY>
	5	<H1>IPSEC_MANUAL</H1>
	6	Section: Maintenance Commands (8)<BR>Updated: 17 July 2001<BR><A HREF="#index">Index</A>
	7	<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
	8
	9
	10	<A NAME="lbAB"> </A>
	11	<H2>NAME</H2>
	12
	13	ipsec manual - take manually-keyed IPsec connections up and down
	14	<A NAME="lbAC"> </A>
	15	<H2>SYNOPSIS</H2>
	16
	17	<B>ipsec</B>
	18
	19	<B>manual</B>
	20
	21	[
	22	<B>--show</B>
	23
	24	] [
	25	<B>--showonly</B>
	26
	27	] [
	28	<B>--other</B>
	29
	30	]
	31	<BR>
	32
	33	[
	34	<B>--iam</B>
	35
	36	address<B>@</B>interface
	37
	38	] [
	39	<B>--config</B>
	40
	41	configfile
	42	]
	43	<BR>
	44
	45	operation connection
	46	<P>
	47	<B>ipsec</B>
	48
	49	<B>manual</B>
	50
	51	[
	52	<I>options</I>
	53
	54	]
	55	<B>--union</B>
	56
	57	operation part ...
	58	<A NAME="lbAD"> </A>
	59	<H2>DESCRIPTION</H2>
	60
	61	<I>Manual</I>
	62
	63	manipulates manually-keyed FreeS/WAN IPsec connections,
	64	setting them up and shutting them down,
65	based on the information in the IPsec configuration file.
66	In the normal usage,
67	<I>connection</I>
68
69	is the name of a connection specification in the configuration file;
70	<I>operation</I>
71
72	is
73	<B>--up</B>,
74
75	<B>--down</B>,
76
77	<B>--route</B>,
78
79	or
80	<B>--unroute</B>.
81
82	<I>Manual</I>
83
84	generates setup (<B>--route</B>
85
86	or
87	<B>--up</B>)
88
89	or
90	teardown (<B>--down</B>
91
92	or
93	<B>--unroute</B>)
94
95	commands for the connection and feeds them to a shell for execution.
96	<P>
97
98	The
99	<B>--up</B>
100
101	operation brings the specified connection up, including establishing a
102	suitable route for it if necessary.
103	<P>
104
105	The
106	<B>--route</B>
107
108	operation just establishes the route for a connection.
109	Unless and until an
110	<B>--up</B>
111
112	operation is done, packets routed by that route will simply be discarded.
113	<P>
114
115	The
116	<B>--down</B>
117
118	operation tears the specified connection down,
119	<I>except</I>
120
121	that it leaves the route in place.
122	Unless and until an
123	<B>--unroute</B>
124
125	operation is done, packets routed by that route will simply be discarded.
126	This permits establishing another connection to the same destination
127	without any ``window'' in which packets can pass without encryption.
128	<P>
129
130	The
131	<B>--unroute</B>
132
133	operation (and only the
134	<B>--unroute</B>
135
136	operation) deletes any route established for a connection.
137	<P>
138
139	In the
140	<B>--union</B>
141
142	usage, each
143	<I>part</I>
144
145	is the name of a partial connection specification in the configuration file,
146	and the union of all the partial specifications is the
147	connection specification used.
148	The effect is as if the contents of the partial specifications were
149	concatenated together;
150	restrictions on duplicate parameters, etc., do apply to the result.
151	(The same effect can now be had, more gracefully, using the
152	<B>also</B>
153
154	parameter in connection descriptions;
155	see
156	<I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)
157
158	for details.)
159	<P>
160
161	The
162	<B>--show</B>
163
164	option turns on the
165	<B>-x</B>
166
167	option of the shell used to execute the commands,
168	so each command is shown as it is executed.
169	<P>
170
171	The
172	<B>--showonly</B>
173
174	option causes
175	<I>manual</I>
176
177	to show the commands it would run, on standard output,
178	and not run them.
179	<P>
180
181	The
182	<B>--other</B>
183
184	option causes
185	<I>manual</I>
186
187	to pretend it is the other end of the connection.
188	This is probably not useful except in combination with
189	<B>--showonly</B>.
190
191	<P>
192
193	The
194	<B>--iam</B>
195
196	option causes
197	<I>manual</I>
198
199	to believe it is running on the host with the specified IP
200	<I>address</I>,
201
202	and that it should use the specified
203	<I>interface</I>
204
205	(normally it determines all this automatically,
206	based on what IPsec interfaces are up and how they are configured).
207	<P>
208
209	The
210	<B>--config</B>
211
212	option specifies a non-standard location for the FreeS/WAN IPsec
213	configuration file (default
214	<I>/etc/ipsec.conf</I>).
215
216	<P>
217
218	See
219	<I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)
220
221	for details of the configuration file.
222	Apart from the basic parameters which specify the endpoints and routing
223	of a connection (<B>left</B>
224	and
225	<B>right</B>,
226
227	plus possibly
228	<B>leftsubnet</B>,
229
230	<B>leftnexthop</B>,
231
232	<B>leftfirewall</B>,
233
234	their
235	<B>right</B>
236
237	equivalents,
238	and perhaps
239	<B>type</B>),
240
241	a non-<B>passthrough</B>
242	<I>manual</I>
243
244	connection needs an
245	<B>spi</B>
246
247	or
248	<B>spibase</B>
249
250	parameter and some parameters specifying encryption, authentication, or
251	both, most simply
252	<B>esp</B>,
253
254	<B>espenckey</B>,
255
256	and
257	<B>espauthkey</B>.
258
259	Moderately-secure keys can be obtained from
260	<I><A HREF="ipsec_ranbits.8.html">ipsec_ranbits</A></I>(8).
261
262	For production use of manually-keyed connections,
263	it is strongly recommended that the keys be kept in a separate file
264	(with permissions
265	<B>rw-------</B>)
266
267	using the
268	<B>include</B>
269
270	and
271	<B>also</B>
272
273	facilities of the configuration file (see
274	<I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)).
275
276	<P>
277
278	If an
279	<B>spi</B>
280
281	parameter is given,
282	<I>manual</I>
283
284	uses that value as the SPI number for all the SAs
285	(which are in separate number spaces anyway).
286	If an
287	<B>spibase</B>
288
289	parameter is given instead,
290	<I>manual</I>
291
292	assigns SPI values by altering the bottom digit
293	of that value;
294	SAs going from left to right get even digits starting at 0,
295	SAs going from right to left get odd digits starting at 1.
296	Either way, it is suggested that manually-keyed connections use
297	three-digit SPIs with the first digit non-zero,
298	i.e. in the range
299	<B>0x100</B>
300
301	through
302	<B>0xfff</B>;
303
304	FreeS/WAN reserves those for manual keying and will not
305	attempt to use them for automatic keying (unless requested to,
306	presumably by a non-FreeS/WAN other end).
307	<A NAME="lbAE"> </A>
308	<H2>FILES</H2>
309
310
311
312	/etc/ipsec.conf<TT>           </TT>default IPsec configuration file<BR>
313	<BR>
314
315	/var/run/ipsec.info<TT>      </TT><B>%defaultroute</B> information<BR>
316	<A NAME="lbAF"> </A>
317	<H2>SEE ALSO</H2>
318
319	<A HREF="ipsec.8.html">ipsec</A>(8), <A HREF="ipsec.conf.5.html">ipsec.conf</A>(5), <A HREF="ipsec_spi.8.html">ipsec_spi</A>(8), <A HREF="ipsec_eroute.8.html">ipsec_eroute</A>(8), <A HREF="ipsec_spigrp.8.html">ipsec_spigrp</A>(8),
320	<A HREF="route.8.html">route</A>(8)
321	<A NAME="lbAG"> </A>
322	<H2>HISTORY</H2>
323
324	Written for the FreeS/WAN project
325	<<A HREF="http://www.freeswan.org/">http://www.freeswan.org/</A>>
326	by Henry Spencer.
327	<A NAME="lbAH"> </A>
328	<H2>BUGS</H2>
329
330	It's not nearly as generous about the syntax of subnets,
331	addresses, etc. as the usual FreeS/WAN user interfaces.
332	Four-component dotted-decimal must be used for all addresses.
333	It
334	<I>is</I>
335
336	smart enough to translate bit-count netmasks to dotted-decimal form.
337	<P>
338
339	If the connection specification for a connection is changed between an
340	<B>--up</B>
341
342	and the ensuing
343	<B>--down</B>,
344
345	chaos may ensue.
346	<P>
347
348	The
349	<B>--up</B>
350
351	operation is not smart enough to notice whether the connection is already up.
352	<P>
353
354	<I>Manual</I>
355
356	is not smart enough to reject insecure combinations of algorithms,
357	e.g. encryption with no authentication at all.
358	<P>
359
360	Any non-IPsec route to the other end which is replaced by the
361	<B>--up</B>
362
363	or
364	<B>--route</B>
365
366	operation will not be re-established by
367	<B>--unroute</B>.
368
369	Whether this is a feature or a bug depends on your viewpoint.
370	<P>
371
372	The optional parameters which
373	override the automatic
374	<B>spibase</B>-based
375
376	SPI assignment are a messy area of the code and bugs are likely.
377	<P>
378
379	``Road warrior'' handling,
380	and other special forms of setup which
381	require negotiation between the two security gateways,
382	inherently cannot be done with
383	<I>manual</I>.
384
385	<P>
386
387	<I>Manual</I>
388
389	generally lags behind
390	<I>auto</I>
391
392	in support of various features,
393	even when implementation <I>would</I> be possible.
394	For example, currently it does not do IPComp content compression.
395	<P>
396
397	<HR>
398	<A NAME="index"> </A><H2>Index</H2>
399	<DL>
400	<DT><A HREF="#lbAB">NAME</A><DD>
401	<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
402	<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
403	<DT><A HREF="#lbAE">FILES</A><DD>
404	<DT><A HREF="#lbAF">SEE ALSO</A><DD>
405	<DT><A HREF="#lbAG">HISTORY</A><DD>
406	<DT><A HREF="#lbAH">BUGS</A><DD>
407	</DL>
408	<HR>
409	This document was created by
410	<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
411	using the manual pages.<BR>
412	Time: 21:40:18 GMT, November 11, 2003
413	</BODY>
414	</HTML>