It would be normal to start \fBpluto\fP in one of the system initializationscripts.  It needs to be run by the superuser.  Generally, no arguments are needed.To run in manually, the superuser can simply type\ \ \ ipsec plutoThe command will immediately return, but a \fBpluto\fP process will be leftrunning, waiting for requests from \fBwhack\fP or a peer..LPUsing \fBwhack\fP, several potential connections would be described:.HP.na\ \ \ ipsec whack \-\-name\ silly\-\-host\ 127.0.0.1 \-\-to \-\-host\ 127.0.0.2\-\-ikelifetime\ 900 \-\-ipseclifetime\ 800 \-\-keyingtries\ 3.ad.LPSince this silly connection description specifies neither encryption,authentication, nor tunneling, it could only be used to establishan ISAKMP SA..HP.na\ \ \ ipsec whack \-\-name\ secret \-\-host\ 10.0.0.1 \-\-client\ 10.0.1.0/24\-\-to \-\-host\ 10.0.0.2 \-\-client\ 10.0.2.0/24\-\-encrypt.ad.LPThis is something that must be done on both sides.  If the otherside is \fBpluto\fP, the same \fBwhack\fP command could be used on it(the command syntax is designed to not distinguish which end is ours)..LPNow that the connections are specified, \fBpluto\fP is ready to handlerequests and replies via the public interfaces.  We must tell it to discoverthose interfaces and start accepting messages from peers:\ \ \ ipsec whack \-\-listen.LPIf we don't immediately wish to bring up a secure connection betweenthe two clients, we might wish to prevent insecure traffic.The routing form asks \fBpluto\fP to cause the packets sent fromour client to the peer's client to be routed through the ipsec0device; if there is no SA, they will be discarded:\ \ \ ipsec whack \-\-route secret.LPFinally, we are ready to get \fBpluto\fP to initiate negotiationfor an IPsec SA (and implicitly, an ISAKMP SA):\ \ \ ipsec whack \-\-initiate\ \-\-name\ secretA small log of interesting events will appear on standard output(other logging is sent to syslog)..LP\fBwhack\fP can also be used to terminate \fBpluto\fP cleanly, tearing downall SAs that it has negotiated.\ \ \ ipsec whack \-\-shutdownNotification of any IPSEC SA deletion, but not ISAKMP SA deletionis sent to the peer.  Unfortunately, such Notification is not reliable.Furthermore, \fBpluto\fP itself ignores Notifications..SS The updown command.LPWhenever \fBpluto\fP brings a connection up or down, it invokesthe updown command.  This command is specified using the \fB\-\-updown\fPoption.  This allows for customized control over routing and firewall manipulation..LPThe updown is invoked for five different operations.  Each ofthese operations can be for our client subnet or for our host itself..TP\fBprepare-host\fP or \fBprepare-client\fPis run before bringing up a new connection if no other connectionwith the same clients is up.  Generally, this is useful for deleting aroute that might have been set up before \fBpluto\fP was run orperhaps by some agent not known to \fBpluto\fP..TP\fBroute-host\fP or \fBroute-client\fPis run when bringing up a connection for a new peer client subnet(even if \fBprepare-host\fP or \fBprepare-client\fP was run).  Thecommand should install a suitable route.  Routing decisions are basedonly on the destination (peer's client) subnet address, unlike erouteswhich discriminate based on source too..TP\fBunroute-host\fP or \fBunroute-client\fPis run when bringing down the last connection for a particular peerclient subnet.  It should undo what the \fBroute-host\fP or \fBroute-client\fPdid..TP\fBup-host\fP or \fBup-client\fPis run when bringing up a tunnel eroute with a pair of client subnetsthat does not already have a tunnel eroute.This command should install firewall rules as appropriate.It is generally a good idea to allow IKE messages (UDP port 500)travel between the hosts..TP\fBdown-host\fP or \fBdown-client\fPis run when bringing down the eroute for a pair of client subnets.This command should delete firewall rules as appropriate.  Note thatthere may remain some inbound IPsec SAs with these client subnets..LPThe script is passed a large number of environment variables to specifywhat needs to be done..TP\fBPLUTO_VERSION\fPindicates what version of this interface is being used.  This documentdescribes version 1.1.  This is upwardly compatible with version 1.0..TP\fBPLUTO_VERB\fPspecifies the name of the operation to be performed(\fBprepare-host\fP,r \fBprepare-client\fP,\fBup-host\fP, \fBup-client\fP,\fBdown-host\fP, or \fBdown-client\fP).  If the address family forsecurity gateway to security gateway communications is IPv6, thena suffix of -v6 is added to the verb..TP\fBPLUTO_CONNECTION\fPis the name of the connection for which we are routing..TP\fBPLUTO_NEXT_HOP\fPis the next hop to which packets bound for the peer must be sent..TP\fBPLUTO_INTERFACE\fPis the name of the ipsec interface to be used..TP\fBPLUTO_ME\fPis the IP address of our host..TP\fBPLUTO_MY_CLIENT\fPis the IP address / count of our client subnet.If the client is just the host, this will be the host's own IP address / max(where max is 32 for IPv4 and 128 for IPv6)..TP\fBPLUTO_MY_CLIENT_NET\fPis the IP address of our client net.If the client is just the host, this will be the host's own IP address..TP\fBPLUTO_MY_CLIENT_MASK\fPis the mask for our client net.If the client is just the host, this will be 255.255.255.255..TP\fBPLUTO_PEER\fPis the IP address of our peer..TP\fBPLUTO_PEER_CLIENT\fPis the IP address / count of the peer's client subnet.If the client is just the peer, this will be the peer's own IP address / max(where max is 32 for IPv4 and 128 for IPv6)..TP\fBPLUTO_PEER_CLIENT_NET\fPis the IP address of the peer's client net.If the client is just the peer, this will be the peer's own IP address..TP\fBPLUTO_PEER_CLIENT_MASK\fPis the mask for the peer's client net.If the client is just the peer, this will be 255.255.255.255..LPAll output sent by the script to stderr or stdout is logged.  Thescript should return an exit status of 0 if and only if it succeeds..SS Rekeying.LPWhen an SA that was initiated by \fBpluto\fP has only a bit oflifetime left,\fBpluto\fP will initiate the creation of a new SA.  This applies toISAKMP and IPsec SAs.The rekeying will be initiated when the SA's remaining lifetime isless than the rekeymargin plus a random percentage, between 0 andrekeyfuzz, of the rekeymargin..LPSimilarly, when an SA that was initiated by the peer has only a bit oflifetime left, \fBpluto\fP will try to initiate the creation of areplacement.To give preference to the initiator, this rekeying will only be initiatedwhen the SA's remaining lifetime is half of rekeymargin.If rekeying is done by the responder, the roles will be reversed: theresponder for the old SA will be the initiator for the replacement.The former initiator might also initiate rekeying, so there maybe redundant SAs created.To avoid these complications, make sure that rekeymargin is generous..LPOne risk of having the former responder initiate is that perhapsnone of its proposals is acceptable to the former initiator(they have not been used in a successful negotiation).To reduce the chances of this happening, and to prevent loss of security,the policy settings are taken from the old SA (this is the case even ifthe former initiator is initiating).These may be stricter than those of the connection..LP\fBpluto\fP will not rekey an SA if that SA is not the most recent of itstype (IPsec or ISAKMP) for its potential connection.This avoids creating redundant SAs..LPThe random component in the rekeying time (rekeyfuzz) is intended tomake certain pathological patterns of rekeying unstable.  If bothsides decide to rekey at the same time, twice as many SAs as necessaryare created.  This could become a stable pattern without therandomness..LPAnother more important case occurs when a security gateway has SAswith many other security gateways.  Each of these connections mightneed to be rekeyed at the same time.  This would cause a high peekrequirement for resources (network bandwidth, CPU time, entropy forrandom numbers).  The rekeyfuzz can be used to stagger the rekeyingtimes..LPOnce a new set of SAs has been negotiated, \fBpluto\fP will never sendtraffic on a superseded one.  Traffic will be accepted on an old SAuntil it expires..SS Selecting a Connection When Responding: Road Warrior Support.LPWhen \fBpluto\fP receives an initial Main Mode message, it needs todecide which connection this message is for.  It picks based solely onthe source and destination IP addresses of the message.  There mightbe several connections with suitable IP addresses, in which case oneof them is arbitrarily chosen.  (The ISAKMP SA proposal contained inthe message could be taken into account, but it is not.).LPThe ISAKMP SA is negotiated before the parties pass furtheridentifying information, so all ISAKMP SA characteristics specified inthe connection description should be the same for every connectionwith the same two host IP addresses.  At the moment, the onlycharacteristic that might differ is authentication method..LPUp to this point,all configuring has presumed that the IP addressesare known to all parties ahead of time.  This will not workwhen either end is mobile (or assigned a dynamic IP address for otherreasons).  We call this situation ``Road Warrior''.  It is fairly trickyand has some important limitations, most of which are features ofthe IKE protocol..LPOnly the initiator may be mobile:the initiator may have an IP number unknown to the responder.  Whenthe responder doesn't recognize the IP address on the first Main Modepacket, it looks for a connection with itself as one end and \fB%any\fPas the other.If it cannot find one, it refuses to negotiate.  If itdoes find one, it creates a temporary connection that is a duplicateexcept with the \fB%any\fP replaced by the source IP address from thepacket; if there was no identity specified for the peer, the new IPaddress will be used..LPWhen \fBpluto\fP is using one of these temporary connections andneeds to find the preshared secret or RSA private key in \fIipsec.secrets\fP,and and the connection specified no identity for the peer, \fB%any\fPis used as its identity.  After all, the real IP address was apparentlyunknown to the configuration, so it is unreasonable to require thatit be used in this table..LPPart way into the Phase 1 (Main Mode) negotiation using one of thesetemporary connection descriptions, \fBpluto\fP will be receive anIdentity Payload.  At this point, \fBpluto\fP checks for a moreappropriate connection, one with an identity for the peer that matchesthe payload but which would use the same keys so-far used forauthentication.  If it finds one, it will switch to using this betterconnection (or a temporary derived from this, if it has \fB%any\fPfor the peer's IP address).  It may even turn out that no connectionmatches the newly discovered identity, including the current connection;if so, \fBpluto\fP terminates negotiation..LPUnfortunately, if preshared secret authentication is being used, theIdentity Payload is encrypted using this secret, so the secret must beselected by the responder without knowing this payload.  Thislimits there to being at most one preshared secret for all Road Warriorsystems connecting to a host.  RSA Signature authentications does notrequire that the responder know how to select the initiator's public keyuntil after the initiator's Identity Payload is decoded (using theresponder's private key, so that must be preselected)..LPWhen \fBpluto\fP is responding to a Quick Mode negotiation via one of thesetemporary connection descriptions, it may well find that the subnetsspecified by the initiator don't match those in the temporaryconnection description.  If so, it will look for a connection withmatching subnets, its own host address, a peer address of \fB%any\fPand matching identities.If it finds one, a new temporary connection is derived from this oneand used for the Quick Mode negotiation of IPsec SAs.  If it does notfind one, \fBpluto\fP terminates negotiation..LPBe sure to specify an appropriate nexthop for the responderto send a message to the initiator: \fBpluto\fP has no way of guessingit (if forwarding isn't required, use an explicit \fB%direct\fP as the nexthopand the IP address of the initiator will be filled in; the obsoletenotation \fB0.0.0.0\fP is still accepted)..LP\fBpluto\fP has no special provision for the initiator side.  The current(possibly dynamic) IP address and nexthop must be used in definingconnections.  These must beproperly configured each time the initiator's IP address changes.\fBpluto\fP has no mechanism to do this automatically..LPAlthough we call this Road Warrior Support, it could also be used tosupport encrypted connections with anonymous initiators.  Theresponder's organization could announce the preshared secret that would be usedwith unrecognized initiators and let anyone connect.  Of course the initiator'sidentity would not be authenticated..LPIf any Road Warrior connections are supported, \fBpluto\fP cannotreject an exchange initiated by an unknown host until it hasdetermined that the secret is not shared or the signature is invalid.This must await thethird Main Mode message from the initiator.  If no Road Warriorconnection is supported, the first message from an unknown sourcewould be rejected.  This has implications for ease of debuggingconfigurations and for denial of service attacks..LPAlthough a Road Warrior connection must be initiated by the mobileside, the other side can and will rekey using the temporary connectionit has created.  If the Road Warrior wishes to be able to disconnect,it is probably wise to set \fB\-\-keyingtries\fP to 1 in theconnection on the non-mobile side to prevent it trying to rekey theconnection.  Unfortunately, there is no mechanism to unroute theconnection automatically..SS Debugging.LP\fBpluto\fP accepts several optional arguments, useful mostly for debugging.Except for \fB\-\-interface\fP, each should appear at most once..TP\fB\-\-interface\fP \fIinterfacename\fPspecifies that the named real public network interface should be considered.The interface name specified should not be \fBipsec\fP\fIN\fP.If the option doesn't appear, all interfaces are considered.To specify several interfaces, use the option once for each.One use of this option is to specify which interface should be usedwhen two or more share the same IP address..TP\fB\-\-ikeport\fP \fIport-number\fPchanges the UDP port that \fBpluto\fP will use(default, specified by IANA: 500).TP\fB\-\-ctlbase\fP \fIpath\fPbasename for control files.\fIpath\fP.ctl is the socket through which \fBwhack\fP communicates with\fBpluto\fP.\fIpath\fP.pid is the lockfile to prevent multiple \fBpluto\fP instances.The default is \fI/var/run/pluto/pluto\fP)..TP\fB\-\-secretsfile\fP \fIfile\fPspecifies the file for authentication secrets(default: \fI/etc/ipsec.secrets\fP).This name is subject to ``globbing'' as in \fIsh\fP(1),so every file with a matching name is processed.Quoting is generally needed to prevent the shell from doing the globbing..TP\fB\-\-adns\fP \fIpathname\fP