
                 Cisco C5921 Software Router
                    README_C5921.txt File
         Copyright (c) 2012-2013, 2016 by Cisco Systems, Inc.
                    All rights reserved.

This README file provides an introduction to the C5921 Software
Router.  An overview of the C5921 Software Router software and a
description of its components is provided.

1.0 Introduction

The C5921 Software Router is a software-only product, designed to run
on the Linux operating system.  The C5921 Software Router is a Linux
application, running entirely in user space.  The C5921 Software
Router utilizes the physical network interfaces provided by the host
Linux system.  In this release of the software, only Ethernet
interfaces are supported.

The C5921 Software Router contains within it a complete implementation
of the CISCO IOS software.  The universalk9 feature set is
supported.

1.1 Cisco Feature Navigator
Cisco Feature Navigator allows you to quickly find the right Cisco software 
release for the features you want to run on your network. You can search by 
feature, technology, image, platform and more.

http://tools.cisco.com/ITDIT/CFN/jsp/index.jsp

1.2 Supported Features
The Cisco 5921 ESR application is built from T Train, Use Cisco Feature Navigator
to see the list of supported features.

2.0 Software Components

The C5921 Software Router software contains several components.  There
are several user space executable programs, each of which runs as a
Linux process. Additionally there are several
standard Linux packages which the C5921 Software Router software
utilizes.

NOTE: c5921i86-XXX-ms - where XXX signifies either "universalk9" or "universalk9_npe"
The components consist of the following:

1. c5921i86-XXX-ms - The software router application
   itself, containing the IOS code.  It runs as a Linux process.

2. swrvcon - A program which can provide a virtual console accessing
   the c5921i86-XXX-ms process.

3. swr_reload - The application used to launch and reload software
   router.

4. libdyncs.so - Software router application specific shared library.
   
5. Standard Linux Packages
   a. tunctl (if using tap interface)
   b. bridge-utils (if using tap interface in a bridge group)
   
2.1 c5921i86-XXX-ms

As mentioned previously, this is the software router application
itself.  It is delivered as a Linux executable application.

It is run as a single user-space process.  It may be run in the
foreground, or in the background.  Most users will always launch the
application in background mode during system initialization with an
initialization script in /etc/init.d directory. 

The software router applicatoin and shared library "libdyncs.so"
must be present in the same direcotory and the library must be
exported using "export LD_LIBRARY_PATH=<path>"

         linux-box# export LD_LIBRARY_PATH=/opt/cisco/c5921

To access the IOS console when it is running in background, use the 
swrvcon application.

NOTE: To run the application in background mode, use the -L option, and
      launch it with the "&".  For example:

         linux-box# c5921i86-XXX-ms -e 1 -L 100 &

If the application is run in the foreground, from the user's point of 
view, it looks like an IOS router, and the user can use the IOS CLI to
manage the router.

As a user-space application, the c5921i86-XXX-ms
accepts several command line options, which allows the user to specify
information such as how many Ethernet ports are to be used, and other
items.  Provided with the distribution is a man page, swr-application.1,
which explains command line options.

c5921i86-XXX-ms models its network interfaces as 4-port
Ethernet line cards.  There can be between 1 and 5 such 4-port Ethernet
line cards, and the number can be specified in the
c5921i86-XXX-ms command line.  In the IOS CLI, each
Ethernet port is referred to using the standard IOS bay/unit notation.
The 4 ports of the first line card are referred to in the CLI as e0/0,
e0/1, e0/2, and e0/3.  The 4 ports of the second line card are
referred to as e1/0, e1/1, e1/2, and e1/3, and similarly for subsequent
line cards.

For more information concerning IOS interface naming, refer to:

http://www.cisco.com/en/US/docs/ios/interface/configuration/guide/15_2T/ir_15_2MT_book.html

Refer to the swr-application.1 man page for more information.

2.2 Swrvcon

Swrvcon is an optional virtual console to the
c5921i86-XXX-ms.  It allows a user to connect and
disconnect to the c5921i86-XXX-ms console.  Swrvcon
will work only when c5921i86-XXX-ms is launched using
its "-L" command line option.  This provides a way for the user to
interact with the c5921i86-XXX-ms when it has been
launched from Linux init scripts.

2.3 Swr_reload

Swr_reload is an optional application to reload Cisco's IOS-Linux based
software router in the event of a crash or a manually initiated reload.
This application completely terminates and restarts all processes related to SWR 
when a reload is initiated (versus simply starting the SWR process over without
actually terminating it). The purpose of swr_reload is to launch and reload 
software router which is specified in SWROPTIONS file, through command-line 
option, or from current working directory. Control-C should be used to exit the 
swr_reload application.

 
2.4 TAP Interfaces for Co-located applications

The software router supports use of Linux TAP interfaces to allow 
applications on the local computer to both access the SWR itself
(for management purposes), or for routing through the SWR to 
destinations in the network. Setting up a TAP interface involves:
 1. Defining the interface to Linux
 2. Supplying an IP address (or addresses) for the Linux "end" of
    the TAP,
 3. Associating the TAP interface with a software router interface,
 4. Configuring the interface in the Software Router.

All of the TAP installation/configuration steps assume that the user
is logged in as root. With that caveat, let us look at each of the
steps in turn:

 Defining the TAP interface

Commands to define the TAP are dependent on the Linux Operating 
system used. For example, to define the TAP on CentOS, the "tunctl"
package must first be installed on the CentOS machine. Installation
of the tunctl package can be accomplished by entering 
"yum install tunctl". After installation, the command 
"tunctl -p -t tap0" should be executed to define a persistent
TAP interface to CentOS.

After initial definition of the TAP interface via "tunctl", 
the TAP is brought up by the "ifconfig" command:  
"ifconfig tap0 up".

 Supply IP address 

The TAP interface can be envisioned as a software version of an 
Ethernet cable, or as a software-only 2 port switch. As such, 
both "ends" of the cable (or both ports of the switch) need IP 
addresses. In the case of Software Router support, one "end" of
the cable is Linux, the other is the Software Router process itself.
Supply an appropriate IP address (or addresses) using the "ifconfig"
command. For example, "ifconfig tap0 10.10.10.1/24" would assign 
the 10.10.10.1 address to the Linux "end" of the tap, with a 24-bit
network mask (e.g., 255.255.255.0).

In order to make the tap0 interface persistent across Linux reboots,
some additional Linux configuration needs to be applied. Enter the
following commands:

cd /etc/sysconfig/network-scripts
vi ifcfg-tap0

and add the following information to the file:
DEVICE=tap0
ONBOOT=yes
BOOTPROTO=none
IPADDR="10.10.10.1"
NETMASK="255.255.255.0"
TYPE=Tap

 Associate the TAP interface with a Software Router interface

The association of the TAP to a software router interface is done 
via the SWROPTIONS file. The form of the SWROPTIONS entry for TAP interfaces
is:  
SWROPTIONS:
     [interface]
     linux=tap0
     ios=e0/0  
     type=tap

Example for configuring "tap" via command line,
c5921i86-XXX-ms -i linux=tap0:ios=eth0/0:type=tap .

 Configure the Software Router Interface

From the perspective of the Software Router, the interface associated 
with the TAP is configured as any other Ethernet interface - to 
continue the example above, the software router configuration might
contain: 

 interface e0/4
 ip address 10.10.10.2 255.255.255.0
 end

Note that, in this example, the software router "end" of the TAP 
interface has its own address (10.10.10.2), and this address is 
in the same subnet as the Linux "end" of the TAP (which is 10.10.10.1).
Entering the above configuration, and starting the interface allows 
the software router to communicate with the local Linux system. As 
a test of the software router TAP support, it should now be possible to 
login to the Linux box, and ping the Software Router address (in this
example, 10.10.10.2) from a shell process. 



3.0 Installation

The C5921 Software Router is delivered as a tar file,
c5921i86-XXX-tar.[RELEASE_LABEL].tar with the following contents:

c5921i86-XXX-ms.152-4.GC/FAQ_C5921.txt
c5921i86-XXX-ms.152-4.GC/README_C5921.txt
c5921i86-XXX-ms.152-4.GC/RELEASE_NOTES_C5921.txt
c5921i86-XXX-ms.152-4.GC/SWROPTIONS.example.txt
c5921i86-XXX-ms.152-4.GC/c5921-swr-init.sh
c5921i86-XXX-ms.152-4.GC/c5921i86-universalk9-ms.SSA
c5921i86-XXX-ms.152-4.GC/c5921i86-universalk9-ms.md5
c5921i86-XXX-ms.152-4.GC/libdyncs.so
c5921i86-XXX-ms.152-4.GC/swr-application.1
c5921i86-XXX-ms.152-4.GC/swr_reload
c5921i86-XXX-ms.152-4.GC/swr_reload.1
c5921i86-XXX-ms.152-4.GC/swroptions.1
c5921i86-XXX-ms.152-4.GC/swrvcon
c5921i86-XXX-ms.152-4.GC/swrvcon.1

The distribution also includes a file,
c5921i86_XXX-ms.md5, which is a MD5 digest of the tar file.

The files from the tar file need merely be extracted, using:
    tar -xf c5921i86-XXX-tar.[RELEASE_LABEL].tar

The software router applicatoin and shared library "libdyncs.so"
must be present in the same direcotory and the library must be
exported using "export LD_LIBRARY_PATH=<path>"

         linux-box# export LD_LIBRARY_PATH=/opt/cisco/c5921
    

4.0 Further reading

man ./swrvcon.1
man ./swr_reload.1
man ./swroptions.1
man ./swr-application.1

Included in the software distribution are the following additional
files:
FAQ_C5921.txt           - Frequently Asked Questions.
README_C5921.txt        - Readme file for the software distribution.
RELEASE_NOTES_C5921.txt - Release notes for the software distribution.
SWROPTIONS.example.txt  - Sample SWROPTIONS file.


