new file mode 100644
@@ -0,0 +1,279 @@
+<manpage program="ovn-firstSteps" title="OVN first steps">
+<h1>OVN - first steps</h1>
+
+<p>This tutorial is intended to help the user to set up a working OVN environment></p>
+
+<h2>Build OVN rpm's</h2>
+
+
+<p>Clone the repository:</p>
+<p><code>git clone https://github.com/openvswitch/ovs</code></p>
+
+<p>
+Install the following packages, they are need to build ovn:</p>
+<p><code>dnf -y install gcc make python-devel openssl-devel kernel-devel graphviz kernel-debug-devel autoconf automake rpm-build redhat-rpm-config rpm-build rpmdevtools bash-completion autoconf automake libtool PyQt4 groff libcap-ng-devel python-twisted-core python-zope-interface graphviz openssl-devel selinux-policy-devel</code></p>
+
+<p>Build the ovn rpms:</p>
+<p><code>cd ovs</code></p>
+<p><code>./boot.sh</code></p>
+<p><code>./configure</code></p>
+<p><code>make dist</code></p>
+<p><code>cp openvswitch-<version>.tar.gz $HOME/rpmbuild/SOURCES</code></p>
+<p><code>cd $HOME/rpmbuild/SOURCES</code></p>
+<p><code>tar xzf openvswitch-<version>.tar.gz</code></p>
+<p><code>cd openvswitch-<version></code></p>
+<p><code>rpmbuild -bb rhel/openvswitch-fedora.spec # or whichever distro you are running</code></p>
+
+<p>The built rpm's will reside here: <code>/root/rpmbuild/RPMS/x86_64/</code></p>
+
+
+<h2>Prepare environment</h2>
+
+Prepare 3 hosts (vm's). All hosts must have a nic connected to the same network.
+The first host will be the central server, used to host north db, south db and
+north deamon.
+The two other hosts will be used to host the ovn controllers.
+
+<pre>
+
+ CENTRAL (ovn-nb, ovn-sb, northd)
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ / \
+ HOST1 (ovn-controller) HOST2 (ovn-controller)
+</pre>
+
+<p>Addressing scheme used in this tutorial:</p>
+<p> CENTRAL - 192.168.124.9</p>
+<p> HOST1 - 192.168.124.10 hostname: f10</p>
+<p> HOST2 - 192.168.124.11 hostname: f11</p>
+
+<h3>Central server installation</h3>
+
+<p>Install the following rpms:</p>
+<p><code>dnf -y install openvswitch openvswitch-ovn-common openvswitch-ovn-central</code></p>
+
+
+<p>Create the north db:</p>
+ <p><code>ovsdb-tool create /etc/openvswitch/ovnnb.db /usr/share/openvswitch/ovn-nb.ovsschema</code></p>
+<p>Create the south db:</p>
+ <p><code>ovsdb-tool create /etc/openvswitch/ovnsb.db /usr/share/openvswitch/ovn-sb.ovsschema</code></p>
+
+<p>Start db:</p>
+<p><code>/usr/share/openvswitch/scripts/ovn-ctl start_ovsdb --db-nb-file=/etc/openvswitch/ovnnb.db --db-sb-file=/etc/openvswitch/ovnsb.db</code></p>
+
+<p>Start north deamon:</p>
+<p><code>/usr/share/openvswitch/scripts/ovn-ctl start_northd --db-nb-file=/etc/openvswitch/ovnnb.db --db-sb-file=/etc/openvswitch/ovnsb.db</code></p>
+
+
+
+
+
+<h3>Host installation</h3>
+
+<p>Install the following rpms:</p>
+<p><code>dnf -y install openvswitch openvswitch-ovn-common openvswitch-ovn-host</code></p>
+
+<p>Start openvswitch:</p>
+<p><code>systemctl start openvswitch</code></p>
+
+<p>Configure HOST1:</p>
+<p><code>ovs-vsctl set open . external-ids:ovn-remote=tcp:192.168.124.9:6642</code></p>
+<p><code>ovs-vsctl set open . external-ids:ovn-encap-type=geneve</code></p>
+<p><code>ovs-vsctl set open . external-ids:ovn-encap-ip=192.168.124.10</code></p>
+
+<p>Configure HOST2:</p>
+<p><code>ovs-vsctl set open . external-ids:ovn-remote=tcp:192.168.124.9:6642</code></p>
+<p><code>ovs-vsctl set open . external-ids:ovn-encap-type=geneve</code></p>
+<p><code>ovs-vsctl set open . external-ids:ovn-encap-ip=192.168.124.11</code></p>
+
+<p>Start ovn controller on both hosts:</p>
+<p><code>/usr/share/openvswitch/scripts/ovn-ctl start_controller</code></p>
+
+
+
+<h2>Prepare virtual interfaces on hosts:</h2>
+
+<p>Add veth pairs on the hosts.</p>
+
+<p><code>ip link add vethouter type veth peer name vethint</code></p>
+<p>vethint will be the interface added to ovs switch, while vethouter will be the outer interface we will use to communicate through.</p>
+
+<p>When successful, you should see the following output to <code>ip link</code>:</p>
+
+<p>HOST1:</p>
+<p><code><pre>
+3: vethint@vethouter: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master ovs-system state UP mode DEFAULT group default qlen 1000
+ link/ether be:34:f3:dd:e9:21 brd ff:ff:ff:ff:ff:ff
+4: vethouter@vethint: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+ link/ether ea:d1:6a:a3:ac:c9 brd ff:ff:ff:ff:ff:ff
+</pre></code></p>
+
+<p>HOST2:</p>
+<p><code><pre>
+4: vethint@vethouter: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master ovs-system state UP mode DEFAULT group default qlen 1000
+ link/ether 62:1c:0e:98:6f:58 brd ff:ff:ff:ff:ff:ff
+5: vethouter@vethint: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
+ link/ether ea:99:ae:00:dd:c3 brd ff:ff:ff:ff:ff:ff
+</pre></code></p>
+
+<h2>Create ovn connections</h2>
+
+<h3>Add logical switch and ports to north db</h3>
+<p>Add a logical switch:</p>
+<p><code>ovn-nbctl ls-add net1</code></p>
+
+<p>Add HOST1 port:</p>
+<p>Add a logical port vnic10.</p>
+<p><code>ovn-nbctl lsp-add net1 vnic10</code></p>
+<p>Set the mac address of the logical port. This will be the mac address of vethouter - the interface we will use to communicate.</p>
+<p><code>ovn-nbctl lsp-set-addresses vnic10 ea:d1:6a:a3:ac:c9</code></p>
+
+<p>Add HOST2 port:</p>
+<p>Add a logical port vnic11.</p>
+<p><code>ovn-nbctl lsp-add net1 vnic11</code></p>
+<p>Set the mac address of the logical port. This will be the mac address of vethouter - the interface we will use to communicate.</p>
+<p><code>ovn-nbctl lsp-set-addresses vnic11 ea:99:ae:00:dd:c3</code></p>
+
+<p>Check the north db:</p>
+<p><code>ovn-nbctl show</code></p>
+<p>The result should be:</p>
+<p><code><pre>
+ switch 596bb991-530a-43c9-9c0e-9bb1aa0e6337 (net1)
+ port vnic10
+ addresses: ["ea:d1:6a:a3:ac:c9"]
+ port vnic11
+ addresses: ["ea:99:ae:00:dd:c3"]
+</pre></code></p>
+
+<h3>Add ports to the ovs switch on hosts</h3>
+
+
+<p>Add a bridge on each of the hosts (in one does not exist yet)</p>
+<p><code>ovs-vsctl add-br br-int</code></p>
+
+<p>HOST1:</p>
+<p>Add the vethint interface to the bridge. Set an external id 'iface-id' pointing to the logical port defined in north db.</p>
+<p><code>ovs-vsctl add-port br-int vethint -- set Interface vethint external_ids:iface-id=vnic10</code></p>
+
+<p>HOST2:</p>
+<p>Add the vethint interface to the bridge. Set an external id 'iface-id' pointing to the logical port defined in north db.</p>
+<p><code>ovs-vsctl add-port br-int vethint -- set Interface vethint external_ids:iface-id=vnic11</code></p>
+
+<p>Check the south db:</p>
+<p><code>ovn-sbctl show</code></p>
+<p>The result should be:</p>
+<p><code><pre>
+Chassis "429390cf-3b71-4702-b77c-88d8431e2445"
+ hostname: "f11"
+ Encap geneve
+ ip: "192.168.124.11"
+ Port_Binding "veth11"
+Chassis "ed831e8f-a429-4f05-9a15-06bf0ed1e43b"
+ hostname: "f10"
+ Encap geneve
+ ip: "192.168.124.10"
+ Port_Binding "veth10"
+</pre></code></p>
+
+<h3>Configure the outer parts of the veth pairs</h3>
+
+<p>Configure the IP addresses on the outer ends of the veth pairs on each host</p>
+<p>HOST1:</p>
+<p><code>ip addr add 192.168.125.10/24 dev vethouter</code></p>
+
+<p>HOST2:</p>
+<p><code>ip addr add 192.168.125.11/24 dev vethouter</code></p>
+
+<h2>Test the connections</h2>
+
+<p>On HOST1:</p>
+<p><code>ping 192.168.125.11</code></p>
+
+<p>On HOST2:</p>
+<p><code>ping 192.168.125.10</code></p>
+
+<h2>Some interesting items to check</h2>
+
+<p>Check the ovs switch on each host:</p>
+<p><code>ovs-vsctl show</code></p>
+<p><code><pre>
+ae79f36e-d61e-4e83-baeb-4553e5ba4eeb
+ Bridge br-int
+ Port br-int
+ Interface br-int
+ type: internal
+ Port vethint
+ Interface vethint
+ Port "ovn-429390-0"
+ Interface "ovn-429390-0"
+ type: geneve
+ options: {key=flow, remote_ip="192.168.124.11"}
+ ovs_version: "2.5.0"
+</pre></code></p>
+
+<br/>
+<p>Check the open flow ports of br-int on each host:</p>
+<p><code>ovs-ofctl show br-int</code></p>
+<p>The result should be:</p>
+<p><code><pre>
+OFPT_FEATURES_REPLY (xid=0x2): dpid:00004a5981399148
+n_tables:254, n_buffers:256
+capabilities: FLOW_STATS TABLE_STATS PORT_STATS QUEUE_STATS ARP_MATCH_IP
+actions: output enqueue set_vlan_vid set_vlan_pcp strip_vlan mod_dl_src mod_dl_dst mod_nw_src mod_nw_dst mod_nw_tos mod_tp_src mod_tp_dst
+ 18(vethint): addr:be:34:f3:dd:e9:21
+ config: 0
+ state: 0
+ current: 10GB-FD COPPER
+ speed: 10000 Mbps now, 0 Mbps max
+ 20(ovn-429390-0): addr:12:cf:f3:85:18:92
+ config: 0
+ state: 0
+ speed: 0 Mbps now, 0 Mbps max
+ LOCAL(br-int): addr:4a:59:81:39:91:48
+ config: 0
+ state: 0
+ speed: 0 Mbps now, 0 Mbps max
+OFPT_GET_CONFIG_REPLY (xid=0x4): frags=normal miss_send_len=0
+</pre></code></p>
+
+<br/>
+<p>Check the open flow rules for br-int on each host:</p>
+<p><code>ovs-ofctl dump-flows br-int</code></p>
+<p>The result should be:</p>
+<p><code><pre>
+NXST_FLOW reply (xid=0x4):
+ cookie=0x0, duration=347222.160s, table=0, n_packets=1013, n_bytes=89066, idle_age=71, hard_age=65534, priority=100,in_port=18 actions=load:0x1->NXM_NX_REG5[],load:0x1->OXM_OF_METADATA[],load:0x5->NXM_NX_REG6[],resubmit(,16)
+ cookie=0x0, duration=347222.160s, table=0, n_packets=723, n_bytes=68082, idle_age=71, hard_age=65534, priority=100,in_port=20 actions=move:NXM_NX_TUN_ID[0..23]->OXM_OF_METADATA[0..23],move:NXM_NX_TUN_METADATA0[16..30]->NXM_NX_REG6[0..14],move:NXM_NX_TUN_METADATA0[0..15]->NXM_NX_REG7[0..15],resubmit(,33)
+ cookie=0x0, duration=347222.160s, table=16, n_packets=0, n_bytes=0, idle_age=65534, hard_age=65534, priority=100,metadata=0x1,vlan_tci=0x1000/0x1000 actions=drop
+ cookie=0x0, duration=347222.160s, table=16, n_packets=0, n_bytes=0, idle_age=65534, hard_age=65534, priority=100,metadata=0x1,dl_src=01:00:00:00:00:00/01:00:00:00:00:00 actions=drop
+ ...
+
+</pre></code></p>
+
+<br/>
+<p>Trace the open-flow rules which are applied to incoming packages:</p>
+<p><code>ovs-appctl ofproto/trace br-int in_port=18,dl_dst=ea:99:ae:00:dd:c3</code></p>
+<p>The result should be:</p>
+<p><code><pre>
+Bridge: br-int
+Flow: in_port=18,vlan_tci=0x0000,dl_src=00:00:00:00:00:00,dl_dst=62:1c:0e:98:6f:58,dl_type=0x0000
+
+Rule: table=0 cookie=0 priority=100,in_port=18
+OpenFlow actions=set_field:0x1->reg5,set_field:0x1->metadata,set_field:0x5->reg6,resubmit(,16)
+
+ Resubmitted flow: reg5=0x1,reg6=0x5,metadata=0x1,in_port=18,vlan_tci=0x0000,dl_src=00:00:00:00:00:00,dl_dst=62:1c:0e:98:6f:58,dl_type=0x0000
+ Resubmitted regs: reg0=0x0 reg1=0x0 reg2=0x0 reg3=0x0 reg4=0x0 reg5=0x1 reg6=0x5 reg7=0x0
+ Resubmitted odp: drop
+ Resubmitted megaflow: recirc_id=0,reg5=0,reg6=0,metadata=0,in_port=18,vlan_tci=0x0000/0x1000,dl_src=00:00:00:00:00:00/01:00:00:00:00:00,dl_type=0x0000
+ Rule: table=16 cookie=0 priority=50,reg6=0x5,metadata=0x1
+ OpenFlow actions=resubmit(,17)
+
+ ...
+</pre></code></p>
+</manpage>