Scroll to navigation

IPSEC-PLUTO(8) Executable programs IPSEC-PLUTO(8)

NAME

ipsec-pluto, pluto - Internet Key Exchange daemon

SYNOPSIS

ipsec pluto [--help] [--version]
[--nofork] [--rundir path] [--leak-detective] [--efence-protect]
[--stderrlog] [--logfile filename] [--log-no-time] [--log-no-append] [--log-no-ip] [--log-no-audit]
[--config filename] [--secretsfile secrets-file] [--ipsecdir dirname] [--nssdir dirname] [--coredir dirname]
[--vendorid VID] [--uniqueids] [--virtual-private network_list] [--keep-alive delay_sec] [--force-busy] [--crl-strict] [--crlcheckinterval] [--listen ipaddr] [--nhelpers number] [--seedbits numbits] [--statsbin filename] [--secctx-attr-type number]
[--use-xfrm] [--use-bsdkame]

DESCRIPTION

pluto is Libreswan's Internet Key Exchange (IKE) daemon.

pluto is not normally run directly. Instead the daemon is controlled the hosts init(8) system (such as systemd(1) or rc(8)) or the command ipsec (see ipsec(8)).

For more general information on Libreswan see libreswan(7).

For information on how to configure Libreswan and the pluto daemon see ipsec.conf(5).

Help Options

--help

show pluto's usage message

--version

show Libreswan's version details

Starting pluto

When starting, pluto attempts to create a lockfile with the name /run/pluto/pluto.pid. If the lockfile cannot be created, pluto exits - this prevents multiple plutos from competing. Any "leftover" lockfile must be manually removed before pluto will run. pluto then writes its PID into this file so that scripts can find it. pluto then forks and the parent exits (this is the conventional "daemon fork").

The following options alter how pluto starts:

--nofork

disable "daemon fork"

In addition, after the lock file and control socket are created, print the line "Pluto initialized" to standard out.

--rundir path

change the run directory from the default /run/pluto)

The run directory contains:

path/pluto.ctl

the socket through which whack communicates with pluto

path/pluto.pid

the lockfile to prevent multiple pluto instances

--leak-detective

enable leak detective

--efence-protect

enable efence protection

Logging

All logging, including diagnostics, are sent to syslog(3) with facility=authpriv; it decides where to put these messages. The following options alter this behaviour:

--stderrlog

direct logging to standard error instead of a log file

Often combined with --nofork debugging pluto.

--logfile filename

direct logging to filename instead of syslog(3)

See ipsec.conf(5) and logfile=filename.

--log-no-time

do not include a timestamp prefix when logging to a file

See ipsec.conf(5) and logtime=no.

--log-no-append

do not append to the end of an existing log file

See ipsec.conf(5) and logappend=no.

--log-no-ip

do not include IP addresses when logging

See ipsec.conf(5) and logip=no.

--log-no-audit

do not generate audit logs (on systems that support Linux Auditing)

See ipsec.conf(5) and audit-log=no.

Configuration Files

The following option overrides the location of configuration files:

--config filename

the configuration file

Default is /etc/ipsec.conf. See ipsec.conf(5).

--secretsfile secrets-file

specify the file for authentication secrets

This name is subject to "globbing" as in sh(1), so every file with a matching name is processed. Quoting is generally needed to prevent the shell from doing the globbing.

Default is /etc/ipsec.secrets. See ipsec.secrets(5).

--ipsecdir dirname

the directory containing additional configuration files

Default is /etc/ipsec.d.

--nssdir dirname

the directory containing the NSS trust store

Default is /var/lib/ipsec/nss.

--coredir dirname

the directory to write a core file should pluto abort

Default is /run/pluto.

Other Options

The following options tweak pluto's behaviour:

--vendorid VID

--uniqueids

require all connections to have a unique identifier

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.

--virtual-private network_list

Pluto supports RFC 3947 NAT-Traversal. The allowed range behind the NAT routers is submitted using the --virtual-private option.

See ipsec.conf(5) for the syntax

--keep-alive delay_sec

The --keep-alive sets the delay (in seconds) of these keep-alive packets. The newer NAT-T standards support port floating, and Libreswan enables this per default.

--force-busy

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.

--crl-strict

reject authentication using X.509 until a valid certificate revocation list has been loaded

--crlcheckinterval

--listen ipaddr

--nhelpers number

specify the number of threads to use when offloading cryptographic operations

Pluto can also use helper children to off-load cryptographic operations. This behavior can be fine tuned using the --nhelpers. Pluto will start (n-1) of them, where n is the number of CPU's you have (including hypherthreaded CPU's). A value of 0 forces pluto to do all operations in the main process. A value of -1 tells pluto to perform the above calculation. Any other value forces the number to that amount.

See ipsec.conf(5) and nhelpers=number.

--seedbits numbits

specify the number of seed bits to read from the RNG before starting

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 --seedbits option can be used to specify the number of bits that will be pulled from /dev/random and seeded into the NSS RNG.

See ipsec.conf(5) and seedbits=number.

This option should not be used by most people.

--statsbin filename

--secctx-attr-type number

Libreswan supports different IPstacks on different operating systems. Since most IPstacks have died the list is very short:

--use-xfrm

linux only

--use-bsdkame

BSD only

Debugging

When running pluto under a debugger, the options --nofork and --stderrlog are recommended.

pluto is willing to produce a prodigious amount of debugging information. There are several classes of debugging output, and pluto may be directed to produce a selection of them. All lines of debugging output are prefixed with "|" to distinguish them from normal diagnostic messages.

See ipsec.conf(5) and plutodebug=options.

Very occasionally it is necessary to enable debugging early in pluto's startup process. The follow options enable this:

--debug help (whack only)

List the debugging classes recognised by pluto.

--debug none

Disable logging for all debugging classes.

--debug base

Enable debug-logging.

--debug cpu-usage

Enable cpu-usage logging.

--debug class, --no-debug class, --debug no-class

Enable (disable) logging of the specified debugging class (--debug help lists debugging classes supported by this version of pluto).

SIGNALS

pluto responds to SIGHUP by issuing a suggestion that ipsec listen might have been intended.

pluto exits when it receives SIGTERM.

EXIT STATUS

pluto normally forks a daemon process, so the exit status is a very preliminary result.

0

means that all is OK so far.

1

means that something was wrong.

10

means that the lock file already exists.

FILES

/run/pluto/pluto.pid /run/pluto/pluto.ctl /etc/ipsec.secrets /etc/ipsec.conf

ENVIRONMENT

pluto does not use any environment variables.

SEE ALSO

The rest of the Libreswan distribution, in particular libreswan(7).

HISTORY

This code is released under the GPL terms. See the accompanying files CHANGES COPYING and CREDITS.* for more details.

Detailed history (including FreeS/WAN and Openswan) can be found in the docs/ directory.

BUGS

Please see https://github.com/libreswan/libreswan/issues for a list of currently known bugs and missing features.

AUTHOR

Paul Wouters Andrew Cagney

03/14/2024 Libreswan 5.0~rc2