vimage (9)

Leading comments

-
 Copyright (c) 2010 The FreeBSD Foundation
 All rights reserved.

 This documentation was written by CK Software GmbH under sponsorship from
 the FreeBSD Foundation.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce...

(The comments found at the beginning of the groff file "man9/vimage.9freebsd".)

NAME

VNET - network subsystem virtualization infrastructure

SYNOPSIS

options VIMAGE options VNET_DEBUG

In sys/vnet.h

Constants and Global Variables

VNET_SETNAME VNET_SYMPREFIX Vt extern struct vnet *vnet0;

Variable Declaration

Fo VNET Fa name Fc Fo VNET_NAME Fa name Fc Fo VNET_DECLARE Fa type name Fc Fo VNET_DEFINE Fa type name Fc

#define V_name  VNET(name)

Virtual Instance Selection

Fo CRED_TO_VNET Fa struct ucred * Fc Fo TD_TO_VNET Fa struct thread * Fc Fo P_TO_VNET Fa struct proc * Fc Fo IS_DEFAULT_VNET Fa struct vnet * Fc Fo VNET_ASSERT Fa exp msg Fc Fo CURVNET_SET Fa struct vnet * Fc Fo CURVNET_SET_QUIET Fa struct vnet * Fc Fn CURVNET_RESTORE Fo VNET_ITERATOR_DECL Fa struct vnet * Fc Fo VNET_FOREACH Fa struct vnet * Fc

Locking

Fn VNET_LIST_RLOCK Fn VNET_LIST_RUNLOCK Fn VNET_LIST_RLOCK_NOSLEEP Fn VNET_LIST_RUNLOCK_NOSLEEP

Startup and Teardown Functions

Ft struct vnet * Fo vnet_alloc Fa void Fc Ft void Fo vnet_destroy Fa struct vnet * Fc Fo VNET_SYSINIT Fa ident Fa enum sysinit_sub_id subsystem Fa enum sysinit_elem_order order Fa sysinit_cfunc_t func Fa const void *arg Fc Fo VNET_SYSUNINIT Fa ident Fa enum sysinit_sub_id subsystem Fa enum sysinit_elem_order order Fa sysinit_cfunc_t func Fa const void *arg Fc

Eventhandlers

Fo VNET_GLOBAL_EVENTHANDLER_REGISTER Fa const char *name Fa void *func Fa void *arg Fa int priority Fc Fo VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG Fa eventhandler_tag tag Fa const char *name Fa void *func Fa void *arg Fa int priority Fc

Sysctl Handling

Fo SYSCTL_VNET_INT Fa parent nbr name access ptr val descr Fc Fo SYSCTL_VNET_PROC Fa parent nbr name access ptr arg handler fmt descr Fc Fo SYSCTL_VNET_STRING Fa parent nbr name access arg len descr Fc Fo SYSCTL_VNET_STRUCT Fa parent nbr name access ptr type descr Fc Fo SYSCTL_VNET_UINT Fa parent nbr name access ptr val descr Fc Fo VNET_SYSCTL_ARG Fa req arg1 Fc

DESCRIPTION

is the name of a technique to virtualize the network stack. The basic idea is to change global resources most notably variables into per network stack resources and have functions, sysctls, eventhandlers, etc. access and handle them in the context of the correct instance. Each (virtual) network stack is attached to a prison with Vt vnet0 being the unrestricted default network stack of the base system.

The global defines for VNET_SETNAME and VNET_SYMPREFIX are shared with kvm(3) to access internals for debugging reasons.

Variable Declaration

Variables are virtualized by using the Fn VNET_DEFINE macro rather than writing them out as type name One can still use static initialization or storage class specifiers, e.g.,

static VNET_DEFINE(int, foo) = 1;

or

static VNET_DEFINE(SLIST_HEAD(, bar), bars);

Static initialization is not possible when the virtualized variable would need to be referenced, e.g., with ``TAILQ_HEAD_INITIALIZER()'' In that case a Fn VNET_SYSINIT based initialization function must be used.

External variables have to be declared using the Fn VNET_DECLARE macro. In either case the convention is to define another macro, that is then used throughout the implementation to access that variable. The variable name is usually prefixed by V_ to express that it is virtualized. The Fn VNET macro will then translate accesses to that variable to the copy of the currently selected instance (see the Sx Virtual instance selection section):

#define        V_name  VNET(name)

NOTE: Do not confuse this with the convention used by
VFS(9).

The Fn VNET_NAME macro returns the offset within the memory region of the virtual network stack instance. It is usually only used with Fn SYSCTL_VNET_* macros.

Virtual Instance Selection

There are three different places where the current virtual network stack pointer is stored and can be taken from:

1. a prison

   "(struct prison *)->pr_vnet"

   For convenience the following macros are provided:

   Fn CRED_TO_VNET struct ucred *
   Fn TD_TO_VNET struct thread *
   Fn P_TO_VNET struct proc *
   

2. a socket

   "(struct socket *)->so_vnet"

3. an interface

   "(struct ifnet *)->if_vnet"

In addition the currently active instance is cached in ``curthread->td_vnet'' which is usually only accessed through the curvnet macro.

To set the correct context of the current virtual network instance, use the Fn CURVNET_SET or Fn CURVNET_SET_QUIET macros. The Fn CURVNET_SET_QUIET version will not record vnet recursions in case the kernel was compiled with options VNET_DEBUG and should thus only be used in well known cases, where recursion is unavoidable. Both macros will save the previous state on the stack and it must be restored with the Fn CURVNET_RESTORE macro.

NOTE: As the previous state is saved on the stack, you cannot have multiple Fn CURVNET_SET calls in the same block.

NOTE: As the previous state is saved on the stack, a Fn CURVNET_RESTORE call has to be in the same block as the Fn CURVNET_SET call or in a subblock with the same idea of the saved instances as the outer block.

NOTE: As each macro is a set of operations and, as previously explained, cannot be put into its own block when defined, one cannot conditionally set the current vnet context. The following will not work:

if (condition)
        CURVNET_SET(vnet);

nor would this work:

if (condition) {
        CURVNET_SET(vnet);
}
CURVNET_RESTORE();

Sometimes one needs to loop over all virtual instances, for example to update virtual from global state, to run a function from a callout(9) for each instance, etc. For those cases the Fn VNET_ITERATOR_DECL and Fn VNET_FOREACH macros are provided. The former macro defines the variable that iterates over the loop, and the latter loops over all of the virtual network stack instances. See Sx Locking for how to savely traverse the list of all virtual instances.

The Fn IS_DEFAULT_VNET macro provides a safe way to check whether the currently active instance is the unrestricted default network stack of the base system (Vt vnet0 )

The Fn VNET_ASSERT macro provides a way to conditionally add assertions that are only active with options VIMAGE compiled in and either options VNET_DEBUG or options INVARIANTS enabled as well. It uses the same semantics as KASSERT(9).

Locking

For public access to the list of virtual network stack instances e.g., by the Fn VNET_FOREACH macro, read locks are provided. Macros are used to abstract from the actual type of the locks. If a caller may sleep while traversing the list, it must use the Fn VNET_LIST_RLOCK and Fn VNET_LIST_RUNLOCK macros. Otherwise, the caller can use Fn VNET_LIST_RLOCK_NOSLEEP and Fn VNET_LIST_RUNLOCK_NOSLEEP .

Startup and Teardown Functions

To start or tear down a virtual network stack instance the internal functions Fn vnet_alloc and Fn vnet_destroy are provided and called from the jail framework. They run the publicly provided methods to handle network stack startup and teardown.

For public control, the system startup interface has been enhanced to not only handle a system boot but to also handle a virtual network stack startup and teardown. To the base system the Fn VNET_SYSINIT and Fn VNET_SYSUNINIT macros look exactly as if there were no virtual network stack. In fact, if options VIMAGE is not compiled in they are compiled to the standard Fn SYSINIT macros. In addition to that they are run for each virtual network stack when starting or, in reverse order, when shutting down.

Eventhandlers

Eventhandlers can be handled in two ways:

1. save the tags returned in each virtual instance and properly free the eventhandlers on teardown using those, or
2. use one eventhandler that will iterate over all virtual network stack instances.

For the first case one can just use the normal EVENTHANDLER(9) functions, while for the second case the Fn VNET_GLOBAL_EVENTHANDLER_REGISTER and Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG macros are provided. These differ in that Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG takes an extra first argument that will carry the Fa tag upon return. Eventhandlers registered with either of these will not run Fa func directly but Fa func will be called from an internal iterator function for each vnet. Both macros can only be used for eventhandlers that do not take additional arguments, as the variadic arguments from an EVENTHANDLER_INVOKE9 call will be ignored.

Sysctl Handling

A sysctl(9) can be virtualized by using one of the Fn SYSCTL_VNET_* macros.

They take the same arguments as the standard sysctl(9) functions, with the only difference, that the Fa ptr argument has to be passed as `&VNET_NAME(foo)' instead of `&foo' so that the variable can be selected from the correct memory region of the virtual network stack instance of the caller.

For the very rare case a sysctl handler function would want to handle Fa arg1 itself the Fn VNET_SYSCTL_ARG req arg1 is provided that will translate the Fa arg1 argument to the correct memory address in the virtual network stack context of the caller.

SEE ALSO

jail(2), kvm(3), EVENTHANDLER(9), KASSERT(9), sysctl(9)

HISTORY

The virtual network stack implementation first appeared in Fx 8.0 .

AUTHORS

This manual page was written by An Bjoern A. Zeeb, CK Software GmbH, under sponsorship from the FreeBSD Foundation.