xenserver: Fix ip_gre_mod modprobe issue in init script
[sliver-openvswitch.git] / INSTALL.OpenFlow
1             Using Open vSwitch as a Simple OpenFlow Switch
2             ==============================================
3
4 Open vSwitch uses OpenFlow as its preferred method of remote flow
5 table configuration.  This is the simplest method of using it with an
6 OpenFlow controller.  The ovs-vsctl "set-controller" command will set
7 the controller for one or more bridges.  We recommend using OpenFlow
8 in this manner.
9
10 However, it is also possible to use Open vSwitch as a simple OpenFlow
11 switch like that provided by the OpenFlow reference implementation
12 [1].  The remainder of this file describes how to use it in that
13 manner.
14
15 What is OpenFlow?
16 -----------------
17
18 OpenFlow is a flow-based switch specification designed to enable
19 researchers to run experiments in live networks.  OpenFlow is based on a
20 simple Ethernet flow switch that exposes a standardized interface for
21 adding and removing flow entries.
22
23 An OpenFlow switch consists of three parts: (1) A "flow table" in
24 which each flow entry is associated with an action telling the switch
25 how to process the flow, (2) a "secure channel" that connects the switch
26 to a remote process (a controller), allowing commands and packets to
27 be sent between the controller and the switch, and (3) an OpenFlow
28 protocol implementation, providing an open and standard way for a
29 controller to talk to the switch.
30
31 An OpenFlow switch can thus serve as a simple datapath element that
32 forwards packets between ports according to flow actions defined by
33 the controller using OpenFlow commands.  Example actions are:
34
35     - Forward this flow's packets to the given port(s)
36     - Drop this flow's packets
37     - Encapsulate and forward this flow's packets to the controller.
38
39 The OpenFlow switch is defined in detail in the OpenFlow switch
40 Specification [2].
41
42 Installation Procedure
43 ----------------------
44
45 The procedure below explains how to use the Open vSwitch as a simple
46 OpenFlow switch. 
47
48 1. Build and install the Open vSwitch kernel modules and userspace
49    programs as described in INSTALL.Linux.
50
51    It is important to run "make install", because some Open vSwitch
52    programs expect to find files in locations selected at installation
53    time.
54
55 2. Load the openvswitch kernel module (which was built in step 1), e.g.:
56
57       % insmod datapath/linux-2.6/openvswitch_mod.ko
58
59    This kernel module cannot be loaded if the Linux bridge module is
60    already loaded.  Thus, you may need to remove any existing bridges
61    and unload the bridge module with "rmmod bridge" before you can do
62    this.
63
64 3. Create a datapath instance.  The command below creates a datapath
65    identified as dp0 (see ovs-dpctl(8) for more detailed usage
66    information).
67
68       # ovs-dpctl add-dp dp0
69    
70    Creating datapath dp0 creates a new network device, also named dp0.
71    This network device, called the datapath's "local port", will be
72    bridged to the physical switch ports by ovs-openflowd(8).  It is
73    optionally used for in-band control as described in step 5.
74
75 4. Use ovs-dpctl to attach the datapath to physical interfaces on the
76    machine.  Say, for example, you want to create a trivial 2-port
77    switch using interfaces eth1 and eth2, you would issue the following
78    commands:
79
80       # ovs-dpctl add-if dp0 eth1
81       # ovs-dpctl add-if dp0 eth2
82
83    You can verify that the interfaces were successfully added by asking
84    ovs-dpctl to print the current status of datapath dp0:
85
86       # ovs-dpctl show dp0
87
88 5. Arrange so that the switch can reach the controller over the network.  
89    This can be done in two ways.  The switch may be configured for 
90    out-of-band control, which means it uses a network separate from the 
91    data traffic that it controls.  Alternatively, the switch may be 
92    configured to contact the controller over one of the network devices 
93    under its control.  In-band control is often more convenient than 
94    out-of-band, because it is not necessary to maintain two independent 
95    networks.
96
97       - If you are using out-of-band control, at this point make sure
98         that the switch machine can reach the controller over the
99         network.
100
101       - If you are using in-band control, then at this point you must
102         configure the dp0 network device created in step 3.  This
103         device is not yet bridged to any physical network (because
104         ovs-openflowd does that, and it is not yet running), so the next
105         step depends on whether connectivity is required to configure
106         the device's IP address:
107
108            * If the switch has a static IP address, you may configure
109              its IP address now, e.g.:
110
111                 # ifconfig dp0 192.168.1.1
112
113            * If the switch does not have a static IP address, e.g. its
114              IP address is obtained dynamically via DHCP, then proceed
115              to the next step.  The DHCP client will not be able to 
116              contact the DHCP server until the secure channel has 
117              started.  The address will be obtained in step 7.
118
119       - If you are using in-band control with controller discovery, no
120         configuration is required at this point.  You may proceed to
121         the next step.
122
123 6. Run ovs-openflowd to start the secure channel connecting the datapath to
124    a remote controller.  If the controller is running on host
125    192.168.1.2 port 6633 (the default port), the ovs-openflowd invocation
126    would look like this:
127
128       # ovs-openflowd dp0 tcp:192.168.1.2
129
130    - If you are using in-band control with controller discovery, omit
131      the second argument to the ovs-openflowd command.
132
133    - If you are using out-of-band control, add --out-of-band to the
134      command line.
135
136    Using the "tcp:<controller_ip>" argument causes the switch to connect
137    in an insecure manner.  Please see INSTALL.SSL for a description of
138    how to connect securely using SSL.
139
140 7. If you are using in-band control with manual configuration, and the
141    switch obtains its IP address dynamically, then you may now obtain
142    the switch's IP address, e.g. by invoking a DHCP client.  The
143    secure channel will only be able to connect to the controller after
144    an IP address has been obtained.
145
146 8. The secure channel should connect to the controller within a few
147    seconds.  It may take a little longer if controller discovery is in
148    use, because the switch must then also obtain its own IP address
149    and the controller's location via DHCP.
150
151 References
152 ----------
153
154     [1] OpenFlow Reference Implementation.
155         <http://www.openflowswitch.org/wp/downloads/>
156
157     [2] OpenFlow Switch Specification.
158         <http://openflowswitch.org/documents/openflow-spec-latest.pdf>