]>
Commit | Line | Data |
---|---|---|
064af421 BP |
1 | README.Debian for openvswitch-switch |
2 | --------------------------------- | |
3 | ||
f085ba1e BP |
4 | To use the Linux kernel-based switch implementation, you will need an |
5 | Open vSwitch kernel module. There are multiple ways to obtain one. | |
6 | In order of increasing manual effort, these are: | |
064af421 | 7 | |
f085ba1e BP |
8 | * Use a Linux kernel 3.3 or later, which has an integrated Open |
9 | vSwitch kernel module. | |
10 | ||
11 | The upstream Linux kernel module lacks a few features that | |
12 | are in the third-party module. For details, please see the | |
13 | FAQ, "What features are not available in the Open vSwitch | |
14 | kernel datapath that ships as part of the upstream Linux | |
15 | kernel?". | |
16 | ||
17 | * Install the "openvswitch-datapath-dkms" Debian package that | |
18 | you built earlier. This should automatically build and | |
19 | install the Open vSwitch kernel module for your running | |
20 | kernel. | |
21 | ||
22 | This option requires that you have a compiler and toolchain | |
23 | installed on the machine where you run Open vSwitch, which | |
24 | may be unacceptable in some production server environments. | |
25 | ||
26 | * Install the "openvswitch-datapath-source" Debian package, use | |
27 | "module-assistant" to build a Debian package of the Open | |
28 | vSwitch kernel module for your kernel, and then install that | |
29 | Debian package. | |
30 | ||
31 | You can install the kernel module Debian packages that you | |
32 | build this way on the same machine where you built it or on | |
33 | another machine or machines, which means that you don't | |
34 | necessarily have to have any build infrastructure on the | |
35 | machines where you use the kernel module. | |
36 | ||
37 | /usr/share/doc/openvswitch-datapath-source/README.Debian has | |
38 | details on the build process. | |
39 | ||
40 | * Build and install the kernel module by hand. | |
064af421 | 41 | |
86b87c92 GS |
42 | |
43 | Debian network scripts integration | |
44 | ---------------------------------- | |
45 | This package lets a user to optionally configure Open vSwitch bridges | |
46 | and ports from /etc/network/interfaces. Please refer to the interfaces(5) | |
47 | manpage for more details regarding /etc/network/interfaces. | |
48 | ||
49 | The stanzas that configure the OVS bridges should begin with "allow-ovs" | |
50 | followed by name of the bridge. Here is an example. | |
51 | allow-ovs br0 | |
52 | ||
53 | The stanzas that configure the OVS ports should begin with | |
54 | "allow-${bridge-name}" followed by name of the port. Here is an example. | |
55 | allow-br0 eth0 | |
56 | ||
57 | The following OVS specific "command" options are supported: | |
58 | ||
5b245e73 GS |
59 | - ovs_type: This can either be OVSBridge, OVSPort, OVSIntPort, OVSBond, |
60 | OVSPatchPort or OVSTunnel depending on whether you configure a bridge, | |
61 | port, an internal port, a bond, a patch port or a tunnel. This is a | |
62 | required option. | |
86b87c92 GS |
63 | |
64 | - ovs_ports: This option specifies all the ports that belong to a bridge. | |
65 | ||
66 | - ovs_bridge: This options specifies a bridge to which a port belongs. | |
67 | This is a required option for a port. | |
68 | ||
69 | - ovs_bonds: This option specifies the list of physical interfaces to be | |
70 | bonded together. | |
71 | ||
5b245e73 GS |
72 | - ovs_patch_peer: For "OVSPatchPort" interfaces, this field specifies |
73 | the patch's peer on the other bridge. | |
74 | ||
364e0394 GS |
75 | - ovs_tunnel_type: For "OVSTunnel" interfaces, the type of the tunnel. |
76 | For example, "gre", "vxlan", etc. | |
77 | ||
78 | - ovs_tunnel_options: For "OVSTunnel" interfaces, this field should be | |
79 | used to specify the tunnel options like remote_ip, key, etc. | |
80 | ||
86b87c92 GS |
81 | - ovs_options: This option lets you add extra arguments to a ovs-vsctl |
82 | command. See examples. | |
83 | ||
84 | - ovs_extra: This option lets you run additional ovs-vsctl commands, | |
85 | separated by "--" (double dash). Variables can be part of the "ovs_extra" | |
86 | option. You can provide all the standard environmental variables | |
87 | described in the interfaces(5) man page. You can also pass shell | |
88 | commands. | |
89 | ||
90 | More implementation specific details can be seen in the examples. | |
91 | ||
92 | Examples: | |
93 | -------- | |
94 | ex 1: A standalone bridge. | |
95 | ||
96 | allow-ovs br0 | |
97 | iface br0 inet static | |
98 | address 192.168.1.1 | |
99 | netmask 255.255.255.0 | |
100 | ovs_type OVSBridge | |
101 | ||
102 | ex 2: A bridge with one port. | |
103 | ||
104 | allow-ovs br0 | |
105 | iface br0 inet dhcp | |
106 | ovs_type OVSBridge | |
107 | ovs_ports eth0 | |
108 | ||
109 | allow-br0 eth0 | |
110 | iface eth0 inet manual | |
111 | ovs_bridge br0 | |
112 | ovs_type OVSPort | |
113 | ||
114 | ex 3: A bridge with multiple physical ports. | |
115 | ||
116 | allow-ovs br0 | |
117 | iface br0 inet dhcp | |
118 | ovs_type OVSBridge | |
119 | ovs_ports eth0 eth1 | |
120 | ||
121 | allow-br0 eth0 | |
122 | iface eth0 inet manual | |
123 | ovs_bridge br0 | |
124 | ovs_type OVSPort | |
125 | ||
126 | allow-br0 eth1 | |
127 | iface eth1 inet manual | |
128 | ovs_bridge br0 | |
129 | ovs_type OVSPort | |
130 | ||
131 | ex 4: A bridge with an OVS internal port. | |
132 | ||
133 | allow-ovs br1 | |
134 | iface br1 inet static | |
135 | address 192.168.1.1 | |
136 | netmask 255.255.255.0 | |
137 | ovs_type OVSBridge | |
138 | ovs_ports vlan100 | |
139 | ||
140 | allow-br1 vlan100 | |
141 | iface vlan100 inet manual | |
142 | ovs_bridge br1 | |
143 | ovs_type OVSIntPort | |
144 | ovs_options tag=100 | |
145 | ovs_extra set interface ${IFACE} external-ids:iface-id=$(hostname -s) | |
146 | ||
147 | ex 5: Bonding. | |
148 | ||
149 | allow-ovs br2 | |
150 | iface br2 inet static | |
151 | address 192.170.1.1 | |
152 | netmask 255.255.255.0 | |
153 | ovs_type OVSBridge | |
154 | ovs_ports bond0 | |
155 | ||
156 | allow-br2 bond0 | |
157 | iface bond0 inet manual | |
158 | ovs_bridge br2 | |
159 | ovs_type OVSBond | |
160 | ovs_bonds eth2 eth3 | |
161 | ovs_options bond_mode=balance-tcp lacp=active | |
162 | ||
5b245e73 GS |
163 | ex 6: Patch ports. |
164 | ||
165 | allow-ovs br0 | |
166 | iface br0 inet manual | |
167 | ovs_type OVSBridge | |
168 | ovs_ports patch0 | |
169 | ||
170 | allow-br0 patch0 | |
171 | iface patch0 inet manual | |
172 | ovs_bridge br0 | |
173 | ovs_type OVSPatchPort | |
174 | ovs_patch_peer patch1 | |
175 | ||
176 | allow-ovs br1 | |
177 | iface br1 inet manual | |
178 | ovs_type OVSBridge | |
179 | ovs_ports patch1 | |
180 | ||
181 | allow-br1 patch1 | |
182 | iface patch1 inet manual | |
183 | ovs_bridge br1 | |
184 | ovs_type OVSPatchPort | |
185 | ovs_patch_peer patch0 | |
186 | ||
187 | ex 7: Tunnel. | |
364e0394 GS |
188 | |
189 | allow-ovs br1 | |
190 | iface br1 inet static | |
191 | address 192.168.1.1 | |
192 | netmask 255.255.255.0 | |
193 | ovs_type OVSBridge | |
194 | ovs_ports gre1 | |
195 | ||
196 | allow-br1 gre1 | |
197 | iface gre1 inet manual | |
198 | ovs_bridge br1 | |
199 | ovs_type OVSTunnel | |
200 | ovs_tunnel_type gre | |
201 | ovs_tunnel_options options:remote_ip=182.168.1.2 options:key=1 | |
202 | ||
5b245e73 | 203 | ex 8: Create and destroy bridges. |
86b87c92 GS |
204 | |
205 | ifup --allow=ovs $list_of_bridges | |
206 | ifdown --allow=ovs $list_of_bridges | |
9a8b5cc1 GS |
207 | |
208 | Notes on dependencies: | |
209 | --------------------- | |
210 | ||
211 | openvswitch-switch depends on $network, $named $remote_fs and $syslog to start. | |
212 | This creates some startup dependency issues. | |
213 | ||
214 | * Since openvswitch utilities are placed in /usr and /usr can be mounted | |
215 | through NFS, openvswitch has to start after it. But if a user uses openvswitch | |
216 | for all his networking needs and hence to mount NFS, there will be a deadlock. | |
217 | So, if /usr is mounted through NFS and openvswitch is used for all networking, | |
218 | the administrator should figure out a way to mount NFS before starting OVS. | |
219 | One way to do this is in initramfs. | |
220 | ||
221 | * Since openvswitch starts after $network, $remote_fs and $syslog, any startup | |
222 | script that depends on openvswitch but starts before it, needs to be changed | |
223 | to depend on openvswitch-switch too. | |
224 | ||
225 | * Ideally, an admin should not add openvswitch bridges in the 'auto' | |
e0dfd67b GS |
226 | section of the 'interfaces' file (i.e., if "br0" is a OVS bridge, you should |
227 | not have a line "auto br0"). This is because, when ifupdown starts | |
9a8b5cc1 GS |
228 | working on bridges listed in 'auto', openvswitch has not yet started. |
229 | ||
230 | But, if the admin wants to go down this route and adds openvswitch bridges | |
231 | in the 'auto' section, openvswitch-switch will forcefully be started when | |
232 | ifupdown kicks in. In a case like this, the admin needs to make sure that /usr | |
233 | has already been mounted and that a remote $syslog (if used) is ready to | |
234 | receive openvswitch logs. | |
e0dfd67b GS |
235 | |
236 | * With systemd, adding openvswitch bridges in the 'auto' section of the | |
237 | 'interfaces' file can cause race conditions (i.e., if "br0" is a OVS bridge, | |
238 | you should not have a line "auto br0"). Debian systems have added a | |
239 | systemd ifup@.service file. This file will call ifdown and ifup on interfaces | |
240 | in "auto" section automatically when the interfaces disappear and appear | |
241 | respectively. This will cause race conditions if you delete and add the same | |
242 | bridges using tools like "ovs-vsctl" or "ovs-dpctl". This is also a problem | |
243 | when you upgrade your openvswitch kernel module using commands like | |
244 | 'force-reload-kmod'. |