VBoxNetFlt.c revision f0626cddb8f2999ecf9a69b4778f163c767c1c66
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VBoxNetFlt - Network Filter Driver (Host), Common Code.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Copyright (C) 2008-2009 Oracle Corporation
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * available from http://www.virtualbox.org. This file is free software;
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * General Public License (GPL) as published by the Free Software
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync/** @page pg_netflt VBoxNetFlt - Network Interface Filter
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * This is a kernel module that attaches to a real interface on the host and
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * filters and injects packets.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * In the big picture we're one of the three trunk interface on the internal
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * network, the one named "NIC Filter Driver": @image html Networking_Overview.gif
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * @section sec_netflt_locking Locking and Potential Races
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The main challenge here is to make sure the netfilter and internal network
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * instances won't be destroyed while someone is calling into them.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The main calls into or out of of the filter driver are:
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Async send completion (not implemented yet)
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Release by the internal network.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Receive.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Disappearance of the host networking interface.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Reappearance of the host networking interface.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The latter two calls are can be caused by driver unloading/loading or the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * device being physical unplugged (e.g. a USB network device). Actually, the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * unload scenario must fervently be prevent as it will cause panics because the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * internal network will assume the trunk is around until it releases it.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * @todo Need to figure which host allow unloading and block/fix it.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Currently the netfilter instance lives until the internal network releases
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * it. So, it is the internal networks responsibility to make sure there are no
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * active calls when it releases the trunk and destroys the network. The
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * netfilter assists in this by providing INTNETTRUNKIFPORT::pfnSetState and
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * INTNETTRUNKIFPORT::pfnWaitForIdle. The trunk state is used to enable/disable
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * promiscuous mode on the hardware NIC (or similar activation) as well
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * indicating that disconnect is imminent and no further calls shall be made
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * into the internal network. After changing the state to disconnecting and
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * prior to invoking INTNETTRUNKIFPORT::pfnDisconnectAndRelease, the internal
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * network will use INTNETTRUNKIFPORT::pfnWaitForIdle to wait for any still
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * active calls to complete.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The netfilter employs a busy counter and an internal state in addition to the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * public trunk state. All these variables are protected using a spinlock.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * @section sec_netflt_msc Locking / Sequence Diagrams - OBSOLETE
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * !OBSOLETE! - THIS WAS THE OLD APPROACH!
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * This secion contains a few sequence diagrams describing the problematic
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * transitions of a host interface filter instance.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The thing that makes it all a bit problematic is that multiple events may
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * happen at the same time, and that we have to be very careful to avoid
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * deadlocks caused by mixing our locks with the ones in the host kernel. The
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * main events are receive, send, async send completion, disappearance of the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * host networking interface and its reappearance. The latter two events are
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * can be caused by driver unloading/loading or the device being physical
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * unplugged (e.g. a USB network device).
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The strategy for dealing with these issues are:
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Use a simple state machine.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Require the user (IntNet) to serialize all its calls to us,
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * while at the same time not owning any lock used by any of the
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * the callbacks we might call on receive and async send completion.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Make sure we're 100% idle before disconnecting, and have a
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * disconnected status on both sides to fend off async calls.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * - Protect the host specific interface handle and the state variables
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * using a spinlock.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * @subsection subsec_netflt_msc_dis_rel Disconnect from the network and release - OBSOLETE
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VM, IntNet, NetFlt, Kernel, Wire;
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VM->IntNet [label="pkt0", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Lock Network", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Route packet -> wire", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Unlock Network", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>NetFlt [label="pkt0 to wire", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>Kernel [label="pkt0 to wire", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Kernel->Wire [label="pkt0 to wire", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * --- [label="Suspending the trunk interface"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Lock Network"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Wire->Kernel [label="pkt1 - racing us", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Kernel=>>NetFlt [label="pkt1 - racing us", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>>IntNet [label="pkt1 recv - blocks", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Mark Trunk Suspended"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Unlock Network"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>NetFlt [label="pfnSetActive(false)"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>NetFlt [label="Mark inactive (atomic)"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet<<NetFlt;
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>NetFlt [label="pfnWaitForIdle(forever)"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>>NetFlt [label="pkt1 to host", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>>Kernel [label="pkt1 to host", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Kernel<-Wire [label="pkt0 on wire", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt<<Kernel [label="pkt0 on wire", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet<<=NetFlt [label="pfnSGRelease", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet<<=IntNet [label="Lock Net, free SG, Unlock Net", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet>>NetFlt [label="pfnSGRelease", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt<-NetFlt [label="idle", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet<<NetFlt [label="idle (pfnWaitForIdle)"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Wire->Kernel [label="pkt2", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * Kernel=>>NetFlt [label="pkt2", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>>Kernel [label="pkt2 to host", linecolor="red", textcolor="red"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VM->IntNet [label="pkt3", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Lock Network", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Route packet -> drop", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Unlock Network", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * --- [label="The trunk interface is idle now, disconnect it"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Lock Network"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Unlink Trunk"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Unlock Network"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>NetFlt [label="pfnDisconnectAndRelease"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>Kernel [label="iflt_detach"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt<<=Kernel [label="iff_detached"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt>>Kernel [label="iff_detached"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt<<Kernel [label="iflt_detach"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * NetFlt=>NetFlt [label="Release"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet<<NetFlt [label="pfnDisconnectAndRelease"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * @subsection subsec_netflt_msc_hif_rm Host Interface Removal - OBSOLETE
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * The ifnet_t (pIf) is a tricky customer as any reference to it can potentially
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * race the filter detaching. The simple way of solving it on Darwin is to guard
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * all access to the pIf member with a spinlock. The other host systems will
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * probably have similar race conditions, so the spinlock is a generic thing.
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VM, IntNet, NetFlt, Kernel;
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * VM->IntNet [label="pkt0", linecolor="green", textcolor="green"];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Lock Network", linecolor="green", textcolor="green" ];
a180a41bba1d50822df23fff0099e90b86638b89vboxsync * IntNet=>IntNet [label="Route packet -> wire", linecolor="green", textcolor="green" ];
* NetFlt=>NetFlt [label="!pIf || fRediscoveryPending (w/ spinlock)", linecolor="red", textcolor="red"];
#include "VBoxNetFltInternal.h"
static PVBOXNETFLTINS vboxNetFltFindInstanceLocked(PVBOXNETFLTGLOBALS pGlobals, const char *pszName)
return pCur;
return NULL;
return pRet;
bool fRediscovered;
bool fDoIt;
if (fDoIt)
if (fDoIt)
if (fRediscovered)
return fRediscovered;
static DECLCALLBACK(int) vboxNetFltPortXmit(PINTNETTRUNKIFPORT pIfPort, void *pvIfData, PINTNETSG pSG, uint32_t fDst)
return rc;
int rc;
return rc;
static DECLCALLBACK(INTNETTRUNKIFSTATE) vboxNetFltPortSetState(PINTNETTRUNKIFPORT pIfPort, INTNETTRUNKIFSTATE enmState)
AssertReturn(vboxNetFltGetState(pThis) == kVBoxNetFltInsState_Connected, INTNETTRUNKIFSTATE_INVALID);
return enmOldTrunkState;
static DECLCALLBACK(void) vboxNetFltPortNotifyMacAddress(PINTNETTRUNKIFPORT pIfPort, void *pvIfData, PCRTMAC pMac)
static DECLCALLBACK(int) vboxNetFltPortConnectInterface(PINTNETTRUNKIFPORT pIfPort, void *pvIf, void **ppvIfData)
int rc;
return rc;
static DECLCALLBACK(void) vboxNetFltPortDisconnectInterface(PINTNETTRUNKIFPORT pIfPort, void *pvIfData)
int rc;
#ifdef VBOXNETFLT_STATIC_CONFIG
int rc;
#ifdef VBOXNETFLT_STATIC_CONFIG
if (fBusy)
if (!cRefs)
if (!cRefs)
if (fBusy)
bool fRc;
if (fRc)
return fRc;
bool fRc;
if (fRc)
return fRc;
static int vboxNetFltConnectIt(PVBOXNETFLTINS pThis, PINTNETTRUNKSWPORT pSwitchPort, PINTNETTRUNKIFPORT *ppIfPort)
int rc;
#ifdef VBOXNETFLT_STATIC_CONFIG
return rc;
static int vboxNetFltNewInstance(PVBOXNETFLTGLOBALS pGlobals, const char *pszName, PINTNETTRUNKSWPORT pSwitchPort,
int rc;
if (!pNew)
return VERR_INTNET_FLT_IF_FAILED;
#ifdef VBOXNETFLT_STATIC_CONFIG
#ifdef VBOXNETFLT_STATIC_CONFIG
return rc;
return rc;
return rc;
#ifdef VBOXNETFLT_STATIC_CONFIG
DECLHIDDEN(int) vboxNetFltSearchCreateInstance(PVBOXNETFLTGLOBALS pGlobals, const char *pszName, PVBOXNETFLTINS *ppInstance, void *pvContext)
int rc;
while (pCur)
switch (enmState)
return VINF_ALREADY_INITIALIZED;
LogRel(("VBoxNetFlt: Huh? An instance of '%s' already exists! [pCur=%p cRefs=%d fDfH=%RTbool enmState=%d]\n",
return VERR_INTNET_FLT_IF_BUSY;
# ifdef RT_STRICT
return rc;
static DECLCALLBACK(int) vboxNetFltFactoryCreateAndConnect(PINTNETTRUNKFACTORY pIfFactory, const char *pszName,
PVBOXNETFLTGLOBALS pGlobals = (PVBOXNETFLTGLOBALS)((uint8_t *)pIfFactory - RT_OFFSETOF(VBOXNETFLTGLOBALS, TrunkFactory));
int rc;
LogFlow(("vboxNetFltFactoryCreateAndConnect: pszName=%p:{%s} fFlags=%#x\n", pszName, pszName, fFlags));
if (pCur)
#ifdef VBOXNETFLT_STATIC_CONFIG
if (pCur)
return rc;
#ifdef VBOXNETFLT_STATIC_CONFIG
NULL,
ppIfPort);
return rc;
PVBOXNETFLTGLOBALS pGlobals = (PVBOXNETFLTGLOBALS)((uint8_t *)pIfFactory - RT_OFFSETOF(VBOXNETFLTGLOBALS, TrunkFactory));
static DECLCALLBACK(void *) vboxNetFltQueryFactoryInterface(PCSUPDRVFACTORY pSupDrvFactory, PSUPDRVSESSION pSession, const char *pszInterfaceUuid)
PVBOXNETFLTGLOBALS pGlobals = (PVBOXNETFLTGLOBALS)((uint8_t *)pSupDrvFactory - RT_OFFSETOF(VBOXNETFLTGLOBALS, SupDrvFactory));
#ifdef LOG_ENABLED
return NULL;
return fRc;
int rc;
return VERR_WRONG_ORDER;
return VERR_WRONG_ORDER;
return rc;
int rc;
rc = SUPR0IdcOpen(&pGlobals->SupDrvIDC, 0 /* iReqVersion = default */, 0 /* iMinVersion = default */, NULL, NULL, NULL);
return rc;
return rc;
return rc;
return rc;
return rc;
return rc;
return rc;