'\" t
.\"     Title: IPSEC-PLUTO
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/14/2024
.\"    Manual: Executable programs
.\"    Source: Libreswan 5.0~rc2
.\"  Language: English
.\"
.TH "IPSEC\-PLUTO" "8" "03/14/2024" "Libreswan 5.0~rc2" "Executable programs"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec-pluto, pluto \- Internet Key Exchange daemon
.SH "SYNOPSIS"
.HP \w'\fBipsec\ pluto\fR\ 'u
\fBipsec pluto\fR [\-\-help] [\-\-version]
.br
[\-\-nofork] [\-\-rundir\ \fIpath\fR] [\-\-leak\-detective] [\-\-efence\-protect]
.br
[\-\-stderrlog] [\-\-logfile\ \fIfilename\fR] [\-\-log\-no\-time] [\-\-log\-no\-append] [\-\-log\-no\-ip] [\-\-log\-no\-audit]
.br
[\-\-config\ \fIfilename\fR] [\-\-secretsfile\ \fIsecrets\-file\fR] [\-\-ipsecdir\ \fIdirname\fR] [\-\-nssdir\ \fIdirname\fR] [\-\-coredir\ \fIdirname\fR]
.br
[\-\-vendorid\ \fIVID\fR] [\-\-uniqueids] [\-\-virtual\-private\ \fInetwork_list\fR] [\-\-keep\-alive\ \fIdelay_sec\fR] [\-\-force\-busy] [\-\-crl\-strict] [\-\-crlcheckinterval] [\-\-listen\ \fIipaddr\fR] [\-\-nhelpers\ \fInumber\fR] [\-\-seedbits\ \fInumbits\fR] [\-\-statsbin\ \fIfilename\fR] [\-\-secctx\-attr\-type\ \fInumber\fR]
.br
[\-\-use\-xfrm] [\-\-use\-bsdkame]
.SH "DESCRIPTION"
.PP
\fBpluto\fR
is
Libreswan\*(Aqs
Internet Key Exchange (IKE) daemon\&.
.PP
\fBpluto\fR
is not normally run directly\&. Instead the daemon is controlled the hosts
\fBinit\fR(8)
system (such as
\fBsystemd\fR(1)
or
\fBrc\fR(8)) or the command
\fBipsec\fR
(see
\fBipsec\fR(8))\&.
.PP
For more general information on
Libreswan
see
\fBlibreswan\fR(7)\&.
.PP
For information on how to configure
Libreswan
and the
\fBpluto\fR
daemon see
\fBipsec.conf\fR(5)\&.
.SS "Help Options"
.PP
\fB\-\-help\fR
.RS 4
show
\fBpluto\*(Aqs\fR
usage message
.RE
.PP
\fB\-\-version\fR
.RS 4
show
Libreswan\*(Aqs
version details
.RE
.SS "Starting pluto"
.PP
When starting,
\fBpluto\fR
attempts to create a lockfile with the name
/run/pluto/pluto\&.pid\&. If the lockfile cannot be created,
\fBpluto\fR
exits \- this prevents multiple
\fBpluto\fRs from competing\&. Any "leftover" lockfile must be manually removed before
\fBpluto\fR
will run\&.
\fBpluto\fR
then writes its
\fIPID\fR
into this file so that scripts can find it\&.
\fBpluto\fR
then forks and the parent exits (this is the conventional "daemon fork")\&.
.PP
The following options alter how
\fBpluto\fR
starts:
.PP
\fB\-\-nofork\fR
.RS 4
disable "daemon fork"
.sp
In addition, after the lock file and control socket are created, print the line "Pluto initialized" to standard out\&.
.RE
.PP
\fB\-\-rundir \fR\fB\fIpath\fR\fR
.RS 4
change the
run
directory from the default
/run/pluto)
.sp
The
run
directory contains:
.PP
\fIpath\fR/pluto\&.ctl
.RS 4
the socket through which
\fBwhack\fR
communicates with
\fBpluto\fR
.RE
.PP
\fIpath\fR/pluto\&.pid
.RS 4
the lockfile to prevent multiple
\fBpluto\fR
instances
.RE
.sp
.RE
.PP
\fB\-\-leak\-detective\fR
.RS 4
enable leak detective
.RE
.PP
\fB\-\-efence\-protect\fR
.RS 4
enable efence protection
.RE
.SS "Logging"
.PP
All logging, including diagnostics, are sent to
\fBsyslog\fR(3)
with
facility=authpriv; it decides where to put these messages\&. The following options alter this behaviour:
.PP
\fB\-\-stderrlog\fR
.RS 4
direct logging to standard error instead of a log file
.sp
Often combined with
\fB\-\-nofork\fR
debugging
\fBpluto\fR\&.
.RE
.PP
\fB\-\-logfile \fR\fB\fIfilename\fR\fR
.RS 4
direct logging to
\fIfilename\fR
instead of
\fBsyslog\fR(3)
.sp
See
\fBipsec.conf\fR(5)
and
logfile=\fIfilename\fR\&.
.RE
.PP
\fB\-\-log\-no\-time\fR
.RS 4
do not include a timestamp prefix when logging to a file
.sp
See
\fBipsec.conf\fR(5)
and
logtime=no\&.
.RE
.PP
\fB\-\-log\-no\-append\fR
.RS 4
do not append to the end of an existing log file
.sp
See
\fBipsec.conf\fR(5)
and
logappend=no\&.
.RE
.PP
\fB\-\-log\-no\-ip\fR
.RS 4
do not include IP addresses when logging
.sp
See
\fBipsec.conf\fR(5)
and
logip=no\&.
.RE
.PP
\fB\-\-log\-no\-audit\fR
.RS 4
do not generate audit logs (on systems that support Linux Auditing)
.sp
See
\fBipsec.conf\fR(5)
and
audit\-log=no\&.
.RE
.SS "Configuration Files"
.PP
The following option overrides the location of configuration files:
.PP
\fB\-\-config \fR\fB\fIfilename\fR\fR
.RS 4
the configuration file
.sp
Default is
/etc/ipsec.conf\&. See
\fBipsec.conf\fR(5)\&.
.RE
.PP
\fB\-\-secretsfile \fR\fB\fIsecrets\-file\fR\fR
.RS 4
specify the file for authentication secrets
.sp
This name is subject to "globbing" as in
\fBsh\fR(1), so every file with a matching name is processed\&. Quoting is generally needed to prevent the shell from doing the globbing\&.
.sp
Default is
/etc/ipsec.secrets\&. See
\fBipsec.secrets\fR(5)\&.
.RE
.PP
\fB\-\-ipsecdir \fR\fB\fIdirname\fR\fR
.RS 4
the directory containing additional configuration files
.sp
Default is
/etc/ipsec.d\&.
.RE
.PP
\fB\-\-nssdir \fR\fB\fIdirname\fR\fR
.RS 4
the directory containing the NSS trust store
.sp
Default is
/var/lib/ipsec/nss\&.
.RE
.PP
\fB\-\-coredir \fR\fB\fIdirname\fR\fR
.RS 4
the directory to write a core file should
\fBpluto\fR
abort
.sp
Default is
/run/pluto\&.
.RE
.SS "Other Options"
.PP
The following options tweak
\fBpluto\*(Aqs\fR
behaviour:
.PP
\fB\-\-vendorid \fR\fB\fIVID\fR\fR
.RS 4
.RE
.PP
\fB\-\-uniqueids\fR
.RS 4
require all connections to have a unique identifier
.sp
If this option has been selected, whenever a new ISAKMP SA is established, any connection with the same Peer ID but a different Peer IP address is unoriented (causing all its SAs to be deleted)\&. This helps clean up dangling SAs when a connection is lost and then regained at another IP address\&.
.RE
.PP
\fB\-\-virtual\-private \fR\fB\fInetwork_list\fR\fR
.RS 4
Pluto supports RFC 3947 NAT\-Traversal\&. The allowed range behind the NAT routers is submitted using the
\fB\-\-virtual\-private\fR
option\&.
.sp
See
\fBipsec.conf\fR(5)
for the syntax
.RE
.PP
\fB\-\-keep\-alive \fR\fB\fIdelay_sec\fR\fR
.RS 4
The
\fB\-\-keep\-alive\fR
sets the delay (in seconds) of these keep\-alive packets\&. The newer NAT\-T standards support
\fIport floating\fR, and Libreswan enables this per default\&.
.RE
.PP
\fB\-\-force\-busy\fR
.RS 4
If this option has been selected, pluto will be forced to be "busy"\&. In this state, which happens when there is a Denial of Service attack, will force pluto to use cookies before accepting new incoming IKE packets\&. Cookies are send and required in ikev1 Aggressive Mode and in ikev2\&. This option is mostly used for testing purposes, but can be selected by paranoid administrators as well\&.
.RE
.PP
\fB\-\-crl\-strict\fR
.RS 4
reject authentication using X\&.509 until a valid certificate revocation list has been loaded
.RE
.PP
\fB\-\-crlcheckinterval\fR
.RS 4
.RE
.PP
\fB\-\-listen \fR\fB\fIipaddr\fR\fR
.RS 4
.RE
.PP
\fB\-\-nhelpers \fR\fB\fInumber\fR\fR
.RS 4
specify the number of threads to use when offloading cryptographic operations
.sp
Pluto can also use helper children to off\-load cryptographic operations\&. This behavior can be fine tuned using the
\fB\-\-nhelpers\fR\&. Pluto will start
\fI(n\-1)\fR
of them, where
\fIn\fR
is the number of CPU\*(Aqs you have (including hypherthreaded CPU\*(Aqs)\&. A value of
\fI0\fR
forces pluto to do all operations in the main process\&. A value of
\fI\-1\fR
tells pluto to perform the above calculation\&. Any other value forces the number to that amount\&.
.sp
See
\fBipsec.conf\fR(5)
and
nhelpers=\fInumber\fR\&.
.RE
.PP
\fB\-\-seedbits \fR\fB\fInumbits\fR\fR
.RS 4
specify the number of seed bits to read from the RNG before starting
.sp
Pluto uses the NSS crypto library as its random source\&. Some government Three Letter Agency requires that pluto reads 440 bits from /dev/random and feed this into the NSS RNG before drawing random from the NSS library, despite the NSS library itself already seeding its internal state\&. As this process can block pluto for an extended time, the default is to not perform this redundant seeding\&. The
\fB\-\-seedbits\fR
option can be used to specify the number of bits that will be pulled from /dev/random and seeded into the NSS RNG\&.
.sp
See
\fBipsec.conf\fR(5)
and
seedbits=\fInumber\fR\&.
.sp
This option should not be used by most people\&.
.RE
.PP
\fB\-\-statsbin \fR\fB\fIfilename\fR\fR
.RS 4
.RE
.PP
\fB\-\-secctx\-attr\-type \fR\fB\fInumber\fR\fR
.RS 4
.RE
.PP
\fBLibreswan\fR
supports different IPstacks on different operating systems\&. Since most IPstacks have died the list is very short:
.PP
\fB\-\-use\-xfrm\fR
.RS 4
linux only
.RE
.PP
\fB\-\-use\-bsdkame\fR
.RS 4
BSD only
.RE
.SS "Debugging"
.PP
When running
\fBpluto\fR
under a debugger, the options
\fB\-\-nofork\fR
and
\fB\-\-stderrlog\fR
are recommended\&.
.PP
\fBpluto\fR
is willing to produce a prodigious amount of debugging information\&. There are several classes of debugging output, and
\fBpluto\fR
may be directed to produce a selection of them\&. All lines of debugging output are prefixed with "|" to distinguish them from normal diagnostic messages\&.
.PP
See
\fBipsec.conf\fR(5)
and
plutodebug=\fIoptions\fR\&.
.PP
Very occasionally it is necessary to enable debugging early in
\fBpluto\*(Aqs\fR
startup process\&. The follow options enable this:
.PP
\fB\-\-debug help\fR (whack only)
.RS 4
List the debugging classes recognised by
\fBpluto\fR\&.
.RE
.PP
\fB\-\-debug none\fR
.RS 4
Disable logging for all debugging classes\&.
.RE
.PP
\fB\-\-debug base\fR
.RS 4
Enable debug\-logging\&.
.RE
.PP
\fB\-\-debug cpu\-usage\fR
.RS 4
Enable cpu\-usage logging\&.
.RE
.PP
\fB\-\-debug \fR\fB\fIclass\fR\fR, \fB\-\-no\-debug \fR\fB\fIclass\fR\fR, \fB\-\-debug no\-\fR\fB\fIclass\fR\fR
.RS 4
Enable (disable) logging of the specified debugging
\fIclass\fR
(\fB\-\-debug help\fR
lists debugging classes supported by this version of
\fBpluto\fR)\&.
.RE
.SH "SIGNALS"
.PP
\fBpluto\fR
responds to
\fBSIGHUP\fR
by issuing a suggestion that
\fBipsec listen\fR
might have been intended\&.
.PP
\fBpluto\fR
exits when it receives
\fBSIGTERM\fR\&.
.SH "EXIT STATUS"
.PP
\fBpluto\fR
normally forks a daemon process, so the exit status is a very preliminary result\&.
.PP
\fB0\fR
.RS 4
means that all is OK so far\&.
.RE
.PP
\fB1\fR
.RS 4
means that something was wrong\&.
.RE
.PP
\fB10\fR
.RS 4
means that the lock file already exists\&.
.RE
.SH "FILES"
.PP
/run/pluto/pluto\&.pid
/run/pluto/pluto\&.ctl
/etc/ipsec.secrets
/etc/ipsec.conf
.SH "ENVIRONMENT"
.PP
\fBpluto\fR
does not use any environment variables\&.
.SH "SEE ALSO"
.PP
The rest of the Libreswan distribution, in particular
\fBlibreswan\fR(7)\&.
.SH "HISTORY"
.PP
This code is released under the GPL terms\&. See the accompanying files CHANGES COPYING and CREDITS\&.* for more details\&.
.PP
Detailed history (including FreeS/WAN and Openswan) can be found in the docs/ directory\&.
.SH "BUGS"
.PP
Please see
\m[blue]\fBhttps://github\&.com/libreswan/libreswan/issues\fR\m[]
for a list of currently known bugs and missing features\&.
.SH "AUTHOR"
.PP
Paul Wouters
Andrew Cagney