#
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
# Copyright (c) 2006, 2015, Oracle and/or its affiliates. All rights reserved.
#
#ident	"@(#)README.Solaris	1.2	11/01/03 SMI"

		SOLARIS' OFFERING OF OPENSOURCE QUAGGA SOFTWARE
	       ************************************************
Quagga(version 0.99.4) in Solaris is comprised of the following packages:

SUNWquagga-daemons:
 - Provides the Quagga daemons and the quaggaadm utility. 
   The daemons installed by this package are:
   
   ripd, ripngd, ospfd, ospf6d, bgpd, and zebra(the routing manager daemon)
                    
   This package has dependencies on SUNWquaggar and SUNWquagga-libs

SUNWquaggar: 
 - Provides sample configuration files in /etc/quagga/, this README.Solaris
   file and SMF manifests for Quagga daemons.

SUNWquagga-libs:
 - Provides Quagga-specific dynamic libraries used by the Quagga daemons.

SUNWquagga-dev:
 - Provides header files, archive libraries and libtool files required for
   building code using the Quagga libraries. Note that these interfaces are
   External to Solaris and come without API stability guarantees. See also the
   attributes (7) manual page.
 
SUNWquaggaS

 - Provides the sources from which this release of the SUNWquagga packages
   were built. You may need to install either the Workshop compilers or gcc
   to compile the source.  In order to compile Quagga's vtysh utility, you
   will need Readline libraries, which are freely available on the web.


Location of Installed Files and Directories
===========================================

Modules of Quagga				Location
-------------------------------------------------------------
Sample configuration files			/etc/quagga
Daemon binaries(zebra,ospfd, ospf6d, ripd, 
                ripngd, bgpd)			/usr/sbin
quaggaadm (formerly zebraadm)			/usr/sbin
daemon start/stop scripts			/lib/svc/method 
SMF manifests					/lib/svc/manifest/network/routing
Quagga Info documentation			/usr/share/info
Manual Pages					/usr/share/man/man8
Libraries					/usr/lib
Development headers				/usr/include/quagga


Upgrading from SUNWzebra
========================

Previously, the Zebra routing protocol suite was delivered as part of the
SFW consolidation.  This has now been replaced with Quagga, and Zebra
routing configuration can be migrated easily, either explicitly by running
"routeadm -u" (see routeadm (8)), or by rebooting the system. The
appropriate configuration files for the daemons used will be migrated to
Quagga, and the equivalent Quagga SMF services will be enabled. 


Incompatibilities of Quagga  
============================

You may use in.routed(8) on other systems on your network, but you must not
run in.routed or in.rdisc on the same system that is configured to run
Quagga. Quagga is incompatible with the Solaris IP Multipathing
(in.mpathd(8)) feature.  Do not enable IPMP on a system running Quagga. If
you have a machine set up with IPMP and wish to run Quagga on it, please
unconfigure IPMP. See

IPMP details at:
Solaris 10 System Administrator Collection >>
	System Administration Guide: IP Services >>
		Part VI IP Network Multipathing (IPMP)  >>
			30. Administering IPMP (Task)) 


IFF_NORTEXCH Interface Flag Support
====================================

Currently Quagga is not aware of the IFF_NORTEXCH interface flag, so if
you're trying to fence off interfaces from the intrusion of unwanted routing
protocols, make sure you don't configure those interfaces in Quagga.


Support Level of Quagga Software
================================

The contents of SUNWquaggar, SUNWquagga-daemons are provided with full Level
1 support in accordance with your current software support agreement. This
support includes Sun's global 24/7 sustaining model.


Configuring a Multi-homed Host as a Router Using Quagga
==========================================================

Steps:
1. Create the appropriate  daemon configuration file in /etc/quagga.
   Sample configuration files have been provided in that directory.  

2.  Enable forwarding 
		routeadm -e ipv4-forwarding
		routeadm -u

    Disable IPMP if machine is set up with it. To do this, you will 
    have to undo all the things you had done to configure IPMP
    on your system. Please see :
	http://docs.sun.com
	Product Categories>> Solaris >> Solaris 10
	Solaris 10 System Administration Guide:IP services, Chapter 30

    for configurations details of IPMP.

3. Ensure that IPMP is disabled, and that the svc:/network/routing/route
   and svc:/network/routing/rdisc SMF services are disabled.

   Also it is important to note that each daemon is invoked with
   arguments to disable remote Telnet access to the daemons as it is a
   security risk. Please do not edit these configuration parameters that
   comprise part of the daemon-args property for each service.

   Pick the appropriate SMF service for the routing daemon that
   you wish to start. To enable a Quagga daemon service, type the following
   routeadm command:

  # routeadm -s routing-svcs="<routing daemon svc>" -e ipv4-routing -u
  
  or

  # svcadm enable <routing daemon svc>

  Example: To enable the ospfd daemon, type the command:

  # routeadm -s routing-svcs=ospf:quagga -e ipv4-routing -u

  To enable the ospf6d daemon, type the command:

  # routeadm -s routing-svcs=ospf6:quagga -e ipv6-routing -u


Editing the Daemon Arguments
----------------------------
You can change the arguments used to invoke the Quagga routing
daemons by modifying the service properties (listed by
running "routeadm -l <routing daemon svc>"). For example,
setting

   # routeadm -m ripng:quagga config_file=/path2/ripng.conf

sets an alternate configuration file.

Monitoring, Debugging and Reconfiguring Quagga Daemons Interactively
====================================================================

Quagga provides a Telnet UI so that the user can access the daemons in
real-time.  This interface is disabled by default for all daemons, but can
be enabled by changing the daemon-args property of Quagga services to a suitable
value, such as "-A 127.0.0.1":

  # routeadm -m ospf:quagga vty_address="127.0.0.1"

This user interface allows one to connect to each daemon, monitor the
daemon, tag debugging parameters, and reconfigure the parameters of the
running daemon. We have provided this facility with a wrapper utility called
quaggaadm (formerly zebraadm).

To access a particular daemon type
	/usr/sbin/quaggaadm zebra - to access a running zebra daemon
	/usr/sbin/quaggaadm ospfd - to access a running ospfd daemon
	/usr/sbin/quaggaadm ripd - to access a running ripd daemon
	/usr/sbin/quaggaadm bgpd - to access a running bgpd daemon

*****WARNING*****WARNING****WARNING********

By default, if the daemon-args are not set so as to restrict access, Quagga
allows a user to remotely access the daemons via the Telnet UI. We STRONGLY
RECOMMEND AGAINST remote Telnet access of the daemons, as it leaves the
system vulnerable to security holes. To avoid leaving your system
vulnerable, all daemons must be invoked with "-A 127.0.0.1" option, as shown
in the example above where routeadm is used to modify the 'daemon-args'
property.

*****WARNING*****WARNING****WARNING********


Disabling Quagga Daemons on a System
====================================

If you have enabled Quagga routing daemons as discussed above, and now wish
to disable them, this can be done generally with:

	# routeadm -d ipv4-routing -u

or

	# routeadm -d ipv6-routing -u

as appropriate. One may also disable just specific daemons with:

	# svcadm disable <daemon service>

High-Availability Networking for Hosts with Quagga
==================================================

The OSPF-MP (OSPF Multi-Pathing) feature is a layer 3 solution to achieve
network connectivity redundancy on servers. It uses the popular technique of
advertising loopback-hosted virtual addresses using a routing protocol, in
this case the OSPF routing protocol.

The OSPF-MP feature is meant to be enabled on multihomed servers to
implement an HA solution based on the OSPF protocol. Note that the server's
interfaces *do not require forwarding to be enabled* for the functioning of
this feature. The feature does require, though, that
ip_strict_dst_multihoming not be enabled. The OSPF-MP feature can be
achieved by configuring Quagga appropriately on a server.

 Configuration
 =============

	  | loopback virtual addresses:
          | lo0:1, lo0:2.... lo0:n
	  |
	---------------------------------------
	| server with OSPF-MP feature enabled |
	---------------------------------------
	      |	   		   |
	   ====== subnet A	 ===== subnet B
	      |                    |
	----------------------------------
        |     OSPF      router           |
	----------------------------------
		   | 
		 ======  subnet C
		   |  
                ----------
		| client |
		----------

 
Setting up a Multi-Homed Host with OSPF-MP
==========================================

Steps
1.Configure loopback aliases on the machine. Following is an
  example: 
	#ifconfig lo0:1 inet plumb 172.16.3.91/32 up

  To have these loopback aliases plumb up across boots, create the
  corresponding /etc/hostname.lo0:<alias#> files. For the above
  example loopback alias case, the corresponding /etc/hostname.lo0:1
  file would have the following entry:
	172.16.3.91 netmask 255.255.255.255 up
  
2. Copy over the OSPF-MP sample configuration files:
          cd /etc/quagga
          cp server-zebra.HA.conf.sample zebra.conf
          cp server-ospfd.HA.conf.sample ospdf.conf

3  Edit the zebra and ospfd configuration files appropriately  

4. Disable forwarding on your server.
		routeadm -d ipv4-forwarding
		routeadm -u

5. Disable IPMP if machine is set up with it. To do this you will
   have to undo all the things you had done to configure IPMP on your
   system. Please see:
        http://docs.sun.com
        Product Categories>> Solaris >> Solaris 10
        Solaris 10 System Administration Guide:IP services, Chapter 30

    for configuration details of IPMP.

6. Enable the OSPF-MP service at boot time, type the following
   routeadm command:
    # routeadm -s routing-svcs=ospf:quagga -e ipv4-routing -u

7. Verify that the loopback hosted addresses are being correctly 
   advertised by OSPF on the server, use the following snoop command:  
	snoop -d <device> -rv ospf

Following is the snoop output on a server that is enabled with OSPF-MP, and
is configured with the loopback alias of the example case above:

ETHER:  ----- Ether Header -----
ETHER:  
ETHER:  Packet 8 arrived at 16:23:57.00008
ETHER:  Packet size = 82 bytes
ETHER:  Destination = 1:0:5e:0:0:5, (multicast)
ETHER:  Source      = 0:d0:b7:b9:ac:b2, 
ETHER:  Ethertype = 0800 (IP)
ETHER:  
IP:   ----- IP Header -----
IP:   
IP:   Version = 4
IP:   Header length = 20 bytes
IP:   Type of service = 0xc0
IP:         xxx. .... = 6 (precedence)
IP:         ...0 .... = normal delay
IP:         .... 0... = normal throughput
IP:         .... .0.. = normal reliability
IP:         .... ..0. = not ECN capable transport
IP:         .... ...0 = no ECN congestion experienced
IP:   Total length = 68 bytes
IP:   Identification = 41685
IP:   Flags = 0x0
IP:         .0.. .... = may fragment
IP:         ..0. .... = last fragment
IP:   Fragment offset = 0 bytes
IP:   Time to live = 1 seconds/hops
IP:   Protocol = 89 (OSPF)
IP:   Header checksum = 2ac5
IP:   Source address = 10.1.1.1, 10.1.1.1
IP:   Destination address = 224.0.0.5, 224.0.0.5
IP:   No options
IP:   
OSPF:  ----- OSPF Header -----
OSPF:  
OSPF:  Version = 2
OSPF:  Type = Hello
OSPF:  Router ID = 10.1.2.1
OSPF:  Area ID = 0.0.0.1
OSPF:  Checksum = 0x2b27
OSPF:  Auth = None
OSPF HELLO:  ----- Hello Packet -----
OSPF HELLO:  
OSPF HELLO:  Options = E
OSPF HELLO:  Mask = 255.255.255.0
OSPF HELLO:  Hello interval = 10
OSPF HELLO:  Priority = 1
OSPF HELLO:  Dead interval = 40
OSPF HELLO:  Designated Router = 10.1.1.2
OSPF HELLO:  Backup Designated Router = 10.1.1.1
OSPF HELLO:  Neighbor: 172.16.3.91
 

Example configuration case on a server with OSPF-MP feature
-----------------------------------------------------------
Given a server with the following ifconfig output:

# ifconfig -a
lo0: flags=1000849<UP,LOOPBACK,RUNNING,MULTICAST,IPv4> mtu 8232 index 1
        inet 127.0.0.1 netmask ff000000 
lo0:1: flags=1000849<UP,LOOPBACK,RUNNING,MULTICAST,IPv4> mtu 8232 index 1
        inet 172.16.3.91 netmask ffffffff 
hme1: flags=1100843<UP,BROADCAST,RUNNING,MULTICAST,ROUTER,IPv4> mtu
1500 index 3  inet 10.10.48.91
netmask ffffff00 broadcast 10.10.48.255 ether 8:0:20:d9:53:71 
qfe0: flags=1100843<UP,BROADCAST,RUNNING,MULTICAST,ROUTER,IPv4> mtu 1500 index 4  inet 10.11.48.91
netmask ffffff00 broadcast 10.11.48.255 ether 0:3:ba:17:4d:47 

Its ospfd and zebra config files for OSPF-MP would be the following:
::::::::::::::
zebra.conf
::::::::::::::
!
! Zebra configuration saved from vty
!   2004/03/08 18:35:11
!
hostname test-machine
password zebra
log file /var/tmp/zebra.log
service advanced-vty
!
interface lo0
interface hme1
 link-detect
interface qfe0
 link-detect
!
line vty
!
::::::::::::::
ospfd.conf
::::::::::::::
!
! Zebra configuration saved from vty
!   2004/03/15 16:23:35
!
hostname test-machine 
password zebra
log file /var/tmp/ospf.log
service advanced-vty
!
router ospf
 ospf router-id 10.10.48.91 
 redistribute connected
 network 10.10.48.0/24 area 1
 network 10.11.48.0/24 area 1
!
line vty
exec-timeout 0 0
!
# 

Troubleshooting the OSPF-MP Feature 
===================================

Use the following monitoring and debugging commands on a running
ospfd daemon via the telnet command (ie "/usr/sbin/quaggaadm ospfd").

Monitoring Commands for the ospfd Daemon
----------------------------------------
  show ip ospf
  show ip ospf neighbor
  show history
  show debugging ospf
  show ip ospf interface [INTERFACE]
  show running-config
  show startup-config 

Debug Commands for the ospfd Daemon
-----------------------------------
  debug ospf event
  debug ospf ism
  debug ospf ism (status|events|timers)
  debug ospf lsa
  debug ospf lsa (generate|flooding|refresh)
  debug ospf nsm
  debug ospf nsm (status|events|timers)
  debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all)
  debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv)
     (detail|)
  debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all)
    (send|recv|detail)
  debug ospf zebra
  debug ospf zebra (interface|redistribute)

Similarly, use the following monitoring and debugging commands on a running
zebra daemon via the telnet command ( ie "/usr/sbin/zebraadm zebra").

Monitor Commands for the zebra Daemon
--------------------------------------
  show history
  show debugging zebra
  show interface [IFNAME]
  show ip forwarding
  show running-config
  show startup-config

Debug Commands for the zebra Daemon
-----------------------------------
  debug zebra events
  debug zebra kernel
  debug zebra packet
  debug zebra packet (recv|send)
  debug zebra packet (recv|send) detail


Fine-tuning the OSPF-MP Feature by Customizing the OSPF Timers
==============================================================
Use specific interface level configuration subcommands of Telnet UI 
to fine-tune the timers of OSPF daemon. To get to the interface level
configuration mode, type:

	/usr/sbin/quaggaadm ospfd
	Password:<type password that is set in the ospfd.conf file>
	<hostname>#configure terminal
	<hostname>(config)# interface <interface name>
	<hostname>(config-if)#

The appropriate subcommands to customize the timers are:

 ip ospf dead-interval <1-65535>
 ip ospf hello-interval <1-65535>
 ip ospf retransmit-interval <3-65535>
 ip ospf transmit-delay <1-65535>

You can have these new parameters committed to the configuration file by
typing:

	<hostname>(config-if)# write file

For further details of the above commands, please see the Quagga
documentation:

	http://www.quagga.net/docs.php