.TH UML_NETJIG 8 "16 June 2002".SH NAMEuml_netjig \- User Mode Linux network testing jig.SH SYNOPSIS.na.nh.HP.ft Buml_netjig[\-\-help][\-\-arpreply][\-\-debug][\-\-exitonempty][\-\-tcpdump][\-\-playpublic\fIfilename\fP][\-\-playprivate]\fIfilename\fP][\-\-recordpublic]\fIfilename\fP][\-\-recordprivate]\fIfilename\fP][\-\-unix\fIdirname\fP][\-\-startup\fIprogram\fP].ft R.HP.ft Buml_netjig [\-\-cmdproto].ft R.hy.ad.SH DESCRIPTION.BR uml_netjigis an descendant of the User-Mode-Linux projects ``uml_switch'') program. Ithas been extended to facilitate automated testing of networking code foundin a User-Mode-Linux guest kernel..BR whackis an auxiliary program to allow requests to be made to a running.BR pluto ..LP.BR plutois used to automatically build shared ``security associations'' on asystem that has IPsec, the secure IP protocol.In other words,.BR plutocan eliminate much of the work of manual keying.The actualsecure transmission of packets is the responsibility of other parts ofthe system (see.BR KLIPS ,the companion implementation of IPsec).\fIipsec_auto\fP(8) provides a more convenient interface to\fBpluto\fP and \fBwhack\fP..SS IKE's Job.LPA \fISecurity Association\fP (\fISA\fP) is an agreement between two network nodes onhow to process certain traffic between them.  This processing involvesencapsulation, authentication, encryption, or compression..LPIKE can be deployed on a network node to negotiate SecurityAssociations for that node.  These IKE implementations can onlynegotiate with other IKE implementations, so IKE must be on each nodethat is to be an endpoint of an IKE-negotiated Security Association.No other nodes need to be running IKE..LPAn IKE instance (i.e. an IKE implementation on a particular networknode) communicates with another IKE instance using UDP IP packets, sothere must be a route between the nodes in each direction..LPThe negotiation of Security Associations requires a number of choicesthat involve tradeoffs between security, convenience, trust, andefficiency.  These are policy issues and are normally specified to theIKE instance by the system administrator..LPIKE deals with two kinds of Security Associations.  The first part ofa negotiation between IKE instances is to build an ISAKMP SA.  AnISAKMP SA is used to protect communication between the two IKEs.IPsec SAs can then be built by the IKEs \- these are used to carryprotected IP traffic between the systems..LPThe negotiation of the ISAKMP SA is known as Phase 1.  In theory,Phase 1 can be accomplished by a couple of different exchange types,but we only implement one called Main Mode (we don't implementAggressive Mode)..LPAny negotiation under the protection of an ISAKMP SA, including thenegotiation of IPsec SAs, is part of Phase 2.  The exchange typethat we use to negotiate an IPsec SA is called Quick Mode..LPIKE instances must be able to authenticate each other as part of theirnegotiation of an ISAKMP SA.  This can be done by several mechanismsdescribed in the draft standards..LPIKE negotiation can be initiated by any instance with any other.  Ifboth can find an agreeable set of characteristics for a SecurityAssociation, and both recognize each others authenticity, they can setup a Security Association.  The standards do not specify what causesan IKE instance to initiate a negotiation..LPIn summary, an IKE instance is prepared to automate the management ofSecurity Associations in an IPsec environment, but a number of issuesare considered policy and are left in the system administrator's hands..SS Pluto.LP\fBpluto\fP is an implementation of IKE.  It runs as a daemon on a networknode.  Currently, this network node must be a LINUX system running the\fBKLIPS\fP implementation of IPsec..LP\fBpluto\fP only implements a subset of IKE.  This is enough for it tointeroperate with other instances of \fBpluto\fP, and many other IKEimplementations.  We are working on implementing more of IKE..LPThe policy for acceptable characteristics for Security Associations ismostly hardwired into the code of \fBpluto\fP (spdb.c).  Eventuallythis will be moved into a security policy database with reasonableexpressive power and more convenience..LP\fBpluto\fP uses shared secrets or RSA signatures to authenticatepeers with whom it is negotiating..LP\fBpluto\fP initiates negotiation of a Security Association when it ismanually prodded: the program \fBwhack\fP is run to trigger this.It will also initiate a negotiation when \fBKLIPS\fP traps an outbound packetfor Opportunistic Encryption..LP\fBpluto\fP implements ISAKMP SAs itself.  After it has negotiated thecharacteristics of an IPsec SA, it directs \fBKLIPS\fP to implement it.It also invokes a script to adjust any firewall and issue \fIroute\fP(8)commands to direct IP packets through \fBKLIPS\fP..LPWhen \fBpluto\fP shuts down, it closes all Security Associations..SS Before Running Pluto.LP\fBpluto\fP runs as a daemon with userid root.  Before running it, a fewthings must be set up..LP\fBpluto\fP requires \fBKLIPS\fP, the FreeS/WAN implementation of IPsec.All of the components of \fBKLIPS\fP and \fBpluto\fP should be installed..LP\fBpluto\fP supports multiple public networks (that is, networksthat are considered insecure and thus need to have their trafficencrypted or authenticated).  It discovers thepublic interfaces to use by looking at all interfaces that areconfigured (the \fB\-\-interface\fP option can be used to limitthe interfaces considered).It does this only when \fBwhack\fP tells it to \-\-listen,so the interfaces must be configured by then.  Each interface with a name of the form\fBipsec\fP[\fB0\fP-\fB9\fP] is taken as a \fBKLIPS\fP virtual public interface.Another network interface with the same IP address (there should be onlyone) is taken as the corresponding real publicinterface.  \fIifconfig\fP(8) with the \fB\-a\fP flag will showthe name and status of each network interface..LP\fBpluto\fP requires a database of preshared secrets and RSA private keys.This is described in the.IR ipsec.secrets (5).\fBpluto\fP is told of RSA public keys via \fBwhack\fP commands.If the connection is Opportunistic, and no RSA public key is known,\fBpluto\fP will attempt to fetch RSA keys using the Domain Name System..SS Setting up \fBKLIPS\fP for \fBpluto\fP.LPThe most basic network topology that \fBpluto\fP supports has two securitygateways negotiating on behalf of client subnets.  The diagram of RGB'stestbed is a good example (see \fIklips/doc/rgb_setup.txt\fP)..LPThe file \fIINSTALL\fP in the base directory of this distributionexplains how to start setting up the whole system, including \fBKLIPS\fP..LPMake sure that the security gateways have routes to each other.  Thisis usually covered by the default route, but may require issuing.IR route (8)commands.  The route must go through a particular IPinterface (we will assume it is \fIeth0\fP, but it need not be).  Theinterface that connects the security gateway to its client must be adifferent one..LPIt is necessary to issue a.IR ipsec_tncfg (8)command on each gateway.  The required command is:\ \ \ ipsec tncfg \-\-attach\ \-\-virtual\ ipsec0 \-\-physical\ eth0A command to set up the ipsec0 virtual interface will also need to berun.  It will have the same parameters as the command used to set upthe physical interface to which it has just been connected using.IR ipsec_tncfg (8)..SS ipsec.secrets file.LPA \fBpluto\fP daemon and another IKE daemon (for example, another instanceof \fBpluto\fP) must convince each other that they are who they are supposedto be before any negotiation can succeed.  This authentication isaccomplished by using either secrets that have been shared beforehand(manually) or by using RSA signatures.  There are other techniques,but they have not been implemented in \fBpluto\fP..LPThe file \fI/etc/ipsec.secrets\fP is used to keep preshared secret keysand RSA private keys forauthentication with other IKE daemons.  For debugging, there is anargument to the \fBpluto\fP command to use a different file.This file is described in.IR ipsec.secrets (5)..SS Running Pluto.LPTo fire up the daemon, just type \fBpluto\fP (be sure to be running asthe superuser).The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons.\fBpluto\fP must be run by the superuser to be able to use the UDP 500 port..LP\fBpluto\fP attempts to create a lockfile with the name\fI/var/run/pluto/pluto.pid\fP.  If the lockfile cannot be created,\fBpluto\fP exits \- this prevents multiple \fBpluto\fPs fromcompeting  Any ``leftover'' lockfile must be removed before\fBpluto\fP will run.  \fBpluto\fP writes its pid into this file sothat scripts can find it.  This lock will not function properly if itis on an NFS volume (but sharing locks on multiple machines doesn'tmake sense anyway)..LP\fBpluto\fP then forks and the parent exits.  This is the conventional``daemon fork''.  It can make debugging awkward, so there is an optionto suppress this fork..LPAll logging, including diagnostics, is sent to.IR syslog (3)with facility=authpriv;it decides where to put these messages (possibly in /var/log/secure).Since this too can make debugging awkward, there is an option tosteer logging to stderr..LPOnce \fBpluto\fP is started, it waits for requests from \fBwhack\fP..SS Pluto's Internal State.LPTo understand how to use \fBpluto\fP, it is helpful to understand a littleabout its internal state.  Furthermore, the terminology is needed to deciphersome of the diagnostic messages..LPThe \fI(potential) connection\fP database describes attributes of aconnection.  These include the IP addresses of the hosts and clientsubnets and the security characteristics desired.  \fBpluto\fPrequires this information (simply called a connection) before it canrespond to a request to build an SA.  Each connection is given a namewhen it is created, and all references are made using this name..LPDuring the IKE exchange to build an SA, the information about thenegotiation is represented in a \fIstate object\fP.  Each state objectreflects how far the negotiation has reached.  Once the negotiation iscomplete and the SA established, the state object remains to representthe SA.  When the SA is terminated, the state object is discarded.Each State object is given a serial number and this is used to referto the state objects in logged messages..LPEach state object corresponds to a connection and can be thought ofas an instantiation of that connection.At any particular time, there may be any number of state objectscorresponding to a particular connection.Often there is one representing an ISAKMP SA and another representingan IPsec SA..LP\fBKLIPS\fP hooks into the routing code in a LINUX kernel.Traffic to be processed by an IPsec SA must be directed through\fBKLIPS\fP by routing commands.  Furthermore, the processing to bedone is specified by \fIipsec eroute(8)\fP commands.\fBpluto\fP takes the responsibility of managing both of these specialkinds of routes..LPEach connection may be routed, and must be while it has an IPsec SA.The connection specifies the characteristics of the route: theinterface on this machine, the ``gateway'' (the nexthop),and the peer's client subnet.  Twoconnections may not be simultaneously routed if they are for the samepeer's client subnet but use different interfaces or gateways(\fBpluto\fP's logic does not reflect any advanced routing capabilities)..LPEach eroute is associated with the state object for an IPsec SAbecause it has the particular characteristics of the SA.Two eroutes conflict if they specify the identical localand remote clients (unlike for routes, the local clients aretaken into account)..LPWhen \fBpluto\fP needs to install a route for a connection,it must make sure that no conflicting route is in use.  If anotherconnection has a conflicting route, that route will be taken down, as longas there is no IPsec SA instantiating that connection.If there is such an IPsec SA, the attempt to install a route will fail..LPThere is an exception.  If \fBpluto\fP, as Responder, needs to installa route to a fixed client subnet for a connection, and there isalready a conflicting route, then the SAs using the route are deletedto make room for the new SAs.  The rationale is that the newconnection is probably more current.  The need for this usually is aproduct of Road Warrior connections (these are explained later; theycannot be used to initiate)..LPWhen \fBpluto\fP needs to install an eroute for an IPsec SA (for astate object), first the state object's connection must be routed (ifthis cannot be done, the eroute and SA will not be installed).If a conflicting eroute is already in place for another connection,the eroute and SA will not be installed (but note that the routingexception mentioned above may have already deleted potentially conflicting SAs).If another IPsecSA for the same connection already has an eroute, all its outgoing trafficis taken over by the new eroute.  The incoming traffic will still beprocessed.  This characteristic is exploited during rekeying..LPAll of these routing characteristics are expected change when\fBKLIPS\fP is modified to use the firewall hooks in the LINUX 2.4.xkernel..SS Using Whack.LP\fBwhack\fP is used to command a running \fBpluto\fP.\fBwhack\fP uses a UNIX domain socket to speak to \fBpluto\fP(by default, \fI/var/pluto.ctl\fP)..LP\fBwhack\fP has an intricate argument syntax.This syntax allows many different functions to be specified.The help form shows the usage or version information.The connection form gives \fBpluto\fP a description of a potential connection.The public key form informs \fBpluto\fP of the RSA public key for a potential peer.The delete form deletes a connection description and all SAs correspondingto it.The listen form tells \fBpluto\fP to start or stop listening on the public interfacesfor IKE requests from peers.The route form tells \fBpluto\fP to set up routing for a connection;the unroute form undoes this.The initiate form tells \fBpluto\fP to negotiate an SA corresponding to a connection.The terminate form tells \fBpluto\fP to remove all SAs corresponding to a connection,including those being negotiated.The status form displays the \fBpluto\fP's internal state.The debug form tells \fBpluto\fP to change the selection of debugging output``on the fly''.  The shutdown form tells\fBpluto\fP to shut down, deleting all SAs..LPMost options are specific to one of the forms, and will be describedwith that form.  There are three options that apply to all forms..TP\fB\-\-ctlbase\fP\ \fIpath\fP\fIpath\fP.ctl is used as the UNIX domain socket for talkingto \fBpluto\fP.This option facilitates debugging..TP\fB\-\-optionsfrom\fP\ \fIfilename\fP