added RCSID
[strongswan.git] / src / ipsec / ipsec.8
1 .TH IPSEC 8 "9 February 2006"
2 .\" RCSID $Id$
3 .SH NAME
4 ipsec \- invoke IPsec utilities
5 .SH SYNOPSIS
6 .B ipsec
7 command [ argument ...]
8 .sp
9 .B ipsec start|update|reload|restart|stop
10 .sp
11 .B ipsec up|down|route|unroute
12 \fIconnectionname\fP
13 .sp
14 .B ipsec status|statusall
15 [
16 \fIconnectionname\fP
17 ]
18 .sp
19 .B ipsec listalgs|listpubkeys|listcerts
20 [
21 .B \-\-utc
22 ]
23 .br
24 .B ipsec listcacerts|listaacerts|listocspcerts
25 [
26 .B \-\-utc
27 ]
28 .br
29 .B ipsec listacerts|listgroups|listcainfos
30 [
31 .B \-\-utc
32 ]
33 .br
34 .B ipsec listcrls|listocsp|listcards|listall
35 [
36 .B \-\-utc
37 ]
38 .sp
39 .B ipsec rereadsecrets|rereadgroups
40 .br
41 .B ipsec rereadcacerts|rereadaacerts|rereadocspcerts
42 .br
43 .B ipsec rereadacerts|rereadcrls|rereadall
44 .sp
45 .B ipsec purgeocsp
46 .sp
47 .B ipsec
48 [
49 .B \-\-help
50 ] [
51 .B \-\-version
52 ] [
53 .B \-\-versioncode
54 ] [
55 .B \-\-copyright
56 ]
57 .br
58 .B ipsec
59 [
60 .B \-\-directory
61 ] [
62 .B \-\-confdir
63 ]
64 .SH DESCRIPTION
65 .I Ipsec
66 invokes any of several utilities involved in controlling the IPsec
67 encryption/authentication system,
68 running the specified
69 .I command
70 with the specified
71 .IR argument s
72 as if it had been invoked directly.
73 This largely eliminates possible name collisions with other software,
74 and also permits some centralized services.
75 .PP
76 The commands
77 .BR start ,
78 .BR update ,
79 .BR reload ,
80 .BR restart ,
81 and
82 .BR stop
83 are built-in and are used to control the
84 .BR "ipsec starter"
85 utility, an extremely fast replacement for the traditional
86 .BR ipsec
87 .BR setup
88 script.
89 .PP
90 The commands
91 .BR up,
92 .BR down,
93 .BR route,
94 .BR unroute,
95 .BR status,
96 .BR statusall,
97 .BR listalgs,
98 .BR listpubkeys,
99 .BR listcerts,
100 .BR listcacerts,
101 .BR listaacerts,
102 .BR listocspcerts,
103 .BR listacerts,
104 .BR listgroups,
105 .BR listcainfos,
106 .BR listcrls,
107 .BR listocsp,
108 .BR listcards,
109 .BR listall,
110 .BR rereadsecrets,
111 .BR rereadgroups,
112 .BR rereadcacerts,
113 .BR rereadaacerts,
114 .BR rereadocspcerts,
115 .BR rereadacerts,
116 .BR rereadcrls,
117 and
118 .BR rereadall
119 are also built-in and completely replace the corresponding
120 .BR "ipsec auto"
121 \-\-\fIoperation\fP"
122 commands. Communication with the pluto daemon happens via the
123 .BR "ipsec whack"
124 socket interface.
125 .PP
126 In particular,
127 .I ipsec
128 supplies the invoked
129 .I command
130 with a suitable PATH environment variable,
131 and also provides IPSEC_DIR,
132 IPSEC_CONFS, and IPSEC_VERSION environment variables,
133 containing respectively
134 the full pathname of the directory where the IPsec utilities are stored,
135 the full pathname of the directory where the configuration files live,
136 and the IPsec version number.
137 .PP
138 .B "ipsec start"
139 calls
140 .BR "ipsec starter"
141 which in turn starts \fIpluto\fR.
142 .PP
143 .B "ipsec update"
144 sends a \fIHUP\fR signal to
145 .BR "ipsec starter"
146 which in turn determines any changes in \fIipsec.conf\fR
147 and updates the configuration on the running \fIpluto\fR daemon, correspondingly.
148 .PP
149 .B "ipsec reload"
150 sends a \fIUSR1\fR signal to
151 .BR "ipsec starter"
152 which in turn reloads the whole configuration on the running \fIpluto\fR daemon
153 based on the actual \fIipsec.conf\fR.
154 .PP
155 .B "ipsec restart"
156 executes
157 .B "ipsec stop"
158 followed by
159 .BR "ipsec start".
160 .PP
161 .B "ipsec stop"
162 stops \fIipsec\fR by sending a \fITERM\fR signal to
163 .BR "ipsec starter".
164 .PP
165 .B "ipsec up"
166 \fIname\fP tells the \fIpluto\fP daemon to start up connection \fIname\fP.
167 .PP
168 .B "ipsec down"
169 \fIname\fP tells the \fIpluto\fP daemon to take down connection \fIname\fP.
170 .PP
171 .B "ipsec route"
172 \fIname\fP tells the \fIpluto\fP daemon to install a route for connection
173 \fIname\fP.
174 .PP
175 .B "ipsec unroute"
176 \fIname\fP tells the \fIpluto\fP daemon to take down the route for connection
177 \fIname\fP.
178 .PP
179 .B "ipsec status"
180 [ \fIname\fP ]  gives concise status information either on connection
181 \fIname\fP or if the \fIname\fP argument is lacking, on all connections.
182 .PP
183 .B "ipsec statusall"
184 [ \fIname\fP ]  gives detailed status information either on connection
185 \fIname\fP or if the \fIname\fP argument is lacking, on all connections.
186 .PP
187 .B "ipsec listalgs"
188 returns a list all supported IKE encryption and hash algorithms, the available
189 Diffie-Hellman groups, as well as all supported ESP encryption and authentication
190 algorithms.
191 .PP
192 .B "ipsec listpubkeys"
193 returns a list of RSA public keys that were either loaded in raw key format
194 or extracted from X.509 and|or OpenPGP certificates.
195 .PP
196 .B "ipsec listcerts"
197 returns a list of X.509 and|or OpenPGP certificates that were loaded locally
198 by the \fIpluto\fP daemon.
199 .PP
200 .B "ipsec listcacerts"
201 returns a list of X.509 Certification Authority (CA) certificates that were
202 loaded locally by the \fIpluto\fP daemon from the \fI/etc/ipsec.d/cacerts/\fP
203 directory or received in PKCS#7-wrapped certificate payloads via the  IKE
204 protocol.
205 .PP
206 .B "ipsec listaacerts"
207 returns a list of X.509 Authorization Authority (AA) certificates that were
208 loaded locally by the \fIpluto\fP daemon from the \fI/etc/ipsec.d/aacerts/\fP
209 directory.
210 .PP
211 .B "ipsec listocspcerts"
212 returns a list of X.509 OCSP Signer certificates that were either loaded
213 locally by the \fIpluto\fP daemon from the \fI/etc/ipsec.d/ocspcerts/\fP
214 directory or were sent by an OCSP server.
215 .PP
216 .B "ipsec listacerts"
217 returns a list of X.509 Attribute certificates that were loaded locally by
218 the \fIpluto\fP daemon from the \fI/etc/ipsec.d/acerts/\fP directory.
219 .PP
220 .B "ipsec listgroups"
221 returns a list of groups that are used to define user authorization profiles.
222 .PP
223 .B "ipsec listcainfos"
224 returns certification authority information (CRL distribution points, OCSP URIs,
225 LDAP servers) that were defined by
226 .BR ca
227 sections in \fIipsec.conf\fP.
228 .PP
229 .B "ipsec listcrls"
230 returns a list of Certificate Revocation Lists (CRLs).
231 .PP
232 .B "ipsec listocsp"
233 returns revocation information fetched from OCSP servers.
234 .PP
235 .B "ipsec listcards"
236 returns a list of certificates residing on smartcards.
237 .PP
238 .B "ipsec listall"
239 returns all information generated by the list commands above. Each list command 
240 can be called with the
241 \-\-url
242 option which displays all dates in UTC instead of local time.
243 .PP
244 .B "ipsec rereadsecrets"
245 flushes and rereads all secrets defined in \fIipsec.conf\fP.
246 .PP
247 .B "ipsec rereadcacerts"
248 reads all certificate files contained in the \fI/etc/ipsec.d/cacerts\fP
249 directory and adds them to \fIpluto\fP's list of Certification Authority (CA) certificates.
250 .PP
251 .B "ipsec rereadaacerts"
252 reads all certificate files contained in the \fI/etc/ipsec.d/aacerts\fP
253 directory and adds them to \fIpluto\fP's list of Authorization Authority (AA) certificates.
254 .PP
255 .B "ipsec rereadocspcerts" 
256 reads all certificate files contained in the \fI/etc/ipsec.d/ocspcerts/\fP
257 directory and adds them to \fIpluto\fP's list of OCSP signer certificates.
258 .PP
259 .B "ipsec rereadacerts"
260 operation reads all certificate files contained in the  \fI/etc/ipsec.d/acerts/\fP
261 directory and adds them to \fIpluto\fP's list of attribute certificates.
262 .PP
263 .B "ipsec rereadcrls"
264 reads  all Certificate  Revocation Lists (CRLs) contained in the
265 \fI/etc/ipsec.d/crls/\fP directory and adds them to \fIpluto\fP's list of CRLs.
266 .PP
267 .B "ipsec rereadall"
268 is  equivalent  to  the  execution  of  \fBrereadsecrets\fP,
269 \fBrereadcacerts\fP, \fBrereadaacerts\fP, \fBrereadocspcerts\fP,
270 \fBrereadacerts\fP, and \fBrereadcrls\fP.
271 .PP
272 .B "ipsec \-\-help"
273 lists the available commands.
274 Most have their own manual pages, e.g.
275 .IR ipsec_auto (8)
276 for
277 .IR auto .
278 .PP
279 .B "ipsec \-\-version"
280 outputs version information about Linux strongSwan.
281 A version code of the form ``U\fIxxx\fR/K\fIyyy\fR''
282 indicates that the user-level utilities are version \fIxxx\fR
283 but the kernel portion appears to be version \fIyyy\fR
284 (this form is used only if the two disagree).
285 .PP
286 .B "ipsec \-\-versioncode"
287 outputs \fIjust\fR the version code,
288 with none of
289 .BR \-\-version 's
290 supporting information,
291 for use by scripts.
292 .PP
293 .B "ipsec \-\-copyright"
294 supplies boring copyright details.
295 .PP
296 .B "ipsec \-\-directory"
297 reports where
298 .I ipsec
299 thinks the IPsec utilities are stored.
300 .PP
301 .B "ipsec \-\-confdir"
302 reports where
303 .I ipsec
304 thinks the IPsec configuration files are stored.
305 .SH FILES
306 /usr/local/lib/ipsec    usual utilities directory
307 .SH ENVIRONMENT
308 .PP
309 The following environment variables control where strongSwan finds its
310 components.
311 The
312 .B ipsec
313 command sets them if they are not already set.
314 .nf
315 .na
316
317 IPSEC_DIR               directory containing ipsec programs and utilities
318 IPSEC_SBINDIR           directory containing \fBipsec\fP command
319 IPSEC_CONFDIR           directory containing configuration files
320 IPSEC_PIDDIR            directory containing PID files
321 IPSEC_NAME              name of ipsec distribution
322 IPSEC_VERSION           version numer of ipsec userland and kernel
323 IPSEC_STARTER_PID       PID file for ipsec starter
324 IPSEC_PLUTO_PID         PID file for IKEv1 keying daemon
325 IPSEC_CHARON_PID        PID file for IKEv2 keying daemon
326 .ad
327 .fi
328 .SH SEE ALSO
329 .hy 0
330 .na
331 ipsec.conf(5), ipsec.secrets(5),
332 ipsec_barf(8),
333 .ad
334 .hy
335 .PP
336 .SH HISTORY
337 Written for Linux FreeS/WAN
338 <http://www.freeswan.org>
339 by Henry Spencer.
340 Updated and extended for Linux strongSwan
341 <http://www.strongswan.org>
342 by Andreas Steffen.