b30152d4baa2b518626ab770369468a87b41ccaa
[openvswitch] / INSTALL.bridge
1               Replacing a Linux Bridge with Open vSwitch
2               ==========================================
3
4 This file documents how Open vSwitch may be used as a drop-in
5 replacement for a Linux kernel bridge in an environment that includes
6 elements that are tightly tied to the Linux bridge tools
7 (e.g. "brctl") and architecture.  We recommend directly using the
8 management tools provided with Open vSwitch rather than these
9 compatibility hooks for environments that are not tightly tied to the
10 Linux bridging tools; they are more efficient and better reflect the
11 actual operation and status.
12
13
14 Installation Procedure
15 ----------------------
16
17 The procedure below explains how to use the Open vSwitch bridge
18 compatibility support.  This procedure is written from the perspective
19 of a system administrator manually loading and starting Open vSwitch
20 in bridge compatibility mode, but of course in practice one would want
21 to update system scripts to follow these steps.
22
23 1. Build and install the Open vSwitch kernel modules and userspace
24    programs as described in INSTALL.Linux.
25
26    It is important to run "make install", because some Open vSwitch
27    programs expect to find files in locations selected at installation
28    time.
29
30 2. Load both the openvswitch and brcompat kernel modules (which were
31    built in step 1), e.g.:
32
33       % insmod datapath/linux-2.6/openvswitch_mod.ko
34       % insmod datapath/linux-2.6/brcompat_mod.ko
35
36    These kernel modules cannot be loaded if the Linux bridge module is
37    already loaded.  Thus, you may need to remove any existing bridges
38    and unload the bridge module with "rmmod bridge" before you can do
39    this.  In addition, if you edit your system configuration files to
40    load these modules at boot time, it should happen before any bridge
41    configuration (e.g. before any calls to "brctl" or "ifup" of any
42    bridge interfaces), to ensure that the Open vSwitch kernel modules
43    are loaded before the Linux kernel bridge module.
44
45 3. Create an initial version of the configuration file, for example
46    /etc/ovs-vswitchd.conf.  This file may be empty initially or may
47    contain add any valid configuration directives described in
48    ovs-vswitchd.conf(5).  However, it must exist when you start
49    ovs-vswitchd.
50
51    To create an empty configuration file:
52
53       % touch /etc/ovs-vswitchd.conf
54
55 4. Start ovs-vswitchd and ovs-brcompatd, e.g.:
56
57       % ovs-vswitchd --pidfile --detach -vANY:console:EMER \
58                 /etc/ovs-vswitchd.conf
59
60       % ovs-brcompatd --pidfile --detach -vANY:console:EMER \
61                 /etc/ovs-vswitchd.conf
62
63 5. Now you should be able to manage the Open vSwitch using brctl and
64    related tools.  For example, you can create an Open vSwitch bridge,
65    add interfaces to it, then print information about bridges with the
66    commands:
67
68       % brctl addbr br0
69       % brctl addif br0 eth0
70       % brctl addif br0 eth1
71       % brctl show
72
73    Each of these commands actually uses or modifies the Open vSwitch
74    configuration file, then notifies the ovs-vswitchd daemon of the
75    change.  For example, after executing the commands above starting
76    from an empty configuration file, "cat /etc/ovs-vswitchd.conf"
77    should show that the configuration file now contains the following:
78
79       bridge.br0.port=br0
80       bridge.br0.port=eth0
81       bridge.br0.port=eth1