Rebuild library.lo after changing ./configure options
[strongswan.git] / src / ipsec / ipsec.8.in
1 .TH IPSEC 8 "2010-05-30" "@IPSEC_VERSION@" "strongSwan"
2 .SH NAME
3 ipsec \- invoke IPsec utilities
4 .SH SYNOPSIS
5 .B ipsec
6 \fIcommand\fP [ \fIarguments\fP ] [ \fIoptions\fP ]
7 .PP
8 .SH DESCRIPTION
9 The
10 .B ipsec
11 utility invokes any of several utilities involved in controlling and monitoring
12 the IPsec encryption/authentication system, running the specified \fIcommand\fP
13 with the specified \fIarguments\fP and \fIoptions\fP as if it had been invoked
14 directly. This largely eliminates possible name collisions with other software,
15 and also permits some centralized services.
16 .PP
17 All the commands described in this manual page are built-in and are used to
18 control and monitor IPsec connections as well as the IKE daemons.
19 .PP
20 For other commands
21 .I ipsec
22 supplies the invoked
23 .I command
24 with a suitable PATH environment variable,
25 and also provides IPSEC_DIR,
26 IPSEC_CONFS, and IPSEC_VERSION environment variables,
27 containing respectively
28 the full pathname of the directory where the IPsec utilities are stored,
29 the full pathname of the directory where the configuration files live,
30 and the IPsec version number.
31 .PP
32 .SS CONTROL COMMANDS
33 .TP
34 .B "ipsec start [ starter options ]"
35 calls
36 .BR "ipsec starter"
37 which in turn parses \fIipsec.conf\fR and starts the IKEv1 \fIpluto\fR and
38 IKEv2 \fIcharon\fR daemons.
39 .PP
40 .TP
41 .B "ipsec update"
42 sends a \fIHUP\fR signal to
43 .BR "ipsec starter"
44 which in turn determines any changes in \fIipsec.conf\fR
45 and updates the configuration on the running IKEv1 \fIpluto\fR and IKEv2
46 \fIcharon\fR daemons, correspondingly.
47 .PP
48 .TP
49 .B "ipsec reload"
50 sends a \fIUSR1\fR signal to
51 .BR "ipsec starter"
52 which in turn reloads the whole configuration on the running IKEv1 \fIpluto\fR
53 and IKEv2 \fIcharon\fR daemons based on the actual \fIipsec.conf\fR.
54 .PP
55 .TP
56 .B "ipsec restart"
57 is equivalent to
58 .B "ipsec stop"
59 followed by
60 .B "ipsec start"
61 after a guard of 2 seconds.
62 .PP
63 .TP
64 .B "ipsec stop"
65 terminates all IPsec connections and stops the IKEv1 \fIpluto\fR and IKEv2
66 \fIcharon\fR daemons by sending a \fITERM\fR signal to
67 .BR "ipsec starter".
68 .PP
69 .TP
70 .B "ipsec up \fIname\fP"
71 tells the responsible IKE daemon to start up connection \fIname\fP.
72 .PP
73 .TP
74 .B "ipsec down \fIname\fP"
75 tells the responsible IKE daemon to terminate connection \fIname\fP.
76 .PP
77 .TP
78 .B "ipsec down \fIname{n}\fP"
79 terminates IKEv2 CHILD SA instance \fIn\fP of connection \fIname\fP.
80 .PP
81 .TP
82 .B "ipsec down \fIname{*}\fP"
83 terminates all IKEv2 CHILD SA instances of connection \fIname\fP.
84 .PP
85 .TP
86 .B "ipsec down \fIname[n]\fP"
87 terminates all IKEv2 IKE SA instance \fIn\fP of connection \fIname\fP.
88 .PP
89 .TP
90 .B "ipsec down \fIname[*]\fP"
91 terminates all IKEv2 IKE SA instances of connection \fIname\fP.
92 .PP
93 .TP
94 .B "ipsec route \fIname\fP"
95 tells the responsible IKE daemon to insert an IPsec policy in the kernel
96 for connection \fIname\fP. The first payload packet matching the IPsec policy
97 will automatically trigger an IKE connection setup.
98 .PP
99 .TP
100 .B "ipsec unroute \fIname\fP"
101 remove the IPsec policy in the kernel for connection \fIname\fP.
102 .PP
103 .TP
104 .B "ipsec status [ \fIname\fP ]"
105 returns concise status information either on connection
106 \fIname\fP or if the argument is lacking, on all connections.
107 .PP
108 .TP
109 .B "ipsec statusall [ \fIname\fP ]"
110 returns detailed status information either on connection
111 \fIname\fP or if the argument is lacking, on all connections.
112 .PP
113 .SS LIST COMMANDS
114 .TP
115 .B "ipsec listalgs"
116 returns a list all supported IKE encryption and hash algorithms, the available
117 Diffie-Hellman groups, as well as all supported ESP encryption and
118 authentication algorithms registered via the Linux kernel's Crypto API.
119 .br
120 Supported by the IKEv1 \fIpluto\fP daemon only.
121 .PP
122 .TP
123 .B "ipsec listpubkeys [ --utc ]"
124 returns a list of RSA public keys that were either loaded in raw key format
125 or extracted from X.509 and|or OpenPGP certificates.
126 .br
127 Supported by the IKEv1 \fIpluto\fP daemon only.
128 .PP
129 .TP
130 .B "ipsec listcerts [ --utc ]"
131 returns a list of X.509 and|or OpenPGP certificates that were either loaded
132 locally by the IKE daemon or received via the IKEv2 protocol.
133 .PP
134 .TP
135 .B "ipsec listcacerts [ --utc ]"
136 returns a list of X.509 Certification Authority (CA) certificates that were
137 loaded locally by the IKE daemon from the \fI/etc/ipsec.d/cacerts/\fP
138 directory or received in PKCS#7-wrapped certificate payloads via the IKE
139 protocol.
140 .PP
141 .TP
142 .B "ipsec listaacerts [ --utc ]"
143 returns a list of X.509 Authorization Authority (AA) certificates that were
144 loaded locally by the IKE daemon from the \fI/etc/ipsec.d/aacerts/\fP
145 directory.
146 .PP
147 .TP
148 .B "ipsec listocspcerts [ --utc ]"
149 returns a list of X.509 OCSP Signer certificates that were either loaded
150 locally by the IKE daemon from the \fI/etc/ipsec.d/ocspcerts/\fP
151 directory or were sent by an OCSP server.
152 .PP
153 .TP
154 .B "ipsec listacerts [ --utc ]"
155 returns a list of X.509 Attribute certificates that were loaded locally by
156 the IKE daemon from the \fI/etc/ipsec.d/acerts/\fP directory.
157 .PP
158 .TP
159 .B "ipsec listgroups [ --utc ]"
160 returns a list of groups that are used to define user authorization profiles.
161 .br
162 Supported by the IKEv1 \fIpluto\fP daemon only.
163 .PP
164 .TP
165 .B "ipsec listcainfos [ --utc ]"
166 returns certification authority information (CRL distribution points, OCSP URIs,
167 LDAP servers) that were defined by
168 .BR ca
169 sections in \fIipsec.conf\fP.
170 .PP
171 .TP
172 .B "ipsec listcrls [ --utc ]"
173 returns a list of Certificate Revocation Lists (CRLs) that were either loaded
174 by the IKE daemon from the \fI/etc/ipsec.d/crls\fP directory or fetched from
175 an HTTP- or LDAP-based CRL distribution point.
176 .PP
177 .TP
178 .B "ipsec listocsp [ --utc ]"
179 returns revocation information fetched from OCSP servers.
180 .PP
181 .TP
182 .B "ipsec listcards [ --utc ]"
183 list all certificates found on attached smart cards.
184 .br
185 Supported by the IKEv1 \fIpluto\fP daemon only.
186 .PP
187 .TP
188 .B "ipsec listall [ --utc ]"
189 returns all information generated by the list commands above. Each list command 
190 can be called with the
191 \fB\-\-utc\fP
192 option which displays all dates in UTC instead of local time.
193 .PP
194 .SS REREAD COMMANDS
195 .TP
196 .B "ipsec rereadsecrets"
197 flushes and rereads all secrets defined in \fIipsec.secrets\fP.
198 .PP
199 .TP
200 .B "ipsec rereadcacerts"
201 reads all certificate files contained in the \fI/etc/ipsec.d/cacerts\fP
202 directory and adds them to the list of Certification Authority (CA)
203 certificates.
204 .PP
205 .TP
206 .B "ipsec rereadaacerts"
207 reads all certificate files contained in the \fI/etc/ipsec.d/aacerts\fP
208 directory and adds them to the list of Authorization Authority (AA)
209 certificates.
210 .PP
211 .TP
212 .B "ipsec rereadocspcerts" 
213 reads all certificate files contained in the \fI/etc/ipsec.d/ocspcerts/\fP
214 directory and adds them to the list of OCSP signer certificates.
215 .PP
216 .TP
217 .B "ipsec rereadacerts"
218 reads all certificate files contained in the  \fI/etc/ipsec.d/acerts/\fP
219 directory and adds them to the list of attribute certificates.
220 .PP
221 .TP
222 .B "ipsec rereadcrls"
223 reads  all Certificate  Revocation Lists (CRLs) contained in the
224 \fI/etc/ipsec.d/crls/\fP directory and adds them to the list of CRLs.
225 .PP
226 .TP
227 .B "ipsec rereadall"
228 executes all reread commands listed above.
229 .PP
230 .SS PURGE COMMANDS
231 .TP
232 .B "ipsec purgeike"
233 purges IKEv2 SAs that don't have a CHILD SA.
234 .PP
235 .TP
236 .B "ipsec purgeocsp"
237 purges all cached OCSP information records.
238 .PP
239 .SS INFO COMMANDS
240 .TP
241 .B "ipsec \-\-help"
242 returns the usage information for the ipsec command.
243 .PP
244 .TP
245 .B "ipsec \-\-version"
246 returns the version in the form of
247 .B Linux strongSwan U<strongSwan userland version>/K<Linux kernel version>
248 if strongSwan uses the native NETKEY IPsec stack of the Linux kernel it is
249 running on.
250 .PP
251 .TP
252 .B "ipsec \-\-versioncode"
253 returns the version number in the form of
254 .B U<strongSwan userland version>/K<Linux kernel version>
255 if strongSwan uses the native NETKEY IPsec stack of the Linux kernel it is
256 running on.
257 .PP
258 .TP
259 .B "ipsec \-\-copyright"
260 returns the copyright information.
261 .PP
262 .TP
263 .B "ipsec \-\-directory"
264 returns the \fILIBEXECDIR\fP directory as defined by the configure options.
265 .PP
266 .TP
267 .B "ipsec \-\-confdir"
268 returns the \fISYSCONFDIR\fP directory as defined by the configure options.
269 .SH FILES
270 /usr/local/lib/ipsec    usual utilities directory
271 .SH ENVIRONMENT
272 .PP
273 The following environment variables control where strongSwan finds its
274 components.
275 The
276 .B ipsec
277 command sets them if they are not already set.
278 .nf
279 .na
280
281 IPSEC_DIR               directory containing ipsec programs and utilities
282 IPSEC_SBINDIR           directory containing \fBipsec\fP command
283 IPSEC_CONFDIR           directory containing configuration files
284 IPSEC_PIDDIR            directory containing PID files
285 IPSEC_NAME              name of ipsec distribution
286 IPSEC_VERSION           version numer of ipsec userland and kernel
287 IPSEC_STARTER_PID       PID file for ipsec starter
288 IPSEC_PLUTO_PID         PID file for IKEv1 keying daemon
289 IPSEC_CHARON_PID        PID file for IKEv2 keying daemon
290 .ad
291 .fi
292 .SH SEE ALSO
293 .hy 0
294 .na
295 ipsec.conf(5), ipsec.secrets(5)
296 .ad
297 .hy
298 .PP
299 .SH HISTORY
300 Originally written for the FreeS/WAN project by Henry Spencer.
301 Updated and extended for the strongSwan project <http://www.strongswan.org> by
302 Tobias Brunner and Andreas Steffen.